erlangsolutions/mongooseim

MongooseIM

MongooseIM是Erlang Solutions推出的健壮高效的XMPP服务器，专为大型部署设计。它针对企业用途开发，具备容错能力，可利用多集群机器资源，并能在需要时轻松扩展容量（只需添加服务器/虚拟机）。

• 文档：https://esl.github.io/MongooseDocs/latest/
• Helm：[***]

可用镜像标签

本仓库中的所有镜像均通过CircleCI基础设施构建，对应以下场景：

• master分支 - 标签为latest
• 发布版本 - 标签与GitHub上的版本号一致
• 拉取请求 - 标签格式为PR-{NUMBER}，其中{NUMBER}是https://github.com/esl/MongooseIM GitHub仓库上的PR编号

用于构建镜像的Dockerfile可在此处查看https://github.com/esl/mongooseim-docker/blob/master/Dockerfile.member%E3%80%82

运行MongooseIM

可通过以下命令创建并启动容器：

bash
docker run -dtP -h mongooseim-1 --name mongooseim-1 erlangsolutions/mongooseim

若要运行PR 1006的构建镜像，命令如下：

bash
docker run -dtP -h mongooseim-1 --name mongooseim-1 erlangsolutions/mongooseim:PR-1006

可通过docker logs mongooseim-1检查日志，应显示类似以下内容：

...
MongooseIM cluster primary node mongooseim@mongooseim-1
Clustered mongooseim@mongooseim-1 with mongooseim@mongooseim-1
Root: /usr/lib/mongooseim
Exec: /usr/lib/mongooseim/erts-13.1.5/bin/erlexec -boot /usr/lib/mongooseim/releases/6.1.0/start -embedded -config /usr/lib/mongooseim/etc/app.config -args_file /usr/lib/mongooseim/etc/vm.args -args_file /usr/lib/mongooseim/etc/vm.dist.args -- live --noshell -noinput +Bd
when=2023-10-24T14:28:03.386139+00:00 level=warning what=report_transparency pid=<0.574.0> at=service_mongoose_system_metrics:report_transparency/1:175 text="We are gathering the MongooseIM system's metrics to analyse the trends and needs of our users, improve MongooseIM, and know where to focus our efforts. For more info on how to customise, read, enable, and disable these metrics visit: \
- MongooseIM docs - \
      https://esl.github.io/MongooseDocs/latest/operation-and-maintenance/System-Metrics-Privacy-Policy/ \
- MongooseIM GitHub page - https://github.com/esl/MongooseIM \
The last sent report is also written to a file log/system_metrics_report.json" report_filename=log/system_metrics_report.json

可通过telnet对MongooseIM节点进行健康检查。需提供容器IP（通常为127.0.0.1）和映射到容器5222端口的宿主机端口。可使用以下命令查找端口：

$ docker ps -f "name=mongooseim-1" --format "{{.Names}}: {{.Ports}}"
mongooseim-1: 0.0.0.0:32772->4369/tcp, 0.0.0.0:32771->5222/tcp, 0.0.0.0:32770->5269/tcp, 0.0.0.0:32769->5280/tcp, 0.0.0.0:32768->9100/tcp

上述示例中，容器内5222端口映射到宿主机32771端口，可用于检查服务器是否监听该端口：

$ telnet 127.0.0.1 32771
Connected to localhost.
Escape character is '^]'.

成功！MongooseIM已开始接受XMPP连接。

暴露端口

此镜像还暴露了其他可能有用的端口，详情请参考https://github.com/esl/mongooseim-docker/blob/master/Dockerfile.member%E3%80%82

添加用户

bash
docker exec mongooseim-1 /usr/lib/mongooseim/bin/mongooseimctl account registerUser --username $USER --domain $XMPP_HOST --password $PASSWORD

其中：

• $USER - 用户名
• $XMPP_HOST - MongooseIM服务的XMPP主机，默认是localhost
• $PASSWORD - 认证密码

示例

bash
$ docker exec mongooseim-1 /usr/lib/mongooseim/bin/mongooseimctl account registerUser --username alice --domain localhost --password secret123
{
  "data" : {
    "account" : {
      "registerUser" : {
        "message" : "User alice@localhost successfully registered",
        "jid" : "alice@localhost"
      }
    }
  }
}

自定义配置

可通过Docker卷挂载自定义配置文件覆盖默认配置。假设本地机器有目录mongooseim-1，包含以下内容：

bash
$ tree mongooseim-1
mongooseim-1
└── mongooseim.toml
└── app.config
└── vm.args

可通过以下命令运行容器：

