配置

Antimatter 存储设置的位置、三种修改方式（系统控制台、环境变量、amctl）以及日志的存放位置。

设置存储在哪里

每个服务器设置都有一个由部分（section）和键（key）组成的名称，例如 ServiceSettings.SiteURL 或 EmailSettings.SMTPServer。它们共同构成一个配置，存储在以下两个位置之一：

• 在数据库中。 站点的 compose 文件将 AM_CONFIG 设置为 PostgreSQL 连接 URL，因此配置是数据库中的一行记录，容器在磁盘上不保留任何数据。共享同一个数据库的多个服务器也会共享它们的配置。
• 在文件中。如果没有设置 AM_CONFIG，服务器会读取其 bin/ 目录旁边的 config/config.json（在 Docker 镜像中为 /antimatter/config/config.json）。antimatter-docker 的发布压缩包和生产环境 compose 文件均采用此方式，.deb 和 .rpm 包也是如此，其文件路径为 /etc/antimatter/config/config.json。请确保此文件仅对服务器用户可读：其中包含密码和密钥。

AM_CONFIG（或 antimatter 命令的 --config 标志）接受文件路径或 postgres:// URL。未指定的设置将采用其默认值。

要将现有配置从文件迁移到数据库，请在服务器上运行此命令，然后将 AM_CONFIG 设置为相同的 URL 并启动服务器：

amctl --local config migrate /opt/antimatter/config/config.json \
    "postgres://antimatter:PASSWORD@localhost:5432/antimatter?sslmode=disable&connect_timeout=10"

环境变量

任何设置都可以通过环境变量提供。环境变量优先于存储的配置，因此它们非常适合用于属于部署环境的配置：数据库、站点 URL、文件存储、端口。

命名规则

先写 AM_，然后是部分，再然后是键，全部使用大写字母并用下划线分隔。部分或键名称内的单词之间不使用分隔符：

• 布尔值设置使用 true 或 false；数字使用普通数字。
• 列表设置的值用空格分隔，例如 AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP"。
• 对象类型的设置接受 JSON。应用程序中唯一的此类变量是 AM_PLUGINSETTINGS_PLUGINS，它会一次性替换所有应用程序的设置：请改为在系统控制台或通过 amctl 设置应用程序设置（见下文）。
• 较旧版本的 Mattermost 使用 MM_ 前缀，例如 MM_SQLSETTINGS_DATASOURCE。它仍然作为遗留别名有效。当两者同时设置时，AM_ 变量优先。

通过变量提供的设置在系统控制台中被锁定，并附有说明：“此设置已通过环境变量设置，无法通过系统控制台更改。”它不会写入存储的配置：移除该变量后，存储的值将重新生效。

使用 Docker Compose

在 antimatter 服务的 environment: 下添加变量，或在 compose.yaml 旁边的 compose.override.yaml 中添加（Compose 会自动读取它，并且它在下载文件更新后仍然保留）：

services:
  antimatter:
    environment:
      AM_EMAILSETTINGS_SMTPSERVER: smtp.example.com
      AM_EMAILSETTINGS_SMTPPORT: "587"
      AM_LOGSETTINGS_CONSOLELEVEL: INFO

使用 docker compose up -d 应用更改，这会重新创建容器。

应用程序读取的变量

有几个变量不属于设置项，也没有对应的系统控制台字段：AM_CONFIG（配置文件的存储位置），以及 AM_AI_ENCRYPTION_KEY 和 AM_AI_ENCRYPTION_PREVIOUS_KEYS，即用于加密模型连接 API 密钥的密钥（参见 AI）。

少数应用程序会读取设置在 antimatter 服务上的专属变量：Calls 应用程序读取 AM_CALLS_*（参见 通话和语音），GIFs 应用程序读取 AM_GIFS_SERVICE_URL、AM_GIFS_API_KEY 和 AM_GIFS_UPLOAD_KEY（参见 内置应用程序）。

系统控制台

系统控制台是 Web 应用的管理区域，供系统管理员使用。要打开它，请点击应用侧栏顶部的头像，然后选择系统控制台，或者访问 https://chat.example.com/admin_console。其侧栏有一个文件设置框，可搜索所有页面。

其部分包括：

