MongooseIM 6.10.0 CLI 命令详解

MongooseIM 6.10.0 CLI 命令详解：mongooseimctl 23 个命令分类全收录，参数 GraphQL 风格规则，账号/会话/群聊/花名册/集群核心命令实测回显，含 deps_not_loaded 模块依赖排障实录。

MongooseIMJabber/XMPP即时通讯2026/10/26

MongooseIM 6.10.0 CLI 命令详解

目标：系统讲解 MongooseIM 的管理命令行工具 mongooseimctl：23 个命令分类全收录、参数风格规则、核心命令实测回显与典型排障实录。全部命令基于 6.10.0 实测（实测日期 2026-10-26），演示账号 admin、alice，密码 q1w2e3r4。文中的「启用 mod_roster / mod_last」等修复实录同时适用于配置管理。

一、总览与参数风格

不带参数执行 mongooseimctl 即得到总览（6.10.0 实测）：

Usage: mongooseimctl [category] command [arguments]

Most MongooseIM commands are grouped into the following categories:
  account           Account management
  blocklist         Blocklist management
  broadcast         Message broadcast management
  cets              CETS internal database management
  domain            Dynamic domain management
  externalServices  External service management
  gdpr              Personal data management according to GDPR
  httpUpload        Generating upload/download URLs for the files
  inbox             Inbox bin flushing
  last              Last activity management
  metric            Browse metrics
  mnesia            Mnesia internal database management
  muc               MUC room management
  muc_light         MUC Light room management
  offline           Deleting old Offline messages
  private           User private storage management
  roster            User roster/contacts management
  server            Server info and management
  session           User session management
  stanza            Sending stanzas and querying MAM
  stat              Server statistics
  token             OAUTH user token management
  vcard             vCard management

To list the commands in a particular category:
  mongooseimctl category

The following basic system management commands do not have a category:
  graphql query  Execute GraphQL query or mutation
  restart        Restart MongooseIM
  status         Get MongooseIM status
  stop           Stop MongooseIM

Commands to start a MongooseIM node:
  start           Start a MongooseIM node as daemon (detached from terminal)
  debug           Attach an interactive Erlang shell to a running MongooseIM node
  live            Start MongooseIM node in live (interactive) mode
  foreground      Start MongooseIM node in foreground (non-interactive) mode
MongooseIM cluster management commands:
  join_cluster other_node_name                Add current node to cluster
  leave_cluster                               Make the current node leave the cluster
  remove_from_cluster other_node_name         Remove dead node from the cluster
Extra Commands:
  bootstrap           Executes MongooseIM init scripts (used for initial configuration)
  print_install_dir   Prints path to MongooseIM release directory
  escript             Runs escript command using embedded Erlang Runtime System

要点：

  • 23 个分类（6.2.x 为 20 个，6.10.0 新增 blocklist、broadcast、externalServices）；
  • 命令发现三步法：mongooseimctl 看分类 → mongooseimctl <分类> 看命令 → mongooseimctl <分类> <命令> --help 看参数；
  • 参数风格是 GraphQL 化的：每个参数写成 --参数名 值，--help 会列出各参数的 GraphQL 类型，带 ! 后缀的为必填。实测例（roster addContact --help）：
Usage: mongooseimctl roster addContact arguments

Each argument has the format: --name value
Available arguments are listed below with the corresponding GraphQL types:
  contact  JID!
  groups   [String!]
  name     String
  user     JID!

Scalar values do not need quoting unless they contain special characters or spaces.
Complex input types are passed as JSON maps or lists, depending on the type.
When a type is followed by '!', the corresponding argument is required.
  • 列表/复杂类型直接传 JSON：如 --groups '["friends"]'（JSON 数组原样直传，不要再加一层引号）；
  • 缺必填参数时命令会拒绝执行并回显完整参数表（见下文 banUser 示例），照抄补参即可，无需查文档。

二、系统与状态命令

命令作用
mongooseimctl status节点状态与版本（最常用的健康检查）
mongooseim version版本徽标（注意：mongooseimctl version 不存在，版本也可从 status 读）
start / stop / restart / foreground / live / debug节点生命周期：后台启停、前台运行、交互 shell 附加
print_install_dir输出发行目录路径
bootstrap执行初始化脚本（compose 部署首次启动即调用它）

status 实测回显（6.10.0）：

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:04:50
    distribution protocol: inet_tcp
    logs:
        log/mongooseim.json
        log/mongooseim.log

server 分类（12 个命令）覆盖服务级信息与操作，实测：

mongooseimctl server getCookie
{
  "data" : { "server" : { "getCookie" : "mongooseim" } }
}
mongooseimctl server getLoglevel
{
  "data" : { "server" : { "getLoglevel" : "WARNING" } }
}

