备份与升级

需要备份哪些内容，如何在新主机上还原，如何升级，以及如何将 Mattermost 服务器或单个社区迁移到 Antimatter。

需要备份的内容

如果没有 AI 加密密钥，还原后的服务器将无法读取其模型连接的 API 密钥，必须重新输入每一个密钥。请将密钥的副本与数据库备份分开保存，以免一个被盗的备份同时包含两者。参见 加密密钥。

数据库和文件是配套的：请同时备份它们，并在服务器之外保留副本。卷名称以 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 › Model connections：

• 每个连接保留其服务的 ID，因此该应用的智能体以及设置为 Agents 服务的自动翻译功能仍能找到它。
• OpenAI、OpenAI 兼容、Anthropic、Mistral、Cohere 和 Gemini 服务将变为指向其 OpenAI 兼容（或 Anthropic）端点的连接。Azure 服务将变为指向该资源 OpenAI 兼容端点的连接：请进行测试。
• AWS Bedrock、Google Vertex AI 和 Cohere North 服务，以及未知类型的服务，将被标记为 Needs attention，并附带原因。它们的云凭证不会被复制：请将它们指向提供商的 OpenAI 兼容端点或 LiteLLM 等网关，然后保存。
• 嵌入服务将变为具有相同地址和密钥的连接的 Embeddings 模型，或成为其自身的连接。转录服务将获得 whisper-1 模型。
• 当重写和摘要功能尚未有连接时，它们将使用应用默认智能体的服务和模型。

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 自带的通话、操作手册、看板（Boards）、智能体及集成版本比已安装版本更新时，Antimatter 会安装其自带的构建版本。如果 Mattermost 拥有其中某个应用的更新版本，请移除该应用并重启 Antimatter，以便安装 Antimatter 自带的构建版本。
6. 重新设置推送通知，使用您自己的推送代理：Antimatter 从不向 Mattermost 的推送服务（无论是测试还是托管服务）发送通知，因为这些服务仅向 Mattermost 自己的应用投递通知。在您更改推送通知服务器之前，服务器不会发送任何推送通知（参见推送通知）。

Antimatter 不会联系由 Mattermost, Inc. 运行的任何服务（参见与外部服务的连接），即使您的配置中仍然指定了这些服务：

• Mattermost 的推送通知服务器保留在设置中，但永远不会被使用；
• Mattermost 的应用市场（市场 URL）和产品通知地址将被清空；
• 应用下载链接（Antimatter Apps Download Page Link、安卓应用下载链接 和 iOS 应用下载 URL）已替换为 Antimatter 应用在 GitHub 上的下载页面；您自行设置的链接将予以保留；
• 通话应用现在使用 Cloudflare 的公共 STUN 服务器，而非 Mattermost 的，且不会更改已保存的设置（参见 通话）；
• 安全更新检查和崩溃报告功能已移除，相关的系统控制台设置（Enable Security Alerts、Enable Diagnostics and Error Reporting）以及 通知 页面也随之移除。

本地模式套接字现为 /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。