• 报告：统计信息和服务器日志。
• 用户管理：用户、群组、社区（列为团队）、频道、权限和委托管理。
• 系统属性：自定义个人资料属性和基于属性的访问控制。
• 环境：Web 服务器、数据库、文件存储、图像代理、SMTP、推送通知、速率限制、日志记录、会话时长、性能监控。
• 站点配置：品牌、用户和团队、通知、帖子、文件共享以及其他服务器范围的行为。
• 身份验证：注册、电子邮件和密码登录、多因素认证（MFA）、AD/LDAP、SAML 2.0、OAuth 2.0、OpenID Connect 以及访客访问。
• AI：模型连接和内置 AI 功能（重写、摘要、自动翻译、文本转语音）。参见 AI。
• 插件：应用管理以及每个已安装应用的设置。
• 集成：Webhook、斜杠命令、机器人账号、GIF、文本转语音、CORS。
• 合规性：数据保留、合规性导出与监控、审计日志、自定义服务条款。
• 实验性功能：可能会发生变化的功能。

在本指南中，设置的书写格式为：其在系统控制台中的路径，然后是标签，最后是配置键。例如 系统控制台 › 站点配置 › 成员和团队 › 启用忽略、屏蔽和消息请求（PrivacySettings.EnableUserBlocking）。

大多数更改在点击 保存 后立即生效。少数设置（如监听地址、部分数据库和缓存设置）需要重启才能生效，页面中会有相应说明。

工作区或社区

每个社区都有一个类型，该类型决定了其部分默认设置：

• 社区，适用于公共或兴趣社区：其频道中的通话功能默认关闭（人们在语音频道中交流），且只有其管理员以及拥有频道管理权限的角色才能归档频道。
• 工作区，适用于公司或组织：其频道中的通话功能默认开启，且频道的管理员（创建者及其指定的管理员）也可以归档该频道。

系统控制台 › 站点配置 › 成员和团队 › 新社区类型（TeamSettings.DefaultCommunityKind，AM_TEAMSETTINGS_DEFAULTCOMMUNITYKIND）决定了此后创建的社区类型：community（默认值）或 workplace。创建社区时选择的布局预设会设定其自身的类型。每个社区的管理员之后可以在团队设置 › 频道 › 社区类型中更改其类型。

amctl 命令行工具

amctl 用于通过命令行管理服务器：用户、社区、频道、应用、配置、任务等。它通过以下两种方式之一与服务器通信。

本地模式（在服务器上）

本地模式允许 amctl 通过 Unix 套接字与服务器通信，而无需登录。Docker 镜像以及 .deb 和 .rpm 软件包默认已启用此模式。对于从归档文件安装的服务器，请通过 ServiceSettings.EnableLocalMode（AM_SERVICESETTINGS_ENABLELOCALMODE=true）开启该模式。套接字默认位于 /var/tmp/antimatter_local.socket（ServiceSettings.LocalModeSocketLocation）。

# with Docker Compose
docker compose exec antimatter amctl --local system status
# with a release archive
sudo -u antimatter /opt/antimatter/bin/amctl --local system status
# with the .deb or .rpm package
sudo -u antimatter amctl --local system status

远程模式（使用账号）

从任意机器，使用系统管理员账号（或个人访问令牌）登录，然后针对该服务器运行命令：

amctl auth login https://chat.example.com --name prod --username admin
amctl system status

配置命令

应用设置位于 PluginSettings.Plugins.<app id> 下，键名使用小写。例如，要从 Docker 主机设置 GIF 应用的服务 URL 和密钥：

docker compose exec -T antimatter amctl --local config patch /dev/stdin <<'EOF'
{"PluginSettings": {"Plugins": {"com.antimatterchat.gifs": {
  "serviceurl": "http://gifs:8080/v2",
  "apikey": "the GIFS_API_KEY of your .env"
}}}}
EOF

其他常用命令：amctl user create、amctl user deactivate、amctl team create、amctl plugin list、amctl plugin enable、amctl system supportpacket 和 amctl logs。运行 amctl help <command> 可查看各命令的选项。

日志

服务器会将日志写入两个位置，每个位置都有独立的日志级别（DEBUG、INFO、WARN 或 ERROR），可在系统控制台 › 环境 › 日志中设置：

日志文件达到 100 MB 时会进行轮转，旧文件会被压缩。

该站点的 compose 文件已关闭文件日志（AM_LOGSETTINGS_ENABLEFILE=false），因此日志仅存在于容器的输出中：

docker compose logs -f antimatter
docker compose logs --since 1h antimatter | grep -i error

控制台日志级别默认为 DEBUG，输出较为详细。在繁忙的服务器上，请设置 AM_LOGSETTINGS_CONSOLELEVEL=INFO。发布归档文件和软件包中的 config.json 已将其设置为 INFO。对于使用 systemd 管理的发布归档文件，控制台输出会写入日志（journalctl -u antimatter），文件日志则位于 /opt/antimatter/logs/antimatter.log。软件包已关闭文件日志记录，因此其日志仅存在于日志系统中。

当文件日志开启时，系统管理员还可以在系统控制台 › 报告 › 服务器日志中查看最新的日志行，或使用 amctl logs 命令查看。