MQTT通信由消息服务器和客户端共同完成。EMQX负责接收并转发消息，MQTTX负责建立连接、订阅主题和发送消息。本教程在一台Windows电脑上完成服务器启动、账号认证和两个客户端的消息互通，适合了解发布订阅流程和开发对接。
适用环境与软件下载
图文步骤采用EMQX 5.3.0的Windows原生安装包。EMQX自5.4.0起停止发布Windows原生安装包，本教程中的5.3.0属于历史版本；新版本部署可使用官方提供的Linux或容器安装方式。MQTTX可从官网选择当前适合自己电脑的桌面安装包。
下载MQTTX桌面客户端，创建连接并查看发布订阅消息。
MQTTX官方下载 ↗| 软件 | 用途 | 下载入口 |
|---|---|---|
| EMQX 5.3.0 Windows | 本教程图文环境的本地MQTT服务器 | 历史Windows安装包 |
| MQTTX Desktop | MQTT连接、订阅与发布 | MQTTX官方下载页面 |
本地联调使用两个端口：1883用于MQTT连接，18083用于EMQX Dashboard。服务器与客户端位于同一台电脑时，客户端地址填写127.0.0.1。
下载并解压EMQX Windows安装包
下载emqx-5.3.0-windows-amd64.zip，解压到路径简短的文件夹，例如D:\EMQX。解压后应能看到bin、etc、data和log等目录。下图为5.3.0的下载和解压界面。
在Windows终端启动EMQX
进入解压目录下的bin文件夹，在该目录打开PowerShell，运行安装包内的启动脚本：
cd D:\EMQX\bin
.\emqx.cmd start启动后查看终端输出，确认没有启动错误。服务的配置和运行日志分别位于解压目录的etc与log文件夹。
打开本地Dashboard并设置管理密码
浏览器访问http://localhost:18083/。使用该安装版本的初始化登录信息进入Dashboard，完成管理员密码设置。Dashboard账号用于管理服务器；下一节创建的MQTT用户用于客户端连接，两者用途不同。
进入概览页后，可以查看当前连接、订阅和消息统计。服务器与MQTTX同机运行时，无需把管理端口开放到公网。
创建用户名与密码认证
在Dashboard的访问控制中进入认证管理，创建认证规则。认证方式选择Password-Based，数据源选择内置数据库。
- 选择基于密码的认证方式。
- 选择内置数据库，使用EMQX保存和管理客户端用户。
- 账号类型选择
username。图示5.3.0环境采用sha256和suffix配置。 - 完成创建后进入用户管理。
创建两个独立客户端账号，本文分别使用MQTT1和MQTT2作为示例用户名；各账号设置自己的密码，并按发布、订阅主题配置访问权限。后续在MQTTX中填写与服务器一致的账号信息。
下载MQTTX并创建两条连接
通过MQTTX官方下载页面下载桌面客户端。安装并打开后，可以在设置中切换简体中文。创建两条连接，或并排打开两个客户端窗口，分别用于发送和接收消息。
下表对应本机联调环境。Host中填写地址即可，协议在单独的下拉框选择。
| 配置项 | 客户端1 | 客户端2 |
|---|---|---|
| 名称 | MQTT1 | MQTT2 |
| Client ID | hao1 | hao2 |
| 协议 | mqtt:// | mqtt:// |
| Host | 127.0.0.1 | 127.0.0.1 |
| 端口 | 1883 | 1883 |
| 用户名 | MQTT1 | MQTT2 |
| 密码 | 该账号自行设置的密码 | 该账号自行设置的密码 |
| MQTT协议版本 | 3.1.1 | 3.1.1 |
两个连接的Client ID必须不同。填写参数后分别连接服务器，并在EMQX概览或客户端列表中查看连接状态。MQTTX的产品名称与连接使用的MQTT协议版本是两个不同概念，本例采用MQTT 3.1.1。
设置发布主题与JSON消息
客户端1发布温度消息，客户端2发布湿度消息。主题名称区分大小写，发布与订阅时保持一致。
| 客户端 | 发布主题 | 消息内容 |
|---|---|---|
| 客户端1 | /MQTT1/pub | {"wendu":23.56} |
| 客户端2 | /MQTT2/pub | {"shidu":77.56} |
发送区的消息格式选择JSON，再填写消息内容。先完成下一节的订阅，再进行发布，便于观察实时消息。
让两个客户端交叉订阅
客户端1订阅/MQTT2/pub，用于接收客户端2的湿度消息；客户端2订阅/MQTT1/pub，用于接收客户端1的温度消息。在新建订阅中填写对应主题并保存。
消息接收区可选择JSON显示格式，并切换为只显示已接收消息，使发送与接收记录更容易区分。
发布消息并检查接收结果
- 确认两条连接均已建立，并完成对应主题的订阅。
- 在客户端1发布
{"wendu":23.56}，查看客户端2接收区的主题与消息。 - 在客户端2发布
{"shidu":77.56}，查看客户端1接收区的主题与消息。 - 再次修改数值并发布，观察接收区是否出现新的消息记录。
两端能接收对方主题下的消息，即可确认本机的连接、认证、订阅和发布链路已经打通。
常见问题与排查
MQTTX连接1883还是18083？
MQTT客户端连接1883。18083用于浏览器打开EMQX Dashboard，两者不能混用。
连接成功却收不到消息，先检查什么？
先确认接收端已订阅，再核对主题的大小写与斜杠是否一致，并检查该账号是否有对应主题的订阅权限。
两条连接为什么会互相断开？
检查Client ID是否重复。同一服务器上的两个独立客户端应使用不同Client ID。
其他电脑能填写127.0.0.1连接这台服务器吗？
不能。127.0.0.1始终指向客户端所在电脑。跨电脑连接应填写服务器可达地址，并核对MQTT监听地址和防火墙设置。
这篇教程是否适用于最新EMQX Windows安装包？
图文步骤对应EMQX 5.3.0历史Windows环境。EMQX自5.4.0起停止发布Windows原生安装包，新版本可采用官方Linux或容器安装方式。
对接物联地带与设备指令
上述步骤建立的是本地EMQX通信环境。对接物联地带时，使用平台提供的地址、账号、设备SN和主题规则；本教程的本地账号及/MQTT1/pub等主题不对应平台设备主题。
设备状态订阅、控制命令与HTTP接口可查看物联地带API接入指南。通道控制命令可通过设备指令生成器选择通道数量和动作后生成。
图文版权与许可
原作者：豪哥追求卓越。原文：《Windows系统下本地MQTT服务器搭建（保姆级教程）》。原文及配图采用CC BY-SA 4.0许可。
本教程对文字结构、版本说明、连接参数表和下载入口进行了改写，保留原作者配图中的署名；本页图文教程的改编内容同样采用CC BY-SA 4.0许可。
