安装 Antimatter

使用现成的 compose 文件、发布版本的 .deb 或 .rpm 软件包，或发布存档安装 Antimatter。然后创建第一个管理员账户。

使用 Docker Compose 安装

这是推荐的方式。一个 compose 文件即可运行 Antimatter、PostgreSQL、文件存储和 GIF 服务。你需要一台装有 Docker Engine 及其 Compose 插件（docker compose）的 Linux 服务器，以及至少 2 个 CPU 核心和 4 GB 内存。

1. 下载 compose 文件

mkdir antimatter && cd antimatter
curl -fsSLO https://antimatter.chat/compose.yaml

2. 创建 .env 文件

compose 文件从同一目录下的 .env 文件中读取配置。请创建该文件并设置随机密钥：

cat > .env <<EOF
SITE_URL=http://localhost:8065
POSTGRES_PASSWORD=$(openssl rand -hex 24)
S3_SECRET_KEY=$(openssl rand -hex 24)
GIFS_API_KEY=$(openssl rand -hex 24)
AM_AI_ENCRYPTION_KEY=$(openssl rand -base64 32)
EOF
chmod 600 .env

将 SITE_URL 设置为用户在浏览器中输入的地址，例如本地网络中的 http://192.168.1.20:8065 或带有域名的 https://chat.example.com。请保留 .env 文件：数据库和存储使用首次启动时这些密码，AI 模型连接的 API 密钥使用 AM_AI_ENCRYPTION_KEY 加密，并且恢复备份时需要使用相同的文件。

3. 启动

docker compose up -d
docker compose ps

首次启动需要一两分钟：PostgreSQL 创建数据库，一次性 bucket 服务创建存储桶，一次性 gifs-stickers 服务导入初始贴纸包，Antimatter 创建其数据表。使用 docker compose logs -f antimatter 跟踪进度。

如需从一开始就使用域名和 HTTPS，请参阅 域名和 HTTPS：使用 compose 文件时，只需在 .env 中多写两行并启用 https 配置即可。

.env 变量

运行内容

PostgreSQL、存储和 GIF 服务位于一个无互联网访问权限的内部网络（private）上，只有 Antimatter 会加入该网络。它们均未发布端口。

Antimatter 容器不在磁盘上保留任何内容：其设置位于数据库中（AM_CONFIG 指向它），其文件和应用位于存储服务中。您可以随时删除并重新创建容器。其 data 卷仅保存 AI 加密密钥文件，当 AM_AI_ENCRYPTION_KEY 为空时由服务器创建。所有需要备份的内容都在 postgres、files、gifs 和 data 卷中，以及您的 .env 文件中。

选择镜像

发布了两个 Antimatter 镜像，均支持 linux/amd64 和 linux/arm64，且均基于每个仓库的 main 分支构建：

该站点的 compose 文件使用 antimatter-next，因为 GIF 服务和本站点描述的大多数应用仅存在于该镜像中。若要更改镜像，请在 .env 中设置 ANTIMATTER_IMAGE，然后运行 docker compose up -d。

镜像内部

• 服务器位于 /antimatter，二进制文件 antimatter 和 amctl 位于 /antimatter/bin（在 PATH 中）。
• 它以非特权用户 antimatter（uid 2000）身份运行，基于极简的 distroless 基础镜像，且无 shell。
• 端口：8065（Web 和 API）、8067（指标）、8074（集群）、8443 UDP 和 TCP（通话）。
• 本地模式（ServiceSettings.EnableLocalMode）已启用，因此可以在容器内使用 amctl --local。健康检查会运行 amctl system status --local。
• 内置应用位于 /antimatter/prepackaged_plugins，并使用 Antimatter 应用签名密钥进行签名。
• 已包含文本提取工具（pdftotext、wvText、unrtf、tidy），因此可以搜索上传文档的内容。

其他 compose 文件

antimatter-docker 仓库在 deploy/compose/ 中提供了一个生产环境配置：使用您自己的证书或 Let's Encrypt（certbot）的 nginx、PostgreSQL、可选的 GIF 服务（配置文件 gifs）以及用于服务器配置、数据和日志的命名卷，具体说明见其 README。默认使用稳定版镜像，并将文件存储在本地卷而非 S3 存储上。如果您更喜欢使用 nginx 而不是 Caddy，或者已经拥有证书，可以使用此配置。

