ThingsBoard 进阶（二）：创建规则链并调试消息流
ThingsBoard 进阶（二）：创建规则链并调试消息流
在上一篇《ThingsBoard 进阶（一）：规则引擎与消息流入门》里，我们梳理了规则引擎、规则链、节点和节点关系。本篇开始动手：创建一条只供测试设备使用的规则链，发送路灯遥测，并通过调试事件确认消息经过了哪些节点。
本篇的重点不是改造线上规则，而是建立一条隔离的验证路径：
1
2
3
4
5
6
7
8
9
测试路灯
│ 使用专用设备配置
▼
路灯遥测测试链
│
├── Message Type Switch
│ └── Post telemetry
▼
Save Timeseries
实际界面、菜单名称和节点可用性可能因 ThingsBoard 版本或 Edition 不同而变化。仓库中现有教程没有记录平台版本，所以本文不把某个版本的截图步骤说成适用于所有版本。开始前请先记录自己的平台版本，并在测试环境确认对应节点与配置项。
一、本篇目标与准备工作
完成本篇后，你应该能够：
- 创建一条独立的规则链，而不是直接修改 Root Rule Chain。
- 使用专用设备配置把测试设备的消息送入这条规则链。
- 通过节点调试事件和设备最新遥测，验证消息路由和保存结果。
准备以下内容：
- 一个可登录的 ThingsBoard 测试环境，以及查看/编辑规则链和设备配置的权限。
- 一个仅用于本次练习的路灯测试设备，或一个可以安全调整配置的测试设备。
- 该设备的 MQTT Access Token。
- 可用的 MQTT 客户端，例如
mosquitto_pub，或上一篇的模拟设备程序。
安全提醒：不要在生产设备正在使用的共享设备配置上直接替换默认规则链。先建立单独的测试设备配置，并只将测试设备分配到该配置。令牌不要提交到代码仓库、截图或公开日志中。
二、先确认版本和测试对象
正式操作前，记录：
| 项目 | 记录值 |
|---|---|
| ThingsBoard 版本 | 例如从 About/系统信息页面确认 |
| Edition | Community Edition 或 Professional Edition |
| 部署方式 | Docker、本地安装或其他方式 |
| 测试设备 | 本文使用的路灯测试设备名称 |
| 测试设备配置 | 本文新建的专用配置名称 |
本文示例名称如下，读者可以按自己的项目改名：
- 规则链：
路灯遥测测试链 - 设备配置：
路灯规则链测试配置 - 测试设备：
路灯规则链测试设备
如果当前版本没有文中提到的设备配置入口，或者配置中无法指定默认规则链，请先停在此处，查阅当前版本对应的设备配置文档。不要为了继续实验而修改正在使用的 Root Rule Chain。
三、创建独立规则链
- 打开平台中的 Rule Chains（规则链） 页面。不同版本可能将入口放在侧边栏或系统管理区域。
- 使用新建操作创建规则链，名称填写
路灯遥测测试链。 - 将它作为普通规则链保存，不要将它设为 Root Rule Chain。
- 打开新建的规则链，确认画布中有规则链输入入口（有些版本在画布中显示为
Input节点）。
此时还没有设备消息进入这条链。创建规则链只是准备好了处理流程，下一步还需要让测试设备配置引用它。
四、为测试设备配置专用入口
ThingsBoard 通常通过设备配置中的默认规则链选择设备消息进入的处理流程。我们为练习单独创建一个设备配置，避免影响其他设备。
- 打开 Device Profiles（设备配置） 页面，创建新的设备配置
路灯规则链测试配置。 - 按当前版本要求填写设备配置的必要信息。
- 在默认规则链选项中选择刚才创建的
路灯遥测测试链，保存设备配置。 - 打开测试路灯设备，将它的设备配置改为
路灯规则链测试配置。 - 保存后再次确认只有本次测试设备使用该配置。
设备配置保存后，先不要用大量数据测试。稍后只发送一条可识别的样例遥测，并马上检查调试事件。如果设备配置页面没有默认规则链选项，或改变设备配置后消息仍进入原链路，请按当前版本的规则链入口机制排查，不要继续改生产 Root Rule Chain。
五、在规则链中连接最小处理流程
本篇使用“识别遥测消息并保存遥测”的最小流程，目的是让输入、分支关系和最终结果都能被验证。
1. 添加消息类型分支节点
在 路灯遥测测试链 的画布上添加 Message Type Switch（消息类型切换） 节点。节点的作用是按消息类型输出到不同关系。
将规则链输入端连接到这个节点。若当前版本进入画布后已有输入端，则从输入端开始连接；如果界面有其他入口表示方式，以本版本画布为准。
2. 添加遥测保存节点
添加 Save Timeseries（保存遥测） 节点，并将 Message Type Switch 的 Post telemetry 关系连接到保存节点。
目标结构如下：
1
2
3
4
5
6
7
Input
│
▼
Message Type Switch
│ Post telemetry
▼
Save Timeseries
不要把 Post attributes、RPC Request 等其他关系误接到保存遥测节点。本次只发送设备遥测，因此只需要验证 Post telemetry 路径。
3. 保存并检查画布
保存规则链后，逐项检查：
- 输入端是否连接到了 Message Type Switch。
Post telemetry是否连接到 Save Timeseries。- 连接线显示的关系名称是否正确。
- 规则链是否仍是普通规则链，而不是 Root Rule Chain。
- 设备配置的默认规则链仍指向这条测试链。
节点名称和保存操作可能随版本变化；如果找不到同名节点，先按功能在当前节点库中确认等价节点，并在文章正式发布前补上对应版本的实际界面截图。
六、开启调试并发送测试遥测
1. 开启节点调试
在规则链画布中，为 Message Type Switch 和 Save Timeseries 开启调试事件/Debug mode（如果当前版本提供此选项）。某些版本需要分别打开节点的调试开关；另一些版本可能把调试事件显示在单独的面板中。
调试事件能帮助确认节点收到的消息和处理结果，但持续开启调试可能产生大量事件。只在测试期间开启，验证后关闭。
2. 发送一条有辨识度的数据
将下列命令中的主机名和设备令牌替换成本地测试值。命令只包含一条遥测：
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":73,"battery":38}'
也可以使用上一篇的模拟程序发送同样的字段。测试值 light: 73 和 battery: 38 只是用于辨认本次消息，不代表实际设备的控制或告警阈值。
3. 在调试事件中检查消息路径
发送后打开规则链的调试事件视图，按测试时间和设备名称筛选本次消息，重点查看：
- Message Type Switch 是否收到一条消息。
- 消息体是否包含
turn、light、battery，数值是否与刚才发送的一致。 - 节点是否通过
Post telemetry关系输出。 - Save Timeseries 是否收到该消息并执行成功。
调试事件的字段名和面板布局因版本而异。判断重点是“哪个节点收到什么消息、产生什么关系、下游节点是否执行”，而不是要求每个版本的 JSON 展示完全相同。
七、验证遥测确实写入
规则链调试显示节点执行，不一定单独证明设备详情页已经能看到数据。因此还要做一次结果验证：
- 打开测试设备详情。
- 查看最新遥测（Latest telemetry）。
- 确认
turn、light、battery中包含刚发送的值。 - 对照时间戳确认是本次测试产生的数据，而不是旧数据。
只有同时确认以下两点，本次流程才算完成：
- 调试事件表明消息通过
Post telemetry路由到了 Save Timeseries。 - 测试设备的最新遥测中出现了本次发送的数据。
如果本篇的节点路径配置未保存遥测，但当前版本要求额外配置或使用不同节点，请先验证当前版本的保存节点行为，再调整本篇步骤。不要仅凭节点名称推断数据已被持久化。
八、排查常见问题
调试事件里完全没有消息
依次检查：
- MQTT 客户端是否连接成功，主机、端口、主题和令牌是否正确。
- 测试设备是否在线，发送命令是否有客户端错误。
- 设备是否确实分配到了专用设备配置。
- 设备配置的默认规则链是否是
路灯遥测测试链。 - 调试开关是否开启在正确的规则链和节点上。
设备在线只说明连接存在，不代表消息已经经过预期的规则链。
消息经过 Message Type Switch，但没有到保存节点
检查连接线上的关系是否为 Post telemetry，再确认当前输入是遥测消息，而不是属性更新或其他消息类型。必要时再发送一条新的遥测，避免把旧的调试事件当作本次结果。
保存节点执行了，但设备详情没有新数据
确认当前设备配置使用的是测试规则链、保存节点连接成功，并检查查看的是同一台测试设备。再对照调试事件中的消息体和时间。如果节点报错，记录错误信息、规则链名称、设备配置和平台版本，以便进一步定位。
看到了数据，但无法确认来自本次测试
重新发送一条具有明显特征的数值，例如将 light 改成 73，再对照最新值和时间戳。不要用不变的旧数据判断消息是否重发成功。
九、清理测试配置
测试完成后：
- 关闭不再需要的节点调试事件。
- 如果测试设备后续仍要使用，先将其改回原来的设备配置。
- 确认没有设备再引用测试配置或测试规则链后，再考虑删除测试对象。
- 不要删除其他设备正在使用的配置，也不要删除生产 Root Rule Chain。
十、本篇小结
本篇创建了一条专用规则链，并通过测试设备配置将一条 MQTT 遥测送入其中。我们用 Message Type Switch 的 Post telemetry 关系把遥测送到 Save Timeseries，最后通过调试事件和设备最新遥测双重确认结果。
下一篇将在这条消息流上增加数据校验和过滤：检查 battery、light 等字段是否存在、类型是否合理，并让正常数据与异常数据进入不同路径。