基于 Ubuntu 搭建 MQTT 服务器并使用 Python 客户端连接的实践

在物联网和分布式系统中，MQTT 作为轻量级消息协议，越来越受到开发者的青睐。本文将介绍如何在 Ubuntu 上搭建 MQTT 服务器（使用 Mosquitto），并在 Windows 上利用 Python 编写客户端连接和测试消息传输的全过程。

一、在 Ubuntu 上安装与配置 Mosquitto

1. 安装 Mosquitto 服务

首先，更新系统后安装 Mosquitto 及其客户端工具：

sudo apt update
sudo apt upgrade
sudo apt install mosquitto mosquitto-clients

安装完成后，Mosquitto 服务会自动启动。你可以用下面的命令查看服务状态：

sudo systemctl status mosquitto

2. 配置 Mosquitto

编辑主配置文件 /etc/mosquitto/mosquitto.conf，示例如下：

pid_file /run/mosquitto/mosquitto.pid

persistence true
persistence_location /var/lib/mosquitto/

log_dest file /var/log/mosquitto/mosquitto.log

include_dir /etc/mosquitto/conf.d

# 监听端口
listener 1883

# 区分测试和生产环境
allow_anonymous true # 测试环境开放匿名访问
# 如果需要使用用户名密码认证，请使用下面的配置，并删除上面的 allow_anonymous true
# allow_anonymous false
# password_file /etc/mosquitto/passwd

注意： 配置文件中出现了重复的匿名访问设置（例如先 allow_anonymous true 后又设置 allow_anonymous false），后者会覆盖前者。如果是生产环境，建议关闭匿名访问，启用密码认证，并用命令生成密码文件：

sudo mosquitto_passwd -c /etc/mosquitto/passwd your_username

修改配置文件后，记得重启 Mosquitto 服务：

sudo systemctl restart mosquitto

如果需要开放远程访问，请确保 Ubuntu 防火墙允许 1883 端口：

sudo ufw allow 1883/tcp

二、使用 Python 客户端连接 MQTT 服务器

在 Windows 上，我们采用 Python 的 paho-mqtt 库进行 MQTT 客户端开发。

1. 安装 paho-mqtt 库

在命令提示符中执行：

pip install paho-mqtt

2. 编写 Python 客户端代码

新版 paho-mqtt（2.x）使用新版回调 API，回调函数需要多一个 properties 参数。下面是一个简单的示例：

import paho.mqtt.client as mqtt

def on_connect(client, userdata, flags, rc, properties=None):
print("Connected with result code:", rc)
# 连接成功后订阅 test/topic
client.subscribe("test/topic")
# 同时发布测试消息
client.publish("test/topic", "Hello MQTT")

def on_message(client, userdata, msg):
print("Received message:")
print("Topic:", msg.topic)
print("Payload:", msg.payload.decode())

broker_address = "192.168.116.3" # 替换为你的 Ubuntu 服务器 IP
port = 1883

# 创建客户端实例
client = mqtt.Client(client_id="WindowsClient")
client.on_connect = on_connect
client.on_message = on_message

client.connect(broker_address, port, keepalive=60)
client.loop_forever()

在上述代码中：

• on_connect 回调： 成功连接后，客户端订阅了 test/topic，并立即发布一条 "Hello MQTT" 的消息。
• on_message 回调： 收到消息后，打印主题和消息内容。

提示： 如果你希望在连接后继续执行其他任务，而不是被 loop_forever() 阻塞，可以使用 client.loop_start() 来开启后台线程，再在主线程中调用 publish 或其它操作。

3. 运行与测试

运行上述 Python 脚本后，控制台应首先输出类似：

Connected with result code: 0

说明客户端与 MQTT 服务器连接成功。当有消息发布到 test/topic 时，回调函数会打印出接收到的消息内容。

三、常见问题与解决方法

1. 连接被拒绝（ConnectionRefusedError）

• 原因： 可能是服务器未正确配置监听公网接口或防火墙未开放相应端口。
• 解决： 检查 Mosquitto 配置中的 listener 1883 是否正确，并确保没有绑定到 127.0.0.1；同时检查防火墙设置。

2. 回调 API 版本错误

• 原因： paho-mqtt 2.x 版本的回调函数要求多一个 properties 参数，旧版代码会报错。
• 解决： 更新回调函数签名，如上例所示，加入 properties=None 参数。

3. 发布消息位置问题

• 原因： client.loop_forever() 会阻塞线程，后续代码无法执行。
• 解决： 将发布消息的代码放入 on_connect 回调中，或者使用 client.loop_start() 开启后台线程后再调用发布方法。

四、总结

本文介绍了在 Ubuntu 上使用 Mosquitto 搭建 MQTT 服务器的基本步骤，并详细讲解了如何用 Python 客户端连接、订阅和发布消息。希望这篇博客能帮助你快速入门 MQTT 系统的搭建与调试。在实际开发中，可以根据项目需求扩展认证、加密（TLS）以及更多高级功能。

如果你有任何问题或改进建议，欢迎在评论区交流讨论！