備份與升級

需要備份哪些內容、如何在新主機上還原、如何升級，以及如何將 Mattermost 伺服器或單一社群遷移至 Antimatter。

需要備份的內容

若沒有 AI 加密金鑰，還原後的伺服器將無法讀取其模型連線的 API 金鑰，必須逐一重新輸入。請將金鑰副本與資料庫備份分開保存，以免單一備份同時包含兩者。詳見加密金鑰。

資料庫與檔案必須一起備份：請在同一時間備份兩者，並將副本儲存在伺服器之外。Volume 名稱以 compose 專案名稱 antimatter 開頭（可使用 docker volume ls 列出）。

備份

從 compose.yaml 所在的目錄執行。先停止 Antimatter 可確保取得完全一致的副本；在執行中備份通常沒問題，但備份期間上傳的檔案可能未包含在內。

stamp=$(date +%Y%m%d-%H%M%S)
mkdir -p backups
docker compose stop antimatter
# Database
docker compose exec -T postgres pg_dump -U antimatter -d antimatter -Fc \
    > "backups/antimatter-db-$stamp.dump"
# File storage, GIF service and the data directory (the AI key file)
for v in files gifs data; do
    docker run --rm -v "antimatter_$v:/data:ro" -v "$PWD/backups:/backup" \
        alpine tar -czf "/backup/antimatter-$v-$stamp.tar.gz" -C /data .
done
docker compose start antimatter
# Secrets
cp .env "backups/env-$stamp"

若尚未設定 AM_AI_ENCRYPTION_KEY，伺服器的金鑰檔案位於 data 卷中，上述迴圈會將其與檔案一併保存。更好的做法是依照加密金鑰的說明，將其內容放入 .env，並將副本與資料庫備份分開保存。

透過 cron 執行每日備份，並將 backups/ 目錄複製到其他機器。請妥善保管 .env 的副本，如同保護伺服器本身：其中包含密碼。

若要逐個複製上傳的檔案（例如複製到另一個 S3 儲存），請使用 bucket 服務的 AWS 命令列工具：

docker compose run --rm -v "$PWD/backups/files:/backup" bucket \
    "aws --endpoint-url http://files:9000 s3 sync s3://antimatter /backup"

使用發行版檔案時，請以 pg_dump -Fc 備份資料庫，並使用慣用工具備份 data/ 和 config/ 目錄（data/ 包含 AI 金鑰檔案）。使用套件時，請以相同方式備份資料庫，並備份 /etc/antimatter、/var/lib/antimatter、/etc/gifs-server 和 /var/lib/gifs-server。

在新主機上還原

將 compose.yaml、已儲存的 .env 與備份檔案放入新目錄，然後：

stamp=20261016-030000          # the backup to restore
docker compose create           # creates the volumes, starts nothing
docker compose up -d postgres
docker compose exec -T postgres pg_restore -U antimatter -d antimatter --no-owner \
    < "backups/antimatter-db-$stamp.dump"
for v in files gifs data; do
    docker run --rm -v "antimatter_$v:/data" -v "$PWD/backups:/backup" \
        alpine tar -xzf "/backup/antimatter-$v-$stamp.tar.gz" -C /data
done
docker compose up -d

請使用相同的 .env：儲存空間和資料庫必須保留原有的密碼，且模型連線需要相同的 AI 加密金鑰。若新主機有不同的位址，請更新 SITE_URL（以及 DOMAIN）。

請定期在其他機器上還原備份以測試其完整性。

升級

1. 先進行備份。
2. 如果您有固定映像標籤（如建議所示），請修改 .env 中的映像標籤（ANTIMATTER_IMAGE）。
3. 拉取並重新啟動：

   docker compose pull
   docker compose up -d
   docker compose logs -f antimatter

啟動時，伺服器會升級資料庫結構（可在日誌中追蹤進度；大型伺服器可能需要數分鐘），並從映像檔中安裝較新版本的內建應用程式。若使用發行版壓縮檔：請停止伺服器，將除 config/、data/、logs/、plugins/ 和 client/plugins/ 以外的所有內容，替換為新壓縮檔的內容，然後重新啟動。若使用 .deb 或 .rpm 套件，請依照升級套件的說明安裝新套件。

