EMQX Docker 容器化部署完全指南

EMQX 简介

EMQX 是全球最具扩展性的开源 MQTT 消息代理，单集群可连接超过1亿台物联网设备，同时保持每秒百万级消息吞吐量和亚毫秒级延迟。它完整支持 MQTT 5.0 和 3.x 标准协议，并提供了 TLS/SSL 加密通信和多种认证机制。

Docker 快速入门

基础运行方式

使用以下命令快速启动一个 EMQX 容器：

docker run -d --name emqx -p 18083:18083 -p 1883:1883 emqx/emqx:latest

这条命令会：

1. 从 Docker 官方镜像仓库拉取最新版 EMQX 镜像
2. 映射 18083 端口（Dashboard）和 1883 端口（MQTT）
3. 以后台模式运行容器

配置参数说明

EMQX 支持通过环境变量配置所有参数，转换规则如下：

1. 前缀 EMQX_ 会被移除
2. 所有大写字母转为小写
3. 双下划线 __ 替换为点 .

例如：

• EMQX_DASHBOARD__DEFAULT_PASSWORD → dashboard.default_password
• EMQX_LISTENERS__SSL__default__ENABLE → listeners.ssl.default.enable

节点名称配置

EMQX_NODE__NAME 环境变量用于指定节点名称，默认格式为 <容器名>@<容器IP>。建议在生产环境中设置固定节点名称以便于管理。

高级部署方案

集群部署指南

EMQX 支持多种集群发现方式，以下是使用静态节点列表的 Docker Compose 示例：

version: '3'

services:
  emqx1:
    image: emqx/emqx:latest
    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]"
    networks:
      emqx-bridge:
        aliases:
          - node1.emqx.io

  emqx2:
    image: emqx/emqx:latest
    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]"
    networks:
      emqx-bridge:
        aliases:
          - node2.emqx.io

networks:
  emqx-bridge:
    driver: bridge

启动集群后，可使用以下命令验证集群状态：

docker exec -it my_emqx_emqx1_1 sh -c "emqx ctl cluster status"

数据持久化配置

为确保数据安全，需要持久化以下目录：

• /opt/emqx/data - 存储运行时数据
• /opt/emqx/log - 存储日志文件

Docker Compose 持久化配置示例：

volumes:
  emqx-data:
  emqx-log:

services:
  emqx:
    image: emqx/emqx:latest
    volumes:
      - emqx-data:/opt/emqx/data
      - emqx-log:/opt/emqx/log
    environment:
      EMQX_NODE__NAME: emqx@127.0.0.1

性能调优建议

内核参数优化

对于 Linux 主机，建议调整以下内核参数以获得最佳性能：

docker run -d --name emqx \
    --sysctl fs.file-max=2097152 \
    --sysctl fs.nr_open=2097152 \
    --sysctl net.core.somaxconn=32768 \
    --sysctl net.ipv4.tcp_max_syn_backlog=16384 \
    --sysctl net.core.netdev_max_backlog=16384 \
    --sysctl net.ipv4.ip_local_port_range="1000 65535" \
    --sysctl net.core.rmem_default=262144 \
    --sysctl net.core.wmem_default=262144 \
    emqx/emqx:latest

重要安全提示：不要使用特权模式运行容器或挂载系统 proc 目录来调整内核参数，这会带来安全隐患。

最佳实践

1. 生产环境建议使用固定版本标签而非 latest
2. 集群部署时确保网络延迟低于 5ms
3. 定期备份持久化数据卷
4. 监控容器资源使用情况，特别是内存和文件描述符

通过本文介绍的 Docker 部署方式，您可以快速搭建高可用的 EMQX 消息服务，满足各种物联网场景的需求。