MongooseIM 6.10.0 安装指南

目标：在一台全新的 Ubuntu 22.04 服务器上从零安装 MongooseIM，完成启动、验证与开机自启。本文提供两条实测路线：方案 A 源码编译安装最新稳定版 6.10.0（获取最新版本的唯一方式，推荐生产采用），方案 B 官方 deb 包安装 6.3.0（包管理路线，适合快速部署）。文中全部命令与回显均为 Ubuntu 22.04 实测记录，演示账号统一为 admin，密码 q1w2e3r4。

一、版本选型与获取渠道对照

安装前先明确「要装哪个版本、从哪里拿」。下表为官方渠道实测结论（查询与实测日期 2026-10-26）：

版本	获取渠道	适用判断
6.10.0（2026-10-15 发布）	GitHub 源码 tag `6.10.0`，`make` 编译	需要 6.10.0 新特性的唯一途径；本文方案 A
6.3.0	官方包仓库 `esl-packages.s3.amazonaws.com` 的 deb/rpm（实测最高版本）	想走包管理、不追新版本；本文方案 B

官方 deb 包的命名规则自解释：mongooseim_6.3.0_1_otp_26.2.1~ubuntu~focal_amd64.deb，即「MongooseIM 6.3.0 + 内嵌 OTP 26.2.1 + 按Ubuntu 20.04 (focal) 构建」。⚠️ 兼容性提醒：包按 focal（OpenSSL 1.1 时代）构建，直接装到 Ubuntu 22.04（OpenSSL 3.0）会启动崩溃，需补装 libssl1.1 兼容库，本文方案 B 有完整排障实录。

两条路线的磁盘准备：源码编译全程约需 2 GB 以上空闲磁盘（实测源码加构建产物共约 311 MB，另加依赖与缓存余量），系统内存建议 ≥2 GB。

二、环境准备（两方案通用）

本文基准环境：Ubuntu 22.04 LTS，root 用户执行。

apt-get update

实测回显（节选）：

Get:1 http://archive.ubuntu.com/ubuntu jammy InRelease [270 kB]
Get:2 http://security.ubuntu.com/ubuntu jammy-security InRelease [129 kB]
...
Reading package lists... Done

端口规划（默认配置将监听，云服务器需在安全组放行对外端口）：

端口	用途	是否对外
5222	客户端 XMPP 连接（c2s）	是
5269	服务器联邦（s2s）	视是否跨域互联
5280	HTTP 服务（BOSH `/http-bind`、WebSocket `/ws-xmpp`）	是
5285	HTTP TLS 服务	是
5541/5561	组件/内部服务	否
5551	本机管理（默认仅 127.0.0.1）	否
4369	Erlang 节点发现（epmd 辅助端口）	仅集群内网

三、方案 A：源码编译安装 6.10.0（推荐）

3.1 安装编译依赖

apt-get install -y build-essential git curl libssl-dev libncurses-dev autoconf xsltproc

实测回显（节选）：

Reading package lists... Done
Building dependency tree... Done
The following additional packages will be installed:
  automake autotools-dev binutils binutils-common ... g++ g++-11 gcc ...
The following NEW packages will be installed:
  build-essential git libncurses-dev libssl-dev xsltproc ...

3.2 安装 Erlang/OTP 28（官方预编译包）

MongooseIM 6.10.0 的官方 CI 使用 OTP 28.4.2 / 29.0.3（见仓库 6.10.0 tag 下 .github/workflows/ci.yml）。这里采用 hex.pm 官方构建的 Ubuntu 22.04 预编译 OTP，免去自行编译 Erlang 的漫长等待：

curl -fL --retry 3 -o /root/otp.tar.gz https://builds.hex.pm/builds/otp/ubuntu-22.04/OTP-28.4.2.tar.gz
mkdir -p /usr/local/lib/erlang
tar -xzf /root/otp.tar.gz -C /usr/local/lib/erlang --strip-components=1
cd /usr/local/lib/erlang && ./Install -minimal /usr/local/lib/erlang