版本

Antimatter 伺服器會報告其所基於的 Mattermost 版本（目前為 12.0.0）。GitHub 上的發行版（包含壓縮檔與套件）擁有獨立的版本編號，在測試期間為 0.9.0 系列：antimatter version 會將其顯示為組建編號。映像檔會從 main 分支重新建置：antimatter-next 每晚建置一次（標籤為 nightly-<YYYYMMDD>），且每次變更時都會建置兩個映像檔（標籤為 sha-<commit>）。請固定使用其中一個標籤，有意識地進行升級，並記錄前一個標籤，以便知道哪個備份與之對應。

PostgreSQL 主要版本

Compose 檔案使用 postgres:17-alpine。Antimatter 需要 PostgreSQL 15 或更新版本。PostgreSQL 的新主要版本無法讀取舊版本資料目錄的內容：若要遷移，請先匯出資料庫，在新的磁碟區上啟動新版本，並將匯出的資料還原至其中。

升級至 0.9.0

首次啟動 0.9.0 版本（或 2026 年 10 月 17 日或之後建置的映像檔）時，會對資料進行幾項一次性變更。每項變更僅執行一次，並記錄在資料庫中。這些變更會將保留在舊預設值的項目更新為新預設值，而不會動到管理員已自行設定的項目。請在日誌中追蹤這些變更。

Agents 應用程式的服務

升級時，系統會將 Agents 應用程式中的每個 AI 服務複製為伺服器層級的模型連線，供所有社群共用，且所有人都可使用，唯獨訪客除外（若要開放給訪客，請開啟 Guests too）。金鑰在傳輸過程中會經過加密，因此伺服器需要具備 AI 加密金鑰：若檔案存放於 S3 的叢集，請先設定 AM_AI_ENCRYPTION_KEY，否則複製作業將等待下次啟動時再執行。接著請檢查 系統控制台 › AI › 模型連線：

• 每個連線都會保留其對應服務的 ID，因此該應用程式的代理程式，以及設定為使用 Agents 服務的自動翻譯功能，仍能找到該服務。
• OpenAI、相容於 OpenAI、Anthropic、Mistral、Cohere 和 Gemini 的服務，將成為指向其相容於 OpenAI（或 Anthropic）端點的連線。Azure 服務則會成為指向該資源相容於 OpenAI 端點的連線：請進行測試。
• AWS Bedrock、Google Vertex AI 和 Cohere North 服務，以及未知類型的服務，將被標記為 Needs attention，並附上原因。這些服務的雲端憑證不會被複製：請將其指向提供者的相容於 OpenAI 端點，或指向 LiteLLM 等閘道，然後儲存。
• 嵌入（Embedding）服務將成為具有相同地址和金鑰之連線的 Embeddings 模型，或成為獨立的連線。文字轉錄服務則會取得 whisper-1 模型。
• 當重寫（rewrite）和摘要（recaps）尚未有對應的連線時，它們將使用該應用程式預設代理程式的服務和模型。

Agents 應用程式自身的設定與資料將保持原狀：其代理程式仍會繼續使用該應用程式的服務。

其他預設值的變更

• 通話：Test mode 預設為關閉，Enable video 預設為開啟。若設定檔中已儲存選擇，則會予以保留。通話也會遵循社群的類型（請參閱 通話與語音）。
• 將訊息置頂的權限屬於頻道的管理員、社群的管理員與版主（需具備 管理訊息 權限）；私人訊息或群組訊息的成員仍可自行置頂。
• 已封存的頻道可以接受新成員加入，新成員可以閱讀歷史記錄。但任何人都不能在這些頻道中發布訊息、做出反應或進行任何變更。

從 Mattermost 遷移

Antimatter 使用 Mattermost 的資料庫結構並新增自己的表格，因此可以接管 Mattermost 伺服器的 PostgreSQL 資料庫和檔案。請先複製一份資料進行測試：

