EMQX 多机集群部署完整实践（Docker + 社区版 5.8.8）

一、整体架构说明

1.1 架构目标

• 多台服务器部署 EMQX

• 形成真正的 高可用 MQTT 集群

• 节点之间直接通信，不依赖 Docker 内部网络

• 为后续：

  • TLS
  • 负载均衡
  • 生产 License
  • Kubernetes
    打好基础

---

1.2 示例拓扑

假设你有 3 台机器（物理机 / 云主机均可）：

节点	主机名	内网 IP
node1	emqx-node-1	10.0.1.11
node2	emqx-node-2	10.0.1.12
node3	emqx-node-3	10.0.1.13

⚠️ 强烈建议使用内网 IP，不要使用公网 IP

---

二、多机部署的核心原则（非常重要）

EMQX（Erlang 集群）节点名里的 host，必须满足：

1. 节点之间 TCP 可直连
2. 在所有节点上 解析一致
3. 长期稳定不变

正确示例

emqx1@10.0.1.11
emqx2@10.0.1.12
emqx3@10.0.1.13

错误示例

• ❌ localhost
• ❌ 127.0.0.1
• ❌ Docker 内部 IP
• ❌ 公网 IP
• ❌ 不一致的 hostname

---

三、网络模式选择（多机的关键点）

✅ 推荐：network_mode: host

原因：

• Erlang 分布式对端口要求严格
• 避免 Docker NAT / 端口映射问题
• 性能最好
• 生产环境最常见

多机部署 不推荐使用 bridge 网络

---

四、每台机器的目录结构

每台机器上都创建：

mkdir -p /opt/emqx/{data,log}
chmod -R 777 /opt/emqx
cd /opt/emqx

---

五、docker-compose.yml（每台机器一份）

⚠️ 每台机器只跑一个 EMQX 节点

---

5.1 node1（10.0.1.11）

services:
  emqx:
    image: emqx/emqx:5.8.8
    container_name: emqx
    restart: unless-stopped
    network_mode: host
    environment:
      EMQX_NODE__NAME: emqx1@10.0.1.11
      EMQX_NODE__COOKIE: emqxclustersecret

      EMQX_CLUSTER__DISCOVERY_STRATEGY: static
      EMQX_CLUSTER__STATIC__SEEDS: emqx1@10.0.1.11,emqx2@10.0.1.12,emqx3@10.0.1.13
    volumes:
      - ./data:/opt/emqx/data
      - ./log:/opt/emqx/log

---

5.2 node2（10.0.1.12）

services:
  emqx:
    image: emqx/emqx:5.8.8
    container_name: emqx
    restart: unless-stopped
    network_mode: host
    environment:
      EMQX_NODE__NAME: emqx2@10.0.1.12
      EMQX_NODE__COOKIE: emqxclustersecret

      EMQX_CLUSTER__DISCOVERY_STRATEGY: static
      EMQX_CLUSTER__STATIC__SEEDS: emqx1@10.0.1.11,emqx2@10.0.1.12,emqx3@10.0.1.13
    volumes:
      - ./data:/opt/emqx/data
      - ./log:/opt/emqx/log

---

5.3 node3（10.0.1.13）

services:
  emqx:
    image: emqx/emqx:5.8.8
    container_name: emqx
    restart: unless-stopped
    network_mode: host
    environment:
      EMQX_NODE__NAME: emqx3@10.0.1.13
      EMQX_NODE__COOKIE: emqxclustersecret

      EMQX_CLUSTER__DISCOVERY_STRATEGY: static
      EMQX_CLUSTER__STATIC__SEEDS: emqx1@10.0.1.11,emqx2@10.0.1.12,emqx3@10.0.1.13
    volumes:
      - ./data:/opt/emqx/data
      - ./log:/opt/emqx/log

---

六、端口与防火墙配置（必须放行）

6.1 EMQX 必需端口

端口	用途
1883	MQTT
8883	MQTT over TLS
18083	Dashboard
4369	Erlang EPMD
5370--5400	Erlang 分布式通信

🔥 云环境请同步配置 安全组

---

七、启动顺序（非常重要）

7.1 所有节点统一配置完成后

在 每台机器 执行：

docker compose up -d

启动顺序 不强制要求，static seeds 会自动发现

---

八、集群验证步骤

8.1 查看节点状态（任意一台）

docker exec -it emqx emqx eval 'node().'

示例输出：

emqx1@10.0.1.11

---

8.2 查看集群状态

docker exec -it emqx emqx ctl cluster status

期望输出：

running_nodes =>
  emqx1@10.0.1.11
  emqx2@10.0.1.12
  emqx3@10.0.1.13

---

九、Dashboard 访问方式

任选一台节点：

http://10.0.1.11:18083

默认账号：

admin / public

---

十、常见问题与排查清单

10.1 节点无法加入集群

• 检查 Cookie 是否一致
• 检查 IP 是否可互通
• 检查防火墙 / 安全组
• 是否清过旧 data 目录

10.2 修改 IP / 主机名后无法启动

rm -rf /opt/emqx/data/*

---

十一、从多机到生产的演进建议

当前阶段：多机 + static seeds + 社区版
↓
加 TLS（设备证书）
↓
前置负载均衡（HAProxy / Nginx）
↓
企业版 License
↓
Kubernetes

---

十二、总结

EMQX 多机集群部署的难点并不在于 Docker 或 Compose，而在于 Erlang 分布式系统对节点身份与网络的严格要求。

对于绝大多数团队来说：

• PoC：5.8.x + Docker
• 生产：多机 + host 网络

是一条最稳、最少踩坑的路径。