实测回显：

-rw-r--r-- 1 root root 77470858 Oct 26 09:0x otp.tar.gz

⚠️ 排障实录：漏掉 ./Install 导致 escript: No such file or directory。hex.pm 的 OTP 预编译包解压后没有 bin/ 目录（/usr/local/lib/erlang/ 下只有 Install、erts-16.3.1、lib、misc、releases、usr），必须执行 ./Install -minimal /usr/local/lib/erlang 生成 bin/ 下的 erl、escript 等启动包装脚本。实测遗漏该步骤时，后续 make 会在编译中段报错并中断：

./tools/configure
/usr/bin/env: 'escript': No such file or directory
make: *** [Makefile:46: configure.out] Error 127

补执行 ./Install 后重新 make 即可恢复。

把 Erlang 加入 PATH（写入 /root/.bashrc 持久化）：

echo 'export PATH=/usr/local/lib/erlang/bin:$PATH' >> /root/.bashrc
export PATH=/usr/local/lib/erlang/bin:$PATH

验证 OTP 就绪：

erl -noshell -eval 'io:format("OTP: ~s~n",[erlang:system_info(otp_release)]),halt().'

实测回显：

OTP: 28

3.3 获取 6.10.0 源码

cd /root
git clone --depth 1 -b 6.10.0 https://github.com/esl/MongooseIM

实测回显：

Cloning into 'MongooseIM'...
Note: switching to '872cfdb8bc8512aa495a10ff54e52a3c5e09b5db'.

即 6.10.0 tag 对应源码提交 872cfdb8bc8512aa495a10ff54e52a3c5e09b5db，可用于审计比对。

3.4 编译与组装

cd /root/MongooseIM
make

全程约 10～20 分钟（视机器性能，期间会自动下载并编译全部 Erlang 依赖）。实测成功结尾：

===> Compiling mongooseim
===> Assembling release mongooseim-6.10.0...
===> Release successfully assembled: _build/prod/rel/mongooseim

编译产物即一个自包含的发行目录（内嵌所需 Erlang 运行时），无需再安装到系统其他位置。安装目录确认：

bin/mongooseim print_install_dir

实测回显：

/root/MongooseIM/_build/prod/rel/mongooseim

下文以 /root/MongooseIM/_build/prod/rel/mongooseim（记为 $MIM_HOME）为准；如需统一到 /usr/lib/mongooseim（与官方 deb 包一致），mv 整个目录后按新路径执行即可。

3.5 启动与验证

cd /root/MongooseIM/_build/prod/rel/mongooseim
bin/mongooseim start
sleep 8
bin/mongooseimctl status

实测回显：

MongooseIM node mongooseim@localhost:
    operating system pid: 4537
    Erlang VM status: started (of: starting | started | stopping)
    boot script status: started
    version: 6.10.0 (as mongooseim)
    uptime: 0 days 00:00:08
    distribution protocol: inet_tcp
    logs:
        log/mongooseim.json
        log/mongooseim.log

版本徽标确认：

bin/mongooseim version

实测回显（ASCII 徽标，节选首尾）：

      ..';:cc:,
     ,ooooooo''l:'
     ...
         ..'',,;;,,'..
MongooseIM version 6.10.0

注册演示账号并复核：

bin/mongooseimctl account registerUser --domain localhost --username admin --password q1w2e3r4
bin/mongooseimctl account checkUser --user admin@localhost

实测回显：

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

端口监听验证：

ss -ltn | grep -E ':5222|:5269|:5280|:5285'

实测回显：

LISTEN 0      1024         0.0.0.0:5222       0.0.0.0:*
LISTEN 0      1024         0.0.0.0:5285       0.0.0.0:*
LISTEN 0      1024         0.0.0.0:5280       0.0.0.0:*
LISTEN 0      1024         0.0.0.0:5269       0.0.0.0:*

3.6 systemd 托管（源码安装线）

源码安装不自带服务单元，参照官方 deb 包自带的单元格式（见 4.4 节实测）编写 /etc/systemd/system/mongooseim.service，把路径换成源码安装位置即可：

