ThingsBoard 进阶（一）：规则引擎与消息流入门
ThingsBoard 进阶（一）：规则引擎与消息流入门
在前面的路灯实战中，我们已经让设备接入 ThingsBoard，上传 turn、light、battery 等遥测，并在仪表盘中展示和控制设备。
到这里，设备数据已经“进得来、看得到”。但项目继续往前做，很快就会遇到新问题：
电量低于阈值时，怎样自动生成告警？
不完整或异常的遥测，怎样过滤或修正？
同一条消息，怎样一边保存、一边通知外部系统？
某个节点处理失败时，怎样知道消息卡在哪里？
这些问题都与 ThingsBoard 的规则引擎有关。本篇先建立消息流的整体概念，并用已有路灯数据梳理一条遥测消息在平台中的处理过程。下一篇再动手创建和调试规则链。
一、本篇目标与环境说明
读完本篇，你应该能够：
区分规则引擎、规则链、规则节点和节点关系。
说清规则节点处理消息时常见的三个部分：消息体、元数据和消息类型。
根据一条路灯遥测，画出它从设备进入平台到后续处理的大致路径。
本篇以此前创建的路灯设备为例，假定设备能通过 MQTT 上传遥测。仓库中的早期文章没有记录 ThingsBoard 的具体版本和 Community/Professional Edition，因此本文不假设各版本的菜单、节点名称完全一致。正式操作前，请在自己的测试环境记录版本与 Edition；如果界面名称不同，以当前实例的实际界面和对应版本文档为准。
规则链的修改会影响消息处理。本文先以理解和观察为主，不替换默认 Root Rule Chain，也不要求在生产环境中改动现有链路。
二、先看消息流，而不是先记节点
可以先把规则引擎理解为一个消息处理流水线：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
路灯设备
│ MQTT 上报遥测
▼
ThingsBoard 接入与消息处理
│
▼
Root Rule Chain（根规则链）
│
├── 过滤 / 校验 / 转换
│
├── 保存遥测或属性
│
├── 判断条件并创建/清除告警
│
└── 转发到外部系统
上图是帮助理解的概念图，不代表每个 ThingsBoard 版本的默认 Root Rule Chain 都长得一样。实际处理取决于当前实例的规则链配置、消息类型、节点关系和可用功能。
规则引擎的价值不只是“收到数据后做一个判断”，而是把数据处理过程拆成可连接、可观察的步骤。比如一条路灯遥测可以先检查电量字段是否有效，再按电量分成正常和低电量两条路径，最后分别保存数据或处理告警。
三、四个核心概念
1. Rule Engine：规则引擎
规则引擎是 ThingsBoard 中处理设备消息及相关事件的基础设施。设备遥测之外，平台中还会产生属性更新、设备生命周期变化、RPC 请求等事件；不同事件会按平台配置进入相应的处理流程。
不要把“有规则引擎”理解为“所有数据自动按照同一条链处理”。消息类型和当前规则链配置都会影响处理路径。
2. Rule Chain：规则链
规则链是组织处理流程的画布。它由入口、节点以及节点之间的关系构成。平台通常有 Root Rule Chain，作为相关消息处理的根入口；也可以创建其他规则链，把较复杂的业务流程拆分开来。
规则链的名字只是帮助维护者理解用途。真正决定消息如何执行的是节点配置和连接关系，而不是名称本身。
3. Rule Node：规则节点
规则节点负责一个相对明确的处理步骤，例如：
判断消息类型；
检查或修改消息内容；
按条件过滤消息；
保存遥测；
创建或清除告警；
调用 RPC 或把数据发送到外部服务。
具体节点、节点名称和配置选项会随 ThingsBoard 版本及 Edition 有差异。设计流程时，先明确“这一步要对消息做什么”，再到当前实例中确认对应节点，避免只按旧截图找名字。
4. Relation：节点关系
节点处理后，会通过一个关系把消息交给后续节点。关系可以表达处理结果或分支类型，例如成功、失败、条件为真或条件为假。下游节点连接到哪个关系，决定消息下一步走向。
因此，画布上“节点连起来了”还不够；还要确认连接使用的关系是否符合预期。连接到了错误的关系，节点可能永远收不到你预期的消息。
四、规则节点看到的消息是什么？
为了分析规则链中的行为，需要把“设备发来的 JSON”与“规则引擎中的消息上下文”区分开。
一个简化的规则引擎消息可以这样理解：
1
2
3
msg 消息体，通常是本次处理的数据
metadata 元数据，用于描述消息来源或处理上下文
msgType 消息类型，用于区分遥测、属性更新等事件
假设路灯上报下面这条遥测：
1
2
3
4
5
{
"turn": 1,
"light": 72,
"battery": 18
}
在规则链的节点中，msg 可以包含这些键值；metadata 则可能携带设备名称、设备标识或其他处理上下文；msgType 表示当前处理的事件类型。元数据的具体字段取决于事件来源和处理过程，不要假设每条消息一定含有同一组字段。
这三个部分用途不同：
| 部分 | 用途 | 路灯示例 |
|---|---|---|
msg | 要检查、保存、转换或转发的数据 | battery: 18 |
metadata | 帮助节点识别来源或传递上下文的信息 | 设备名称等字段，具体以实例为准 |
msgType | 标识当前处理的事件类别 | 遥测或其他平台事件 |
一个常见误区是把设备属性、遥测字段和规则链元数据当作同一种数据。它们在平台中的含义和使用位置不同；后续配置节点时，应先确认字段来自哪一部分。
五、用路灯电量理解一条处理流程
接下来先不配置节点，只设计一条目标流程：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
收到路灯遥测
│
▼
检查 battery 是否存在且为有效数值
│
├── 无效 ──► 记录/处理异常，不进入低电量判断
│
└── 有效
│
▼
判断 battery < 20
│
├── 是 ──► 进入低电量处理
│
└── 否 ──► 进入正常处理
这里的 20 是本教程用于演示的阈值，不代表所有路灯或电池都适用。真实项目要根据设备规格、采样频率和业务要求设定阈值。
这个流程中有几个值得留意的设计点：
先验证，再比较。 如果
battery缺失或不是数值，直接比较可能得到错误结果或触发失败。分支要明确。 低电量和正常数据是不同处理结果，应连接到各自对应的后续路径。
告警有生命周期。 低电量触发后，还要定义电量恢复时如何清除或关闭告警；不能只实现“创建”。
数据保存要确认。 被过滤或进入失败路径的消息是否仍应保存，需要作为设计选择验证，而不能凭流程图推断。
后续几篇会逐步把这个设计落实为可运行的规则链、遥测检查和告警处理。
六、发送一条测试遥测
如果已经按前文创建了路灯设备，可以通过 MQTT 客户端发送一条测试数据。以下示例使用 mosquitto_pub；请替换服务器地址和设备访问令牌，不要把真实令牌发布到文章、截图或代码仓库。
1
2
3
4
5
6
mosquitto_pub \
-h '<THINGSBOARD_HOST>' \
-p 1883 \
-u '<DEVICE_ACCESS_TOKEN>' \
-t 'v1/devices/me/telemetry' \
-m '{"turn":1,"light":72,"battery":18}'
如本机未安装 mosquitto_pub，也可以继续使用之前教程中的设备模拟程序发送相同字段。重点是保持消息结构清晰，并记下发送时间、设备名称和字段值，方便稍后对照调试信息。
发送前检查
使用的是目标路灯对应的设备访问令牌。
设备能连接到当前 ThingsBoard 实例的 MQTT 端口。
JSON 中的键名与规则设计一致，例如
battery，不要在不同地方混用battery和Battery。测试令牌只保存在本地，不贴到公开日志或截图中。
此步骤只用于确认消息已从设备端发出，不等同于已经证明它经过了哪条规则链。消息是否被平台接收、节点如何处理，应在下一篇通过规则链和调试信息进一步验证。
七、如何观察现有处理过程
在测试环境中，可以打开当前实例的规则链页面，先识别 Root Rule Chain 及其现有节点，再确认遥测消息对应的入口和后续连接。
不同版本的入口菜单和调试操作可能不同；建议按以下顺序观察，而不是直接改默认链：
确认当前登录用户有查看规则链的权限。
找到 Root Rule Chain，浏览现有节点及其连接关系。
查看连接线上的关系名称，标出成功、失败或条件分支。
如当前版本支持节点调试事件，在测试实例中短暂开启相关节点的调试，再发送一条有明确时间和值的测试遥测。
对照调试事件中的消息体、元数据、消息类型和节点关系，确认消息经过了哪些步骤。
测试结束后关闭不再需要的调试设置，避免长时间记录大量调试事件。
如果没有权限查看规则链，或者当前界面与文档截图不一致，先记录版本、Edition 和页面位置，不要通过修改或替换默认链来“试试看”。下一篇会使用独立测试流程讲解规则链创建和调试。
八、常见理解偏差
1. “遥测上传成功”就表示规则处理成功
设备端发布消息、平台接收到消息、规则节点处理成功和数据最终保存，是不同阶段。要定位问题，应分别确认设备连接、消息到达、节点执行和最终结果。
2. “所有节点都会按画布从左到右执行”
画布布局主要帮助人阅读。实际的执行顺序由节点之间的关系连接决定；消息只会沿着实际触发的关系继续处理。
3. “节点返回失败，消息就一定被重新处理”
失败关系通常用于把处理结果交给后续节点，不应直接理解成自动重试。重试、重新投递或失败消息保存取决于具体节点、队列和规则链配置，需要对照当前版本验证。
4. “低电量就是一个阈值判断”
阈值判断只是告警流程的一部分。还需要考虑告警归属、重复触发、恢复条件、告警展示及通知方式。
九、本篇小结
规则引擎可以看作由规则链、处理节点和节点关系组成的消息处理流程。理解它时，先问三个问题：
这是什么消息，消息体和元数据分别是什么？
当前节点处理后会产生哪些关系？
每种关系分别连接到哪里，最后产生什么可观察的结果？
下一篇将创建一条独立的测试规则链，逐步连接节点，并通过实际遥测和调试信息验证消息流转。届时会以明确记录的 ThingsBoard 版本和 Edition 为准，把每个配置步骤、预期结果和排查方式写完整。