EMQX 部署指南：百万级 MQTT 物联网消息平台详解

一、项目介绍

EMQX 是目前全球扩展性最强、可靠性最高的开源 MQTT 消息平台，专为高性能、高可靠、安全的物联网数据基础设施而设计。它完整支持 MQTT 5.0、3.1.1 与 3.1 协议，并兼容 MQTT-SN、CoAP、LwM2M 以及 MQTT over QUIC 等物联网常用协议。EMQX 单集群可接入超过一亿台并发 MQTT 客户端，每秒处理数百万条消息，端到端延迟控制在亚毫秒级，广泛应用于 AIoT、工业物联网、车联网、智慧城市、智慧能源等场景。项目由 EMQ 公司主导开发，源码托管在 github.com/emqx/emqx，官方文档位于 docs.emqx.com。

从 5.9.0 版本开始，EMQX 将原开源版与企业版的全部功能统一到单一发行版中，采用 Business Source License（BSL）1.1 协议发布。这意味着开发者可以免费使用包括规则引擎、数据桥接、集群、TLS 加密、ACL 鉴权在内的全部能力，仅在商业转售或 SaaS 对外提供服务时需要额外授权。EMQX 内置基于 SQL 的规则引擎，可对流入消息进行过滤、转换、富化，并桥接到 Kafka、RabbitMQ、PostgreSQL、MySQL、MongoDB、Redis、ClickHouse、InfluxDB 等五十多种后端系统，也支持 Webhook 与自定义 HTTP 服务对接。

除了核心 Broker，EMQX 还提供可视化 Dashboard、HTTP 管理 API、Prometheus 监控指标、Grafana 仪表盘、OpenTelemetry 链路追踪等运维能力，并通过 EMQX Operator 在 Kubernetes 上提供声明式部署。无论是家庭实验室里的树莓派，还是公有云上的大规模集群，EMQX 都能以同一套架构平滑扩展。

在典型的物联网业务架构中，EMQX 处于设备接入与业务后端之间的关键位置：海量传感器、网关、车载终端通过 MQTT 协议把数据上报到 EMQX，EMQX 根据主题规则把数据分发到实时流处理、时序数据库、消息队列、数据仓库与告警系统。这种"接入层与业务层解耦"的设计让设备侧协议保持简单，业务侧则可以按需替换底层存储与计算组件，是工业互联网、车联网、智慧能源等领域的事实标准。相比自研 MQTT Broker，EMQX 的优势在于经过大规模生产验证的稳定性、完整的协议兼容矩阵以及开箱即用的数据集成生态。

EMQX 的性能数据同样亮眼：官方基准测试中，单集群可处理每秒数百万条消息，端到端亚毫秒延迟；无主集群架构让任意节点故障都不会导致整体不可用，节点扩容只需加入集群即可自动完成负载均衡。这些特性使 EMQX 在国内外头部云厂商、新能源车企、智慧城市项目中被广泛采用，成为物联网基础设施层的核心组件之一。

二、项目结构与核心组件

EMQX 仓库以 Erlang/Elixir 编写，主分支为 master，稳定版本按 release-XY 分支维护，例如 release-62 对应 6.2.N 系列。仓库根目录下，apps 是核心应用集合，其中 emqx 是 Broker 主程序，emqx_dashboard 提供 Web 控制台，emqx_rule_engine 实现 SQL 规则引擎，emqx_bridge 与 emqx_connector 负责外部系统桥接，emqx_auth_* 系列插件实现用户名密码、JWT、X.509、LDAP、Redis、MySQL、PostgreSQL 等多种鉴权方式，emqx_gateway 则统一接入 CoAP、LwM2M、MQTT-SN 等非 MQTT 协议。

运行时层面，EMQX 由四个核心组件构成：第一是协议接入层，负责监听 1883（MQTT）、8883（MQTT over TLS）、8083（MQTT over WebSocket）、8084（WSS）、18083（Dashboard HTTP）等端口，完成 TCP 连接与 MQTT 报文解析；第二是会话与订阅层，维护每个客户端的会话状态、订阅关系与遗嘱消息；第三是路由层，基于 Erlang 的分布式一致性哈希在集群节点间路由消息，实现无主节点的高可用集群；第四是集成层，通过规则引擎与数据桥接把消息投递到外部系统。

