15分钟部署EMQX集群：Docker Compose多节点配置实战

15分钟部署EMQX集群：Docker Compose多节点配置实战

【免费下载链接】emqx The most scalable open-source MQTT broker for IoT, IIoT, and connected vehicles 项目地址: https://gitcode.com/gh_mirrors/em/emqx

为什么需要EMQX集群？

物联网（IoT）应用中，单节点MQTT Broker（消息代理）面临三大痛点：

• 连接瓶颈：单节点仅支持约10万并发连接，无法满足百万级设备接入需求
• 单点故障：单节点宕机导致整个消息系统瘫痪
• 地域限制：远距离设备连接延迟高，影响实时性

EMQX集群通过分布式架构解决上述问题，支持水平扩展至数千万连接。本文将详解如何用Docker Compose在15分钟内搭建高可用EMQX集群。

环境准备

系统要求

项目	最低配置	推荐配置
CPU	2核	4核
内存	4GB	8GB
磁盘	20GB SSD	100GB SSD
Docker	20.10+	最新稳定版
Docker Compose	2.0+	最新稳定版

网络规划

部署步骤

1. 创建Docker Compose文件

新建docker-compose.yml文件，配置双节点集群：

version: '3.8'

services:
  emqx1:
    image: emqx/emqx:latest
    container_name: emqx1
    restart: always
    environment:
      - "EMQX_NODE__NAME=emqx@node1.emqx.io"
      - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
      - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io, emqx@node2.emqx.io]"
      - "EMQX_DASHBOARD__DEFAULT_USERNAME=admin"
      - "EMQX_DASHBOARD__DEFAULT_PASSWORD=public"
    ports:
      - "1883:1883"  # MQTT TCP
      - "8083:8083"  # MQTT WebSocket
      - "18083:18083" # Dashboard
    volumes:
      - emqx1_data:/opt/emqx/data
      - emqx1_log:/opt/emqx/log
    networks:
      emqx_cluster:
        aliases:
          - node1.emqx.io

  emqx2:
    image: emqx/emqx:latest
    container_name: emqx2
    restart: always
    environment:
      - "EMQX_NODE__NAME=emqx@node2.emqx.io"
      - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
      - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io, emqx@node2.emqx.io]"
    ports:
      - "1884:1883"  # MQTT TCP (主机端口映射避免冲突)
      - "8084:8083"  # MQTT WebSocket (主机端口映射避免冲突)
    volumes:
      - emqx2_data:/opt/emqx/data
      - emqx2_log:/opt/emqx/log
    networks:
      emqx_cluster:
        aliases:
          - node2.emqx.io

networks:
  emqx_cluster:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 172.28.0.0/16

volumes:
  emqx1_data:
  emqx1_log:
  emqx2_data:
  emqx2_log:

2. 启动集群

在docker-compose.yml所在目录执行：

# 后台启动集群
docker-compose up -d

# 查看启动状态
docker-compose ps

预期输出：

     Name                   Command               State                                 Ports                              
-------------------------------------------------------------------------------------------------------------------------
emqx1               /usr/bin/docker-entrypoint ...   Up      0.0.0.0:18083->18083/tcp, 0.0.0.0:1883->1883/tcp, 8083/tcp
emqx2               /usr/bin/docker-entrypoint ...   Up      18083/tcp, 0.0.0.0:1884->1883/tcp, 0.0.0.0:8084->8083/tcp

3. 验证集群状态

# 检查节点1集群状态
docker exec -it emqx1 sh -c "emqx ctl cluster status"

# 检查节点2集群状态
docker exec -it emqx2 sh -c "emqx ctl cluster status"

成功集群会显示：

Cluster status: #{running_nodes => ['emqx@node1.emqx.io','emqx@node2.emqx.io'],
                  stopped_nodes => []}

关键配置解析

节点发现机制

EMQX支持多种集群发现策略，生产环境推荐：

策略	适用场景	配置复杂度
static	固定节点数量的小规模集群	低
etcd	动态扩缩容的中大型集群	中
k8s	Kubernetes环境	高

本文使用static策略，通过EMQX_CLUSTER__STATIC__SEEDS指定集群节点列表。

