6.3 云平台对接与设备影子

6.3 云平台对接与设备影子

本节摘要：设备会离线，用户界面不会；命令会迟到，期待不会。设备影子是解决这个时间差的标准模式：云端持有一份设备状态的"档案副本"，期望值与报告值各自记录、各自更新，双方离线也能对账。本节讲透影子的双向同步机制、属性与遥测的边界划分，并用一次设定值冲突的排查案例演示影子的实战价值。

6.2 节解决了消息怎么送；这一节解决消息送到之后的状态管理。问题的根源在时间差：用户在界面上点了"调到 24 度"，设备此刻可能正在离线落盘——这条命令存哪、设备上线后怎么知道、两个管理员同时改听谁的，影子模式就是为这三问而生的标准答案。

设备睡了，界面还醒着

先看没有影子的世界：界面直发命令给设备，设备离线则命令消失，界面却显示"已设置"——用户以为改成了，设备根本不知道。反过来，设备重启后也不知道"上次有人要我改设定"，只能上报一个自己的当前值，界面跟着跳回旧值。两侧的痛苦同源：没有一个中立的地方存放"应该是什么"与"实际是什么"。

影子就是这个中立仓库。云端为每台设备维护一份 JSON 文档，分两个字段：期望值是人们想要的（设定温度 24 度），报告值是设备自述的（当前实际 22.5 度）。设备在线时订阅期望值的变更，离线时漏掉的变更由云端暂存；设备任何时候上线，先拉期望值对账。界面的读写也只面对影子——界面与设备从此不必同时在线，时间差被影子填平。

图：影子双向对账的完整时序

属性与遥测：两种数据的户口

对接云平台前先分清两类数据的户口。遥测是设备不断产出的时间序列（每分钟的温度读数），特征是量大、只增、按时间查询——它进时序存储，画曲线、做报表。属性（影子的内容）是设备的当前状态与设定（固件版本、设定温度、运行模式），特征是量小、可覆盖、按设备查询——它进影子文档，做控制与展示。

混户口的两种典型病：把遥测塞进影子（影子文档被高频改写，平台配额瞬间耗尽）；把设定值塞进遥测（要"当前设定"就得从头翻历史，控制逻辑变得又慢又脆）。判断口诀：会变的当前值进影子，只增的历史流进遥测。

// 影子对账的最小实现：上线先拉期望值，按版本号拒绝过期命令
#include <ArduinoJson.h>

int  desiredSetpoint = -1;   // 云端想要的
int  reportedSetpoint = 0;   // 设备实际的
long desiredVersion = -1;    // 期望值的版本号

void onShadowDelta(char* topic, byte* payload, unsigned int len) {
  StaticJsonDocument<256> doc;
  if (deserializeJson(doc, payload, len)) return;
  long v = doc["version"] | -1;
  if (v <= desiredVersion) return;            // 过期变更，直接忽略
  desiredVersion = v;
  desiredSetpoint = doc["state"]["setpoint"] | reportedSetpoint;
}

void reconcile() {                            // 每轮对账：追期望、报实际
  if (desiredSetpoint >= 0 && desiredSetpoint != reportedSetpoint) {
    applySetpoint(desiredSetpoint);           // 真正执行
    reportedSetpoint = desiredSetpoint;
    publishReported(reportedSetpoint);        // 汇报给影子
  }
}
​

版本号是这段代码的灵魂：两个管理员先后改设定，云端合并后版本号递增，设备只认最新版本——迟到半拍的旧命令（版本号更小）被直接丢弃。没有版本号，影子模式在并发修改下会退化成"谁后到谁说了算"的赌博。

案例：两个管理员的设定值拉锯战

背景：连锁门店的温控后台，店长与总部运营都能改目标温度。上线一个月后投诉：设备温度"自己变来变去"，日志显示设定值一天内被改十余次，双方都否认连续操作。

操作：查影子历史版本，发现真相不是设备异常，而是两人都真的在改——店长下午调高，运营晚上按节能策略调低，来回拉锯。技术侧设备并无故障，但产品侧缺少"变更可见性"：双方都看不到对方的修改。三步整改：影子文档增加最近一次修改的操作者与时间（元数据随版本走）；界面在提交前展示当前期望值与最近修改人；增加变更频率保护（十分钟内重复变更走确认流程）。

结果："设备自己变"的投诉归零——温度依然会变，但每次变化都有主、有据、可追溯。

解读：这个案例的价值在于划清技术与产品的边界：影子机制忠实执行了每一次变更，"问题"出在变更不被看见。影子的完整能力 = 状态同步 + 版本仲裁 + 变更溯源，三者齐备才能支撑多人协作的管理场景。设备端的功课（版本号仲裁）在本案例里只是及格线，真正的产品力在元数据那两行。

变式：多设备联动的场景（一个开关控制一片灯），影子可以升级为"组影子"：组级文档存联动策略，设备级影子只存各自状态，两层对账互不干扰。层级化的影子与 6.2 节的主题层级设计一脉相承。

⚠️ 常见坑：把影子当实时通道用，期望值改一次推送一次命令——影子是"最后状态"语义，不是"每次变更"语义。需要逐条命令到达确认的场景，请回 6.2 的 QoS1 加幂等，影子只管当前态。

💡 关键直觉：影子的本质是把"分布式系统的一致性"问题换成"对账"问题——不追求两侧实时一致，只保证最终能对上账。接受这个降级，联网产品的复杂度立刻减半。

本节要点回顾

• 影子填平时间差：期望值排队等离线设备，报告值供在线界面阅读；
• 两种数据分户口：会变的当前值进影子，只增的历史流进遥测；
• 版本号是并发仲裁的基石，没有版本号的影子在多人操作下必然混乱；
• 变更溯源是产品力：操作者与时间随版本记录，"设备自己变"的投诉源于不可见而非故障；
• 影子管当前态，不管逐条命令，命令可靠性回 6.2 解决。