配置文件统一位于 etc/emqx.conf，从 5.x 起采用 HOCON 格式，支持热加载。集群通过 cluster.hocons 或 cluster.conf 配置节点发现方式，支持静态节点列表、DNS、K8s 自动发现等多种模式。

安全方面，EMQX 内置了完整的鉴权与授权体系。鉴权支持用户名密码、JWT、X.509 证书、PSK 预共享密钥等方式，并可对接 LDAP、MySQL、PostgreSQL、Redis、HTTP Webhook 等外部用户库；授权则通过 ACL 规则精确控制每个客户端能发布或订阅哪些主题。生产环境强烈建议在 8883 端口启用 TLS，并配合 X.509 双向认证，避免设备凭据泄露后被冒用。

三、版本与环境要求

当前主线版本为 EMQX 6.x，5.x 仍在维护。EMQX 5.4 及以上版本需要 Erlang/OTP 25 或 26；5.9+ 支持 OTP 27；6.1+ 支持 OTP 28。需要特别注意的是，EMQX 不直接使用上游 Erlang/OTP，而是基于 emqx/otp 这个 fork 版本构建，仓库根目录的 .tool-versions 文件锁定了精确版本号，例如 erlang 27.3.4.2-9，末尾数字是 fork 修订号，上游发行版无法匹配。

操作系统方面，EMQX 官方提供 Ubuntu 20.04/22.04、Debian 11/12、CentOS 7/8、RHEL 8/9、macOS 12+ 的二进制包与 Docker 镜像。最低硬件要求为 1 核 CPU、1GB 内存、1GB 磁盘；生产环境建议至少 4 核 8GB 内存，并根据连接数调整文件描述符上限（ulimit -n 65536）。端口方面，1883、8883、8083、8084、18083 必须放行，集群节点之间还需开放 4370（分布式节点通信）与 5369（RPC）端口。

时间同步对集群一致性至关重要，所有节点应通过 chrony 或 systemd-timesyncd 与同一 NTP 服务器同步，时间偏差过大可能导致分布式协议异常。操作系统层面建议关闭透明大页、调整 TCP keepalive 参数以适配海量长连接，并把 net.core.somaxconn 提升到 32768 以上。

四、本地部署

方式一：Docker 一键启动（最快体验）

官方 README 给出的最简命令如下：

docker run -d --name emqx \
  -p 1883:1883 -p 8083:8083 -p 8084:8084 \
  -p 8883:8883 -p 18083:18083 \
  emqx/emqx-enterprise:latest

启动后立即可以通过 http://服务器IP:18083 访问 Dashboard，默认账号 admin，默认密码 public，首次登录会强制修改密码。生产环境建议挂载数据卷：-v emqx-data:/opt/emqx/data -v emqx-etc:/opt/emqx/etc。

方式二：系统包安装（DEB/RPM）

Debian/Ubuntu 用户：

wget https://www.emqx.com/en/downloads/broker/6.1.0/emqx-6.1.0-ubuntu22.04-amd64.deb
sudo dpkg -i emqx-6.1.0-ubuntu22.04-amd64.deb
sudo systemctl enable --now emqx

RHEL/CentOS 用户：

wget https://www.emqx.com/en/downloads/broker/6.1.0/emqx-6.1.0-el8-amd64.rpm
sudo rpm -ivh emqx-6.1.0-el8-amd64.rpm
sudo systemctl enable --now emqx

安装后可使用 emqx_ctl status 查看运行状态，emqx_ctl listeners 查看监听端口，emqx_ctl clients list 列出在线客户端。

方式三：二进制压缩包

从 官方下载页 选择对应平台的 tar.gz 包，解压后进入 bin/ 目录：

tar xzf emqx-6.1.0-ubuntu22.04-amd64.tar.gz
cd emqx
./bin/emqx console      # 前台运行，日志直接打印
./bin/emqx start        # 后台启动
./bin/emqx stop         # 停止

