5分钟跑通MQTT：EMQX Docker部署+MQTTX联调（2026最新版，含踩坑）
一、为什么第一步是"本地跑一个 Broker"
上一篇讲了 MQTT 是什么，这一篇直接上手。但在动手前，先建立正确预期：
MQTT 是"Broker 中心化"的协议 ------消息永远要经过中间那个 Broker。所以想跑通 MQTT，你需要的不是"写代码"，而是先把一个 Broker 起起来 ，再用一个客户端工具连上去收发消息。这两件事今天 5 分钟就能搞定。
我选 EMQX（开源版）而不是 Mosquitto，原因很实际：
- 自带一个 Web Dashboard，能看到连接数、消息吞吐、订阅关系------对新手极其友好；
- 原生支持 MQTT 3.1.1 / 5.0 / WebSocket，后续篇章（共享订阅、消息流转、压测）都能在它上面跑；
- 它在国内生产环境占有率很高，你现在练手的东西，以后真上生产还用得上。
二、先选对版本（2026 年现状，很多人在这里踩坑）
截至本文写作，EMQX 的版本线是这样的：
| 版本线 | 定位 | Docker 镜像 | 说明 |
|---|---|---|---|
| EMQX 5.8.x（开源版） | 社区/生产都在用 | emqx/emqx:5.8 |
本教程使用，最新 5.8.9，文档最全 |
| EMQX 6.x（Enterprise） | 企业版，已到 6.3 LTS | emqx/emqx-enterprise |
功能更强，但默认安全策略有调整，新手不必追新 |
⚠️ 坑点提醒 ：网上很多"EMQX 安装教程"还在写
emqx/emqx:4.x，4.x 早已停止维护，命令和 Dashboard 差异很大。认准 5.x 的emqx/emqx镜像。Enterprise 6.x 对新手来说多了一层"安全加固配置"的干扰，本文不展开，等你把 5.x 玩熟再升级无痛。
客户端工具 MQTTX 当前最新是 v1.13.0（官网 https://mqttx.app 下载，支持 macOS/Windows/Linux，也有 Web 版和 CLI 版）。
三、端口规划：先认识这几个端口（可截图保存）
EMQX 默认监听下面这些端口，记不住没关系，先收藏这张表：
| 端口 | 协议 | 用途 |
|---|---|---|
| 1883 | MQTT over TCP | 设备/客户端标准接入（本文联调用它） |
| 8083 | MQTT over WebSocket | 浏览器/前端接入 |
| 8084 | MQTT over WebSocket + TLS | 浏览器加密接入 |
| 8883 | MQTT over TLS | 设备加密接入（生产必用） |
| 18083 | HTTP | Dashboard 管理后台（浏览器访问它） |
坑点预告 ：新手最常见的报错就是"连不上"，原因十有八九是端口没映射对 或用错端口（比如拿 WebSocket 的 8083 去当 TCP 的 1883 连）。下一节我会给排查表。
四、Docker 一键部署 EMQX
前置条件：本机已装好 Docker（docker -v 能输出版本号即可）。
bash
# 1. 拉取并启动 EMQX（开源版 5.8）
docker run -d \
--name emqx \
-p 1883:1883 \
-p 8083:8083 \
-p 8084:8084 \
-p 8883:8883 \
-p 18083:18083 \
emqx/emqx:5.8
# 2. 看启动日志，确认没有报错（首次启动约需 10~20 秒）
docker logs -f emqx命令逐行解释（这些以后生产部署也这么写）：
-d：后台运行；--name emqx：给容器起名，方便后面docker logs emqx/docker stop emqx；-p 宿主机端口:容器端口：把容器内的 5 个端口映射到本机，冒号两边端口号别写错；emqx/emqx:5.8：开源版镜像 + 指定 5.8 版本（不写 tag 默认latest，但生产里永远显式指定版本，避免半夜自动升级出幺蛾子）。
看到日志里出现 EMQX ... is running now 之类的字样，说明启动成功。
五、登录 Dashboard
浏览器打开：http://localhost:18083
- 默认账号：
admin - 默认密码：
public
登录后你会看到「总览 / 连接 / 主题 / 订阅 / 规则 / 监控」等菜单。这里先做一件事：改默认密码 （系统设置 → 用户 里操作）。admin/public 是全世界都知道的默认值，公网环境不改等于裸奔------这是我在生产巡检里反复强调的一条。
六、MQTTX 联调：一次真实的收发
-
下载安装 MQTTX ：去 https://mqttx.app 下对应系统的版本（macOS 也可以
brew install --cask mqttx）。 -
新建连接，填这几个字段：
字段 填写值 说明 Name 随意，如 local-test连接配置的名字 Host mqtt://localhost协议 + 主机 Port 1883对应 TCP 端口 Client ID 留空（自动生成） 客户端唯一标识，第 5 篇讲它为什么重要 Username / Password 留空 EMQX 默认允许匿名接入 点击右上角「连接」，看到状态变绿、能收到 Broker 回包，说明连接成功。
-
订阅一个主题 ：点「+ 新建订阅」，Topic 填
test/temp，QoS 选1。 -
发布一条消息 ：在下方发布区，Topic 填
test/temp，Payload 填：json{"device":"sensor-01","temp":26.5,"ts":1750000000}点发送，你会立刻在上面订阅区收到这条消息------这就是 MQTT 最基本的"发布 → Broker → 订阅"闭环，跑通了。
想验证"一对多"：再开一个 MQTTX 连接（或复用同一个，再订阅一次
test/#），往test/temp发消息，两个订阅都会收到。这就是上一篇讲的发布订阅。
七、📌 可拿走资产：常见"连接被拒绝"排查表
第一次连不上太正常了。按这张表从上到下查，90% 的问题能在 2 分钟内定位：
| 现象 / 报错 | 最常见原因 | 怎么解决 |
|---|---|---|
Connection refused |
端口没映射 / 没启动 | docker ps 看容器是否 running；docker logs emqx 看是否启动完成 |
| 连的是 8083 却报拒 | WebSocket 端口 ≠ TCP 端口 | TCP 客户端用 1883，浏览器/WebSocket 才用 8083 |
Connection refused (8883) |
用了 TLS 端口但没配证书 | 先别连 8883，用明文 1883 跑通再上 TLS |
Not authorized（拒绝授权） |
Dashboard 改了认证但客户端没带账号 | 给连接填对 Username/Password，或回 Dashboard 检查认证设置 |
Bad username or password |
账号密码错 | 确认是 EMQX 里创建的用户，不是 Dashboard 的 admin |
Identifier rejected（标识被拒） |
Client ID 重复且开了"踢旧连接"之外的策略 | 换一个唯一的 Client ID（生产里 Client ID 冲突有专门一篇讲） |
Unacceptable protocol version |
客户端和 Broker 的 MQTT 版本不匹配 | 统一用 MQTT 3.1.1 或 5.0（EMQX 默认两者都支持） |
| 本机连得上、别的机器连不上 | 防火墙 / 安全组 | 放通 1883（及 18083）；云服务器要在安全组里加规则 |
| Docker 端口映射了但宿主机不通 | 监听地址绑定 127.0.0.1 或端口被占用 | docker port emqx 看映射；`netstat -tlnp |
八、📌 可拿走资产：部署命令速查
bash
# 启动（显式指定版本）
docker run -d --name emqx -p 1883:1883 -p 8083:8083 -p 8084:8084 -p 8883:8883 -p 18083:18083 emqx/emqx:5.8
# 查看日志
docker logs -f emqx
# 停止 / 启动 / 删除（删除会丢数据，慎用）
docker stop emqx && docker start emqx
docker rm -f emqx # 彻底删除容器
# 看端口映射是否正确
docker port emqx九、写在最后
到这一步，你已经有了一个能跑通收发的本地 MQTT 环境，后面每一篇的实验都能在这个环境上复现。但"跑通"只是开始------MQTT 里最容易用错、也最影响生产的，是 QoS。很多人的理解是"QoS2 最可靠，那就都用 QoS2"，这恰恰是生产事故的起点。
下一篇 第 3 篇：QoS 0/1/2 怎么选？90% 的人用错------QoS2 不是越高越好，我会把三个等级的一次握手流程画给你看，讲清楚"为什么 QoS2 会把你推向凌晨三点的积压事故"。
🔔 评论区提问： 你第一次连 EMQX 是卡在哪个报错上？或者你有没有遇到过"本机通、远程不通"的诡异情况？留言说说，我在故障复盘篇会专门讲网络层那些坑。