EMQX 集群搭建指南

1. 准备

1.1 硬件要求：

3台服务器，每台服务器至少 4 核 CPU，8GB 内存，100GB 硬盘空间。
3台服务器拥有外网IP，网卡配置为静态 IP，服务器之间互通。

1.2 软件要求：

Docker 24.04版本及以上

2. 集群搭建

2.1 使用 Docker Swarm 创建和管理网络通信

搭建 EMQX 集群（v5.6.1），首先，选择一台服务器作为管理节点初始化 Swarm 集群，其他服务器作为工作节点加入 Swarm 集群，
其次，管理节点创建 Overlay 网络，以确保各个节点容器之间可以相互通信。

初始化 Swarm 集群

运行此命令前，请确保管理节点已安装 Docker 且已启动，替换为管理节点的 IP 地址。

1 2	# 管理节点 docker swarm init --advertise-addr <MANAGER-IP>

执行结果如下，代表集群初始化成功。

Swarm initialized: current node (vnxkqcu6k****4fqwor3o8f16) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-4idcf6cbizcpmyg5nu****e1em0hytl1spldbkgv2gegg5kord-11w37gbq9bdksj7yxjpt8zzqg <MANAGER-IP>:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.

获取加入令牌

1 2	# 管理节点 docker swarm join-token worker

输出结果如下，代表成功获取加入令牌。

1
2
3

To add a worker to this swarm, run the following command:

docker swarm join --token SWMTKN-1-4idcf6cbizcpmyg5nu****e1em0hytl1spldbkgv2gegg5kord-11w37gbq9bdksj7yxjpt8zzqg 172.18.18.110:2377

增加工作节点

运行此命令前，请确保工作节点已安装 Docker 且已启动。在每台工作节点上运行以下命令，将节点加入 Swarm 集群，
替换为上步操作获取到的加入令牌，替换为管理节点的 IP 地址。
1
2
# 工作节点1
docker swarm join --token <SWARM-TOKEN> <MANAGER-IP>:2377
1
2
# 工作节点2
docker swarm join --token <SWARM-TOKEN> <MANAGER-IP>:2377
输出结果如下，代表成功加入 Swarm 集群。
1
This node joined a swarm as a worker.

查看集群状态

经过以上操作，我们已经拥有了一个 Swarm 集群，包含一个管理节点和两个工作节点。

1 2	# 管理节点 docker node ls

输出结果如下，代表集群正常创建。

ID                            HOSTNAME                    STATUS    AVAILABILITY   MANAGER STATUS   ENGINE VERSION
ocbtqtblqg0x6d****4mr15a2     gateway                     Ready     Active                          26.1.3
vnxkqcu6kf2104****r3o8f16 *   schinper                    Ready     Active         Leader           26.1.3
zca0hm9jcgenj5****umd8c2s     training03                  Ready     Active                          26.1.3

创建 Overlay 网络

运行以下命令在管理节点上创建 overlay 网络，替换为自定义网络名称。
1
2
# 管理节点
docker network create --driver overlay --attachable <pub_emqx-net>
输出结果如下，代表成功创建 overlay 网络。
1
w7e475k2m****po21nkc1idan

2.2 启动 EMQX 节点容器

在每台机器上启动 EMQX 容器，并指定容器的主机名。修改节点名称（EMQX_NODE_NAME）和集群节点通信 Cookie（EMQX_NODE_COOKIE）以确保唯一性和安全性。
确保每个节点的端口映射不冲突，并且端口是可用的。

注意事项：

确保每个节点的主机名是唯一的。
确保每个节点的容器在同一个 Docker 网络中。
如果有防火墙，确保节点间的通信端口是开放的。
建议将节点间的时间进行同步，以避免时间差导致的问题。

EMQX 容器1：核心节点

在管理节点命令行工具中输入如下命令，替换为自定义网络名称，下载并运行最新版 EMQX。

