alpine/emqx

EMQ X 旧版本 Docker 镜像文档

1. 镜像概述

本镜像为EMQ X（一款开源的MQTT消息服务器）的历史版本Docker镜像。需注意以下版本状态：

• v2.1.0：存在start.sh脚本bug，无法正确配置auth.mysql.username参数，不建议使用。
  Dockerfile地址：https://github.com/emqx/emqx-docker/blob/b55440cf96f978ef8dba5a9b20fcaad8d9891f32/Dockerfile

• v2.1.1：同样存在start.sh脚本bug，无法正确配置auth.mysql.username参数，不建议使用。
  Dockerfile地址：https://github.com/emqx/emqx-docker/blob/1b04e44610f5d02c1ba073375117ddaaae4e7279/Dockerfile

• v2.3.4：功能正常，推荐使用此版本。
  Dockerfile地址：https://github.com/emqx/emqx-docker/blob/24ad314468a40ea24b09345c94b899505a096435/Dockerfile

2. 核心功能与特性

• MQTT协议支持：兼容MQTT 3.1/3.1.1协议，提供TCP监听端口（默认1883），支持百万级并发连接。
• 插件系统：支持加载多种插件，如emq_auth_mysql（MySQL认证）、emq_dashboard（Web控制台）、emq_retainer（消息留存）等。
• 环境变量配置：可通过环境变量灵活配置服务器参数，如监听端口、认证信息、插件加载列表等。
• 稳定性：v2.3.4版本修复了start.sh脚本的配置bug，可正常设置auth.mysql.username等关键参数。

3. 使用场景

适用于需要部署旧版本EMQ X MQTT消息服务器的场景，例如：

• 对历史版本EMQ X有依赖的 legacy 系统；
• 需要验证旧版本功能或进行兼容性测试；
• 因特定业务需求无法升级至新版本的环境。

4. 使用方法与配置说明

4.1 前提条件

• 已安装Docker环境（Docker 1.13+）；
• 若使用MySQL认证插件，需提前准备MySQL数据库服务及相关表结构。

4.2 快速启动命令

以下命令基于v2.3.4版本，通过docker run快速部署EMQ X容器，包含MySQL认证配置（需替换<project>、<mysql_url>、<xxxxxxxx>等占位符）：

bash
# 设置容器名称（替换<project>为实际项目名）
name="emqx-<project>"

# 清理同名旧容器（若存在）
docker rm -f $(docker ps -aq --filter name=${name}) || echo "容器不存在，继续部署"

# 启动EMQ X容器（v2.3.4版本）
docker run -d --name ${name} --restart=always \
    -p 18083:18083 -p 1883:1883 -p 4369:4369 \
    -e EMQ_MQTT__LISTENER__TCP=1883 \  # MQTT TCP监听端口
    -e EMQ_LOADED_PLUGINS="emq_auth_mysql,emq_recon,emq_modules,emq_retainer,emq_dashboard" \  # 加载的插件列表
    -e EMQ_AUTH__MYSQL__SERVER="<mysql_url>:3306" \  # MySQL服务器地址（替换<mysql_url>）
    -e EMQ_AUTH__MYSQL__USERNAME="admin" \  # MySQL用户名
    -e EMQ_AUTH__MYSQL__PASSWORD="<xxxxxxxx>" \  # MySQL密码（替换<xxxxxxxx>为实际密码）
    -e EMQ_AUTH__MYSQL__PASSWORD_HASH=plain \  # 密码加密方式（此处为明文，生产环境建议使用哈希）
    -e EMQ_AUTH__MYSQL__DATABASE="mqtt_table" \  # MySQL数据库名
    alpine/emqx:2.3.4 sh -c "sleep 5 & /opt/emqttd/start.sh"  # 需先执行sleep 5解决start.sh启动问题

4.3 参数说明

端口映射

关键环境变量

4.4 注意事项

• sleep 5的必要性：v2.3.4版本需在启动start.sh前执行sleep 5，以解决脚本启动时的配置加载问题。
• 版本选择：避免使用v2.1.0和v2.1.1版本，这两个版本的start.sh脚本存在bug，无法正确设置auth.mysql.username参数。
• 安全建议：生产环境中，EMQ_AUTH__MYSQL__PASSWORD_HASH建议使用哈希方式（如sha256），并确保MySQL数据库访问权限限制。

4.5 参考文档

更多配置细节可参考上游官方文档：https://hub.docker.com/r/emqx/emqx