[Unit]
Description=MongooseIM XMPP service
After=network.target

[Service]
Type=forking
RemainAfterExit=yes
Restart=on-failure
RestartSec=5
ExecStart=/root/MongooseIM/_build/prod/rel/mongooseim/bin/mongooseimctl start
ExecStop=/root/MongooseIM/_build/prod/rel/mongooseim/bin/mongooseimctl stop

[Install]
WantedBy=multi-user.target

随后：

systemctl daemon-reload
systemctl enable mongooseim
systemctl start mongooseim
systemctl status mongooseim --no-pager

⚠️ 由于单元是 Type=forking，systemctl status 显示 active 不代表 Erlang 节点真正起来了，必须再用 mongooseimctl status 复核（详见第七节排障实录三）。

四、方案 B：官方 deb 包安装 6.3.0

4.1 下载官方包

从官方包仓库下载 Ubuntu 20.04 (focal) 构建的 6.3.0 包：

cd /root
wget "https://esl-packages.s3.amazonaws.com/ubuntu/pool/contrib/m/mongooseim/mongooseim_6.3.0_1_otp_26.2.1~ubuntu~focal_amd64.deb" -O mongooseim_6.3.0.deb

实测回显：

-rw-r--r-- 1 root root 61068092 Nov  9  2025 mongooseim_6.3.0.deb

（包约 61 MB，内嵌独立的 OTP 26.2.1 运行时，不依赖系统 Erlang。）

4.2 安装

dpkg -i mongooseim_6.3.0.deb

实测回显：

Selecting previously unselected package mongooseim.
(Reading database ... 7011 files and directories currently installed.)
Preparing to unpack mongooseim_6.3.0.deb ...
Unpacking mongooseim (6.3.0-1) ...
Setting up mongooseim (6.3.0-1) ...

4.3 ⚠️ 排障实录：Ubuntu 22.04 上首次启动崩溃（libcrypto.so.1.1 缺失）

直接启动会得到「systemd 显示 active、实际节点没起来」的假象：

systemctl start mongooseim
mongooseimctl status

实测回显：

Failed RPC connection to the node mongooseim@localhost: nodedown

同时 /var/log/mongooseim/ 下出现 erl_crash.dump。查看应用日志定位根因：

grep -i "load" /var/log/mongooseim/erlang.log.1 | head -5

实测关键行：

[error] Unable to load crypto library. Failed with error:
"load_failed, Failed to load NIF library /usr/lib/mongooseim/lib/crypto-5.4/priv/lib/crypto: 'libcrypto.so.1.1: cannot open shared object file: No such file or directory'"
OpenSSL might not be installed on this system.

定位：6.3.0 包内嵌的 OTP 26.2.1 按 focal（OpenSSL 1.1）构建，而 Ubuntu 22.04 只带 OpenSSL 3.0（libssl3），没有 libcrypto.so.1.1，Erlang crypto 模块加载失败后连锁导致 credentials_obfuscation 等核心应用启动失败、整个节点崩溃退出。

解决：补装 Ubuntu 20.04 源的 libssl1.1 兼容库（实测 focal 最新补丁版 1.1.1f-1ubuntu2.24）：

cd /root
wget "http://archive.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1f-1ubuntu2.24_amd64.deb" -O libssl1.1.deb
dpkg -i libssl1.1.deb

实测回显：

-rw-r--r-- 1 root root 1323248 Feb 20  2025 libssl1.1.deb
...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

重启服务：

systemctl restart mongooseim

复核（恢复正常）：

MongooseIM node mongooseim@localhost:
    operating system pid: 2932
    Erlang VM status: started (of: starting | started | stopping)
    boot script status: started
    version: 6.3.0 (as mongooseim)
    uptime: 0 days 00:00:07
    distribution protocol: inet_tcp
    logs:
        /var/log/mongooseim/mongooseim.json
        /var/log/mongooseim/mongooseim.log

4.4 systemd 启动与开机自启