bash
docker run -dt -h mongooseim-1 --name mongooseim-1 -p 5222:5222 -v `pwd`/mongooseim-1:/member erlangsolutions/mongooseim

服务器将使用自定义配置文件。vm.dist.args文件也可通过相同方式覆盖。

集群设置

集群设置有两种方法：默认自动集群和手动集群（可更精确控制集群形成）。

默认集群

要使用默认集群行为，容器的名称（--name选项）和主机名（-h选项）需带有-n后缀，其中n是从1开始的连续整数（可通过MASTER_ORDINAL环境变量配置），例如mongooseim-1、mongooseim-2等。确保先启动带有-${MASTER_ORDINAL}后缀的节点（如-h mongooseim-1和--name mongooseim-1），其他节点将连接到该节点加入集群。

以下几点很重要：

1. 若在docker/docker-compose中使用，以下参数必须设置为相同值。第二个及后续容器也有相同要求。

   • -h选项为容器设置HOSTNAME环境变量，进而设置机器的长主机名。https://github.com/esl/mongooseim-docker/blob/bcaa3c17/member/start.sh#L19%E8%84%9A%E6%9C%AC%E5%9C%A8%60NODE_TYPE=name%60%E6%97%B6%E4%BD%BF%E7%94%A8%E5%AE%83%E7%94%9F%E6%88%90Erlang%E8%8A%82%E7%82%B9%E5%90%8D%E3%80%82%E8%8B%A5%60NODE_TYPE=sname%60%EF%BC%88%E9%BB%98%E8%AE%A4%EF%BC%89%EF%BC%8C%E5%88%99%E4%BD%BF%E7%94%A8%E7%9F%AD%E4%B8%BB%E6%9C%BA%E5%90%8D%E3%80%82%E8%8B%A5%60-h%60%E6%8F%90%E4%BE%9B%E7%9A%84%E5%80%BC%E5%B7%B2%E6%98%AF%E7%9F%AD%E4%B8%BB%E6%9C%BA%E5%90%8D%EF%BC%8C%E5%88%99%E7%9B%B4%E6%8E%A5%E4%BD%BF%E7%94%A8%EF%BC%9B%E5%90%A6%E5%88%99%E6%88%AA%E6%96%AD%EF%BC%88%E4%B8%8D%E5%90%AB'.'%E7%9A%84%E6%9C%80%E9%95%BF%E9%83%A8%E5%88%86%EF%BC%89%E3%80%82
   • --name用于提供容器间的自动DNS解析。详见Docker网络文档。

2. 主机名格式：

   • 第一个容器的主机名必须为${NODE_NAME}-${MASTER_ORDINAL}格式。这使https://github.com/esl/mongooseim-docker/blob/bcaa3c17/member/start.sh#L75%E8%83%BD%E8%AF%86%E5%88%AB%E9%9B%86%E7%BE%A4%E7%9A%84%E4%B8%BB%E8%8A%82%E7%82%B9%E3%80%82
   • 后续容器必须遵循${NODE_NAME}-N主机名格式，其中N > ${MASTER_ORDINAL}。

示例

创建用户定义的桥接网络并启动两个节点：

bash
docker network create mim
docker run -dt --net mim -h mongooseim-1 --name mongooseim-1 erlangsolutions/mongooseim
docker run -dt --net mim -h mongooseim-2 --name mongooseim-2 erlangsolutions/mongooseim

节点应已形成集群。检查：

bash
$ docker exec mongooseim-1 /usr/lib/mongooseim/bin/mongooseimctl mnesia systemInfo --keys '["running_db_nodes"]'
{
  "data" : {
    "mnesia" : {
      "systemInfo" : [
        {
          "result" : [
            "mongooseim@mongooseim-2",
            "mongooseim@mongooseim-1"
          ],
          "key" : "running_db_nodes"
        }
      ]
    }
  }
}
$ docker exec mongooseim-2 /usr/lib/mongooseim/bin/mongooseimctl mnesia systemInfo --keys '["running_db_nodes"]'
{
  "data" : {
    "mnesia" : {
      "systemInfo" : [
        {
          "result" : [
            "mongooseim@mongooseim-1",
            "mongooseim@mongooseim-2"
          ],
          "key" : "running_db_nodes"
        }
      ]
    }
  }
}

Kubernetes注意事项

默认集群可作为Kubernetes StatefulSet部署的一部分工作，但需两项更改：

• MASTER_ORDINAL需设为0，因为StatefulSet实例从0开始计数
• NODE_TYPE需设为name（使用长名称），因为Kubernetes使用内部DNS的FQDN解析pod IP。注意，要使pod域名正常工作，需运行与StatefulSet匹配的无头服务（详见[***]

