设备影子与物模型:把「命令下发成功」这句话拆成四个问题
学习目标
- 能说出物模型里属性、服务、事件三者的方向差异,并判断一个字段该定义成哪一种。
- 能画出期望态、上报态、差值三者的关系,说清为什么影子不能当审计日志用。
- 会为批量指令设计幂等键和超时判据,并能解释"投递成功"和"执行成功"为什么是两件事。
- 能独立判断一条
online状态是怎么算出来的,而不是只看 TCP 连接数。
1. 先把现场钉死:一条返回 200 的命令为什么没生效
2026 年 3 月某个凌晨,一个智慧照明项目在控制台点了「全场调光到 30%」。
接口返回 200,下发日志显示 12,431 台设备全部投递成功。
第二天巡检,3,000 多盏灯还停在 100% 亮度。运维的第一判断是灯坏了,第二批人的判断是平台丢了指令。
两个判断都不对。那 3,000 多台设备正在休眠上报周期里,MQTT 连接早断了;平台把"写进 broker"记成了"设备已执行"。
要把这条链路拆开,先回答:一次下发里有几次"成功",每次各代表什么。
2. 知识位置:协议之上还有一层,那一层才是设备管理
左边是业务,右边是硬件,中间那一列才是本文的主题。把 B 和 C 当成一回事的人,会用 topic 名当设备模型、用 broker 会话数当在线数。后面的事故基本都从这里长出来。
MQTT 只保证字节到了某个 topic。它不知道 power 是布尔还是枚举,也不知道这条消息该不该重发。
3. 物模型:给每个字段一个类型、一个单位、一份权限
物模型(Thing Model,阿里云文档里叫 TSL)是一份结构化描述:这台设备有哪些数据、能接受哪些动作、会上报哪些事件。它落成 JSON,用 identifier 而不是中文名做键。
三个反例,都是我在项目里真见过的。
反例一:温度定义成 string。下游做告警规则时得先 parseFloat,一次解析失败整条规则静默失效。类型是契约,不是备注。
反例二:没有单位,也没有量程。temperature: 235 是 23.5℃ 还是 235℃?固件按 0.1℃ 放大上报,云端按整度展示,两边都没错,数字差了十倍。
反例三:只读属性被云端写。电量百分比由设备上报,云端为了"修正"直接写了一版,设备下一次上报又覆盖回去,两边打架,看板上数字开始跳。
| 要素 | 数据方向 | 典型内容 | 常见误用 |
|---|---|---|---|
| 属性 property | 双向(可读可写)或单向(只读) | 亮度、目标温度、固件版本 | 把只读量设成可写,导致双写打架 |
| 服务 service | 云端调用,设备应答 | 校准、重启、抓日志 | 把长耗时动作做成同步服务,必然超时 |
| 事件 event | 设备上报 | 故障码、门磁触发、低电告警 | 用属性模拟事件,丢了发生次数 |
属性是状态,事件是事实。状态可被覆盖,事实不能。用属性承载事件,等于只留最后一次告警。
4. 影子:期望态和上报态是两本账,不是一本流水
设备影子的最小模型只有三个字段:期望态 desired(云端希望设备变成什么)、上报态 reported(设备说自己现在是什么)、差值 delta(两者不一致的部分)。
{
"state": {
"desired": { "brightness": 30, "mode": "auto" },
"reported": { "brightness": 100, "mode": "manual" }
},
"metadata": { "desired": { "brightness": { "timestamp": 1770000000 } } }
}这份影子的意思很明确:云端要 30%,设备还在 100%,模式也没对上。设备重连后拉一次,就知道往哪收敛。
这里有个必须记住的限制:影子只存最新值,不存历史。ThingsBoard 的属性文档写得很直白——属性是半静态数据,平台只保留最后一次的值;要时间序列得走遥测通道。所以别拿影子做审计:凌晨三点到底被改过几次,它答不上来。
反例:把 desired 当命令队列用。连发三条 desired.brightness = 30/40/50,设备只会看到最后一条,中间两条在这套模型里根本不存在。这是设计使然。要每条都执行,得走指令通道。
一个容易忽略的顺序问题
设备上报 reported 的同时,如果平台顺手把 desired 也清了,会出现"设备已到目标值、期望态被抹掉"的状态。下次设备离线重连拉影子,看到的是空 desired,于是不改。看起来一切正常,实际上下一次批量调光会重新打一遍全量。期望态的生命周期要显式设计,别让它跟着上报被隐式清空。
5. 批量下发:超时、幂等、串行阻塞,三个坑排队等你
批量下发最容易出事的地方不在并发量,在语义。先把失败模式列清楚。
| 失败模式 | 现象 | 判据 |
|---|---|---|
| 设备离线 | 消息进了 broker,没有订阅者 | 会话未建立 / 无 PUBACK,不能算成功 |
| 设备收到但没执行 | 电量不足、正在 OTA | 只有业务回执能证明,连接层证明不了 |
| 执行了但回执丢了 | 灯变了,日志没记 | 回执要带指令 ID,靠 ID 对账而不是靠时间 |
| 重复投递 | 同一指令执行两次 | 设备侧按 commandId 去重,窗口期要够长 |
第三条和第四条是同一个问题的两面:没有幂等键的重试,本质是把网络问题转换成业务问题。所以下发消息里必须自带一个业务侧生成的 commandId,设备本地保留最近 N 条已执行的 ID。去重窗口在设备侧怎么存,见 把五种固件结构选择摊开讲。
ThingsBoard 的 RPC 文档里有两个数字值得记住:默认等待投递超时是 10,000 毫秒,最小值 5,000 毫秒(RPC 文档,截至 2026 年 11 月未变)。它把命令分成两类——轻量级(lightweight)只在内存里活着,设备离线就直接丢;持久化(persistent)落库并带可配 TTL,设备重连后会补发。
{
"method": "setBrightness",
"params": { "value": 30, "commandId": "cmd-20260317-7f3a" },
"timeout": 15000,
"persistent": true,
"expirationTime": 600000
}这是我在项目里用的形状:commandId 自行添加,平台不校验,但设备侧去重有了依据;expirationTime 给十分钟——凌晨调的光不该在中午补上。
这里有一处只有真做过才会记住的细节:ThingsBoard 的持久化两向 RPC 对同一台设备是串行投递的,一次只有一条在飞。如果一条等回执的命令卡住,后面所有命令都排在它后面。文档里也写了这个组合风险:高重试次数 + 长过期时间,会让一条卡住的 RPC 堵住整台设备。我遇到过一次批量重启,一条 reboot 等回执等了 40 分钟,那台设备上后续 11 条命令全部超时——设备其实是活的,只是命令队列堵着。
由此得出一个判断:会重启、会掉电的动作不要用两向持久 RPC,用一向(one-way)加重启后的状态上报。两向 RPC 适合"改参数并确认生效"这类短动作。
6. 设备状态机:别用连接数判断在线
"在线"这个词有四种口径:TCP 连接在、MQTT 会话在、心跳在、业务数据在。四者可以任意组合。
一个典型场景:设备用 CoAP 或 NB-IoT,本来就没有长连接,按 TCP 口径统计会得到"99% 离线"。另一个场景反过来:MQTT 配了 cleanSession=false,broker 替设备保留了会话,于是断网三天的设备在平台上显示"在线",只是所有下行都进了队列。
我的口径分三档:connecting、online(一个心跳周期内有上行)、stale(超时未到离线阈值)。只对 online → stale 告警,stale → offline 只记录。一次抖动只出一条告警。
7. 动手任务:跑一次期望态收敛,看它会不会停
这一段不需要真设备。用一段 Python 模拟影子合并与幂等,先把逻辑跑对,再接到 broker 上。
from dataclasses import dataclass, field
@dataclass
class Shadow:
desired: dict = field(default_factory=dict)
reported: dict = field(default_factory=dict)
version: int = 0
seen: set = field(default_factory=set) # 真系统里换成带过期的 LRU
def patch_desired(self, patch: dict) -> None:
self.desired.update(patch)
self.version += 1
def report(self, patch: dict) -> None:
self.reported.update(patch)
self.version += 1
def delta(self) -> dict:
return {k: v for k, v in self.desired.items() if self.reported.get(k) != v}
def accept(self, cmd_id: str) -> bool:
if cmd_id in self.seen:
return False
self.seen.add(cmd_id)
return True
s = Shadow()
s.patch_desired({"brightness": 30, "mode": "auto"})
s.report({"brightness": 100})
print("delta:", s.delta())
print("first :", s.accept("cmd-7f3a"))
print("second:", s.accept("cmd-7f3a"))
s.report({"brightness": 30})
print("delta:", s.delta(), "version:", s.version)预期输出(Python 3.11 及以上,无第三方依赖):
delta: {'brightness': 30, 'mode': 'auto'}
first : True
second: False
delta: {'mode': 'auto'} version: 3第三行是这套模型的关键:亮度收敛了,mode 还差着,所以 delta 不为空。如果你的实现里 delta 变成空字典,说明你在上报时把 desired 也覆盖了——那台设备会永远停在 mode: manual,而看板显示一切正常。
然后把同一份逻辑接到 broker 上,用 ThingsBoard 的共享属性 topic 验证一次下行:
# 终端 1:以设备身份订阅共享属性更新
mosquitto_sub -h 127.0.0.1 -p 1883 \
-u "DEVICE_ACCESS_TOKEN" -P "" \
-t "v1/devices/me/attributes" -v
# 终端 2:下发一条两向 RPC,15 秒内要回执
curl -s -X POST "http://127.0.0.1:8080/api/rpc/twoway/<deviceId>" \
-H "X-Authorization: Bearer $TB_JWT" \
-H "Content-Type: application/json" \
-d '{"method":"setBrightness","params":{"value":30},"timeout":15000}'预期现象:终端 1 打印一行 v1/devices/me/attributes {"brightness":30};curl 的返回体里带一个 id 字段,用它可以和设备侧日志对上。设备不回执时,curl 拿不到这个 id——具体返回哪个状态码,我在 4.3.x 上见过 504,但没在 4.2 上复测过,别把状态码写死进你的重试逻辑,用"有没有 id"判断更稳。
8. 两套平台的取舍:阿里云 IoT 与 ThingsBoard 4.3.x
| 维度 | 阿里云 IoT | ThingsBoard 4.3.x |
|---|---|---|
| 模型载体 | TSL:属性/服务/事件,带数据类型与单位 | 无独立物模型,靠 Device Profile + 属性/遥测命名约定 |
| 期望态 | 设备影子,desired/reported 两本账 | 共享属性由平台写、设备读;客户端属性由设备写、平台只读 |
| 命令通道 | 云端 API 或自定义 Topic 下发 | RPC:单向/两向,轻量级/持久化两档 |
| 有效期 | 依产品实现 | 持久化 RPC 带可配 TTL 与状态机;轻量级不落库 |
| 文档状态 | 该产品文档页标注"停止维护";新版公共实例设备上限 500 台 | 4.3.x 为 Active LTS,补丁号与 EOL 日期见 ThingsBoard release notes |
| 授权 | 商业云服务 | 自 v4.4 起改为 source-available,自建前先读许可证 |
最要紧的是第二条。
阿里云把"设备说什么"和"云端要什么"放进同一份影子的两个字段;ThingsBoard 拆成两类属性,权限天然分离,代价是你得自己维护"哪个属性是目标值"。
有一个判断我给得很明确:不建议把共享属性当命令通道。它是覆盖写,没有回执语义,也没有 TTL,设备离线三天后重连还会读到三天前的配置。要下发动作就走 RPC,要下发配置就接受"最终一致、可能很旧"这个前提。
至于平台选择,如果今天从零开始,我会先确认阿里云那个实例的长期维护路径——文档页上"停止维护"四个字是硬信号。ThingsBoard 这边注意 v4.4 的授权变化,4.3.x 还在 LTS 窗口内。
9. 八个词,评审会上会被反复追问
这八个词会在评审会上反复出现。
| 术语 | 英文 | 一句话解释 |
|---|---|---|
| 物模型 | Thing Model / TSL | 描述设备属性、服务、事件的结构化契约 |
| 设备影子 | Device Shadow | 保存期望态与上报态的服务端副本,只留最新值 |
| 期望态 | desired | 云端希望设备达到的目标值 |
| 上报态 | reported | 设备自述的当前值 |
| 幂等键 | idempotency key | 让重复投递不产生重复副作用的标识 |
| 两向 RPC | two-way RPC | 平台下发并等待设备回执的调用模型 |
| 会话保持 | persistent session | broker 替离线设备保留订阅与队列 |
| 收敛 | convergence | 设备从当前值追到期望值的过程 |
10. 三处常见误解,两道需要真想一想的题
很多人以为"消息进了 broker 就算下发成功",实际上那只叫投递成功:PUBACK 只证明 broker 收到了,没有设备侧的证词。
很多人以为影子能当操作日志,实际它只留最新值——定位是收敛目标,不是流水账。
很多人以为状态机可以省,实际只要设备会休眠、会掉电、会换网,状态就有四种口径;省掉它等于让看板替你判断。
两道题:
第一道,12,000 台设备的灌溉系统,每天只在早六点到八点在线。要下发当天的灌溉计划,你会用共享属性、持久化 RPC,还是设备上电后主动拉配置?三种方案各自的最坏延迟是多少?
第二道,设备只有收到回执才算命令成功,但网络是 LoRa,单次下行 200 字节、延迟 30 秒起。幂等窗口设多大合适?太大和太小分别会引入什么故障?
回到开头那个照明项目。他们最后补的不是模型,是一条对账逻辑:每次批量下发都生成一个 commandId,设备执行后回执带上同一个 ID,平台按 ID 台账统计"已执行 / 已投递未执行 / 未投递"三档。第一次跑出来,那 3,000 多台设备的归属是"已投递未执行"——和现场看到的灯没变完全对得上。
这件事之后我改了一个习惯:凡是设计下发接口,先把"成功"这个词的三种解释写进接口文档,再写代码。写成哪一种,取决于业务能不能接受设备休眠八小时之后才执行,而这个答案只有业务方有。