MongooseIM 6.2.x Docker Compose 部署指南

目标：使用官方镜像与 Docker Compose 在一台宿主机上部署双节点 MongooseIM 集群，覆盖 compose 文件编写、集群自动组建、数据持久化、重启恢复、日常运维与故障排查。全部命令与回显为实测记录（实测日期 2026-10-26），演示账号 admin，密码 q1w2e3r4。若需要最新稳定版 6.10.0，官方镜像尚未跟进，请走源码编译路线，见《MongooseIM 6.10.0 安装指南》（https://www.quzuo.net/document/BcBSfRKHmSUd）。

一、版本说明与环境准备

1.1 部署版本与来源

本篇使用 Docker Hub 官方镜像 mongooseim/mongooseim 的 latest 标签。⚠️ 版本须知（2026-10-26 实测）：该标签自报版本为 6.2.1-579-g30df72366——含义是「6.2.1 基线 + 579 个 master 分支提交的快照构建」，镜像构建时间为 2024-09-19，并不等于 GitHub Releases 的最新稳定版 6.10.0。用官方镜像做集群部署与功能验证没有问题，但版本表述以 GitHub Releases 为准；需要 6.10.0 必须源码编译（见安装篇）。

节点实际版本可用以下命令确认（进入任一节点执行）：

mongooseimctl status

实测回显（节选）：

MongooseIM node mongooseim@mongooseim-1:
    Erlang VM status: started (of: starting | started | stopping)
    version: 6.2.1-579-g30df72366 (as mongooseim)
    uptime: 0 days 00:30:48

1.2 前置条件

宿主机已安装 Docker 与 Docker Compose v2（docker compose version 可执行）；
规划端口（本文实测占用，可按需调整）：8128→5222、8129→5280、8130→5269（节点一），8135→5222、8136→5280（节点二）；
⚠️ 端口选择前先 ss -ltn 预检，避免与宿主机已有服务冲突（实测曾因宿主 8132 被其他服务占用导致节点二 Bind failed，改用 8135/8136 后恢复）；
建一个专用目录，本文以 /opt/mongooseim-compose/ 为例，数据目录随 compose 文件落在本目录下。

二、编写 docker-compose.yml

文件 /opt/mongooseim-compose/docker-compose.yml 完整内容（实测可用）：

name: mongooseim-6-2-stack

services:
  mongooseim1:
    image: mongooseim/mongooseim:latest
    container_name: mongooseim-1
    hostname: mongooseim-1
    ports:
      - "8128:5222"
      - "8129:5280"
      - "8130:5269"
    environment:
      - BOOTSTRAP_ENABLED=true
      - CLUSTER_COOKIE=mongooseim
    volumes:
      - ./data/member1:/member
      - ./data/mnesia1:/var/lib/mongooseim
      - ./data/logs1:/var/log/mongooseim
    networks:
      - mim

  mongooseim2:
    image: mongooseim/mongooseim:latest
    container_name: mongooseim-2
    hostname: mongooseim-2
    ports:
      - "8135:5222"
      - "8136:5280"
    environment:
      - BOOTSTRAP_ENABLED=true
      - CLUSTER_COOKIE=mongooseim
    depends_on:
      - mongooseim1
    volumes:
      - ./data/member2:/member
      - ./data/mnesia2:/var/lib/mongooseim
      - ./data/logs2:/var/log/mongooseim
    networks:
      - mim

networks:
  mim:
    driver: bridge

逐段说明：

name: mongooseim-6-2-stack：显式 compose 项目名。⚠️ 实测经验：项目名不要用点号（如 mongooseim-6.2-stack 这类写法应改为连字符），且专用项目名能避免与其他 compose 项目的同名服务互相干扰，docker compose down 只作用于本项目。
hostname: mongooseim-1 / mongooseim-2：这是本方案最关键的一处。官方启动脚本（镜像内 /start.sh）按主机名后缀决定集群角色：后缀为 -1 的节点被认定为集群主节点（primary），启动时执行 Mnesia 引导；其余后缀（-2、-3…）自动向 {服务名前缀}-1 发起加入集群。因此两节点的主机名必须成对命名为 mongooseim-1、mongooseim-2。
BOOTSTRAP_ENABLED=true：主节点首次启动时执行 mongooseimctl bootstrap 初始化内部数据库。
CLUSTER_COOKIE=mongooseim：Erlang 节点互通 cookie，两节点必须一致（默认值即 mongooseim，生产环境建议改掉）。
volumes：三个绑定挂载——/member 用于放置自定义配置（mongooseim.toml、vm.args 等，存在则自动软链到程序目录）、/var/lib/mongooseim 是 Mnesia 数据目录、/var/log/mongooseim 是日志目录。数据落宿主机 ./data/ 下，重启不丢。
networks：自定义 bridge 网络内建 DNS，mongooseim-2 按主机名即可解析到 mongooseim-1。

