mahmoudsamy/emqx

EMQ Docker

镜像概述和主要用途

EMQ（Erlang MQTT Broker）是一个分布式、大规模可扩展、高扩展性的MQTT消息代理，采用Erlang/OTP编写。本Docker镜像提供了EMQ的便捷部署方式，适用于构建物联网（IoT）、实时通信等场景的消息中间件服务。

当前Docker镜像大小：37.1 MB

获取镜像

您可以自行构建此Docker镜像：

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

运行EMQ

在Docker镜像下执行命令的基本格式：

bash
docker run --rm -ti -v `pwd`:$(somewhere) emq/$(image) $(somecommand)

例如，启动EMQ服务：

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

EMQ Erlang代理在Docker容器中以Linux用户emqtt身份运行。

配置

环境变量配置规则

使用环境变量配置EMQ Docker容器，遵循以下规则：

• 以EMQ_为前缀的环境变量映射到配置文件，其中.替换为__
  示例：
  EMQ_LISTENER__SSL__EXTERNAL__ACCEPTORS <--> listener.ssl.external.acceptors
EMQ_MQTT__MAX_PACKET_SIZE <--> mqtt.max_packet_size

• 以PLATFORM_为前缀的环境变量映射到配置文件中的模板字符串
  示例：
  PLATFORM_ETC_DIR <--> {{ platform_etc_dir }}

• 非映射环境变量（不用于配置文件）：
  EMQ_NAME、EMQ_HOST

EMQ核心配置

注意：https://github.com/emqtt/emqttd/blob/master/etc/emq.conf%E4%B8%AD%E7%9A%84%E6%89%80%E6%9C%89EMQ%E9%85%8D%E7%BD%AE%E5%9D%87%E5%8F%AF%E9%80%9A%E8%BF%87%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E8%AE%BE%E7%BD%AE%E3%80%82%E4%BB%A5%E4%B8%8B%E5%88%97%E8%A1%A8%E4%BB%85%E4%B8%BA%E7%A4%BA%E4%BE%8B%EF%BC%8C%E9%9D%9E%E5%AE%8C%E6%95%B4%E9%85%8D%E7%BD%AE%E3%80%82

若设置EMQ_NAME和EMQ_HOST但未设置EMQ_NODE__NAME，则EMQ_NODE__NAME=$EMQ_NAME@$EMQ_HOST。

示例：将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_LOADED_PLUGINS环境变量包含：

• emq_recon
• emq_modules
• emq_retainer
• emq_dashboard

bash
# 默认EMQ_LOADED_PLUGINS环境变量值
EMQ_LOADED_PLUGINS="emq_recon,emq_modules,emq_retainer,emq_dashboard"

示例：加载emq_auth_redis插件，将其添加到EMQ_LOADED_PLUGINS，可使用逗号、空格或其他分隔符：

bash
EMQ_LOADED_PLUGINS="emq_auth_redis,emq_recon,emq_modules,emq_retainer,emq_dashboard"
EMQ_LOADED_PLUGINS="emq_auth_redis emq_recon emq_modules emq_retainer emq_dashboard"
EMQ_LOADED_PLUGINS="emq_auth_redis | emq_recon | emq_modules | emq_retainer | emq_dashboard"

插件配置

以EMQ_为前缀的环境变量同样适用于所有EMQ插件的配置文件，.替换为__。

示例：
EMQ_AUTH__REDIS__SERVER <--> auth.redis.server
EMQ_AUTH__REDIS__PASSWORD <--> auth.redis.password

Docker镜像会自动查找并配置插件配置文件，无需手动指定路径。

示例：使用Redis认证插件

bash
docker run --rm -ti --name emq -p 18083:18083 -p 1883:1883 -p 4369:4369 \
    -e EMQ_LISTENER__TCP__EXTERNAL=1883 \
    -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

集群

可指定初始集群并加入。

注意：EMQ集群需暴露端口4369及6000-6999端口范围。

示例：使用6000-6100端口范围构建集群

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 Docker或挂载系统proc到容器内进行内核调优，这是不安全的。

致谢

感谢@je-al提供环境变量映射的思路（将配置文件中的点替换为双下划线）。