创建第一个管理员

在浏览器中打开 SITE_URL 并创建一个账户。在新服务器上创建的第一个账户将成为系统管理员，随后设置流程将引导您创建第一个社区（Antimatter 对团队或工作区的称呼）。

请在首次启动后立即执行此操作：在此之前，最先访问服务器的任何人都将成为其管理员。如果希望从命令行创建账户，请在服务器可从外部访问之前执行以下操作：

docker compose exec antimatter amctl --local user create --system-admin --email-verified \
    --email admin@example.com --username admin --password 'a-long-password'
docker compose exec antimatter amctl --local team create --name main --display-name "Main"
docker compose exec antimatter amctl --local team users add main admin

然后在 SITE_URL 登录。在命令前加一个空格，以避免密码出现在 shell 历史记录中（需设置 HISTCONTROL=ignorespace），或者在登录后更改密码。

进入系统后的后续步骤：

1. 对于公司或组织，将 新社区类型 设置为 工作场所，并在其设置中更改已创建社区的类型：工作场所或社区。
2. 决定谁可以创建账户：登录与账户。
3. 配置电子邮件，以便邀请和密码重置功能正常工作：电子邮件与推送通知。
4. 在防火墙中开放通话端口：通话与语音。
5. 检查哪些应用已启用：内置应用。

下载发布版本

不使用 Docker，从 GitHub 上的发布文件安装 Antimatter：github.com/AntimatterChat/antimatter/releases。每个发布版本都有一个版本号，例如 0.9.0，其标签是前面加 v 的相同数字（v0.9.0）。

每个发布版本都包含以下文件，适用于 amd64 和 arm64 服务器：

软件包和归档文件包含相同的程序：服务器（antimatter）、命令行工具（amctl）、两个 Web 应用（默认界面和经典界面）、内置应用、电子邮件模板和翻译文件。软件包额外包含一个 systemd 服务和一个配置文件，因此每个软件包都是一体化的安装：您只需添加一个 PostgreSQL 数据库。没有单独的二进制文件下载：二进制文件位于归档文件的 antimatter/bin/ 目录中。它们是静态编译的，因此可以在其架构对应的任何 Linux 发行版上运行。

在软件包名称中，预发布版本的连字符会变为波浪号，以便包管理器将预发布版本排在最终版本之前：版本 0.9.0-rc.1 对应 antimatter_0.9.0~rc.1-1_amd64.deb 和 antimatter-0.9.0~rc.1-1.x86_64.rpm。归档文件保留连字符。

antimatter version 命令将发布版本打印为 编译号，并将构建所用的提交打印为 编译哈希。其 版本 行是 Antimatter 所基于的 Mattermost 系列的版本。

检查下载

将您需要的文件和 SHA256SUMS 下载到同一目录（从发布页面下载或使用 curl），然后检查文件：

curl -fLO https://github.com/AntimatterChat/antimatter/releases/download/v<version>/antimatter_<version>-1_amd64.deb
curl -fLO https://github.com/AntimatterChat/antimatter/releases/download/v<version>/SHA256SUMS
sha256sum --check --ignore-missing SHA256SUMS

您下载的每个文件都必须显示为 OK。任何其他结果都意味着文件已损坏或不完整：请重新下载，不要安装它。SHA256SUMS 没有签名：它只能检测损坏的下载，其证明力不超过从 GitHub 进行的 HTTPS 下载。

安装 .deb 或 .rpm 软件包

该软件包将 Antimatter 安装为 systemd 服务，启动时只需要一个数据库。请在带有 systemd 的 64 位 Debian、Ubuntu、Fedora 或与 RHEL 兼容的服务器上使用。

软件包安装的内容

服务器在 /opt/antimatter 中写入的目录（config、data、plugins、client/plugins 和 logs）是指向 /etc/antimatter、/var/lib/antimatter 和 /var/log/antimatter 的链接。因此，替换 /opt/antimatter 的升级操作绝不会触及您的数据。该包还会创建系统用户 antimatter，用于运行服务器并拥有这些目录。