# 管理节点
docker run -d --restart=always --name emqx1 \
    --hostname e1.emqx.io \
    -e TZ=Asia/Shanghai \
    -e EMQX_NODE_NAME=emqx@e1.emqx.io \
    -e EMQX_NODE_COOKIE=emqxsecretschinper \
    --network <pub_emqx-net> \
    --network-alias e1.emqx.io \
    -v /opt/emqx/data:/opt/emqx/data \
    -v /opt/emqx/log:/opt/emqx/log \
    -p 1883:1883 \
    -p 8083:8083 \
    -p 4369:4369 \
    -p 8084:8084 \
    -p 8883:8883 \
    -p 18083:18083 \
    -e EMQX_NODE__PROCESS_LIMIT=2097152 \
    -e EMQX_NODE__MAX_PORTS=1048576 \
    -e EMQX_ERLANG__ASYNC_THREADS=1280 \
    -e EMQX_ERLANG__SMP=auto \
    -e EMQX_LISTENER__TCP__EXTERNAL__ACCEPTORS=1024 \
    -e EMQX_LISTENER__TCP__EXTERNAL__MAX_CONNECTIONS=1024000 \
    -e EMQX_LISTENER__WS__EXTERNAL__ACCEPTORS=1024 \
    -e EMQX_LISTENER__WS__EXTERNAL__MAX_CONNECTIONS=1024000 \
    -e EMQX_LISTENER__WS__EXTERNAL__BUFFER=1310720 \
    -e EMQX_LISTENER__WS__EXTERNAL__RECBUF=1310720 \
    -e EMQX_LISTENER__WS__EXTERNAL__SNDBUF=1310720 \
    -e EMQX_MQTT__MAX_PACKET_SIZE=20MB \
    emqx:5.6.1

设置权限

1 2	# 管理节点 chmod -R 777 /opt/emqx/*

EMQX 容器2：核心节点

在工作节点1命令行工具中输入如下命令，替换为自定义网络名称，下载并运行最新版 EMQX。

# 工作节点1
docker run -d --restart=always --name emqx2 \
    --hostname e2.emqx.io \
    -e TZ=Asia/Shanghai \
    -e EMQX_NODE_NAME=emqx@e2.emqx.io \
    -e EMQX_NODE_COOKIE=emqxsecretschinper \
    --network <pub_emqx-net> \
    --network-alias e2.emqx.io \
    -v /opt/emqx/data:/opt/emqx/data \
    -v /opt/emqx/log:/opt/emqx/log \
    -p 1883:1883 \
    -p 8083:8083 \
    -p 4369:4369 \
    -p 8084:8084 \
    -p 8883:8883 \
    -p 18083:18083 \
    -e EMQX_NODE__PROCESS_LIMIT=2097152 \
    -e EMQX_NODE__MAX_PORTS=1048576 \
    -e EMQX_ERLANG__ASYNC_THREADS=1280 \
    -e EMQX_ERLANG__SMP=auto \
    -e EMQX_LISTENER__TCP__EXTERNAL__ACCEPTORS=1024 \
    -e EMQX_LISTENER__TCP__EXTERNAL__MAX_CONNECTIONS=1024000 \
    -e EMQX_LISTENER__WS__EXTERNAL__ACCEPTORS=1024 \
    -e EMQX_LISTENER__WS__EXTERNAL__MAX_CONNECTIONS=1024000 \
    -e EMQX_LISTENER__WS__EXTERNAL__BUFFER=1310720 \
    -e EMQX_LISTENER__WS__EXTERNAL__RECBUF=1310720 \
    -e EMQX_LISTENER__WS__EXTERNAL__SNDBUF=1310720 \
    -e EMQX_MQTT__MAX_PACKET_SIZE=20MB \
    emqx:5.6.1

设置权限

1 2	# 管理节点 chmod -R 777 /opt/emqx/*

EMQX 容器3：核心节点

在工作节点2命令行工具中输入如下命令，替换为自定义网络名称，下载并运行最新版 EMQX。