手动集群

手动集群方法需通过CLUSTER_WITH环境变量显式指定要加入的集群节点名称。也可通过设置JOIN_CLUSTER=false（默认true）在容器启动时完全禁用集群。

示例

手动指定要加入的集群节点名称：

bash
docker run -dt --net mim -h first-node --name first-node -e JOIN_CLUSTER=false erlangsolutions/mongooseim
docker run -dt --net mim -h second-node --name second-node -e CLUSTER_WITH=mongooseim@first-node erlangsolutions/mongooseim

第一条命令启动节点并禁止加入任何集群（因无其他节点）。第二条命令告知第二个节点加入第一个节点的集群。

检查节点是否形成集群：

bash
$ docker exec first-node /usr/lib/mongooseim/bin/mongooseimctl mnesia systemInfo --keys '["running_db_nodes"]'
{
  "data" : {
    "mnesia" : {
      "systemInfo" : [
        {
          "result" : [
            "mongooseim@second-node",
            "mongooseim@first-node"
          ],
          "key" : "running_db_nodes"
        }
      ]
    }
  }
}
$ docker exec second-node /usr/lib/mongooseim/bin/mongooseimctl mnesia systemInfo --keys '["running_db_nodes"]'
{
  "data" : {
    "mnesia" : {
      "systemInfo" : [
        {
          "result" : [
            "mongooseim@first-node",
            "mongooseim@second-node"
          ],
          "key" : "running_db_nodes"
        }
      ]
    }
  }
}

数据库设置

MongooseIM可与多种数据库和外部服务集成。例如，运行https://hub.docker.com/_/postgres/%E5%AE%B9%E5%99%A8%EF%BC%9A

bash
docker run -d --name mongooseim-postgres --net mim \
       -e POSTGRES_PASSWORD=mongooseim -e POSTGRES_USER=mongooseim \
       -v ${PATH_TO_MONGOOSEIM_PGSQL_FILE}:/docker-entrypoint-initdb.d/pgsql.sql:ro \
       -p 5432:5432 postgres

${PATH_TO_MONGOOSEIM_PGSQL_FILE}是MongooseIM仓库中priv/pgsql.sql文件的绝对路径。

别忘了在mongooseim.toml中配置https://esl.github.io/MongooseDocs/latest/configuration/outgoing-connections/%E4%BB%A5%E8%BF%9E%E6%8E%A5%E8%AE%BE%E7%BD%AE%E7%9A%84%E6%9C%8D%E5%8A%A1%EF%BC%81

持久化Mnesia文件

Mnesia文件位于容器内/var/lib/mongooseim目录。某些情况下，更新镜像时需保留这些文件，此时应将/var/lib/mongooseim目录挂载到宿主机目录。

使用CETS

可使用CETS替代Mnesia - 详见https://esl.github.io/MongooseDocs/latest/tutorials/CETS-configure/%E3%80%82%E9%9C%80%E5%90%AF%E5%8A%A8%E6%89%80%E6%9C%89%E8%8A%82%E7%82%B9%E6%97%B6%E8%AE%BE%E7%BD%AE%60JOIN_CLUSTER=false%60%EF%BC%8C%E5%9B%A0%E4%B8%BACETS%E4%BD%BF%E7%94%A8%E5%85%B3%E7%B3%BB%E6%95%B0%E6%8D%AE%E5%BA%93%E5%8F%91%E7%8E%B0%E9%9B%86%E7%BE%A4%E8%8A%82%E7%82%B9%E3%80%82

bash
docker run -dt --net mim -h mongooseim-1 --name mongooseim-1 -v `pwd`/mongooseim-1:/member -e JOIN_CLUSTER=false erlangsolutions/mongooseim
docker run -dt --net mim -h mongooseim-2 --name mongooseim-2 -v `pwd`/mongooseim-2:/member -e JOIN_CLUSTER=false erlangsolutions/mongooseim

检查两个节点的CETS状态以确认集群成功：

bash
$ docker exec mongooseim-1 /usr/lib/mongooseim/bin/mongooseimctl cets systemInfo
{
  "data" : {
    "cets" : {
      "systemInfo" : {
        (...)
        "availableNodes" : [
          "mongooseim@mongooseim-1",
          "mongooseim@mongooseim-2"
        ]
      }
    }
  }
}

$ docker exec mongooseim-2 /usr/lib/mongooseim/bin/mongooseimctl cets systemInfo
{
  "data" : {
    "cets" : {
      "systemInfo" : {
        (...)
        "availableNodes" : [
          "mongooseim@mongooseim-2",
          "mongooseim@mongooseim-1"
        ]
      }
    }
  }
}