该包依赖于 ca-certificates。它推荐安装 PostgreSQL（Debian 和 Ubuntu 上为 postgresql，Fedora 和 RHEL 上为 postgresql-server）、media-types（.rpm 包中为 mailcap）以及 gifs-server（GIF 服务，有独立的发布版本，见下文）。apt 和 dnf 在找到推荐包时会安装它们。它还建议安装 poppler-utils、wv、unrtf 和 tidy（.rpm 包中无 wv）：这些工具用于提取上传文档中的文本，以便搜索功能能够找到其中的单词。如需此功能，请自行安装。

1. 安装包

下载适用于您架构的 Antimatter 包和 GIF 服务包，按照上述方法校验它们，并在一条命令中同时安装这两个包，以满足 gifs-server 的推荐依赖（它不在发行版的软件仓库中）：

# Debian, Ubuntu
sudo apt install ./antimatter_<version>-1_amd64.deb ./gifs-server_*_amd64.deb
# Fedora, RHEL
sudo dnf install ./antimatter-<version>-1.x86_64.rpm ./gifs-server-*.x86_64.rpm

保留 ./：它告诉 apt 和 dnf 安装本地文件。若要安装不包含 GIF 服务的版本，请省略其软件包。该软件包会启用 antimatter 服务，但不会启动它，并会打印后续步骤。

2. 创建数据库

Antimatter 需要 PostgreSQL 15 或更高版本，可部署在本服务器或其他服务器上。使用 psql --version 检查你的发行版中 PostgreSQL 的版本。如果版本较旧，请从 PostgreSQL 项目自己的软件仓库安装更新版本，或使用其他服务器上的数据库。在 Debian 和 Ubuntu 上，postgresql 软件包会启动数据库。在 Fedora 和 RHEL 上，请先创建并启动它：

sudo postgresql-setup --initdb
sudo systemctl enable --now postgresql

然后为 Antimatter 创建一个用户和一个数据库：

sudo -u postgres psql -c "CREATE USER antimatter WITH PASSWORD 'a-long-password'"
sudo -u postgres psql -c "CREATE DATABASE antimatter OWNER antimatter"

PostgreSQL 必须接受来自 127.0.0.1 的密码连接：其 pg_hba.conf 文件中的 host 行，使用 scram-sha-256 方法。

3. 设置数据库和站点 URL

编辑 /etc/antimatter/antimatter.env（sudoedit /etc/antimatter/antimatter.env）。删除你使用的行前面的 #，并设置数据库和人们将打开的地址：

AM_SQLSETTINGS_DRIVERNAME=postgres
AM_SQLSETTINGS_DATASOURCE=postgres://antimatter:a-long-password@localhost:5432/antimatter?sslmode=disable&connect_timeout=10
AM_SERVICESETTINGS_SITEURL=https://chat.example.com

配置中的任何设置都可以写入此文件，格式为 AM_<SECTION>_<SETTING>：例如，SqlSettings.DataSource 对应 AM_SQLSETTINGS_DATASOURCE。在此处设置的配置项无法在系统控制台中更改。请参阅配置。每次更改后请重启服务器：sudo systemctl restart antimatter。

该服务还会设置一些默认值，这些值可被 antimatter.env 中的一行覆盖：日志记录到文件是关闭的（AM_LOGSETTINGS_ENABLEFILE=false，AM_NOTIFICATIONLOGSETTINGS_ENABLEFILE=false），本地模式是开启的（AM_SERVICESETTINGS_ENABLELOCALMODE=true），以便 amctl --local 能在服务器上工作。

4. 启动服务

sudo systemctl start antimatter
journalctl -u antimatter -f
sudo -u antimatter amctl --local system status

首次启动时，服务器会创建其数据表，然后监听 8065 端口。打开 http://<server>:8065，或者在配置好反向代理后打开你的域名（参见 域名和 HTTPS），并立即创建第一个账户：该账户将成为系统管理员。如果你希望从命令行创建该账户，请使用 创建第一个管理员 中的 amctl 命令，并用 sudo -u antimatter amctl --local 替代 docker compose exec antimatter amctl --local。

5. 启用 GIF 图像

GIF 图像应用已内置并处于开启状态，且 antimatter.env 已将其指向同一服务器上的 GIF 服务（AM_GIFS_SERVICE_URL=http://127.0.0.1:8080/v2）。不过，它仍然需要该服务的 API 密钥。gifs-server 软件包在安装时生成了一个密钥：

