EMQX Docker镜像文档

快速参考

• 获取帮助：
  [] 或 []

• 提交问题：
  [***]

• 支持的架构：
  amd64、arm64v8、arm32v7、i386、s390x

• 支持的Docker版本：
  最新版本

什么是EMQX

EMQX 是一款完全开源、高可扩展、高可用的分布式MQTT消息代理，专为IoT、M2M和移动应用设计，可处理数千万并发客户端。

从3.0版本开始，EMQX代理完全支持MQTT V5.0协议规范，并向后兼容MQTT V3.1和V3.1.1，同时支持MQTT-SN、CoAP、LwM2M、WebSocket和STOMP等其他通信协议。3.0版本的EMQX代理集群可支持超过1000万并发MQTT连接。

如何使用此镜像

运行EMQX

在Docker镜像下执行以下命令启动EMQX：

bash
docker run -d --name emqx emqx/emqx:$(tag)

示例：

bash
docker run -d --name emqx -p ***:*** -p 1883:1883 emqx/emqx:latest

EMQX代理在Docker容器中以Linux用户emqx身份运行。

配置

可通过环境变量配置EMQX Docker容器。默认情况下，前缀为EMQX_的环境变量会映射为配置文件中的键值对。可通过覆盖CUTTLEFISH_ENV_OVERRIDE_PREFIX来修改前缀。

环境变量映射规则

示例：

bash
EMQX_LISTENER__SSL__EXTERNAL__ACCEPTORS <--> listener.ssl.external.acceptors
EMQX_MQTT__MAX_PACKET_SIZE              <--> mqtt.max_packet_size

• 移除前缀EMQX_
• 所有大写字母转换为小写
• __（双下划线）替换为.（点）

若设置CUTTLEFISH_ENV_OVERRIDE_PREFIX=DEV_，则映射规则变为：

bash
DEV_LISTENER__SSL__EXTERNAL__ACCEPTORS <--> listener.ssl.external.acceptors
DEV_MQTT__MAX_PACKET_SIZE              <--> mqtt.max_packet_size

不映射的环境变量

bash
EMQX_NAME
EMQX_HOST

这些环境变量不会用于配置文件。

EMQX配置

注意：etc/emqx.conf 中的所有EMQX配置均可通过环境变量设置。以下列表仅为示例，非完整配置。

此列表不完整，可能随etc/emqx.conf和插件配置文件变化，但映射规则一致。

若设置EMQX_NAME和EMQX_HOST且未设置EMQX_NODE_NAME，则EMQX_NODE_NAME=$EMQX_NAME@$EMQX_HOST。

示例：将MQTT TCP端口设置为1883

bash
docker run -d --name emqx -e EMQX_LISTENER__TCP__EXTERNAL=1883 -p ***:*** -p 1883:1883 emqx/emqx:latest

已加载模块配置

默认EMQX_LOADED_MODULES环境变量包含：

• emqx_mod_acl_internal
• emqx_mod_presence

bash
# 默认EMQX_LOADED_MODULES环境变量
EMQX_LOADED_MODULES="emqx_mod_acl_internal,emqx_mod_acl_internal"

示例：设置EMQX_LOADED_MODULES=emqx_mod_delayed,emqx_mod_rewrite以加载这两个模块。支持逗号、空格或其他分隔符：

bash
EMQX_LOADED_MODULES="emqx_mod_delayed,emqx_mod_rewrite"
EMQX_LOADED_MODULES="emqx_mod_delayed emqx_mod_rewrite"
EMQX_LOADED_MODULES="emqx_mod_delayed | emqx_mod_rewrite"

已加载插件配置

默认EMQX_LOADED_PLUGINS环境变量包含：

• emqx_recon
• emqx_retainer
• emqx_rule_engine
• emqx_management
• emqx_dashboard

bash
# 默认EMQX_LOADED_PLUGINS环境变量
EMQX_LOADED_PLUGINS="emqx_recon,emqx_retainer,emqx_management,emqx_dashboard"

示例：设置EMQX_LOADED_PLUGINS=emqx_auth_redis,emqx_auth_mysql以加载这两个插件。支持逗号、空格或其他分隔符：

