📚 课程目录第2章 MQTT基础

2、MQTT基础：MQTT协议核心概念、发布订阅模式、QoS级别

2.1 核心概念：从“设备影子同步报错”说起

在解决设备影子同步报错之前，必须先理解 MQTT 协议本身。MQTT（Message Queuing Telemetry Transport，消息队列遥测传输）是一种基于 TCP/IP 的轻量级发布/订阅消息协议，专为低带宽、高延迟或不可靠网络环境下的物联网设备设计。它的核心设计哲学是“极简、解耦、异步”。

与 HTTP 的“请求-响应”模式不同，MQTT 采用“发布-订阅”模式。这意味着消息的发送者（发布者）和接收者（订阅者）之间不需要直接建立连接，也不需要知道对方的存在。它们之间通过一个称为 Broker（代理服务器） 的中介进行消息路由。设备影子同步正是依赖这一机制：设备端将状态上报到 Broker 的某个主题，云端影子服务订阅该主题并更新影子文档；当云端需要下发期望状态时，影子服务发布消息到另一个主题，设备端订阅该主题接收指令。

理解 MQTT 的三个核心概念是排查影子同步故障的基础：

主题（Topic）：消息的分类标签，采用斜杠分层结构，如 devices/device001/status。Broker 根据主题将消息路由给所有匹配的订阅者。
服务质量（QoS）：消息传递的可靠性等级，分为 0、1、2 三级，直接影响消息是否可能丢失或重复。
会话（Session）：客户端与 Broker 之间的逻辑连接状态，分为持久会话和临时会话，决定了离线消息的存储策略。

  关键认知：设备影子同步报错，往往不是“消息没发出去”，而是“消息发到了错误的主题”或“QoS 等级与 Broker 策略不匹配”。因此，掌握 MQTT 的底层机制是定位问题的第一步。

2.2 发布订阅模式：主题与通配符

MQTT 的主题系统是消息路由的核心。主题采用 UTF-8 字符串，用正斜杠 / 分隔层级，例如 devices/device001/status。主题不需要预先创建，客户端发布或订阅时即隐式创建。这种设计使得系统具有极高的灵活性，但也带来了影子同步中常见的“主题不匹配”问题。

订阅时可以使用通配符来匹配多个主题：

+（单层通配符）：匹配一个层级。例如订阅 devices/+/status 可以匹配 devices/device001/status 和 devices/device002/status，但不能匹配 devices/device001/temp/status。
#（多层通配符）：匹配任意多个层级，必须放在主题末尾。例如订阅 devices/# 可以匹配 devices/device001/status 和 devices/device001/temp/status。

在设备影子场景中，AWS IoT 使用 $aws/things/<thingName>/shadow 作为影子主题前缀，包含以下子主题：

主题后缀	方向	用途
`/update`	设备 → 云端	设备上报最新状态（reported）
`/update/accepted`	云端 → 设备	云端确认 update 成功
`/update/rejected`	云端 → 设备	云端拒绝 update（格式错误等）
`/update/delta`	云端 → 设备	下发期望状态与当前状态的差异
`/get`	设备 → 云端	请求获取完整影子文档
`/get/accepted`	云端 → 设备	返回完整影子文档
`/delete`	设备 → 云端	删除影子文档

常见误区：设备端订阅了 /update/accepted 但忘记订阅 /update/delta，导致云端下发的期望状态无法到达设备，表现为“影子状态不一致”但设备端无任何报错日志。排查时应先确认订阅主题是否完整。

2.3 QoS 级别：消息可靠性的三档选择

MQTT 定义了三个 QoS 级别，用于控制消息传递的可靠性。QoS 级别越高，消息越可靠，但网络开销和延迟也越大。在设备影子同步中，QoS 的选择直接影响同步的最终一致性。

QoS 0（至多一次）：消息发送后不等待确认，可能丢失。适用于实时性要求高、丢失可容忍的遥测数据，如温度传感器每秒上报一次。
QoS 1（至少一次）：消息发送后等待 PUBACK 确认，若超时未收到则重发。消息可能重复，但不会丢失。适用于设备影子状态上报，因为重复的 JSON 状态覆盖不会造成逻辑错误。
QoS 2（恰好一次）：通过四步握手（PUBLISH → PUBREC → PUBREL → PUBCOMP）确保消息不重不漏。适用于计费指令、关键控制命令等对重复敏感的场合。

QoS 的协商机制是：最终生效的 QoS 取发布方 QoS 和订阅方 QoS 中的较小值。例如，发布方以 QoS 1 发布消息，但订阅方以 QoS 0 订阅，则实际传输为 QoS 0。这意味着即使设备端以 QoS 1 发布状态，如果云端影子服务订阅时使用了 QoS 0，消息仍可能丢失。

// 设备端发布影子状态（使用 QoS 1）
mqttClient.publish("$aws/things/device001/shadow/update", 
    JSON.stringify({ "state": { "reported": { "temp": 25.5 } } }), 
    1);  // QoS 1

// 云端影子服务订阅（应使用 QoS 1 或 2）
mqttClient.subscribe("$aws/things/device001/shadow/update", 
    1);  // QoS 1，确保不丢失

2.4 会话与遗嘱：连接状态的隐形因素

MQTT 的会话机制是另一个影响影子同步的关键因素。客户端连接 Broker 时可以指定 cleanSession 标志：

cleanSession = true（临时会话）：连接断开后，Broker 清除该客户端的所有订阅和离线消息。重连后需要重新订阅。
cleanSession = false（持久会话）：Broker 保存客户端的订阅关系，并在客户端离线期间缓存 QoS 1/2 的消息，重连后自动恢复。

在设备影子场景中，如果设备使用临时会话且网络不稳定，频繁断线重连会导致订阅丢失，云端下发的 delta 消息无法到达设备。此外，遗嘱消息（Last Will） 可以在设备异常离线时向指定主题发布一条消息，用于通知云端设备已离线，从而触发影子状态的“离线”标记。

实践建议：对于需要长期保持影子同步的设备，应使用持久会话（cleanSession=false），并将遗嘱消息发布到 $aws/things/<thingName>/shadow/update，内容为 {"state":{"reported":{"online":false}}}，这样云端可以及时感知设备离线。

2.5 案例复盘：一次典型的影子同步失败

某智能路灯项目反馈：设备上报状态成功，但云端影子文档始终不更新。通过抓包分析发现：

设备端发布主题为 devices/light001/status，而云端影子服务订阅的是 $aws/things/light001/shadow/update，两者主题不匹配，消息被 Broker 路由到其他订阅者。
设备端发布 QoS 为 0，在弱网环境下消息丢失，且无重发机制。
设备使用临时会话，每次重连后未重新订阅 /update/delta，导致云端下发的期望状态无法接收。

修复方案：统一主题为 $aws/things/light001/shadow/update，将发布 QoS 提升至 1，并改用持久会话。修复后影子同步恢复正常，状态更新延迟从“永不更新”降至 200ms 以内。