# 工作节点2
docker run -d --restart=always --name emqx3 \
    --hostname e3.emqx.io \
    -e TZ=Asia/Shanghai \
    -e EMQX_NODE_NAME=emqx@e3.emqx.io \
    -e EMQX_NODE_COOKIE=emqxsecretschinper \
    --network <pub_emqx-net> \
    --network-alias e3.emqx.io \
    -v /opt/emqx/data:/opt/emqx/data \
    -v /opt/emqx/log:/opt/emqx/log \
    -p 1883:1883 \
    -p 8083:8083 \
    -p 4369:4369 \
    -p 8084:8084 \
    -p 8883:8883 \
    -p 18083:18083 \
    -e EMQX_NODE__PROCESS_LIMIT=2097152 \
    -e EMQX_NODE__MAX_PORTS=1048576 \
    -e EMQX_ERLANG__ASYNC_THREADS=1280 \
    -e EMQX_ERLANG__SMP=auto \
    -e EMQX_LISTENER__TCP__EXTERNAL__ACCEPTORS=1024 \
    -e EMQX_LISTENER__TCP__EXTERNAL__MAX_CONNECTIONS=1024000 \
    -e EMQX_LISTENER__WS__EXTERNAL__ACCEPTORS=1024 \
    -e EMQX_LISTENER__WS__EXTERNAL__MAX_CONNECTIONS=1024000 \
    -e EMQX_LISTENER__WS__EXTERNAL__BUFFER=1310720 \
    -e EMQX_LISTENER__WS__EXTERNAL__RECBUF=1310720 \
    -e EMQX_LISTENER__WS__EXTERNAL__SNDBUF=1310720 \
    -e EMQX_MQTT__MAX_PACKET_SIZE=20MB \
    emqx:5.6.1

设置权限

1 2	# 管理节点 chmod -R 777 /opt/emqx/*

将节点加入集群

在管理节点命令行工具中输入如下命令，将工作节点加入 EMQX 集群。

1
2
3

# 管理节点
docker exec -it emqx2 emqx_ctl cluster join emqx@e1.emqx.io
docker exec -it emqx3 emqx_ctl cluster join emqx@e1.emqx.io

3.验证

在管理节点上执行查询命令，验证集群状态。

1	docker exec -it emqx1 /opt/emqx/bin/emqx_ctl cluster status

输出结果如下，代表集群状态正常。

1
2
3

Cluster status: #{running_nodes =>
                      ['emqx@e1.emqx.io','emqx@e2.emqx.io','emqx@e3.emqx.io'],
                  stopped_nodes => []}

Web界面查看：http://
:18083
- 默认账户：admin public,请及时登录并修改密码

Reference

官方文档：https://www.emqx.io/docs/zh/v5.6/
- 性能测试（emqtt_bench）：https://www.emqx.io/docs/zh/v5.6/performance/benchmark-emqtt-bench.html
- 集群构建：https://www.emqx.io/docs/zh/v5.6/deploy/cluster/introduction.html
- 配置文件：https://www.emqx.io/docs/zh/v5.6/configuration/configuration.html
  - EMQX 主配置文件为 emqx.conf，根据安装方式其所在位置有所不同：
  - DEB 或 RPM 包安装：/etc/emqx/emqx.conf
  - Docker 容器： /opt/emqx/etc/emqx.conf
  - 解压缩包安装： ./etc/emqx.conf
- 性能调优：https://www.emqx.io/docs/zh/v5.6/performance/overview.html
- 系统调优：https://www.emqx.io/docs/zh/v5.6/performance/tune.html
- 使用限制：https://www.emqx.io/docs/zh/v5.6/getting-started/restrictions.html
- 常见问题解答：https://www.emqx.io/docs/zh/v5.6/faq/faq.html
- EMQX 配置手册：https://www.emqx.io/docs/zh/v5.6.1/hocon/