sudo systemctl start gifs-server-stickers    # imports the sticker pack, about a minute and a half
sudo systemctl start gifs-server
sudo grep -v '^#' /etc/gifs-server/api-keys

将该密钥作为 AM_GIFS_API_KEY=<key> 写入 antimatter.env 并重启 Antimatter，或者在 系统控制台 › 插件 › GIF 图像 中将其输入为 API 密钥。如果 GIF 服务运行在另一台服务器上，请将 AM_GIFS_SERVICE_URL 设置为该服务的地址。若要允许用户添加自己的 GIF 图像和贴纸，请参见 GIF 图像。

该服务

• 它以 antimatter 用户身份运行，位于 /opt/antimatter 目录，并读取 /etc/antimatter/antimatter.env 文件。systemd 会在服务器退出时自动重启它，并允许其最多一小时的时间完成启动，因为新版本的数据迁移可能需要较长时间。
• 其日志位于日志系统中：journalctl -u antimatter。
• 该服务已进行安全加固：对于服务器而言，/usr 和 /etc 目录是只读的，/etc/antimatter/config 除外；并且它无法访问 /home、/root 或 /run/user。如果你移动了文件存储位置（FileSettings.Directory），请选择一个位于这些目录之外且由 antimatter 用户拥有的目录。
• 升级时会替换服务文件。若要修改该文件，请使用 sudo systemctl edit antimatter，这样你的修改将保存在一个单独的文件中。

升级软件包

1. 先进行备份（参见 备份与升级）。
2. 下载新的软件包和 SHA256SUMS 文件，并校验它们。
3. 停止服务器，将新软件包覆盖安装在旧软件包之上，然后再次启动服务器：

   sudo systemctl stop antimatter
   sudo apt install ./antimatter_<new version>-1_amd64.deb     # or: sudo dnf install ./antimatter-<new version>-1.x86_64.rpm
   sudo systemctl start antimatter
   journalctl -u antimatter -f

该包不会自动重启服务器。升级完成后，它会输出 Antimatter was upgraded; restart it to run the new version: sudo systemctl restart antimatter：如果你之前没有停止服务器，请立即重启。升级过程会替换 /opt/antimatter 和服务文件，但会保留 antimatter.env、config.json、/var/lib/antimatter 以及日志。服务器启动时，会自动升级数据库并安装捆绑应用的新版本。

如果新版本更改了默认的 antimatter.env，apt 会询问是否保留你的版本：请选择保留。dnf 会保留你的版本，并将新文件保存为 /etc/antimatter/antimatter.env.rpmnew。升级只能向前进行：请勿在较新版本上安装旧版本。

移除软件包

sudo apt remove antimatter 或 sudo dnf remove antimatter 会停止并禁用服务，并移除程序。它会保留数据（/var/lib/antimatter）、配置（/etc/antimatter）、数据库以及 antimatter 用户：如需完全移除 Antimatter，请自行删除这些内容。

软件包和归档中的应用

软件包和归档包含这些应用的最新签名版本，位于 prepackaged_plugins/ 目录中：Agents、Calls、GIFs、Memes、Notes、Polls、Todo、Voice Channels 和 Whiteboard。如果在构建服务器版本时尚未发布的应用会被排除在外：ls /opt/antimatter/prepackaged_plugins 可查看你的版本包含哪些应用。Memes 和 Todo 已包含但尚未启用：捆绑应用 介绍了如何安装和启用它们。

Docker 镜像中的其他应用未包含在软件包或归档中：Kanban、Playbooks、Mail、Calendar、GitHub、GitLab、Jira 和 Metrics。请从各自的发布页面安装：

每个应用发布版本都包含应用包（.tar.gz 文件）、其签名（同名文件加上 .sig 后缀）以及 SHA256SUMS 文件。要安装应用，请先允许上传，然后使用 amctl 添加该应用包：

# 1. In /etc/antimatter/antimatter.env, add this line, then restart Antimatter
AM_PLUGINSETTINGS_ENABLEUPLOADS=true
sudo systemctl restart antimatter
# 2. Download the bundle where the antimatter user can read it, and install it
cd /tmp
curl -fLO https://github.com/AntimatterChat/antimatter-plugin-boards/releases/download/v<version>/<bundle>.tar.gz
sudo -u antimatter amctl --local plugin add <bundle>.tar.gz
sudo -u antimatter amctl --local plugin enable focalboard