bash
EMQX_LOADED_PLUGINS="emqx_auth_redis,emqx_auth_mysql"
EMQX_LOADED_PLUGINS="emqx_auth_redis emqx_auth_mysql"
EMQX_LOADED_PLUGINS="emqx_auth_redis | emqx_auth_mysql"

EMQX插件配置

前缀为EMQX_的环境变量同样适用于所有EMQX插件的配置文件（.替换为__）。

示例：

bash
EMQX_AUTH__REDIS__SERVER   <--> auth.redis.server
EMQX_AUTH__REDIS__PASSWORD <--> auth.redis.password

无需关心插件配置文件位置，Docker镜像会自动查找并配置。

示例：使用Redis认证插件

bash
docker run -d --name emqx -p ***:*** -p 1883:1883 -p 4369:4369 \
    -e EMQX_LISTENER__TCP__EXTERNAL=1883 \
    -e EMQX_LOADED_PLUGINS="emqx_auth_redis" \
    -e EMQX_AUTH__REDIS__SERVER="your.redis.server:6379" \
    -e EMQX_AUTH__REDIS__PASSWORD="password_for_redis" \
    -e EMQX_AUTH__REDIS__PASSWORD_HASH=plain \
    emqx/emqx:latest

对于带编号的配置项（如backend.redis.pool1.server），可通过唯一编号配置多个实例：

bash
docker run -d --name emqx -p ***:*** -p 1883:1883 -p 4369:4369 \
    -e EMQX_BACKEND_REDIS_POOL1__SERVER=127.0.0.1:6379 \
    -e EMQX_BACKEND__REDIS__POOL5__SERVER=127.0.0.5:6379 \
    -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__1='{"topic": "persistant/topic1", "action": {"function": "on_message_publish"}, "pool": "pool1"}' \
    -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__2='{"topic": "persistant/topic2", "action": {"function": "on_message_publish"}, "pool": "pool1"}' \
    emqx/emqx:latest

集群

EMQX支持多种集群方式，详见文档。以下通过docker-compose创建静态节点列表集群。

创建docker-compose.yaml：

yaml
version: '3'

services:
  emqx1:
    image: emqx/emqx:latest
    environment:
      - "EMQX_NAME=emqx"
      - "EMQX_HOST=node1.emqx.io"
      - "EMQX_CLUSTER__DISCOVERY=static"
      - "EMQX_CLUSTER__STATIC__SEEDS=***, ***"
    networks:
      emqx-bridge:
        aliases:
          - node1.emqx.io

  emqx2:
    image: emqx/emqx:latest
    environment:
      - "EMQX_NAME=emqx"
      - "EMQX_HOST=node2.emqx.io"
      - "EMQX_CLUSTER__DISCOVERY=static"
      - "EMQX_CLUSTER__STATIC__SEEDS=***, ***"
    networks:
      emqx-bridge:
        aliases:
          - node2.emqx.io

networks:
  emqx-bridge:
    driver: bridge

启动集群：

bash
docker-compose -p my_emqx up -d

查看集群状态：

bash
$ docker exec -it my_emqx_emqx1_1 sh -c "emqx_ctl cluster status"
Cluster status: #{running_nodes => ['***','***'],
                  stopped_nodes => []}

持久化

若需持久化EMQX Docker容器，需保留以下目录：

• /opt/emqx/data
• /opt/emqx/etc
• /opt/emqx/log

由于这些目录中的部分数据存储在/opt/emqx/data/mnesia/${node_name}下，需复用相同节点名称以恢复之前状态。可通过指定EMQX_NAME和EMQX_HOST（如EMQX_HOST=127.0.0.1或网络别名）实现。

docker-compose示例：

yaml
volumes:
  vol-emqx-data:
    name: foo-emqx-data
  vol-emqx-etc:
    name: foo-emqx-etc
  vol-emqx-log:
    name: foo-emqx-log

services:
  emqx:
    image: emqx/emqx:v4.0.0
    restart: always
    environment:
      EMQX_NAME: foo_emqx
      EMQX_HOST: 127.0.0.1
    volumes:
      - vol-emqx-data:/opt/emqx/data
      - vol-emqx-etc:/opt/emqx/etc
      - vol-emqx-log:/opt/emqx/log

