树莓派3B+（Raspbian）MQTT启动失败：缺少callback_api_version参数

问题背景 #

使用无SD卡的树莓派3B+，通过MQTT接收Home Assistant指令控制GPIO，此前运行正常，改为有线网络后3台设备需重装。按官方文档重新安装后，supervisor启动pi_mqtt_gpio时卡在STARTING状态，日志报错：

pi@raspberrypi005:~ $ sudo tail /var/log/pi-mqtt-gpio.log
    return _run_code(code, main_globals, None,
  File "/usr/lib/python3.9/runpy.py", line 87, in _run_code
    exec(code, run_globals)
  File "/home/pi/ve/lib/python3.9/site-packages/pi_mqtt_gpio/server.py", line 1269, in <module>
    main(args)
  File "/home/pi/ve/lib/python3.9/site-packages/pi_mqtt_gpio/server.py", line 1064, in main
    client = init_mqtt(config["mqtt"], config["digital_outputs"], config["stream_writes"])
  File "/home/pi/ve/lib/python3.9/site-packages/pi_mqtt_gpio/server.py", line 410, in init_mqtt
    client = mqtt.Client(client_id=client_id, clean_session=False, protocol=protocol)
TypeError: __init__() missing 1 required positional argument: 'callback_api_version'

已尝试：旧版Raspbian（32/64位）、不同Python版本（含3.7.3、Pyenv切换版本），排除Home Assistant配置问题（另外2台设备正常运行）。

原因分析 #

报错根源是paho-mqtt版本不兼容：pi_mqtt_gpio的旧代码基于paho-mqtt v1.x版本编写，新安装环境会自动拉取最新的paho-mqtt v2.0+版本，该版本对mqtt.Client()初始化方法新增了强制必填的callback_api_version参数，旧代码未适配此变化。

解决方案 #

方案1：降级paho-mqtt到兼容版本

在虚拟环境中执行以下命令：

# 进入虚拟环境
source /home/pi/ve/bin/activate
# 卸载当前paho-mqtt
pip uninstall -y paho-mqtt
# 安装兼容的1.x版本（示例为1.6.1）
pip install paho-mqtt==1.6.1

重启supervisor服务：

sudo supervisorctl restart pi_mqtt_gpio

方案2：修改pi_mqtt_gpio代码适配新版本

若需使用paho-mqtt v2.0+，修改/home/pi/ve/lib/python3.9/site-packages/pi_mqtt_gpio/server.py第410行，添加callback_api_version参数：

# 修改前
client = mqtt.Client(client_id=client_id, clean_session=False, protocol=protocol)
# 修改后
client = mqtt.Client(client_id=client_id, clean_session=False, protocol=protocol, callback_api_version=mqtt.CallbackAPIVersion.VERSION1)

保存文件后重启supervisor服务即可。

方案3：锁定依赖版本（避免后续重装出问题）

在虚拟环境的requirements.txt中添加固定版本的paho-mqtt，防止下次安装自动更新：

paho-mqtt==1.6.1

内容的提问来源于stack exchange，提问作者user1527079