设备影子（Device Shadow，也常被口语化叫作“影子设备”）是 IoT 平台为一台真实设备维护的云端状态副本；它用 desired、reported 和 delta 等字段在设备离线、弱网或休眠时保存期望状态，并在设备上线后完成状态同步。
设备影子不是虚拟设备本身，也不是命令执行结果。它是一份带版本、时间和差异语义的状态文档，用来把“云端希望设备变成什么状态”和“设备实际上报自己是什么状态”分开。
核心问题
IoT 设备经常不稳定在线：
- 低功耗设备会长时间休眠。
- 移动设备可能处于弱网、断网或漫游状态。
- 云端应用希望随时修改配置，但设备不一定马上可达。
- 运维系统希望读取最后一次已知状态，而不是每次都实时连设备。
- 多个应用可能同时改同一台设备的配置，需要有版本和冲突边界。
如果没有设备影子，云端只能在设备在线时直接发命令；设备离线时，控制请求容易丢失，业务系统也难以区分“命令已保存”“命令已送达”“设备已执行”这三个不同状态。
核心对象
| 对象 | 含义 | 工程关注点 |
|---|---|---|
| physical device | 真实设备 | 传感器、机器人、网关、家电或控制器 |
| shadow document | 云端设备影子文档 | JSON 状态、版本、时间戳、元数据 |
reported | 设备实际上报的状态 | 设备当前认为自己的事实状态 |
desired | 云端期望设备达到的状态 | 用户、规则引擎或运维系统写入的目标 |
delta | desired 与 reported 的差异 | 设备需要处理的待同步状态 |
| version | 影子文档版本号 | 并发更新、幂等和冲突检测 |
| device client | 设备端同步逻辑 | 拉取 delta、执行动作、上报 reported |
| application client | 云端或业务应用 | 读取 reported、写入 desired、订阅变更 |
核心机制
最小设备影子文档可以写成：
{
"state": {
"desired": {
"power": "on",
"target_temperature": 24
},
"reported": {
"power": "off",
"target_temperature": 26
}
},
"version": 17,
"timestamp": 1780561500
}desired是云端或用户希望设备达到的目标状态。reported是设备最近一次上报的实际状态。version是这份影子文档的递增版本，用于判断自己看到的状态是否过期。timestamp是影子更新时间，不能等同于设备真实采样时间，除非协议明确由设备上报采样时间。
平台通常会从 desired 和 reported 计算 delta：
delta = desired - reported这里的 - 不是数学减法，而是字段级差异计算：如果某个字段在 desired 中存在，并且与 reported 的值不同，它就进入 delta。例如上面的 delta 可以理解为：
{
"power": "on",
"target_temperature": 24
}典型同步流程如下：
- 应用写入
desired，例如希望设备开机并设置目标温度。 - IoT 平台保存影子文档，递增
version，计算新的delta。 - 如果设备在线，平台通过 MQTT、HTTP 或其他通道通知设备；如果设备离线，
desired留在云端。 - 设备上线后拉取或订阅
delta。 - 设备尝试执行配置变更。
- 设备执行成功或部分成功后，上报新的
reported。 - 平台重新计算差异；如果
reported已追上desired，delta消失。
这个机制让系统接近 最终一致性：云端期望状态和设备实际上报状态不要求实时相等，但在网络恢复、设备执行成功并完成上报后，它们应该收敛。
工程用途
- 离线配置下发：设备离线时先保存期望配置，上线后再同步。
- 最后状态查询：业务系统读取最近的
reported，不用直接访问设备。 - 低功耗设备管理：设备周期性醒来处理 delta，处理后再次休眠。
- 远程参数调整：如采样周期、告警阈值、目标温度、功能开关。
- 设备运维视图：和 设备生命周期管理、OTA、告警系统一起形成设备运营状态。
在机器人或嵌入式设备平台中，设备影子适合管理“配置状态”和“可延迟收敛的目标状态”，例如日志级别、采样开关、上报周期、非实时功能开关；不适合承载强实时控制。
边界与常见坑
- 设备影子不是命令队列：
desired表示目标状态，不表示每条命令都要执行一次；如果需要“开门一次”这类边沿触发动作，应使用命令、任务或事件模型。 - 写入 desired 不等于设备已执行：只有设备上报相应
reported，才能认为状态已被设备确认。 - reported 也不是绝对真相：它来自设备上报，仍受设备固件、传感器、网络延迟和身份认证影响。
- delta 不是业务差分补丁：它只是期望状态与上报状态的差异，不负责描述执行步骤或回滚流程。
- 并发写入要看 version：多个应用同时修改 desired，如果不做版本条件更新，可能互相覆盖。
- 状态和事件要分开：温度、开关、模式适合影子；告警发生、按钮点击、升级完成这类瞬时事实更适合事件流。
- 安全边界不能靠影子本身保证：谁能写 desired、谁能读 reported、设备身份如何认证，仍要由平台权限、凭据和传输安全保证。