其中 setLoglevel 可在线调日志级别（如排障时临时 setLoglevel --loglevel info，格式以 --help 为准），joinCluster/leaveCluster/removeFromCluster/removeNode 是集群命令在 server 分类下的等价形式（与无分类的 join_cluster 等重复提供）。

三、账号管理（account 分类，10 个命令）

速查：banUser / changeUserPassword / checkPassword / checkPasswordHash / checkUser / countUsers / importUsers / listUsers / registerUser / removeUser。

实测演示（先注册 alice，再走一遍完整生命周期）：

mongooseimctl account registerUser --domain localhost --username alice --password q1w2e3r4
{
  "data" : { "account" : { "registerUser" : {
    "message" : "User alice@localhost successfully registered",
    "jid" : "alice@localhost" } } }
}

mongooseimctl account listUsers --domain localhost
{
  "data" : { "account" : { "listUsers" : [
    "admin@localhost", "alice@localhost", "bob@localhost" ] } }
}
mongooseimctl account countUsers --domain localhost
{ "data" : { "account" : { "countUsers" : 3 } } }
mongooseimctl account checkPassword --user admin@localhost --password q1w2e3r4
{ "data" : { "account" : { "checkPassword" : {
  "message" : "Password 'q1w2e3r4' for user admin@localhost is correct",
  "correct" : true } } } }

封禁与删除：

mongooseimctl account banUser --user bob@localhost
Missing mandatory arguments for command 'banUser': 'reason'
...（回显参数表：reason String!、user JID!）
mongooseimctl account banUser --user bob@localhost --reason "demo ban"
{ "data" : { "account" : { "banUser" : {
  "message" : "User bob@localhost successfully banned with reason: demo ban",
  "jid" : "bob@localhost" } } } }
mongooseimctl account removeUser --user bob@localhost
{ "data" : { "account" : { "removeUser" : {
  "message" : "User bob@localhost successfully unregistered",
  "jid" : "bob@localhost" } } } }
mongooseimctl account countUsers --domain localhost
{ "data" : { "account" : { "countUsers" : 2 } } }

banUser 会踢掉该账号全部会话并重置为随机密码；removeUser 按数据保护要求连 associated personal data 一并清除（GDPR 语义，等价的手工导出见 gdpr 分类）。

四、会话管理（session 分类，10 个命令）

速查：countSessions / countUserResources / countUsersWithStatus / getUserResource / kickUser / kickUserSession / listSessions / listUserSessions / listUsersWithStatus / setPresence。

实测（无在线会话时）：

mongooseimctl session countSessions
{ "data" : { "session" : { "countSessions" : 0 } } }
mongooseimctl session listSessions
{ "data" : { "session" : { "listSessions" : [ ] } } }

在线治理典型用法：listSessions --domain localhost 列出某域全部在线会话，kickUser --user alice@localhost 强制下线（kickUserSession 需带资源全 JID 精确到单会话）。

五、群聊管理（muc 与 muc_light 分类）

⚠️ 前置：muc 分类依赖 mod_muc 模块，6.10.0 默认配置未启用，需先在 mongooseim.toml 追加 [modules.mod_muc]（host/access 三参数，见《MongooseIM 6.10.0 配置参数详解》5.3 节）并重启。

建房与查询实测：

mongooseimctl muc createInstantRoom --room demoroom@muc.localhost --owner admin@localhost --nick admin
{ "data" : { "muc" : { "createInstantRoom" : {
  "usersNumber" : 0, "title" : "demoroom", "private" : false,
  "jid" : "demoroom@muc.localhost" } } } }

mongooseimctl muc listRooms --mucDomain muc.localhost --from admin@localhost
{ "data" : { "muc" : { "listRooms" : {
  "rooms" : [ { "usersNumber" : 0, "title" : "demoroom", "private" : false,
               "jid" : "demoroom@muc.localhost" } ],
  "last" : "demoroom", "index" : 0, "first" : "demoroom", "count" : 1 } } } }

muc 分类共 16 个命令，覆盖房间全生命周期：createInstantRoom / changeRoomConfiguration / getRoomConfig / deleteRoom（配置与删除）、enterRoom / exitRoom / inviteUser / kickUser（成员进出与请踢）、listRoomUsers / listRoomAffiliations / setUserAffiliation / setUserRole（成员与权限）、sendMessageToRoom / sendPrivateMessage / getRoomMessages（消息与存档读取）。

muc_light 分类（13 个命令）是 ESL 自研轻量群聊的同构管理面（createRoom / listUserRooms / setBlockingList 等），依赖 mod_muc_light，方法与语义类似，不重复展开。

六、花名册 roster：依赖缺失排障实录（重点）