内核调优

在Linux主机上，最简单的方式是参考调优指南。若需通过Docker调优内核，需确保Docker版本≥1.12：

bash
docker run -d --name emqx -p ***:*** -p 1883:1883 -p 4369:4369 \
    --sysctl fs.file-max=2097152 \
    --sysctl fs.nr_open=2097152 \
    --sysctl net.core.somaxconn=32768 \
    --sysctl net.ipv4.tcp_max_syn_backlog=*** \
    --sysctl net.core.netdev_max_backlog=*** \
    --sysctl net.ipv4.ip_local_port_range=1000 65535 \
    --sysctl net.core.rmem_default=262144 \
    --sysctl net.core.wmem_default=262144 \
    --sysctl net.core.rmem_max=*** \
    --sysctl net.core.wmem_max=*** \
    --sysctl net.core.optmem_max=*** \
    --sysctl net.ipv4.tcp_rmem=1024 4096 *** \
    --sysctl net.ipv4.tcp_wmem=1024 4096 *** \
    --sysctl net.ipv4.tcp_max_tw_buckets=*** \
    --sysctl net.ipv4.tcp_fin_timeout=15 \
    emqx/emqx:latest

注意：不要以特权模式运行EMQX Docker容器，或挂载系统proc到容器中调优内核，这是不安全的。

致谢

• @je-al
• @RaymondMouthaan
• @zhongjiewu===SHORT_DESC=== EMQX是一款完全开源、高可扩展、高可用的分布式MQTT消息代理，适用于IoT、M2M和移动应用，可处理数千万并发客户端，支持MQTT V5.0及多种通信协议。 ===FULL_DESC===# EMQX Docker镜像文档

快速参考

• 获取帮助：
  [] 或 []

• 提交问题：
  [***]

• 支持的架构：
  amd64、arm64v8、arm32v7、i386、s390x

• 支持的Docker版本：
  最新版本

什么是EMQX

EMQX 是一款完全开源、高可扩展、高可用的分布式MQTT消息代理，专为IoT、M2M和移动应用设计，可处理数千万并发客户端。

从3.0版本开始，EMQX代理完全支持MQTT V5.0协议规范，并向后兼容MQTT V3.1和V3.1.1，同时支持MQTT-SN、CoAP、LwM2M、WebSocket和STOMP等其他通信协议。3.0版本的EMQX代理集群可支持超过1000万并发MQTT连接。

如何使用此镜像

运行EMQX

在Docker镜像下执行以下命令启动EMQX：

bash
docker run -d --name emqx emqx/emqx:$(tag)

示例：

bash
docker run -d --name emqx -p ***:*** -p 1883:1883 emqx/emqx:latest

EMQX代理在Docker容器中以Linux用户emqx身份运行。

配置

可通过环境变量配置EMQX Docker容器。默认情况下，前缀为EMQX_的环境变量会映射为配置文件中的键值对。可通过覆盖CUTTLEFISH_ENV_OVERRIDE_PREFIX来修改前缀。

环境变量映射规则

示例：

bash
EMQX_LISTENER__SSL__EXTERNAL__ACCEPTORS <--> listener.ssl.external.acceptors
EMQX_MQTT__MAX_PACKET_SIZE              <--> mqtt.max_packet_size

• 移除前缀EMQX_
• 所有大写字母转换为小写
• __（双下划线）替换为.（点）

若设置CUTTLEFISH_ENV_OVERRIDE_PREFIX=DEV_，则映射规则变为：

bash
DEV_LISTENER__SSL__EXTERNAL__ACCEPTORS <--> listener.ssl.external.acceptors
DEV_MQTT__MAX_PACKET_SIZE              <--> mqtt.max_packet_size

不映射的环境变量

bash
EMQX_NAME
EMQX_HOST

这些环境变量不会用于配置文件。

EMQX配置

注意：etc/emqx.conf 中的所有EMQX配置均可通过环境变量设置。以下列表仅为示例，非完整配置。