4、调试模式入门：规则链调试模式开启方法、调试面板布局、实时消息流可视化查看

规则链调试模式是 ThingsBoard 平台最强大的故障排查工具之一。它允许你在规则链节点上设置断点，实时观察消息（Msg）、元数据（Metadata）以及消息类型（Msg Type）在节点间的流转过程。本章将带你从零开始，掌握调试模式的开启、面板布局解读以及实时消息流的可视化查看技巧。

4.1 调试模式开启方法

调试模式并非全局开关，而是针对单个规则链节点逐一开启的。开启后，该节点会捕获所有经过它的消息快照，供开发者分析。

4.1.1 开启步骤

1. 进入规则链编辑界面：在“规则链”菜单中，点击目标规则链，进入可视化编辑器。
2. 选中目标节点：单击需要调试的节点（例如“Save Timeseries”节点），右侧弹出节点配置面板。
3. 开启调试开关：在配置面板的“高级”选项卡中，找到 Debug mode 开关，将其切换为 ON（蓝色高亮状态）。
4. 保存并应用：点击节点配置面板底部的“保存”按钮，然后点击规则链编辑器右上角的“保存”按钮，使配置生效。

4.1.2 调试模式参数说明

4.2 调试面板布局详解

开启调试模式后，你需要知道去哪里查看捕获到的消息。ThingsBoard 提供了专门的调试面板，其布局分为三个核心区域。

4.2.1 调试面板入口

在规则链编辑器的右下角，有一个 “调试” 按钮（通常显示为 “Debug” 或 “Events” 图标）。点击该按钮，即可从右侧滑出调试面板。

4.2.2 面板三区域功能

4.3 实时消息流可视化查看

调试面板不仅展示静态的快照，还支持实时消息流的可视化追踪。当设备持续上报数据时，调试面板会动态刷新，让你看到消息如何从一个节点“流”到下一个节点。

4.3.1 实时流查看操作

• 保持面板开启：在规则链编辑器页面，保持右侧调试面板处于打开状态。
• 触发消息：通过模拟设备（如使用 MQTT 客户端）发送一条遥测数据，或等待真实设备上报。
• 观察动态刷新：调试面板的事件列表会自动滚动，新事件会出现在列表顶部。点击任意新事件，底部详情区立即显示该消息的完整内容。
• 节点高亮联动：在事件列表中点击某条事件时，规则链画布上对应的节点会短暂高亮闪烁，帮助你建立“事件 ↔ 节点”的视觉关联。

4.3.2 消息流转路径分析

通过连续查看多个节点的调试事件，你可以还原出一条消息的完整流转路径。例如：

1. 消息首先进入 “Message Type Switch” 节点（事件 A）。
2. 根据消息类型，流转到 “Save Timeseries” 节点（事件 B）。
3. 保存成功后，通过“成功”链路进入 “Push to Kafka” 节点（事件 C）。

如果事件 B 显示失败，而事件 C 没有出现，则说明故障点就在 “Save Timeseries” 节点。

4.4 调试模式最佳实践

• 按需开启：只对怀疑有问题的节点开启调试，避免所有节点同时开启导致事件列表过载。
• 设置合理的 TTL：根据调试周期设置事件存活时间，避免过期事件占用存储。
• 结合日志：调试面板展示消息内容，而 ThingsBoard 服务器日志（如 /var/log/thingsboard/thingsboard.log）提供更底层的错误堆栈。两者结合使用效果最佳。
• 清理调试事件：调试完成后，关闭节点的 Debug mode 并保存，系统会自动清理该节点的调试事件缓存。