1. 備份 Mattermost 資料庫、其檔案儲存空間（data/ 或 S3 儲存桶）以及 config.json，然後停止 Mattermost。
2. 將資料庫還原至 Antimatter 的 PostgreSQL，或將 Antimatter 指向該資料庫的副本（AM_SQLSETTINGS_DATASOURCE）。
3. 將檔案複製至 Antimatter 的儲存空間，並保留其路徑：若使用 S3 工具，請複製至 antimatter 儲存桶；若使用發行版檔案，請複製至 data/。
4. 重用您的設定：複製 config.json，或使用 amctl --local config migrate 將其移入資料庫（請參閱 設定）。您的 MM_ 環境變數仍可繼續使用；在方便時可將其重新命名為 AM_。
5. 啟動 Antimatter，並觀察日誌以查看資料庫升級過程。接著檢查 系統控制台 › 擴充程式 › 擴充程式管理。當 Antimatter 自建的通話、操作手冊、看板、代理程式及整合版本比已安裝的版本更新時，系統會自動安裝這些版本。若 Mattermost 已安裝其中某項較新的版本，請移除該應用程式並重新啟動 Antimatter，以確保安裝的是 Antimatter 自建的版本。
6. 請使用您自己的推播代理重新設定推播通知：Antimatter 不會將通知傳送至 Mattermost 的推播服務（無論是測試或託管環境），因為這些服務僅能傳遞至 Mattermost 自家的應用程式。在您變更 推播通知伺服器 之前，伺服器不會發送任何推播通知（請參閱 推播通知）。

Antimatter 不會連線至任何由 Mattermost, Inc. 營運的服務（請參閱 對外部服務的連線），即使您的設定檔中仍保留相關項目：

• Mattermost 的推送通知伺服器設定會保留，但絕不會被使用；
• Mattermost 的應用程式市集（市集網址）與產品通知的網址已被清空；
• 原本為 Mattermost 預設值的應用程式下載連結（Antimatter Apps Download Page Link、Android 應用程式下載連結 和 iOS 應用程式下載連結）已更換為 Antimatter 應用程式在 GitHub 上的下載頁面；您自行設定的連結將予以保留；
• Calls 應用程式會改用 Cloudflare 的公開 STUN 伺服器，而非 Mattermost 的伺服器，且不會修改已儲存的設定（請參閱 Calls）；
• 安全更新檢查與崩潰報告功能已移除，相關的系統控制台設定（啟用安全警示、啟用診斷與錯誤報告）以及 通知 頁面也一併移除。

本地模式套接字現在為 /var/tmp/antimatter_local.socket；amctl 也會嘗試使用舊的 /var/tmp/mattermost_local.socket。Mattermost 近期版本僅支援 PostgreSQL，Antimatter 亦然：請先將 MySQL 資料庫遷移至 PostgreSQL。若在 Antimatter 升級資料庫後要退回 Mattermost，則必須還原您的 Mattermost 備份。

匯出與匯入資料

批次匯出格式可用於在伺服器之間移動資料：您可以匯出整個伺服器、部分社群或特定頻道，並可選擇包含附件、個人頭像與自訂表情符號。

# on the source server
amctl export create --team-name design --include-profile-pictures
amctl export list
amctl export download <export file> design.zip
# on the destination server
amctl import upload design.zip
amctl import list available
amctl import process <uploaded file> --imported-users active

使用 amctl export job list 和 amctl import job list 來查看工作。對於社群或頻道匯出，必須指定 --imported-users：當人員遷移至此伺服器時使用 active；當匯入到這些人員已有帳號的伺服器時使用 inactive，這樣從不確定匹配建立的帳號就會保持停用，直到管理員檢查為止。使用 --destination-team-name 可匯入到現有的社群。匯出和匯入檔案預設會保留在伺服器的儲存空間（ExportSettings.Directory、ImportSettings.Directory）中 30 天。

在伺服器本機上，antimatter export bulk 和 antimatter import bulk --apply 可透過檔案執行相同的操作，無需使用 API。