通过 Docker 运行 EMQX

本页将指导您使用官方 Docker 镜像快速安装和运行 EMQX，并使用 Docker Compose 实现集群搭建。

部署前准备

在 Docker 中启动 EMQX 前，请了解以下部署注意事项。

配置稳定的节点名

EMQX 将节点数据存储在 data/mnesia/<节点名> 目录中。首次启动容器前，请配置稳定的节点名，避免后续节点名发生变化导致数据丢失。

对于单节点部署，使用 EMQX_NODE_NAME 环境变量配置节点名，格式为 emqx@<host>。容器主机名应与 <host> 的值保持一致。

注意： <host> 部分必须是 IP 地址或完全限定域名（FQDN），例如 node1.emqx.com。EMQX 的 Erlang 节点以长节点名模式运行，因此不能使用不含点号的短主机名，例如 node1。

准备持久化存储

要在容器被删除后保留 EMQX 数据，请将以下容器目录挂载到宿主机：

• /opt/emqx/data：存储 EMQX 数据。
• /opt/emqx/log：存储文件日志和崩溃转储文件。

EMQX 容器默认使用控制台日志，但节点异常终止时，Erlang 虚拟机会将崩溃转储文件写入 /opt/emqx/log。如果未挂载该目录，删除容器后将无法保留转储文件。宿主机上的日志目录必须对容器内的 emqx 用户（UID 1000）可写。详情参见 Docker 中的崩溃转储文件。

有关 EMQX 目录结构的更多信息，参见 EMQX 文件和目录。

访问宿主机服务

如果 EMQX 需要访问宿主机上运行的服务，请勿使用 localhost 或 127.0.0.1 作为服务地址。这些地址指向容器自身的网络接口。请使用宿主机 IP 地址或 host 网络模式。在 Docker Desktop for Mac 或 Windows 中，也可以使用 host.docker.internal。

通过 Docker 运行单个 EMQX 节点

按照以下步骤运行单个 EMQX 节点。有关 EMQX 官方 Docker 镜像的更多信息，参见 Docker Hub - emqx/emqx-enterprise。

1. 拉取 Docker 镜像：

   docker pull emqx/emqx-enterprise:6.3.0

2. 创建宿主机目录，并确保容器内的 emqx 用户对日志目录具有写权限：

   mkdir -p $PWD/data $PWD/log
   sudo chown $UID:$GID $PWD/log

3. 使用稳定的节点名和已挂载的目录启动容器：

   docker run -d --name emqx-enterprise \
     --hostname node1.emqx.com \
     -e "EMQX_NODE_NAME=emqx@node1.emqx.com" \
     -p 1883:1883 -p 8083:8083 \
     -p 8084:8084 -p 8883:8883 \
     -p 18083:18083 \
     -v $PWD/data:/opt/emqx/data \
     -v $PWD/log:/opt/emqx/log \
     emqx/emqx-enterprise:6.3.0

配置 Docker 中的默认监听地址

Docker 镜像默认设置

从 EMQX 6.3.0 开始，当环境变量 EMQX_NODE__DEFAULT_LISTENER_ADDRESS 未设置或为空时，官方镜像的入口脚本将其设置为 all。

该默认值使仅指定端口的 MQTT 监听器、网关监听器和 Dashboard HTTP 监听器监听所有网络接口，从而在两种安全配置方案下均可通过发布的容器端口访问。

监听器绑定中显式指定的 IP 地址保持不变。该配置仅控制绑定地址，不会放宽认证或授权要求。

覆盖默认设置

如需覆盖此默认值，可通过 docker run -e EMQX_NODE__DEFAULT_LISTENER_ADDRESS=<value> 传入其他支持的值，或在 Docker Compose 服务的 environment 部分设置该变量。

环境变量的优先级高于配置文件，因此，仅在挂载的 emqx.conf 中设置 node.default_listener_address 不会覆盖入口脚本的默认值。

支持的取值参见默认监听地址。

重要提示

使用 Docker 桥接网络时，将该变量设置为 loopback 会使受影响的监听器绑定到容器网络命名空间内的回环地址。此时，即使使用 -p，也无法通过发布的端口访问这些监听器。

