MongooseIM 6.10.0 配置参数详解

目标：逐段解析 MongooseIM 6.10.0 默认配置文件 mongooseim.toml（共 261 行、22 个配置段），讲清每个参数的含义、默认值与调整方法，并给出两处「修改配置 → 重启 → 验证生效」的完整实测。文中配置差异处同时标注 6.2.x/6.3.0 版本的行为区别，帮助从旧版本迁移的读者对齐。全部内容基于 6.10.0 发行目录实测（实测日期 2026-10-26）。

一、配置体系总览

MongooseIM 的配置由四个文件组成（源码安装在发行目录 etc/ 下，deb 包安装在 /etc/mongooseim/ 下，文件清单一致）：

两个全局机制先建立认知：

• @HOST@ 占位符：配置值中写 @HOST@ 时，加载阶段会为 [general].hosts 里的每一个域名展开一份（例如 host = "muc.@HOST@" 且 hosts = ["localhost"] 时展开为 muc.localhost）。多域名部署时一个占位符即可为全部域生效。
• 配置生效方式 = 重启：mongooseim.toml 无热加载。实测流程为「改文件 → mongooseimctl stop → mongooseim start → 验证」，第八节有完整实录。

二、[general] 全局段

默认内容（照抄自 6.10.0 发行文件）：

[general]
  loglevel = "warning"
  hosts = ["localhost"]
  host_types = []
  default_server_domain = "localhost"
  registration_timeout = "infinity"
  language = "en"

逐参数说明：

三、监听器 [[listen.*]] 全解

6.10.0 默认配置定义了 9 个监听器，实测监听状态（ss -ltn）全部与配置吻合：

关键参数解读：

• HTTP 公共传输参数：每个 [[listen.http]] 都有 transport.num_acceptors = 10（接受连接的进程数）与 transport.max_connections = 1024（最大并发连接），高并发场景按需上调。
• TLS 三件套：tls.certfile/tls.keyfile 指定证书，tls.verify_mode 控制对端校验（"none" 不校验，生产对 s2s 建议改 "peer" 并提供 CA）。默认的 priv/ssl/fake_cert.pem 是自签假证书，只能用于测试。
• 管理 API 端口绑定：ip_address = "127.0.0.1" 限定仅本机访问。5551 的 handler 自带 username/password，生产务必修改（默认 secret）或收紧绑定地址。
• c2s 限流参数：shaper = "normal"（引用第六节的限速器）、max_stanza_size = 65536（单 stanza 最大 64 KB，防大包攻击）；s2s 为 fast 限速器与 128 KB 上限。

⚠️ 版本差异（6.2.x/6.3.0 → 6.10.0）：

1. 旧版有一个 [[listen.service]] 段（8888 端口，外部组件接入），6.10.0 更名为 [[listen.component]]，功能与参数不变（实测 6.10.0 该段默认绑定 127.0.0.1）；
2. 旧版默认还有 8088（mongoose_admin_api，路径 /api）与 8089（mongoose_client_api）两个 HTTP API 监听，6.10.0 默认文件中已移除，管理面统一走 5551/5541/5561 的 GraphQL handler。从 6.3.0 升级后不要找 8088，改用 5551。

四、认证与数据库

4.1 [auth] 认证

[auth]

  # methods
  [auth.internal]

默认使用内置认证：账号密码存于内部数据库（Mnesia），SCRAM 加盐哈希存储。对接 LDAP、JWT、外部 HTTP 认证时在此段追加对应子表（如 [auth.http] 指向外部认证服务），多认证方式可并存。

4.2 数据库后端

[internal_databases.mnesia]

默认所有内部数据（账号、花名册、离线消息等）存 Mnesia——零外部依赖、开箱即用，数据目录由 app.config 的 mnesia.dir 指定（源码安装为发行目录内 Mnesia.节点名/，deb 包为 /var/lib/mongooseim/Mnesia.节点名/）。

文件中注释掉的 [outgoing_pools.rdbms.default] 段是切换外部数据库的模板，逐参数：

启用方式：取消注释并把 rdbms 池配好后，将各功能的后端声明指向 rdbms（如 MAM、vCard、离线消息等模块的 backend 参数）。生产部署建议：账号与 MAM 存档切换到 PostgreSQL/MySQL，Mnesia 仅保留集群元数据。

💡 技术拓展：内部数据库后端选型。Mnesia 是 Erlang 自带的分布式 KV 库：优点是零依赖、与节点同生命周期、天然随节点复制；缺点是无成熟外部工具链、备份恢复能力弱、大数据量内存压力高。RDBMS（PostgreSQL/MySQL）优点是生态成熟、可独立备份监控、支持海量 MAM 存档；缺点是引入外部依赖与一跳网络延迟。Redis 常用于会话与缓存类数据。本系列部署实测采用默认 Mnesia（单机/轻集群够用），生产大规模与强合规场景建议 Mnesia + RDBMS 混合。

五、服务与模块

5.1 [services] 服务

默认启用两个：service_bosh（BOSH 协议服务，配合 5280 监听器）与 service_mongoose_system_metrics（匿名系统指标上报，可按合规要求禁用——删除该段即关闭上报）。

5.2 [modules] 默认启用模块

mod_register.ip_access 的写法是 ACL 策略数组：按顺序匹配，先命中先生效。开放公网注册的典型改法：

[modules.mod_register]
  ip_access = [
    {address = "127.0.0.0/8", policy = "allow"},
    {address = "0.0.0.0/0", policy = "allow"}
  ]

5.3 实战实测：启用群聊 mod_muc

6.10.0 默认不启用 MUC 群聊。在 mongooseim.toml 末尾追加（access 三个规则在默认 [access] 段中已预置好，直接引用即可）：

