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 仓库以 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 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）端口。
四、本地部署
方式一：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 emqxRHEL/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 会自动完成集群组建与滚动升级。
五、浏览器端部署与可视化管理
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 或主题开启链路追踪，查看消息从接入到投递的完整路径。
六、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 文档。
七、常见问题 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/ 目录，并在测试环境验证规则引擎与数据桥接兼容性。
相关链接： EMQ 官网 · EMQX 官方文档 · GitHub 仓库 · Docker 镜像 · MQTTX 客户端工具