三、启动与首启日志解读

cd /opt/mongooseim-compose
docker compose up -d
docker compose ps

实测回显：

NAME           STATUS
mongooseim-1   Up 53 minutes
mongooseim-2   Up 51 minutes

首次启动的集群组建过程在日志里完整可见。

节点一（主节点，引导数据库）：

docker compose logs mongooseim1 | grep -iE 'cluster|bootstrap|join'

实测回显：

Execute /usr/lib/mongooseim/scripts/bootstrap01-hello.sh
Hello from /usr/lib/mongooseim/scripts/bootstrap01-hello.sh script.
Execute /usr/lib/mongooseim/scripts/bootstrap20-template.escript
MongooseIM cluster primary node mongooseim@mongooseim-1
Clustered mongooseim@mongooseim-1 with mongooseim@mongooseim-1

节点二（自动加入）：

docker compose logs mongooseim2 | grep -iE 'cluster|join|success'

实测回显：

MongooseIM node mongooseim@mongooseim-2 joining mongooseim@mongooseim-1
You have successfully added the MongooseIM node 'mongooseim@mongooseim-2' to the cluster with node member 'mongooseim@mongooseim-1'.
Clustered mongooseim@mongooseim-2 with mongooseim@mongooseim-1

若节点二日志出现 Failed clustering ... exit 2 并退出，按第七节问题一/问题四排查。

四、集群功能验证

4.1 账号数据跨节点互通

在节点一注册账号：

docker compose exec mongooseim1 mongooseimctl account registerUser --domain localhost --username admin --password q1w2e3r4

实测回显：

{
  "data" : {
    "account" : {
      "registerUser" : {
        "message" : "User admin@localhost successfully registered",
        "jid" : "admin@localhost"
      }
    }
  }
}

到节点二查询同一账号：

docker compose exec mongooseim2 mongooseimctl account checkUser --user admin@localhost
docker compose exec mongooseim2 mongooseimctl account countUsers --domain localhost

实测回显：

{
  "data" : {
    "account" : {
      "checkUser" : {
        "message" : "User admin@localhost exists",
        "exist" : true
      }
    }
  }
}
{
  "data" : {
    "account" : {
      "countUsers" : 1
    }
  }
}

节点二能查到节点一注册的账号且用户计数一致，即集群数据复制生效。

4.2 客户端接入验证（BOSH 握手）

两个节点的 5280 端口分别映射到宿主机 8129/8136，用标准 BOSH 建立流握手：

curl -s -X POST http://127.0.0.1:8129/http-bind -H 'Content-Type: text/xml' \
  --data '<?xml version="1.0"?><body content="text/xml; charset=utf-8" hold="1" rid="1001" to="localhost" wait="60" xml:lang="en" xmlns="http://jabber.org/protocol/httpbind"/>'

实测回显（两节点一致，sid 各自不同）：

<body wait='60' requests='2' hold='1' from='localhost' accept='deflate, gzip' sid='d63796980bd200c5f3b4e5946e1a444b84aa310e' xmpp:restartlogic='true' xmpp:version='1.0' xmlns='http://jabber.org/protocol/httpbind' xmlns:xmpp='urn:xmpp:xbosh' xmlns:stream='http://etherx.jabber.org/streams' inactivity='30' maxpause='120'><stream:features><register xmlns='http://jabber.org/features/iq-register'/><mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>...

返回携带 sid 与 SASL 机制列表的 <body> 即接入面正常。⚠️ 注意：直接 POST 空体或非标准 XML 会得到 500，必须使用上述含 rid/to/wait/hold 属性的标准握手体。

4.3 关于 `cets systemInfo` 的说明

6.x 的集群机制名为 CETS。直接查询：

docker compose exec mongooseim1 mongooseimctl cets systemInfo

实测回显：

{
  "errors" : [ {
    "path" : [ "cets", "systemInfo" ],
    "message" : "Some of the required internal databases are not loaded",
    "extensions" : { "not_loaded_internal_databases" : [ "cets" ], "code" : "deps_not_loaded" }
  } ],
  "data" : { "cets" : { "systemInfo" : null } }
}

实测结论：镜像默认配置下该管理查询视角会报 deps_not_loaded，不代表集群没建成——以 4.1 节的账号数据互通为集群验证的判据。

五、数据持久化与重启恢复

三个绑定挂载保证数据落盘：./data/mnesia1|2（Mnesia 数据）、./data/logs1|2（日志）、./data/member1|2（配置）。实测重启恢复：

cd /opt/mongooseim-compose
docker compose down
docker compose up -d
sleep 30
docker compose exec mongooseim2 mongooseimctl account checkUser --user admin@localhost

