dwdraju/emqx

EMQ Docker镜像文档

镜像概述

EMQ（Erlang MQTT Broker）是一个分布式、大规模可扩展、高度可扩展的MQTT消息代理，采用Erlang/OTP编写。本Docker镜像提供了EMQ的便捷部署方式，当前镜像大小为37.1 MB。

核心功能与特性

• 分布式架构：支持集群部署，可实现大规模扩展
• 多协议支持：原生支持MQTT、WebSocket等多种协议
• 灵活配置：通过环境变量轻松配置所有参数
• 插件系统：支持动态加载插件，如认证、存储等扩展功能
• 安全可靠：遵循Erlang/OTP的高可用性设计

使用场景

• IoT设备消息通信
• 实时数据传输系统
• 分布式消息传递架构
• MQTT协议测试与开发环境

使用方法

构建镜像

可通过源码构建Docker镜像：

bash
git clone -b master https://github.com/emqtt/emq_docker.git
cd emq_docker
docker build -t emq:latest .

运行容器

基本运行命令：

bash
docker run --rm -ti --name emq -p 18083:18083 -p 1883:1883 emq:latest

注意：EMQ在容器内以emqtt用户身份运行

配置说明

环境变量映射规则

• 以EMQ_为前缀的环境变量映射到配置文件，配置项中的.替换为__
  • 示例：EMQ_LISTENER__SSL__EXTERNAL__ACCEPTORS 对应 listener.ssl.external.acceptors
• 以PLATFORM_为前缀的环境变量映射到配置文件中的模板字符串
  • 示例：PLATFORM_ETC_DIR 对应 {{ platform_etc_dir }}
• 特殊环境变量（不映射到配置文件）：EMQ_NAME、EMQ_HOST

主要配置选项

注：完整配置可参考https://github.com/emqtt/emqttd/blob/master/etc/emq.conf%EF%BC%8C%E6%98%A0%E5%B0%84%E8%A7%84%E5%88%99%E7%9B%B8%E5%90%8C

配置示例

修改MQTT TCP端口为1883：

bash
docker run --rm -ti --name emq -e EMQ_LISTENER__TCP__EXTERNAL=1883 -p 18083:18083 -p 1883:1883 emq:latest

插件配置

已加载插件配置

默认插件包括：emq_recon、emq_modules、emq_retainer、emq_dashboard

加载额外插件

通过EMQ_LOADED_PLUGINS环境变量指定要加载的插件，支持任意分隔符：

bash
# 示例：加载emq_auth_redis插件
docker run --rm -ti --name emq -p 18083:18083 -p 1883:1883 \
    -e EMQ_LOADED_PLUGINS="emq_auth_redis,emq_recon,emq_modules,emq_retainer,emq_dashboard" \
    emq:latest

插件参数配置

插件配置同样遵循EMQ_前缀+__替换.的规则：

bash
# 示例：配置Redis认证插件
docker run --rm -ti --name emq -p 18083:18083 -p 1883:1883 -p 4369:4369 \
    -e EMQ_LOADED_PLUGINS="emq_auth_redis,emq_recon,emq_modules,emq_retainer,emq_dashboard" \
    -e EMQ_AUTH__REDIS__SERVER="your.redis.server:6379" \
    -e EMQ_AUTH__REDIS__PASSWORD="password_for_redis" \
    -e EMQ_AUTH__REDIS__PASSWORD_HASH=plain \
    emq:latest

集群部署

集群要求

• 必须暴露端口4369和6000-6999端口范围

集群示例

bash
docker run --rm -ti --name emq -p 18083:18083 -p 1883:1883 -p 4369:4369 -p 6000-6100:6000-6100 \
    -e EMQ_NAME="emq" \
    -e EMQ_HOST="s2.emqtt.io" \
    -e EMQ_LISTENER__TCP__EXTERNAL=1883 \
    -e EMQ_JOIN_CLUSTER="emq@s1.emqtt.io" \
    emq:latest

内核调优

在Linux主机上，推荐直接调优主机内核。如需通过Docker调优，需确保Docker版本≥1.12：

bash
docker run --rm -ti --name emq -p 18083:18083 -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=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 \
    --sysctl net.core.rmem_max=16777216 \
    --sysctl net.core.wmem_max=16777216 \
    --sysctl net.core.optmem_max=16777216 \
    --sysctl net.ipv4.tcp_rmem=1024 4096 16777216 \
    --sysctl net.ipv4.tcp_wmem=1024 4096 16777216 \
    --sysctl net.ipv4.tcp_max_tw_buckets=1048576 \
    --sysctl net.ipv4.tcp_fin_timeout=15 \
    emq:latest

注意：不要以特权模式运行EMQ容器或挂载系统proc目录来调优内核，这是不安全的做法。