如需控制发布端口所使用的宿主机地址，请参见 Docker 端口发布和映射。

使用功能门控启动 EMQX

从 EMQX 6.3.0 开始，可以使用 EMQX_FEATURES 环境变量控制启动时可用的可选功能。例如，如需仅启动核心应用，运行：

docker run -d --name emqx-enterprise \
  -e "EMQX_FEATURES=ESSENTIAL" \
  -p 1883:1883 -p 8083:8083 \
  -p 8084:8084 -p 8883:8883 \
  emqx/emqx-enterprise:6.3.0

如需使用自定义功能集启动 EMQX，运行：

docker run -d --name emqx-enterprise \
  -e "EMQX_FEATURES=dashboard,metrics,plugins" \
  -p 1883:1883 -p 18083:18083 \
  emqx/emqx-enterprise:6.3.0

完整功能列表和依赖行为请参见功能门控。

通过 Docker Compose 构建 EMQX 集群

Docker Compose 是一个用于编排和运行多容器的工具，下面将指导您通过 Docker Compose 创建简单的 EMQX 静态集群用于测试。

本节中的 Docker Compose 示例仅适用于本地测试，其中的卷挂载配置默认被注释。要保留数据和崩溃转储文件，请按照部署前准备中的说明准备宿主机目录，并取消 volumes 配置的注释。有关生产环境中的集群部署，参见构建集群。

TIP

目前 Docker Compose 已经包含在 Docker 安装包中无需单独安装，如果您的 Docker 中没有包含 Compose 请参考 Install Docker Compose 进行安装。

1. 在任意目录创建 docker-compose.yml 文件，内容如下：

   version: '3'
   
   services:
     emqx1:
       image: emqx/emqx-enterprise:6.3.0
       container_name: emqx1
       environment:
       - "EMQX_NODE_NAME=emqx@node1.emqx.com"
       # - "EMQX_FEATURES=dashboard,metrics,plugins"
       - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
       - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.com,emqx@node2.emqx.com]"
       healthcheck:
         test: ["CMD", "/opt/emqx/bin/emqx", "ctl", "status"]
         interval: 5s
         timeout: 25s
         retries: 5
       networks:
         emqx-bridge:
           aliases:
           - node1.emqx.com
       ports:
         - 1883:1883
         - 8083:8083
         - 8084:8084
         - 8883:8883
         - 18083:18083
       # volumes:
       #   - $PWD/emqx1_data:/opt/emqx/data
       #   - $PWD/emqx1_log:/opt/emqx/log
   
     emqx2:
       image: emqx/emqx-enterprise:6.3.0
       container_name: emqx2
       environment:
       - "EMQX_NODE_NAME=emqx@node2.emqx.com"
       # - "EMQX_FEATURES=dashboard,metrics,plugins"
       - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
       - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.com,emqx@node2.emqx.com]"
       healthcheck:
         test: ["CMD", "/opt/emqx/bin/emqx", "ctl", "status"]
         interval: 5s
         timeout: 25s
         retries: 5
       networks:
         emqx-bridge:
           aliases:
           - node2.emqx.com
       # volumes:
       #   - $PWD/emqx2_data:/opt/emqx/data
       #   - $PWD/emqx2_log:/opt/emqx/log
   
   networks:
     emqx-bridge:
       driver: bridge

   如果在 Docker Compose 集群中设置 EMQX_FEATURES，请为所有 EMQX 服务使用相同的值。

2. 通过命令行切换 docker-compose.yml 文件所在目录，然后输入以下命令启动 EMQX 集群：

   docker-compose up -d

3. 查看集群状态：

   $ docker exec -it emqx1 sh -c "emqx ctl cluster status"
   Cluster status: #{running_nodes => ['emqx@node1.emqx.com','emqx@node2.emqx.com'],
                     stopped_nodes => []}

下一步

使用客户端连接到 EMQX，进行消息收发，请参考发布订阅操作。

配置 EMQX 参数及其他功能，请参考配置文件。

将多个 EMQX 节点组建为一个集群，请参考构建集群。