要升级通过此方式安装的应用，请使用 plugin add --force 添加新的应用包：软件包升级只会升级捆绑的应用。之后您可以再次移除 AM_PLUGINSETTINGS_ENABLEUPLOADS 行。有关安装应用的其他方法，请参阅安装其他应用。

应用签名

应用包使用 Antimatter 应用签名密钥进行签名：每个 .tar.gz.sig 文件都是其对应应用包的分离式 GPG 签名。服务器在安装捆绑应用之前会检查这些签名。要自行检查应用包：

curl -fsSLO https://raw.githubusercontent.com/AntimatterChat/antimatter-docker/main/keys/antimatter-plugin-signing.asc
gpg --import antimatter-plugin-signing.asc
gpg --verify <bundle>.tar.gz.sig <bundle>.tar.gz

gpg 必须报告来自 Antimatter Plugin Signing 的有效签名，指纹为 06C8 1032 4677 0F08 BBA7 78B9 E69B 05C3 92A6 9A45。它还会警告该密钥未使用受信任的签名进行认证：对于您未自行签名的密钥，这是正常现象。没有 .sig 文件的应用发布版本属于未签名版本，其发布说明中会注明这一点。

从发布存档安装

归档文件 antimatter-<version>-linux-<arch>.tar.gz（例如 antimatter-0.9.0-linux-amd64.tar.gz）适用于没有 .deb 或 .rpm 软件包的发行版，或者您自定义的布局。它包含一个单独的 antimatter/ 目录，其中有 bin/antimatter、bin/amctl、config/config.json、Web 应用（client/ 和 client-fusion/）、捆绑应用（prepackaged_plugins/，参见上文）、电子邮件模板以及翻译文件。

1. 准备 PostgreSQL

Antimatter 仅支持 PostgreSQL 15 或更高版本（旧版本可以启动，但日志中会显示错误）。请创建一个用户和一个数据库：

sudo -u postgres psql <<'EOF'
CREATE USER antimatter WITH PASSWORD 'a-long-password';
CREATE DATABASE antimatter OWNER antimatter;
EOF

2. 解压并配置

sudo tar -xzf antimatter-<version>-linux-amd64.tar.gz -C /opt
sudo useradd --system --user-group antimatter
sudo mkdir -p /opt/antimatter/data
sudo chown -R antimatter:antimatter /opt/antimatter

将服务器指向数据库，可以在 /opt/antimatter/config/config.json（SqlSettings.DataSource）中设置，也可以使用环境变量，并设置站点 URL：

AM_SQLSETTINGS_DRIVERNAME=postgres
AM_SQLSETTINGS_DATASOURCE=postgres://antimatter:a-long-password@localhost:5432/antimatter?sslmode=disable&connect_timeout=10
AM_SERVICESETTINGS_SITEURL=https://chat.example.com

归档文件中的 config.json 是完整的默认配置：您在系统控制台中更改的设置会保存回该文件。如果希望将配置保存在数据库中，请参阅配置。

3. 作为服务运行

systemd 单元文件，位于 /etc/systemd/system/antimatter.service：

[Unit]
Description=Antimatter
After=network.target postgresql.service

[Service]
Type=notify
User=antimatter
Group=antimatter
WorkingDirectory=/opt/antimatter
ExecStart=/opt/antimatter/bin/antimatter
EnvironmentFile=-/etc/antimatter.env
TimeoutStartSec=3600
Restart=always
RestartSec=10
LimitNOFILE=49152

[Install]
WantedBy=multi-user.target

将您的 AM_ 变量放入 /etc/antimatter.env（仅限 root 可读），然后：

sudo systemctl daemon-reload
sudo systemctl enable --now antimatter
journalctl -u antimatter -f

服务器监听 8065 端口。打开 http://<server>:8065，或者在配置反向代理后打开您的域名（请参阅域名和 HTTPS），并创建第一个账户：该账户将成为系统管理员。

bin/amctl 用于从命令行管理正在运行的服务器。在服务器本机，它可以通过本地模式工作而无需登录：设置 AM_SERVICESETTINGS_ENABLELOCALMODE=true，然后运行 sudo -u antimatter /opt/antimatter/bin/amctl --local system status。