roster 分类（10 个命令：addContact / addContacts / deleteContact / deleteContacts / getContact / listContacts / setMutualSubscription / subscribeAllToAll / subscribeToAll / subscription）依赖 mod_roster 模块。6.10.0 默认配置未启用该模块，直接执行会得到：

mongooseimctl roster addContact --user admin@localhost --contact alice@localhost
{
  "errors" : [ {
    "path" : [ "roster", "addContact" ],
    "message" : "Some of the required modules are not loaded",
    "extensions" : { "not_loaded_modules" : [ "mod_roster" ],
                     "code" : "deps_not_loaded" } } ],
  "data" : { "roster" : { "addContact" : null } }
}

（6.2.x 版本上同类操作曾以 resolver_crash 崩溃呈现，6.10.0 已改为明确的 deps_not_loaded 报错，定位更直接。）

修复：mongooseim.toml 追加 [modules.mod_roster] 空段后重启。修复后实测：

mongooseimctl roster addContact --user admin@localhost --contact alice@localhost --groups '["friends"]'
{ "data" : { "roster" : { "addContact" : "Contact added successfully" } } }

mongooseimctl roster listContacts --user admin@localhost
{ "data" : { "roster" : { "listContacts" : [ {
  "subscription" : "NONE", "name" : "", "jid" : "alice@localhost",
  "groups" : [ "friends" ], "ask" : "NONE" } ] } } }

注意 --groups 的值是 JSON 数组原样直传；不加联系人分组时可省略该参数。

七、活跃度与用户资料（last / vcard / private 分类）

last 分类（5 个命令：countActiveUsers / getLast / listOldUsers / removeOldUsers / setLast）依赖 mod_last，默认未启用，直接执行报 deps_not_loaded（not_loaded_modules: ["mod_last"]）。追加 [modules.mod_last] 重启后实测：

mongooseimctl last getLast --user admin@localhost
{
  "errors" : [ {
    "path" : [ "last", "getLast" ],
    "message" : "Given user's last info not found",
    "extensions" : { "user" : "admin@localhost", "code" : "last_not_found" } } ],
  ...
}

从「模块未加载」变为「无记录」即修复成功（该账号无登出记录，属正常业务响应）。listOldUsers/removeOldUsers 是僵尸账号治理利器（按「最近登录天数」筛选/删除）。

vcard 分类（getVcard / setVcard）：查询未设置过资料的账号返回 vcard_not_found（code 同名），属正常。private 分类（getPrivate / setPrivate）管理用户私有存储（XEP-0049）。

八、消息与数据合规（stanza / gdpr 分类）

stanza 分类（6 个命令）支持从服务端代发消息与查询存档：

mongooseimctl stanza sendMessage --from admin@localhost --to alice@localhost --body "hello from admin"
{ "data" : { "stanza" : { "sendMessage" : { "id" : "380f3c65f9a8f97b" } } } }

返回消息 id 即投递成功；getLastMessages 拉取某账号最近 50 条收发记录（依赖 MAM 存档后端），sendStanza 仅全局管理员可用，可投递任意 XML stanza。

gdpr 分类（1 个命令）导出用户全部个人数据（合规审计）：

mongooseimctl gdpr retrievePersonalData --help
  domain          DomainName!
  resultFilepath  String!
  username        UserName!

即 retrievePersonalData --domain localhost --username alice --resultFilepath /tmp/alice.json（三参数均必填，输出为 JSON 文件）。

九、集群与内部数据库（cets / mnesia 分类与集群命令）

集群命令（无分类）：join_cluster <node> 在新节点上执行加入既有集群；leave_cluster 让当前节点退出；remove_from_cluster <node> 从集群中移除已死亡节点（在存活成员上执行）。compose 双节点部署的首启自动组网即由启动脚本调用 join_cluster 完成（见部署篇实测）。

cets 分类（2 个命令）：systemInfo 查询 CETS 集群状态、tableInfo 列出本地节点表。注意 6.2.x 镜像默认配置下 systemInfo 会报 deps_not_loaded（not_loaded_internal_databases: ["cets"]），集群是否正常以数据互通为准（部署篇 4.3 节实录）。

mnesia 分类（9 个命令）：内部数据库备份恢复工具箱——backup <path> 备份、restore <path> 恢复、dump/load 明文转储与加载、dumpTable 单表导出、changeNodename 迁移节点名（换主机名部署时关键）、setMaster 指定主节点、installFallback 安装回退、systemInfo 查看属性。生产迁移/灾备演练建议先在测试环境演练 backup → changeNodename → restore 链路。

十、GraphQL 直通（graphql 命令）

mongooseimctl graphql '<查询>' 等价于把 Admin GraphQL API 的能力带到命令行（两者共用同一 schema，对应本机 5551 端口的 admin endpoint）。用 introspection 一次列出全部查询根字段（实测 19 个）：