官方包自带服务单元，实测内容：

systemctl cat mongooseim

实测回显：

# /etc/systemd/system/mongooseim.service
[Unit]
Description=MongooseIM XMPP service
After=network.target

[Service]
Type=forking
RemainAfterExit=yes
User=mongooseim
Group=mongooseim
Restart=on-failure
RestartSec=5
ExecStart=/usr/bin/mongooseimctl start
ExecStop=/usr/bin/mongooseimctl stop
#PrivateDevices=true
#ProtectSystem=full

[Install]
WantedBy=multi-user.target

设为开机自启并启动：

systemctl enable mongooseim
systemctl start mongooseim
systemctl status mongooseim --no-pager

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/mongooseim.service → /etc/systemd/system/mongooseim.service.
● mongooseim.service - MongooseIM XMPP service
     Loaded: loaded (/etc/systemd/system/mongooseim.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-26 09:11:40 UTC; 6s ago
    Process: 2555 ExecStart=/usr/bin/mongooseimctl start (code=exited, status=0/SUCCESS)
      Tasks: 1 (limit: 19553)
     Memory: 1.6M

再次强调：Type=forking 下 status 的 active 只是「启动命令成功返回」，以 mongooseimctl status 为准（本例修复 libssl 后实测已正常）。

4.5 目录结构与全局命令

路径	内容
`/usr/lib/mongooseim/`	程序主体（bin、内嵌 erts-14.2.1/OTP 26 运行时、lib、priv、releases）
`/etc/mongooseim/`	配置四件套：`mongooseim.toml`、`app.config`、`vm.args`、`vm.dist.args`
`/var/lib/mongooseim/`	Mnesia 数据目录（运行后出现 `DECISION_TAB.LOG`、`passwd.DCD` 等）
`/var/log/mongooseim/`	日志（`mongooseim.log`、`mongooseim.json`、崩溃时的 `erl_crash.dump`）
`/usr/bin/mongooseimctl`	全局管理命令

注意：deb 包只提供全局 mongooseimctl，没有全局 mongooseim 启动脚本（后者在 /usr/lib/mongooseim/bin/ 下）。查看版本：

/usr/lib/mongooseim/bin/mongooseim version
mongooseimctl status | grep version

实测回显：

MongooseIM version 6.3.0
    version: 6.3.0 (as mongooseim)

注册演示账号（与方案 A 相同的命令）：

mongooseimctl account registerUser --domain localhost --username admin --password q1w2e3r4

实测回显：

"message" : "User admin@localhost successfully registered",
"jid" : "admin@localhost"

五、安装后基线验证清单

无论走哪条路线，以下五项全部通过即认为安装成功：

mongooseimctl status 显示 Erlang VM status: started 且版本号正确；
ss -ltn 能看到 5222/5269/5280/5285 监听；
account registerUser 注册成功、account checkUser 返回 exist: true；
/var/log/mongooseim/mongooseim.log 持续滚动且无 error；
开机自启生效（systemctl is-enabled mongooseim 返回 enabled）。

两方案的默认监听端口实测对照（ss -ltn 全量采集）：

端口	6.10.0（源码默认）	6.3.0（deb 默认）
5222 / 5269 / 5280 / 5285	✔	✔
5541 / 5561	✔	✔
5551（127.0.0.1，管理 GraphQL API）	✔	✔
8888（127.0.0.1，外部组件接入）	✔	—
8088（127.0.0.1，管理 API）/ 8089（客户端 API）	—	✔

可见两版本默认监听差异明显：6.3.0 有 8088/8089 两个 HTTP API 端口，6.10.0 默认已移除、管理面统一走 5551/5541/5561 的 GraphQL handler；8888 为外部组件接入口（两版本均有，段名自 6.2.x 的 listen.service 更名为 listen.component），配置细节见《MongooseIM 6.10.0 配置参数详解》篇。

六、升级与卸载

6.1 deb 包线

升级：官方包仓库发布更高版本后，直接下载新版 deb 再 dpkg -i 即为覆盖升级；升级前建议停止服务并备份 /etc/mongooseim/ 与 /var/lib/mongooseim/。

卸载实测：

dpkg --purge mongooseim
ls /var/lib/mongooseim /var/log/mongooseim

实测回显：

dpkg: warning: while removing mongooseim, directory '/var/lock/mongooseim' not empty so not removed
dpkg: warning: while removing mongooseim, directory '/var/lib/mongooseim' not empty so not removed
dpkg: warning: while removing mongooseim, directory '/usr/lib/mongooseim' not empty so not removed
/var/lib/mongooseim:
DECISION_TAB.LOG
LATEST.LOG
passwd.DCD
passwd.DCL
pid

即 --purge 会移除程序与 /etc/mongooseim/ 配置（实测 /usr/bin/mongooseimctl 与 /etc/mongooseim 均已消失），但数据、日志、运行目录非空时会保留（/var/lib/mongooseim 中的 Mnesia 数据文件原样存在），确认不再回迁后手动删除：

rm -rf /var/lib/mongooseim /var/log/mongooseim /var/lock/mongooseim /usr/lib/mongooseim

6.2 源码线

升级到新版本：停服 → 备份 /etc 对应配置与数据目录 → 拉取新 tag 重新编译（数据目录与安装目录分离，重建 release 不影响 Mnesia 数据）：

cd /root/MongooseIM/_build/prod/rel/mongooseim
bin/mongooseimctl stop
cd /root/MongooseIM
git fetch --tags --depth 1 origin tag <新版本号>
git checkout <新版本号>
make
bin/mongooseim start

卸载：停服后删除安装目录即可（本文为 /root/MongooseIM 整目录，连同构建缓存一并清掉），再移除第三节编写的 systemd 单元并 daemon-reload。

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

问题一：编译中途报 /usr/bin/env: 'escript': No such file or directory（Error 127） 原因与解法见 3.2 节排障实录：hex.pm 预编译 OTP 解压后必须执行 ./Install -minimal /usr/local/lib/erlang 生成 bin/ 包装脚本，然后重新 make。

问题二：deb 安装后节点崩溃，日志报 libcrypto.so.1.1: cannot open shared object file 见 4.3 节排障实录：6.3.0 包按 Ubuntu 20.04/OpenSSL 1.1 构建，在 22.04 需补装 libssl1.1（focal 源的 1.1.1f-1ubuntu2.24 实测可用）后重启服务。若目标是 Ubuntu 20.04 服务器则不存在此问题。

问题三：systemctl status 显示 active (running)，但 mongooseimctl status 报 nodedown 服务单元是 Type=forking：mongooseimctl start 命令成功返回即被 systemd 判定 active，Erlang 节点随后自行崩溃并不会反映到 status 上。判定真相一律以 mongooseimctl status 与 /var/log/mongooseim/erlang.log.*（崩溃时伴随 erl_crash.dump）为准。若进程异常退出码为 137，先用 dmesg | grep -i -E "oom|killed process" 与 journalctl -k 排查是否为系统 OOM killer 所杀，再查人为的 kill 信号。

问题四：mongooseimctl 全局命令存在，但找不到 mongooseim 命令 deb 包不安装全局 mongooseim 启动脚本，它位于 /usr/lib/mongooseim/bin/mongooseim；需要 start/stop 之外的动作（如 version）时使用全路径调用。

八、参考链接

官方文档站（安装章节）：esl.github.io/MongooseDocs/latest/
源码仓库与版本 tag：github.com/esl/MongooseIM（6.10.0 tag，commit 872cfdb8bc8512aa495a10ff54e52a3c5e09b5db）
官方包仓库：esl-packages.s3.amazonaws.com（ubuntu/pool/contrib/m/mongooseim/，最高 6.3.0）
Erlang/OTP 预编译构建：builds.hex.pm/builds/otp/ubuntu-22.04/
本系列前篇：《MongooseIM 6.10.0 介绍与选型指南》（https://www.quzuo.net/document/L5AMPUnUTdN5）