MQTT 3.1.1/5.0速成：Mosquitto安装与调试实战总结

MQTT约束

• MQTT版本：MQTT 3.1.1、MQTT 5.0
• Broker服务器：Mosquitto (开源)
• 传输数据格式：JSON
• 文件编码：UTF-8
• QOS：重要指令是QOS1，循环上报的是QOS0

Mosquitto 安装与依赖

# Mosquitto (开源)
sudo apt install mosquitto mosquitto-clients
# 启动并且设置开机自启动
sudo systemctl start mosquitto
sudo systemctl enable mosquitto
# 关闭
sudo systemctl stop mosquitto
# 依赖
sudo apt-get install -y libmosquitto-dev libmosquittopp-dev libjsoncpp-dev libyaml-cpp-dev libpaho-mqtt-dev libpaho-mqttpp-dev

安装Paho MQTT C库

# 安装依赖
sudo apt-get update
sudo apt-get install build-essential cmake libssl-dev

# 编译安装Paho MQTT C库
cd ~
git clone https://github.com/eclipse/paho.mqtt.c.git
cd ~/paho.mqtt.c
mkdir build && cd build
# 加上DPAHO_WITH_SSL=TRUE编译ssl安全认证版本
cmake -DPAHO_BUILD_STATIC=ON -DPAHO_BUILD_SHARED=ON -DPAHO_BUILD_DOCUMENTATION=OFF -DPAHO_BUILD_SAMPLES=OFF -DPAHO_WITH_SSL=TRUE ..
make
sudo make install
sudo ldconfig
# ------------------------------------------------------------------------------
# 卸载重新编译
# 进入源码目录并执行卸载
cd ~/paho.mqtt.c/build
sudo make uninstall
# 清理编译缓存
cd ~/paho.mqtt.c
sudo rm -rf build
*# 查找并删除残留的库文件和头文件*
find /usr/local/lib /usr/local/include -name "*paho*" -exec sudo rm -rf {} \;
*# 更新动态链接库缓存*
sudo ldconfig
# ------------------------------------------------------------------------------

# 安装Paho MQTT C++库
cd ~
git clone https://github.com/eclipse/paho.mqtt.cpp.git
cd paho.mqtt.cpp
mkdir build && cd build
cmake -DPAHO_WITH_SSL=OFF ..
make
sudo make install
sudo ldconfig

JSON类型说明对照表

JSON类型	对应语言类型	说明
string	string / char*	字符串
integer	int / long	整数
number	float / double	数字（含小数）
boolean	bool	布尔值
object	struct / class / dict	对象/结构体
array	vector / list / array	数组
null	nullptr / NULL / None	空值

MQTT定位手段

检查Broker进程

# 查看Mosquitto服务状态
sudo systemctl status mosquitto
# 或查看进程
ps aux | grep mosquitto

测试网络连通性与端口

# 测试Broker主机是否可达
ping <broker_ip>
# 测试1883端口是否开放 (如果未安装telnet，使用nc)
telnet <broker_ip> 1883
# 或使用 netcat
nc -zv <broker_ip> 1883

监听所有经过Broker的消息，实时查看出现的主题和内容

mosquitto_sub -t "#" -v

使用通配符监听业务流量

# 监听所有应用层主题（通常需要权限）
mosquitto_sub -h <broker_ip> -t "#" -v

基础订阅测试

# 在终端1：订阅一个特定主题并等待消息
mosquitto_sub -h <broker_ip> -t "test/status" -v
# 在终端2：向同一个主题发布消息
mosquitto_pub -h <broker_ip> -t "test/status" -m "hello"

订阅系统主题 ($SYS/#)

# 获取Broker的内部指标（连接数、消息计数、版本等）
#$SYS/broker/clients/connected：当前连接数。
#$SYS/broker/messages/received：Broker累计接收消息数
mosquitto_sub -h <broker_ip> -t "\$SYS/#" -v

启用并分析Broker日志

<a href="javascript:;">#修改Mosquitto配置</a> (mosquitto.conf)
log_dest file /var/log/mosquitto/mosquitto.log
log_type all  # 可改为 warning, error, info, debug 等控制详细程度
connection_messages true  # 详细记录连接信息
<a href="javascript:;">#查看日志</a>
sudo tail -f /var/log/mosquitto/mosquitto.log

数据包抓取分析

sudo tcpdump -i any port 1883 -w mqtt_capture.pcap

用 Wireshark 打开 .pcap 文件，可以无损解析所有MQTT报文（CONNECT, PUBLISH, SUBSCRIBE），精确查看每个字段，是诊断协议级问题的金标准。

利用管理HTTP API（如EMQX）

<a href="javascript:;">#现代Broker</a>（如EMQX）提供丰富的API，可编程化查询客户端、主题、订阅信息。
*# 示例：查询EMQX的客户端列表*
curl -u admin:public http://<broker_ip>:18083/api/v4/clients

图像化工具

MQTT Explorer：强烈推荐。像“文件管理器”一样浏览所有主题，实时查看消息，直观展示主题树。
MQTT.fx / MQTTX：优秀的通用客户端，方便测试连接、发布订阅和格式化报文。

前台启动查看信息

mosquitto -v

常用验证定位手段

# 终端A：订阅
mosquitto_sub -t "sensor/#" -v
# 终端B：发布
mosquitto_pub -t "sensor/temperature" -m "25.6"
# 终端A：订阅
mosquitto_sub -t "test/topic" -v
# 终端B：发布
mosquitto_pub -h localhost -t "test/topic" -m "Test message from mosquitto"

模拟发送MQTT主题

客户端下载：https://mqttx.app/zh

网页版：http://www.emqx.io/online-mqtt-client