实测回显：

{
  "data" : {
    "account" : {
      "checkUser" : {
        "message" : "User admin@localhost exists",
        "exist" : true
      }
    }
  }
}

节点二重启日志：

MongooseIM node mongooseim@mongooseim-2 already clustered
Clustered mongooseim@mongooseim-2 with mongooseim@mongooseim-1

即：down 后数据保留（绑定挂载不受影响）；再次 up 时节点二检测到本地 Mnesia schema 已存在，跳过加入流程直接以集群成员身份启动，账号数据完好。

六、日常运维

docker compose stop            # 停止（保留数据与网络）
docker compose start           # 恢复启动
docker compose restart         # 重启全部节点
docker compose logs -f mongooseim1   # 跟随节点一日志
docker compose down            # 停止并移除（绑定挂载的数据保留）
docker compose down -v         # 连同命名卷一起清（本项目数据在绑定挂载，此命令影响有限）

扩容第三节点的步骤：复制 mongooseim2 的整段 service 配置为 mongooseim3，改 container_name: mongooseim-3、hostname: mongooseim-3，宿主端口换一组未占用值（如 8140/8141），数据目录改 ./data/member3、./data/mnesia3、./data/logs3，然后 docker compose up -d。新节点本地 Mnesia 目录为空，启动脚本会自动向 mongooseim-1 发起加入并同步数据。

七、常见问题（排障实录）

问题一：单节点部署时报 Failed clustering mongooseim@mongooseim with mongooseim@mongooseim-1，进程退出码 2 根因：官方启动脚本默认 JOIN_CLUSTER=true，主机名不以 -1 结尾的节点都会尝试加入 mongooseim-1，单节点环境下无对象可加，超时后退出。解法二选一：把单节点的主机名命名为 mongooseim-1（走主节点分支），或在环境变量中显式加 JOIN_CLUSTER=false。

问题二：up 报 Conflict. The container name "/mongooseim-1" is already in use 宿主机上有同名残留。清理后重建：

docker rm -f mongooseim-1
docker network rm mongooseim-6-2-stack_mim   # 若网络也残留
docker compose up -d

问题三：节点二起不来，日志报端口 Bind failed 宿主端口被其他服务占用（实测 8132 被占）。用 ss -ltn 预检换空闲端口即可。

问题四：服务异常退出，退出码 137 137 = 128 + 9，即进程收到 SIGKILL 被强杀。先区分是否内存不足：

docker inspect mongooseim-1 --format 'ExitCode={{.State.ExitCode}} OOMKilled={{.State.OOMKilled}}'

OOMKilled=true：容器超出内存限制被杀，调大 compose 的 deploy.resources.limits.memory 或宿主机内存；
OOMKilled=false：来自外部的 kill 信号（如宿主机 OOM killer 或人为强杀），用 dmesg | grep -i -E 'oom|killed process' 与 journalctl -k 查内核记录。实测环境曾出现 OOMKilled=false 的 137，即属外部强杀，容器重新 up 后集群自动恢复（见第五节）。

问题五：join_cluster 超时失败 依次检查：两节点 CLUSTER_COOKIE 是否一致；自定义网络是否同一网络（跨网络主机名解析不通）；主节点是否已完全启动（depends_on 只保证启动顺序，不等待就绪，必要时先起节点一，确认 mongooseimctl status 正常后再起其余节点）。

八、卸载与清理

cd /opt/mongooseim-compose
docker compose down      # 移除服务与网络
rm -rf ./data            # 确认不再需要数据后，删除绑定挂载的数据目录

九、参考链接

镜像与版本说明：hub.docker.com/r/mongooseim/mongooseim（latest 自报 6.2.1-579-g30df72366，2024-09-19 构建）
官方文档站：esl.github.io/MongooseDocs/latest/
站内前篇：《MongooseIM 6.10.0 安装指南》（https://www.quzuo.net/document/BcBSfRKHmSUd）、[《MongooseIM 6.10.0 介绍与选型指南》](https://www.quzuo.net/document/L5AMPUnUTdN5)（https://www.quzuo.net/document/L5AMPUnUTdN5）

MongooseIM 6.2.x Docker Compose 部署指南

MongooseIM 6.2.x Docker Compose 部署指南

一、版本说明与环境准备

1.1 部署版本与来源

1.2 前置条件

二、编写 docker-compose.yml

三、启动与首启日志解读

四、集群功能验证

4.1 账号数据跨节点互通

4.2 客户端接入验证（BOSH 握手）

4.3 关于 cets systemInfo 的说明

五、数据持久化与重启恢复

六、日常运维

七、常见问题（排障实录）

八、卸载与清理

九、参考链接

4.3 关于 `cets systemInfo` 的说明