Skip to content

设备影子与物模型:把「命令下发成功」这句话拆成四个问题 ​

学习目标

  • 能说出物模型里属性、服务、事件三者的方向差异,并判断一个字段该定义成哪一种。
  • 能画出期望态、上报态、差值三者的关系,说清为什么影子不能当审计日志用。
  • 会为批量指令设计幂等键和超时判据,并能解释"投递成功"和"执行成功"为什么是两件事。
  • 能独立判断一条 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(两者不一致的部分)。

json
{
  "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,设备重连后会补发。

json
{
  "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 上。

python
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 及以上,无第三方依赖):

text
delta: {'brightness': 30, 'mode': 'auto'}
first : True
second: False
delta: {'mode': 'auto'} version: 3

第三行是这套模型的关键:亮度收敛了,mode 还差着,所以 delta 不为空。如果你的实现里 delta 变成空字典,说明你在上报时把 desired 也覆盖了——那台设备会永远停在 mode: manual,而看板显示一切正常。

然后把同一份逻辑接到 broker 上,用 ThingsBoard 的共享属性 topic 验证一次下行:

bash
# 终端 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 ​

维度阿里云 IoTThingsBoard 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让重复投递不产生重复副作用的标识
两向 RPCtwo-way RPC平台下发并等待设备回执的调用模型
会话保持persistent sessionbroker 替离线设备保留订阅与队列
收敛convergence设备从当前值追到期望值的过程

10. 三处常见误解,两道需要真想一想的题 ​

很多人以为"消息进了 broker 就算下发成功",实际上那只叫投递成功:PUBACK 只证明 broker 收到了,没有设备侧的证词。

很多人以为影子能当操作日志,实际它只留最新值——定位是收敛目标,不是流水账。

很多人以为状态机可以省,实际只要设备会休眠、会掉电、会换网,状态就有四种口径;省掉它等于让看板替你判断。

两道题:

第一道,12,000 台设备的灌溉系统,每天只在早六点到八点在线。要下发当天的灌溉计划,你会用共享属性、持久化 RPC,还是设备上电后主动拉配置?三种方案各自的最坏延迟是多少?

第二道,设备只有收到回执才算命令成功,但网络是 LoRa,单次下行 200 字节、延迟 30 秒起。幂等窗口设多大合适?太大和太小分别会引入什么故障?

回到开头那个照明项目。他们最后补的不是模型,是一条对账逻辑:每次批量下发都生成一个 commandId,设备执行后回执带上同一个 ID,平台按 ID 台账统计"已执行 / 已投递未执行 / 未投递"三档。第一次跑出来,那 3,000 多台设备的归属是"已投递未执行"——和现场看到的灯没变完全对得上。

这件事之后我改了一个习惯:凡是设计下发接口,先把"成功"这个词的三种解释写进接口文档,再写代码。写成哪一种,取决于业务能不能接受设备休眠八小时之后才执行,而这个答案只有业务方有。