一、MQTT 简介MQTTMessage Queuing Telemetry Transport是一种基于发布/订阅模式的轻量级消息传输协议广泛应用于物联网、传感器数据采集、即时通讯等场景。MQTT 的核心架构包含三个角色Broker消息代理负责接收、过滤和分发消息的中间服务器。Publisher发布者向 Broker 指定主题发送消息的客户端。Subscriber订阅者从 Broker 订阅主题并接收消息的客户端。本教程选用Eclipse Mosquitto作为 Broker它是目前最流行的开源 MQTT Broker 之一支持 MQTT 3.1、3.1.1 和 5.0 协议并自带mosquitto_pub和mosquitto_sub命令行客户端工具。下面分别讲解在 Windows 和 Linux 上的安装与使用方法。二、Windows 平台安装与使用2.1 下载与安装打开浏览器访问 Mosquitto 官方下载页面https://mosquitto.org/download/在 “Binary installation” 区域下载 Windows 安装程序64 位或 32 位文件名为mosquitto-x.x.x-install-windows-x64.exe或类似格式。双击运行安装程序在安装向导中勾选Service组件这样 Mosquitto 会注册为 Windows 服务开机自动启动。默认安装路径为C:\Program Files\mosquitto。按照向导完成安装点击 Finish。静默安装可选在命令行中执行mosquitto-2.0.15-install-windows-x64.exe /S可无界面安装使用/D参数可指定安装目录。2.2 将 Mosquitto 添加到系统 PATH推荐为了方便在任意命令行窗口中直接使用mosquitto、mosquitto_pub、mosquitto_sub等命令建议将安装目录加入系统环境变量打开 “开始” 菜单搜索并进入 “编辑系统环境变量”。点击 “环境变量” → 在 “系统变量” 中找到Path→ 点击 “编辑”。点击 “新建”添加路径C:\Program Files\mosquitto。点击确定保存。2.3 配置 Mosquitto默认情况下Mosquitto 只监听本地回环地址不允许远程连接。如需让局域网内其他设备连接需要修改配置文件以管理员身份打开记事本打开文件C:\Program Files\mosquitto\mosquitto.conf。找到#listener行取消注释并设置为listener 1883这样 Mosquitto 会监听所有网络接口的 1883 端口。找到#allow_anonymous true行取消注释改为allow_anonymous true这允许匿名连接仅建议在测试环境使用。保存文件。2.4 管理 Mosquitto 服务安装完成后Mosquitto 已作为 Windows 服务自动运行。如需重启使配置生效以管理员身份打开命令提示符CMD执行net stop mosquitto net start mosquitto也可以按Win R输入services.msc在服务列表中找到 “Mosquitto Broker” 进行启动、停止或重启操作。2.5 配置 Windows 防火墙如果允许外部设备连接需要放行 1883 端口打开 “Windows Defender 防火墙” → “高级设置”。点击 “入站规则” → “新建规则”。选择 “端口” → “TCP” → 输入 “特定本地端口”1883。选择 “允许连接”勾选所有网络类型命名规则为 “MQTT” 后完成。也可以同时添加程序规则允许C:\Program Files\mosquitto\mosquitto.exe通过防火墙。2.6 基本测试打开两个命令提示符窗口窗口 1 — 订阅主题mosquitto_sub -h localhost -t test/topic -v窗口 2 — 发布消息mosquitto_pub -h localhost -t test/topic -m hello world发布后窗口 1 应显示test/topic hello world说明 Broker 工作正常。三、Linux 平台安装与使用以 Ubuntu 24.04 为例进行讲解其他发行版如 CentOS/RHEL步骤类似包管理器命令有所不同。3.1 安装 Mosquitto 及客户端在终端中执行sudoaptupdatesudoaptinstall-ymosquitto mosquitto-clientsmosquitto是 Broker 服务端mosquitto-clients包含mosquitto_pub和mosquitto_sub命令行工具。安装完成后可以验证版本mosquitto-v3.2 管理 Mosquitto 服务Mosquitto 在 Ubuntu 中通过 systemd 管理。常用命令# 查看服务状态sudosystemctl status mosquitto# 启动服务sudosystemctl start mosquitto# 停止服务sudosystemctl stop mosquitto# 重启服务修改配置后使用sudosystemctl restart mosquitto# 设置开机自启并立即启动sudosystemctlenable--nowmosquitto默认安装后 Mosquitto 可能仅允许本地连接需要根据需求调整配置。3.3 配置 MosquittoMosquitto 的主配置文件位于/etc/mosquitto/mosquitto.conf但更推荐在/etc/mosquitto/conf.d/目录下创建独立的配置文件便于管理和覆盖。创建配置文件sudonano/etc/mosquitto/conf.d/default.conf添加以下内容listener 1883 allow_anonymous truelistener 1883监听所有网络接口的 1883 端口允许远程连接。allow_anonymous true允许匿名连接仅限测试环境生产环境应启用认证。保存后重启服务sudosystemctl restart mosquitto3.4 配置防火墙Ubuntu 默认使用ufw防火墙放行 1883 端口sudoufw allow1883如果使用firewalldCentOS/RHEL则执行sudofirewall-cmd--permanent--add-port1883/tcpsudofirewall-cmd--reload3.5 基本测试打开两个终端窗口终端 1 — 订阅mosquitto_sub-hlocalhost-thome/sensor/temperature-v终端 2 — 发布mosquitto_pub-hlocalhost-thome/sensor/temperature-m23.5终端 1 会实时显示收到的消息。使用-q 1参数可指定 QoS 等级-r参数可设置保留消息。3.6 使用 Docker 部署可选方案如果偏好容器化部署可以使用官方 Mosquitto Docker 镜像dockerrun-d\--namemosquitto\-p1883:1883\-v$(pwd)/mosquitto.conf:/mosquitto/config/mosquitto.conf\eclipse-mosquitto其中-p 1883:1883将容器端口映射到宿主机-v挂载自定义配置文件。如果使用默认配置直接运行可简化为dockerrun-d--namemosquitto-p1883:1883 eclipse-mosquitto需要注意的是Docker 部署时也要确保宿主机防火墙放行了 1883 端口且配置文件中的listener应设置为0.0.0.0以允许外部访问。四、启用密码认证安全加固匿名访问仅适合本地测试。在对外提供服务时应启用用户名/密码认证。Windows以管理员身份打开命令提示符进入 Mosquitto 安装目录执行cd C:\Program Files\mosquitto mosquitto_passwd.exe -c passwd.txt yourusername系统会提示输入密码。-c表示创建新文件后续添加用户时去掉-c即可。编辑mosquitto.conf修改为allow_anonymous false password_file C:\Program Files\mosquitto\passwd.txt重启 Mosquitto 服务。Linuxsudomosquitto_passwd-c/etc/mosquitto/passwd yourusername输入密码后编辑配置文件allow_anonymous false password_file /etc/mosquitto/passwd重启服务sudo systemctl restart mosquitto。启用认证后客户端连接时需要携带用户名和密码mosquitto_pub-hlocalhost-ttest-mhello-uyourusername-Pyourpassword五、Python 客户端使用示例Mosquitto 自带的命令行工具适合快速测试实际项目中通常使用编程语言的客户端库。Python 推荐使用paho-mqttpipinstallpaho-mqtt订阅端代码subscriber.pyimportpaho.mqtt.clientasmqttdefon_connect(client,userdata,flags,rc,propertiesNone):ifrc0:print(Connected to MQTT Broker!)client.subscribe(home/sensor/temperature)else:print(fConnection failed with code{rc})defon_message(client,userdata,msg):print(fReceived {msg.payload.decode()} from {msg.topic})clientmqtt.Client(mqtt.CallbackAPIVersion.VERSION2)client.on_connecton_connect client.on_messageon_message client.connect(localhost,1883,60)client.loop_forever()发布端代码publisher.pyimportpaho.mqtt.clientasmqtt clientmqtt.Client(mqtt.CallbackAPIVersion.VERSION2)client.connect(localhost,1883,60)client.publish(home/sensor/temperature,25.6)client.disconnect()print(Message published.)先运行 subscriber.py再运行 publisher.py订阅端将输出Received 25.6 from home/sensor/temperature。六、常见问题与排查Q1客户端无法远程连接到 Broker检查三处① 配置文件中是否设置了listener 1883且没有绑定127.0.0.1② 防火墙是否放行 1883 端口③ Windows 上是否将 Mosquitto 服务配置为允许外部连接。Q2Windows 上mosquitto命令找不到将C:\Program Files\mosquitto添加到系统 PATH 环境变量后重新打开命令提示符即可。Q3如何验证 Broker 是否正在监听 1883 端口Windowsnetstat -ano | findstr 1883Linuxsudo ss -tlnp | grep 1883Q4Mosquitto 默认只允许本地连接怎么办这是 Mosquitto 2.x 的安全默认行为。在配置文件中显式添加listener 1883即可允许远程连接。Q5如何测试公网/远程 Broker可以使用 Mosquitto 官方提供的公共测试服务器test.mosquitto.orgmosquitto_pub-htest.mosquitto.org-ttest/topic-mhellomosquitto_sub-htest.mosquitto.org-ttest/topic-v以上即为 MQTTMosquitto Broker在 Windows 和 Linux 平台上从安装、配置、测试到安全加固和编程使用的完整教程。建议先在本地环境完成基本测试再逐步引入密码认证和 TLS 加密以适应生产环境需求。