macOS 用户同样使用 tar.gz 包，解压后即可运行，无需额外依赖。Windows 暂不支持原生运行，推荐使用 WSL2 或 Docker Desktop。

方式四：源码编译

git clone https://github.com/emqx/emqx.git
cd emqx
make
_build/emqx-enterprise/rel/emqx/bin/emqx console

如果本地没有匹配的 Erlang/OTP fork 版本，最简单的方式是使用官方 builder 镜像：

docker run --rm -it -v "$PWD:/emqx" -w /emqx \
  ghcr.io/emqx/emqx-builder/6.1-17:27.3.4.2-9-ubuntu22.04 \
  make

打包为 tar.gz：make emqx-enterprise-tgz；打包为 DEB/RPM：make emqx-enterprise-pkg；构建 Docker 镜像：PROFILE=emqx-enterprise make docker。

方式五：Kubernetes 部署

生产级集群推荐使用 EMQX Operator。先通过 Helm 安装 Operator：

helm repo add emqx https://repos.emqx.io/charts
helm repo update
helm install emqx-operator emqx/emqx-operator --namespace emqx-operator-system --create-namespace

然后编写 EmqxPlatform 自定义资源，声明副本数、资源配额、服务类型、持久化存储等字段，Operator 会自动完成集群组建与滚动升级。

部署后的初始配置建议

无论采用哪种部署方式，首次启动后都建议完成以下基础配置：修改 Dashboard 默认密码；在 etc/emqx.conf 中关闭匿名认证（authorization.no_match = deny）；配置至少一种鉴权后端，例如内置数据库的用户名密码；在 8883 端口加载 TLS 证书；调整 node.max_ports 与系统 ulimit 匹配；开启 Prometheus 指标抓取并接入现有监控体系。这些步骤完成后，EMQX 才算具备生产可用的安全水位。

五、浏览器端部署与可视化管理

EMQX 自带的 Dashboard 是运维管理的核心入口。默认地址为 http://服务器IP:18083，首次登录使用 admin/public，登录后立即修改密码。Dashboard 左侧菜单包括概览、客户端、订阅、消息、规则引擎、数据集成、认证授权、监控、设置等模块。概览页实时展示连接数、消息吞吐、主题数、队列数等关键指标；客户端页可查看每个在线 MQTT 客户端的连接详情，包括用户名、客户端 ID、IP、订阅数、收发流量，并支持强制踢下线；订阅页可按主题反查订阅者；规则引擎页以可视化方式配置 SQL 规则与目标动作。

除了 Dashboard，EMQX 还集成了 Prometheus 指标抓取，默认在 /prometheus 路径暴露指标。在 etc/emqx.conf 中开启 prometheus.enable = true 后，Prometheus 即可抓取 emqx_messages_total、emqx_clients_connected 等数百项指标，配合官方 Grafana 仪表盘 ID 17446 即可获得开箱即用的监控大屏。日志方面，Dashboard 内置 tracing 功能，可按客户端 ID 或主题开启链路追踪，查看消息从接入到投递的完整路径。

Dashboard 还内置了"WebSocket 客户端"调试面板，无需额外安装工具即可在浏览器中直接连接 EMQX、订阅主题、发布消息，非常适合验证设备侧协议。对于需要多租户隔离的 SaaS 场景，EMQX 支持通过主题前缀与 ACL 把不同客户的设备数据物理隔离，并在 Dashboard 中按标签分组展示集群节点、客户端与告警事件。

六、API 用法

EMQX 提供完整的 HTTP 管理 API，默认监听 18083 端口，路径前缀为 /api/v5/。调用前需要在 Dashboard 的"设置→密钥"页面生成 API Key 与 Secret，然后使用 Basic Auth 调用。下面是几个常用的 curl 示例：

# 查看集群概况
curl -u app_id:app_secret http://localhost:18083/api/v5/brokers

# 列出所有在线客户端
curl -u app_id:app_secret http://localhost:18083/api/v5/clients

# 强制踢下线某个客户端
curl -u app_id:app_secret -X DELETE http://localhost:18083/api/v5/clients/client-001

# 发布一条 MQTT 消息
curl -u app_id:app_secret -X POST http://localhost:18083/api/v5/publish \
  -H "Content-Type: application/json" \
  -d '{"topic":"a/b","payload":"hello","qos":1}'