[modules.mod_muc]
  host = "muc.@HOST@"
  access = "muc"
  access_create = "muc_create"
  access_admin = "muc_admin"

重启后验证（实测回显）：

bin/mongooseimctl muc listRooms --mucDomain muc.localhost --from admin@localhost
{
  "data" : {
    "muc" : {
      "listRooms" : {
        "rooms" : [

        ],
        "last" : null,
        "index" : null,
        "first" : null,
        "count" : 0
      }
    }
  }
}

返回空房间列表（count: 0）即 MUC 服务已在 muc.localhost 域正常挂载，客户端可建房。

其他常用可选模块（此处列默认写法，按需追加）：mod_mam（消息存档 MAM，生产强烈建议，配 mam_* 限速与后端参数）、mod_muc_light（轻量群聊）、mod_inbox（统一收件箱）、mod_offline（离线消息）、mod_http_upload（HTTP 文件上传，需配 host 与外链域名）。

六、流控与访问控制

6.1 [shaper.*] 限速器

限速器定义「每连接的流量速率上限」（单位：字节/秒），被监听器与访问规则按名引用：

⚠️ mam_shaper 默认值 1 是「每 MAM 查询限速」的强约束模板值，启用 MAM 后按业务流量调大，否则客户端拉历史会非常慢。

6.2 [acl] 与 [access] 访问规则

两层结构：[acl] 定义「名单」（默认 local = [{}] 即本域全部用户），[access] 定义「规则组」（每条 {acl = ..., value = ...} 顺序匹配）。默认规则组速查：

自定义示例：把单账号会话数放宽到 20：

  max_user_sessions = [
    {acl = "all", value = 20}
  ]

七、[s2s] 服务器联邦

[s2s]
  default_policy = "deny"

  [s2s.outgoing]
    port = 5269
    tls.mode = "starttls"
    tls.verify_mode = "none"
    ...

• default_policy = "deny"：默认拒绝与其他域互联（保守安全姿势）。需要联邦互通时改为 "allow"，或用 trusted_domains 精确放行伙伴域；
• outgoing.tls.mode = "starttls"：对外连接尝试 STARTTLS 升级；verify_mode = "none" 不校验对端证书，生产联邦建议换真实证书并开启校验，防中间人。

八、实战：修改配置并验证生效（完整实测）

以两处真实改动演示标准流程（环境：6.10.0 源码安装，发行目录记为 $MIM_HOME）。

8.1 修改 component 端口 8888 → 18888

第一步，备份并编辑：

cd $MIM_HOME
cp etc/mongooseim.toml etc/mongooseim.toml.bak
# 将 [[listen.component]] 段的 port = 8888 改为 port = 18888（编辑工具或 sed 均可）
sed -i 's/^  port = 8888/  port = 18888/' etc/mongooseim.toml

第二步，重启生效：

bin/mongooseimctl stop
bin/mongooseim start
sleep 9
bin/mongooseimctl status | grep -E 'VM status|version'

实测回显（stop 阶段逐行）：

ok
Waiting for 4537 for 0 seconds
Waiting for 4537 for 1 seconds
Zs, PID = 4537
4537 is zombie (defunct), stop waiting

status 回显：

    Erlang VM status: started (of: starting | started | stopping)
    version: 6.10.0 (as mongooseim)

第三步，验证新端口监听：

ss -ltn | grep 18888

实测回显：

LISTEN 0      1024       127.0.0.1:18888      0.0.0.0:*

8.2 启用 mod_muc 并验证

编辑追加第五节 5.3 的 MUC 段后按同样流程重启，验证命令与实测回显见 5.3 节（muc listRooms 返回空列表即生效）。

8.3 回滚

任何配置改动异常时，恢复备份并重启即可：

cp etc/mongooseim.toml.bak etc/mongooseim.toml
bin/mongooseimctl stop && bin/mongooseim start

九、常见问题

问题一：改了配置不生效 三种可能：改的不是运行实例加载的那份文件（注意源码安装是发行目录 etc/，deb 包是 /etc/mongooseim/；多实例时确认改对了实例）；只改文件没重启（toml 无热加载）；TOML 语法错误导致启动回退——看 log/erlang.log 或 mongooseim.log 里的解析报错行号。

问题二：TOML 语法错误导致起不来 典型如数组元素 {acl = "all", value = 10} 写成单引号或漏逗号。启动日志会有明确的解析错误位置，先跑一次 mongooseimctl stop; mongooseim foreground 前台启动可直接看到报错栈，修复后再转后台。

问题三：端口被占用 监听器端口冲突时节点启动失败，用 ss -ltnp 查占用者：系统服务抢了规划端口就换端口，或是上一次未退干净的本服务旧进程就先 mongooseimctl stop 清理。

问题四：从 6.3.0 迁移后找不到 8088 管理 API 6.10.0 默认已移除 8088/8089 监听，管理面改用 5551（admin GraphQL，默认凭据 admin/secret，生产必须修改）。若确需旧 API 面可自行在 toml 补回对应 handler 段。

十、参考链接

1. 官方文档站（配置章节）：esl.github.io/MongooseDocs/latest/
2. 6.10.0 默认配置基准：github.com/esl/MongooseIM tag 6.10.0 rel/files/mongooseim.toml（发行目录 etc/mongooseim.toml 与之同源）
3. 站内前篇：《MongooseIM 6.10.0 安装指南》（https://www.quzuo.net/document/BcBSfRKHmSUd）、[《MongooseIM 6.2.x Docker Compose 部署指南》](https://www.quzuo.net/document/w2XMFdiF3K5m)（https://www.quzuo.net/document/w2XMFdiF3K5m）