mongooseimctl graphql "{ __schema { queryType { fields { name } } } }"
{ "data" : { "__schema" : { "queryType" : { "fields" : [
  { "name" : "account" }, { "name" : "blocklist" }, { "name" : "broadcast" },
  { "name" : "cets" }, { "name" : "checkAuth" }, { "name" : "domain" },
  { "name" : "gdpr" }, { "name" : "last" }, { "name" : "metric" },
  { "name" : "mnesia" }, { "name" : "muc" }, { "name" : "muc_light" },
  { "name" : "private" }, { "name" : "roster" }, { "name" : "server" },
  { "name" : "session" }, { "name" : "stanza" }, { "name" : "stat" },
  { "name" : "vcard" } ] } } }

多根字段组合查询实测（一次拿统计与会话数）：

mongooseimctl graphql "{ session { countSessions } stat { globalStats { registeredUsers onlineUsers } } }"
{ "data" : { "stat" : { "globalStats" : { "registeredUsers" : 3, "onlineUsers" : 0 } },
             "session" : { "countSessions" : 0 } } }

这也解释了命令行参数为何是 GraphQL 风格：每个分类命令都是对同一 GraphQL schema 的封装。需要批量、脚本化运维时直接走 graphql 命令或 Admin API 更灵活。

十一、其余分类速查

分类命令与用途默认可用性
blocklist（新增）阻止名单管理依赖对应模块
broadcast（新增）全域消息广播依赖对应模块
externalServices（新增）外部服务管理依赖对应服务
domain（10 命令）动态域名增删启停（addDomain/removeDomain/enableDomain/disableDomain/domainDetails 等）⚠️ 默认报 deps_not_loaded（not_loaded_services: ["service_domain_db"]），需启用域名数据库服务后使用；静态域名改 toml hosts 即可
httpUploadgetUrl 管理员代用户生成上传/下载链接依赖 mod_http_upload
inboxflushUserBin/flushDomainBin/flushGlobalBin 清理收件箱积压依赖 mod_inbox
metricgetMetrics/getMetricsAsDicts/getClusterMetricsAsDicts 读运行时指标可用
offlinedeleteExpiredMessages/deleteOldMessages 清理过期离线消息依赖 mod_offline
tokenrequestToken/revokeToken 用户 OAuth 令牌签发与吊销requestToken --user <jid>
statglobalStats/domainStats 全局/域统计可用，实测回显见第十节组合查询

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

问题一：命令报 Some of the required modules are not loaded（code: deps_not_loaded） 命令所依赖的模块/服务/内部数据库未在当前配置加载。看 extensions 里的字段名定位：not_loaded_modules（如 mod_roster、mod_last、mod_muc）→ 在 mongooseim.toml 补对应 [modules.<名>] 段；not_loaded_services（如 service_domain_db）→ 补 [services.<名>] 段；not_loaded_internal_databases（如 cets）→ 检查内部数据库与集群配置。改完重启后重试。本篇第六、七、十一节均有该实录。

问题二：Missing mandatory arguments for command ... 缺必填参数。错误回显自带完整参数表，! 后缀即必填，照补即可（实测见第三节 banUser 需补 --reason）。

问题三：列表型参数传了却报错 列表/复杂类型按 JSON 原样直传并整体加引号：--groups '["friends"]'。常见错误是再加一层引号（写成 '\"[\"friends\"]\"' 形式）导致 JSON 解析失败。

问题四：mongooseimctl version 提示 Unknown category 该命令不存在。版本信息用 mongooseim version（发行目录内脚本）或读 mongooseimctl status 的 version: 行。

问题五：命令长时间无响应（nodedown） CLI 经 Erlang RPC 与节点通信，节点未运行时超时报 Failed RPC connection to the node ...: nodedown。先 mongooseimctl status 确认节点状态，启动节点后重试；多节点环境确认节点名（-sname）与当前主机名匹配。

十三、参考链接

  1. 官方文档站（Admin API 与 CLI 章节）：esl.github.io/MongooseDocs/latest/
  2. 源码仓库：github.com/esl/MongooseIM（6.10.0）
  3. 站内前篇：《MongooseIM 6.10.0 安装指南》（https://www.quzuo.net/document/BcBSfRKHmSUd）、[《MongooseIM 6.10.0 配置参数详解》](https://www.quzuo.net/document/TkwHaEP8emR1)（https://www.quzuo.net/document/TkwHaEP8emR1）、[《MongooseIM 6.2.x Docker Compose 部署指南》](https://www.quzuo.net/document/w2XMFdiF3K5m)（https://www.quzuo.net/document/w2XMFdiF3K5m）