1、规则链基础：ThingsBoard规则链概述、核心概念与引擎工作原理
1.1 规则链概述
ThingsBoard 规则链（Rule Chain）是平台的核心数据处理引擎，负责对设备上报的遥测数据、属性更新、生命周期事件及 RPC 请求进行路由、过滤、转换与持久化。规则链采用可视化编排方式，用户无需编写后端代码即可构建复杂的物联网数据处理逻辑。
核心定位：规则链是 ThingsBoard 中“数据从哪里来、到哪里去、怎么处理”的唯一决策中枢。所有设备消息都必须经过至少一条规则链才能被存储或转发。
1.2 核心概念
| 概念 | 说明 | 类比 |
|---|---|---|
| 节点（Node） | 规则链中的最小处理单元，每个节点执行单一职责：过滤、转换、增强、路由或外部集成。 | 工厂流水线上的单个工位 |
| 连接（Connection） | 节点之间的有向边，定义消息流转路径。连接可附带标签（Label），用于区分成功/失败/自定义链路。 | 工位之间的传送带 |
| 消息（Message） | 在节点间传递的数据载体，包含元数据（Metadata）和载荷（Payload）。 | 传送带上的工件 |
| 规则链（Rule Chain） | 由节点和连接构成的有向无环图（DAG），定义完整的消息处理流程。 | 整条流水线布局图 |
1.3 消息结构详解
每条消息由三部分组成：
- 元数据（Metadata）：键值对集合，携带上下文信息（如设备名称、客户ID、消息来源规则链）。
- 载荷（Payload）：消息主体，支持 JSON、字符串、二进制三种格式。遥测数据通常为 JSON 对象。
- 消息类型（Message Type）：标识消息用途，常见类型包括
POST_TELEMETRY、POST_ATTRIBUTES、DEVICE_CONNECTED、RPC_REQUEST等。
// 消息示例：温度传感器上报
{
"metadata": {
"deviceName": "temp-sensor-01",
"deviceType": "temperature",
"ts": "1712345678000"
},
"payload": {
"temperature": 23.5,
"humidity": 68.2
},
"msgType": "POST_TELEMETRY"
}1.4 规则链引擎工作原理
ThingsBoard 规则链引擎基于事件驱动模型，采用单线程 + 队列架构确保消息有序处理。核心工作流程如下：
- 消息入链：设备或应用通过 MQTT/HTTP/CoAP 上报数据，平台将消息封装为标准格式并推入根规则链的起始节点。
- 节点执行：引擎按拓扑顺序遍历节点，每个节点执行其特定逻辑（如检查温度阈值、转换单位、调用外部 REST API）。
- 连接路由：节点执行完成后，根据返回结果（True/False/自定义标签）选择对应的连接，将消息传递给下一个节点。
- 终止条件：消息到达没有出边的节点（如“保存到数据库”节点）或触发错误处理逻辑时，该消息的生命周期结束。
关键特性：规则链引擎保证至少一次（At-Least-Once）消息处理语义。若节点执行失败，引擎会根据配置进行重试或路由到错误处理分支。
1.5 节点类型与连接标签
规则链提供 6 大类节点，覆盖物联网数据处理的常见场景：
| 节点类别 | 典型节点 | 用途 |
|---|---|---|
| 过滤器（Filter） | 消息类型过滤器、设备类型过滤器、脚本过滤器 | 根据条件决定消息是否继续流转 |
| 转换器（Transformer） | 脚本转换节点、KV 转换节点、单位转换节点 | 修改消息的 payload 或 metadata |
| 动作（Action） | 保存到数据库、发送邮件、创建告警 | 执行持久化或外部通知 |
| 外部集成（External） | REST API 调用、Kafka 生产者、MQTT 发布 | 与第三方系统交互 |
| 路由（Routing） | 检查关系、检查属性、延迟节点 | 控制消息流向与时机 |
| 脚本（Script） | JavaScript 脚本节点 | 自定义复杂逻辑 |
连接标签（Connection Label）是调试规则链的关键线索。每个节点输出端可定义多个标签，常见标签约定：
- True / Success：节点执行成功且条件满足
- False / Failure：节点执行成功但条件不满足
- Error：节点执行抛出异常
- Custom：用户自定义标签（如
high_temp、low_battery）
调试陷阱：连接标签名称必须与节点输出端定义的标签完全一致（区分大小写）。常见故障是标签拼写错误导致消息“丢失”——实际上消息被路由到了未连接的标签分支。
1.6 规则链引擎的队列与并发模型
ThingsBoard 使用 Akka actor 模型实现规则链引擎的并发处理。每个规则链实例对应一个 actor，消息通过 FIFO 队列进入 actor 的邮箱。关键参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
rule_engine.queue.max_pending_requests |
10000 | 队列最大积压消息数，超过后新消息被拒绝 |
rule_engine.queue.ack_strategy |
AFTER_PROCESSING | 确认策略：处理完成后才从队列移除 |
rule_engine.retry.max_attempts |
3 | 节点执行失败时的最大重试次数 |
性能建议：当设备数量超过 10,000 台时，建议将规则链拆分为根规则链 + 子规则链的层级结构，避免单条规则链成为性能瓶颈。子规则链通过“规则链节点”引用，实现逻辑隔离与并行处理。
1.7 本章小结
- 规则链是 ThingsBoard 的数据处理核心，由节点、连接、消息三大要素构成。
- 消息包含元数据、载荷、消息类型三部分，调试时需重点关注元数据中的上下文信息。
- 引擎采用事件驱动 + DAG 遍历方式处理消息，保证至少一次语义。
- 连接标签是消息路由的关键，标签名称必须精确匹配，否则消息会静默丢失。
- 理解队列与并发模型有助于在设备规模增长时进行性能调优。