智能制造与工业软件 / 系统课时
用遗嘱消息感知网关异常离线
用遗嘱消息感知网关异常离线
网关断电或网络中断时,它通常来不及主动报告离线。可以让 MQTT Broker 在连接建立时保存遗嘱消息,并在检测到异常断开后代发 offline。本篇使用本地 Broker 与 Python 客户端,复现正常退出和静默失联两种情况,并判断通知为何可能滞后。
学习目标
- 正确设置 Keep Alive、Will Topic、QoS 和 Retain。
- 复现异常静默触发遗嘱,并与正常
DISCONNECT对照。 - 区分 MQTT 连接离线、网关实际故障和设备离线。
遗嘱的触发边界
网关发送 CONNECT 时声明遗嘱主题 factory/gateway/edge-gw-01/status、载荷 offline、QoS 1、Retain 为 true。Broker 保存这份声明;网关成功连接后自行向同一主题发布保留消息 online。监控程序订阅该主题,接收状态变化。
设置 Keep Alive 为 10 秒,表示客户端在没有其他 MQTT 控制报文时也要发送 PINGREQ。按照 MQTT 3.1.1,Broker 在距最后一份客户端控制报文超过约 1.5 倍 Keep Alive(本例约 15 秒)仍未收到消息时,会断开连接并发布遗嘱。计时起点不是设备断电时刻,也不是测试人员按下暂停键的时刻。
| 连接情况 | 是否触发遗嘱 | 判断依据 |
|---|---|---|
客户端正常发送 DISCONNECT |
否 | Broker 知道是正常退出 |
| 连接被异常关闭且 Broker 立即感知 | 是 | 不必等满 Keep Alive |
| TCP 未关闭,但客户端持续静默 | 是 | Broker 等待保活超时 |
| Broker 自身故障或重启 | 不保证及时发布 | Broker 也可能失去代发能力 |

启动本地 Broker 并配置网关
以下命令适用于 Linux、macOS 或 WSL 的 Bash,需预装 Docker 和 Python 3。Mosquitto 2.x 容器使用内置的无认证演示配置,并且只把 1883 端口映射到宿主机回环地址;不要将该配置暴露到生产网络。
docker run --rm -d --name mqtt-will-lab \
-p 127.0.0.1:1883:1883 \
eclipse-mosquitto:2 mosquitto -c /mosquitto-no-auth.conf
python3 -m pip install "paho-mqtt==2.1.0"预期结果:Docker 输出一个容器 ID,Python 依赖安装成功;容器对本机 127.0.0.1:1883 提供 MQTT 服务。容器 ID 和安装日志因环境而异。
将以下完整程序保存为 mqtt_will_demo.py。观察者与网关使用不同的 Client ID;网关必须在 connect() 之前调用 will_set(),网络循环负责定期发送保活报文。代码采用 Paho MQTT Python 2.1.0 的 VERSION2 回调接口、MQTT 3.1.1 协议。
import os
import sys
import time
import paho.mqtt.client as mqtt
TOPIC = "factory/gateway/edge-gw-01/status"
def on_connect(client, mode, flags, reason_code, properties):
if reason_code != 0:
print(f"连接失败: {reason_code}", flush=True)
return
if mode == "watch":
client.subscribe(TOPIC, qos=1)
else:
# 重连后覆盖旧的保留离线状态
client.publish(TOPIC, "online", qos=1, retain=True)
def on_message(client, mode, message):
print(f"{message.topic} {message.payload.decode('utf-8')}", flush=True)
def main():
mode = sys.argv[1] if len(sys.argv) == 2 else ""
if mode not in ("watch", "gateway"):
raise SystemExit("用法: python3 mqtt_will_demo.py watch|gateway")
client_id = "status-watch-01" if mode == "watch" else "edge-gw-01"
client = mqtt.Client(
mqtt.CallbackAPIVersion.VERSION2,
client_id=client_id,
userdata=mode,
protocol=mqtt.MQTTv311,
)
client.on_connect = on_connect
client.on_message = on_message
if mode == "gateway":
# Will 必须在 connect 前设置
client.will_set(TOPIC, "offline", qos=1, retain=True)
client.connect("127.0.0.1", 1883, keepalive=10)
client.loop_start()
print(f"mode={mode} pid={os.getpid()}", flush=True)
try:
while True:
time.sleep(1)
except KeyboardInterrupt:
client.disconnect()
client.loop_stop()
if __name__ == "__main__":
main()预期结果:watch 在连接后订阅状态主题;gateway 在每次成功连接后发布 online,异常断线才由 Broker 代发保留的 offline。pid 是系统分配的进程 ID,实际值会变化。
对照验证静默超时与正常退出
- 终端 A 执行
python3 -u mqtt_will_demo.py watch,保持订阅。 - 终端 B 执行
python3 -u mqtt_will_demo.py gateway,记下显示的pid;终端 A 应先收到online。 - 在终端 C 执行
kill -STOP 12345,把12345换成网关实际 PID。该操作暂停整个进程但不主动关闭 TCP 连接,可模拟客户端不再发送任何报文。 - 观察终端 A 收到
offline,然后执行kill -CONT 12345恢复网关;如果客户端完成自动重连,应再次收到online。 - 网关恢复在线后,在终端 B 按
Ctrl+C正常退出。观察者不应因此收到新的遗嘱offline。
预期输出(终端 A,以下三行依次出现;最后一次正常退出不会增加第四行):
factory/gateway/edge-gw-01/status online
factory/gateway/edge-gw-01/status offline
factory/gateway/edge-gw-01/status onlineoffline 的出现时间取决于最近一次 MQTT 控制报文与 Broker 的超时检查,不是执行 kill -STOP 后精确 15 秒。若改为强制结束进程并使 TCP 连接立即关闭,Broker 可能几乎立即发送遗嘱。上述 SIGSTOP、SIGCONT 仅适用于支持这些信号的 Linux、macOS 或 WSL 环境。
避免把连接异常误判为设备故障
Will 说明的是 Broker 与网关的 MQTT 连接异常终止,不证明 PLC、传感器或整台网关已经断电。反过来,网关正常发送 DISCONNECT 后不会触发遗嘱;因为本例启用了 Retain,之前的 online 仍可能保留,后加入的订阅者也会读到这个旧状态。
生产环境可在计划停机时先主动发布 maintenance 或 offline(QoS 1,等待确认),再正常断开;监控端除接收 Will 外,还记录服务端观察到的最近业务数据时间。比如业务测点要求 30 秒内更新,超过 30 秒未收到有效数据即可标为“数据陈旧”,不要仅凭 online 判断采集仍正常。QoS 1 允许重复投递,状态处理应具备幂等性。
本例使用 MQTT 3.1.1,没有可配置的遗嘱发布延迟:读到的等待主要来自异常连接检测。MQTT 5 另有 Will Delay Interval,可在连接关闭后延后发布遗嘱;两种延迟不能混为一谈。