持久化配置

EMQX需要持久化的数据包括：

• 消息数据（/opt/emqx/data）
• 日志文件（/opt/emqx/log）

通过Docker volumes实现数据持久化，注意：必须保持节点名称不变才能恢复数据。

性能优化参数

在environment中添加以下参数优化性能：

- "EMQX_NODE__MAX_PORTS=65535"          # 最大文件描述符
- "EMQX_LISTENERS__TCP__DEFAULT__MAX_CONNECTIONS=102400"  # 最大连接数
- "EMQX_MQTT__MAX_PACKET_SIZE=1MB"      # 最大消息包大小

集群管理

访问Dashboard

通过http://localhost:18083访问EMQX Dashboard，默认账号密码：admin/public。

在Cluster页面可查看集群状态：

集群扩容

1. 编辑docker-compose.yml，添加emqx3服务
2. 更新集群种子列表：[emqx@node1.emqx.io, emqx@node2.emqx.io, emqx@node3.emqx.io]
3. 执行docker-compose up -d

节点监控

# 查看节点资源使用情况
docker stats emqx1 emqx2

# 查看集群 metrics
curl http://localhost:18083/api/v5/metrics -u admin:public

高可用配置

负载均衡

推荐使用Nginx作为MQTT负载均衡器：

stream {
    upstream emqx_cluster {
        server emqx1:1883 weight=1 max_fails=2 fail_timeout=30s;
        server emqx2:1883 weight=1 max_fails=2 fail_timeout=30s;
    }

    server {
        listen 1883;
        proxy_pass emqx_cluster;
        proxy_timeout 300s;
        proxy_buffer_size 4k;
    }
}

健康检查

添加健康检查配置到docker-compose.yml：

healthcheck:
  test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

常见问题解决

集群节点无法通信

解决方案：

1. 检查网络是否互通：docker exec -it emqx1 ping node2.emqx.io
2. 确保节点Cookie一致：所有节点设置相同的EMQX_NODE__COOKIE
3. 验证种子列表格式：正确格式为[emqx@node1,emqx@node2]（无空格）

数据持久化失败

错误表现：容器重启后配置丢失 解决方案：

# 检查卷挂载状态
docker volume inspect emqx1_data

# 确保权限正确
docker exec -it emqx1 chown -R emqx:emqx /opt/emqx/data

生产环境建议

安全加固

1. 修改默认密码：EMQX_DASHBOARD__DEFAULT_PASSWORD=强密码
2. 启用TLS/SSL：配置EMQX_LISTENERS__SSL__DEFAULT__ENABLE=true
3. 限制容器权限：添加cap_drop: [ALL]

备份策略

# 创建数据备份脚本 backup.sh
#!/bin/bash
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
docker exec emqx1 tar -czf /tmp/emqx1_data_$TIMESTAMP.tar.gz /opt/emqx/data
docker cp emqx1:/tmp/emqx1_data_$TIMESTAMP.tar.gz ./backups/

监控集成

通过Prometheus和Grafana监控集群：

1. 启用Prometheus插件：EMQX_PROMETHEUS__ENABLE=true
2. 添加Prometheus Job：

- job_name: 'emqx'
  static_configs:
    - targets: ['emqx1:18083', 'emqx2:18083']

总结

本文详细介绍了Docker Compose部署EMQX集群的全过程，包括：

• 15分钟快速部署双节点EMQX集群
• 关键配置参数解析与优化
• 集群管理与监控方法
• 高可用与安全最佳实践

通过这种方式部署的EMQX集群可支持约20万并发连接，满足中小型IoT项目需求。对于大规模部署，建议使用Kubernetes进行编排管理。

下一步建议：

1. 测试集群故障自动恢复能力
2. 配置TLS加密保障数据安全
3. 集成规则引擎实现消息转发

EMQX集群为IoT项目提供了可靠的消息基础设施，祝你的物联网项目顺利扩展！

【免费下载链接】emqx The most scalable open-source MQTT broker for IoT, IIoT, and connected vehicles 项目地址: https://gitcode.com/gh_mirrors/em/emqx