规则引擎的 SQL 示例：把所有主题为 device/+/up 的消息桥接到 Kafka：

SELECT
  topic, payload.msg as message, payload.ts as ts
FROM
  "device/+/up"
WHERE
  direction = 'up'

创建规则后，在"动作"中选择"桥接数据到 Kafka"，指定 Kafka 集群地址、Topic 与消息格式即可。完整 API 文档参见 EMQX HTTP API 文档。

除了 HTTP API，EMQX 还提供 emqx_ctl 命令行工具用于本地运维，例如 emqx_ctl clients list 列出在线客户端、emqx_ctl topics list 查看订阅关系、emqx_ctl listeners 查看监听状态、emqx_ctl admins 管理 Dashboard 账号。在没有浏览器的服务器排障场景下，emqx_ctl 是最直接的诊断入口。

七、常见问题 FAQ

Q1：Dashboard 登录提示"用户名或密码错误"？
A：默认账号是 admin，默认密码是 public，首次登录会强制修改。如果已经修改过但忘记，可执行 emqx_ctl admins reset_password admin NewPass@123 重置，或删除 data/admin/authz 目录后重启。

Q2：客户端连接 1883 端口被拒绝？
A：依次检查：防火墙与安全组是否放行 1883；EMQX 监听是否正常（emqx_ctl listeners）；客户端地址是否误写成 8883（TLS 端口）；TCP 连接数是否达到 ulimit 上限。生产环境建议把 ulimit -n 调整到 65536 以上。

Q3：集群节点无法互相发现？
A：确认节点间 4370、5369 端口已互通；节点使用的 cookie 必须一致（etc/emqx.conf 中 node.cookie）；主机名必须可解析，建议在 /etc/hosts 中固定；时间偏差不应超过 5 秒。

Q4：BSL 协议下集群部署是否需要付费？
A：自 5.9.0 起，单节点部署免费；超过 1 个节点的集群需要加载 license 文件才能启动。免费 license 可在 EMQ 官网申请，包含有限的连接数与功能；商业 license 解除全部限制。详细说明参见 EMQX License FAQ。

Q5：消息丢失或 QoS 1/2 不生效？
A：检查客户端与 Broker 之间是否有中间网关修改 QoS；持久会话是否开启（Clean Session = false）；Broker 是否重启导致会话状态丢失；规则引擎动作是否失败但被忽略。开启 tracing 可以逐跳定位消息在哪一环丢失。

Q6：如何升级到新版本？
A：5.x 内部相邻小版本支持滚动升级，参见 README 中的升级路径矩阵。从 5.x 升级到 6.x 会丢失持久会话状态，客户端重连后会创建全新会话。升级前务必备份 data/ 与 etc/ 目录，并在测试环境验证规则引擎与数据桥接兼容性。

Q7：单节点能支撑多少连接？
A：官方基准测试显示，4 核 8GB 云主机单节点可稳定支撑 100 万并发 MQTT 连接。实际承载量取决于报文大小、QoS 等级、订阅数量与规则复杂度。接入更多设备时，优先横向扩展集群节点，而不是盲目堆高单机配置。

Q8：如何排查设备频繁断线？
A：Dashboard 的"客户端"页可以看到每个连接的断线原因码，常见原因包括 Keepalive 超时、认证失败、ACL 拒绝、客户端主动断开。开启 trace.client_id 日志可以看到完整的握手与心跳过程。网络层面还要排查 NAT 会话超时、运营商中间设备静默丢包等问题。

Q9：Docker 启动后立刻退出？
A：最常见原因是内存不足导致 Erlang 虚拟机启动失败。执行 docker logs emqx 查看日志，若看到 eheap_alloc: Cannot allocate 字样，请调大容器内存限制。其次检查 1883、18083 等端口是否被宿主机其他进程占用。最后确认挂载的数据卷权限是否正确，容器内运行用户对 /opt/emqx/data 必须有读写权限。

相关链接： EMQ 官网 · EMQX 官方文档 · GitHub 仓库 · Docker 镜像 · MQTTX 客户端工具