对于 GIF，请安装 GIF 服务（见下文），并按照软件包的第 5 步设置 AM_GIFS_SERVICE_URL 和 AM_GIFS_API_KEY。

GIF 服务和推送代理软件包

GIF 服务和推送代理拥有各自的发布版本，规则与服务器相同：一个 .tar.gz 归档文件，适用于 amd64 和 arm64 的 .deb 和 .rpm 软件包，以及一个 SHA256SUMS 文件。带有连字符的版本号为预发布版本。与服务器一样，使用 sha256sum --check --ignore-missing SHA256SUMS 检查下载文件。

GIF 服务 (gifs-server)

发布版本：github.com/AntimatterChat/gifs-server/releases。归档文件名为 gifs-server-<version>-linux-<arch>.tar.gz；软件包名称为 gifs-server。

sudo apt install ./gifs-server_*_amd64.deb      # Debian, Ubuntu
sudo dnf install ./gifs-server-*.x86_64.rpm     # Fedora, RHEL

该软件包安装：

• /usr/bin/gifs-server，以及 gifs-server 服务，该服务以 gifs-server 用户身份运行，并将其目录保存在 /var/lib/gifs-server 中；
• gifs-server-stickers 服务，在启动时会导入或更新 /usr/share/gifs-server/stickers 中的贴纸包，然后停止；
• 其配置文件 /etc/gifs-server/gifs-server.env（包含 AM_GIFS_ 变量，升级时会保留）和 /etc/gifs-server/api-keys，每行一个 API 密钥，首次安装时会生成一个随机密钥。

它监听 127.0.0.1:8080，因此只有同一服务器上的 Antimatter 才能访问它。如果 Antimatter 运行在其他位置，请在 gifs-server.env 中设置 AM_GIFS_LISTEN=:8080，并使用防火墙限制对该端口的访问。该文件列出了其他设置：AM_GIFS_UPLOAD_KEYS（允许添加 GIF 和贴纸，以及删除使用这些密钥添加的内容的密钥）、AM_GIFS_PUBLIC_URL、AM_GIFS_TRUST_PROXY 和 AM_GIFS_LOG_LEVEL。该软件包推荐安装 ffmpeg、gifsicle、librsvg2-bin（.rpm 为 librsvg2-tools）和 DejaVu 字体：服务在导入或接收文件时使用它们来生成 GIF、视频和贴纸格式，没有它们也能运行。

与服务器一样，该服务在安装后处于启用但未启动状态。请按照软件包的第 5 步所示启动它。升级后，请重启它：sudo systemctl restart gifs-server。删除软件包会保留 /var/lib/gifs-server 中的目录。

推送代理

版本发布：github.com/AntimatterChat/push-proxy/releases。归档文件名为 antimatter-push-proxy-<version>-linux-<arch>.tar.gz；软件包名称为 antimatter-push-proxy。该软件包会安装 /usr/bin/antimatter-push-proxy 和 antimatter-push-proxy 服务，该服务以 antimatter-push-proxy 用户身份运行，并读取 /etc/antimatter-push-proxy/antimatter-push-proxy.json（升级时会保留此文件）。Apple 和 Firebase 的凭据应放置在 /etc/antimatter-push-proxy/certs 目录中：推送通知 介绍了这些凭据的来源。

sudo apt install ./antimatter-push-proxy_*_amd64.deb      # or: sudo dnf install ./antimatter-push-proxy-*.x86_64.rpm
sudo install -o root -g antimatter-push-proxy -m 0640 \
    AuthKey_ABCDE12345.p8 firebase-service-account.json /etc/antimatter-push-proxy/certs/
sudoedit /etc/antimatter-push-proxy/antimatter-push-proxy.json
sudo systemctl start antimatter-push-proxy
journalctl -u antimatter-push-proxy -f

在设置文件中，路径是相对于 /etc/antimatter-push-proxy 的：例如 "AppleAuthKeyFile": "./certs/AuthKey_ABCDE12345.p8" 和 "ServiceFileLocation": "./certs/firebase-service-account.json"。然后在 Antimatter 中将 推送通知服务器 设置为 http://<proxy host>:8066。升级后，请重启服务：sudo systemctl restart antimatter-push-proxy。

其他服务器命令

除了运行服务器（antimatter 或 antimatter server）之外，该二进制文件还有几个维护命令。它们读取与服务器相同的配置。