2、ThingsBoard设备影子架构：客户端影子、服务端影子、影子同步机制

好，咱们接着聊设备影子。上一章我们把设备影子是什么、能干什么讲清楚了。这一章，我带你深入看看它的内部结构——说白了，就是搞清楚「影子到底长什么样，又是怎么同步的」。

我个人习惯把设备影子理解成一个「状态缓存层」。你想想看，物联网设备经常掉线、网络不稳定，如果每次查询状态都要直接问设备，那体验肯定很差。影子就是来解决这个问题的。

2.1 客户端影子 vs 服务端影子

ThingsBoard 里的影子，其实分两边：客户端影子和服务端影子。这两个概念很多人容易搞混，我刚开始接触时也绕了一阵子。

对比项	客户端影子	服务端影子
存储位置	设备本地（内存/Flash）	ThingsBoard 服务端数据库
谁维护	设备自身	ThingsBoard 平台
主要作用	保存设备本地状态，离线时也能工作	作为设备状态的「官方副本」
数据格式	JSON，与服务端影子结构一致	JSON，存储在 PostgreSQL 或 Cassandra 中
同步方向	主动上报或被动响应	接收上报，下发期望状态

客户端影子，就是设备自己手里那份状态。比如一个温控器，它本地存着当前温度、目标温度、工作模式。就算网络断了，它照样能按本地影子里的设定运行。

服务端影子，是 ThingsBoard 平台维护的那份。你通过 Web UI 或 REST API 查到的设备状态，其实都是从服务端影子读的，不是直接问设备要的。

2.2 影子数据结构

嗯，这里要讲清楚影子的数据长什么样。ThingsBoard 的设备影子，本质上是一个 JSON 文档。我截一个我在项目中实际用过的例子给你看：

{
  "client": {
    "temperature": 25.6,
    "humidity": 68.3,
    "power": "on",
    "mode": "auto"
  },
  "server": {
    "targetTemperature": 22.0,
    "schedule": {
      "enabled": true,
      "startTime": "08:00",
      "endTime": "22:00"
    }
  },
  "metadata": {
    "lastUpdated": "2024-03-15T10:30:00Z",
    "deviceType": "thermostat",
    "firmwareVersion": "v2.1.3"
  }
}

看到没？影子分三个顶层字段：

• client：设备上报的实时状态。温度、湿度这些，设备每隔几秒就会更新一次。
• server：平台下发的期望状态。比如你通过 App 把目标温度设为 22 度，这个值就写在 server 里，设备下次同步时会读到。
• metadata：元数据，记录版本号、更新时间等辅助信息。

2.3 影子同步机制

同步机制，说白了就是「客户端影子」和「服务端影子」怎么保持一致。这里分三种场景：

场景一：设备上报状态

设备主动把当前状态推给平台。流程是这样的：

1. 设备通过 MQTT 发布消息到 v1/devices/me/telemetry
2. ThingsBoard 收到后，更新服务端影子中的 client 字段
3. 平台返回确认，设备更新本地时间戳

代码示例（设备端，使用 MQTT 客户端）：

// 设备上报温度
String payload = "{\"temperature\": 25.6, \"humidity\": 68.3}";
mqttClient.publish("v1/devices/me/telemetry", payload.getBytes(), 0, false);

场景二：平台下发期望状态

你在 Web 界面上改了设备配置，平台会把这个「期望状态」写到服务端影子的 server 字段。设备怎么知道呢？

• 设备订阅 v1/devices/me/attributes 主题
• 平台通过 v1/devices/me/attributes 推送 server 字段的变化
• 设备收到后，更新本地客户端影子，并执行相应动作

场景三：冲突处理

如果设备离线期间，平台改了期望状态，设备上线后又上报了旧状态，怎么办？

ThingsBoard 的处理方式是：以服务端影子为准。设备上报时，平台会比较版本号。如果设备版本落后，平台会拒绝旧数据，并重新下发最新的期望状态。

我建议你在设备端实现一个「版本号校验」逻辑：

// 伪代码：设备上报前检查版本号
if (deviceShadow.version < serverShadow.version) {
    // 先拉取最新期望状态
    pullDesiredState();
    // 再上报当前状态
    reportState();
} else {
    // 正常上报
    reportState();
}

2.4 同步的三种模式

根据项目需求，你可以选择不同的同步模式：

模式	触发方式	适用场景	延迟
实时推送	状态变化立即推送	需要秒级响应的控制场景	< 1秒
定时同步	设备每隔 N 秒上报一次	数据采集、监控类场景	几秒到几分钟
按需同步	平台主动请求时上报	低功耗设备、电池供电场景	不确定

你想想看，如果是智能门锁这种低功耗设备，让它每秒都上报状态，电池两天就废了。这时候用「按需同步」就合适——用户开门时才上报，平时休眠。

2.5 避坑指南

最后，分享几个我在项目中踩过的坑：

• 不要依赖实时同步：网络延迟、设备离线都是常态。设计业务逻辑时，要假设影子数据可能有几秒甚至几分钟的延迟。
• 注意影子大小：ThingsBoard 对影子文档大小有限制（默认 64KB）。别把历史数据全塞进去，只存当前状态就好。
• 版本号别乱改：影子的版本号是平台自动维护的。我曾经手贱在设备端改了版本号，结果同步全乱了。让它自己管就好。

下一章，我会带你手把手实现一个设备影子的实战案例。到时候咱们用代码把今天讲的理论串起来，你就能真正体会到影子的威力了。