4. 平台架构解析

ThingsBoard 作为一款开源物联网平台，其架构设计直接决定了二次开发的效率与系统上限。本章将深入剖析其整体微服务架构，逐一拆解 Transport、Rule Engine、Web UI、Device Service 等核心模块的职责边界与协作机制。理解这些模块的底层逻辑，是进行协议扩展、规则链定制、UI 深度改造以及性能调优的前提。我们将从架构演进、模块通信、数据流路径到实战案例，构建一个完整的架构认知框架。

4.1 整体微服务架构的核心原理

ThingsBoard 从单体应用演进为微服务架构，其核心设计哲学是“协议接入与业务逻辑分离、消息流转与数据存储解耦”。在 3.x 版本中，平台默认提供两种部署形态：单机单体模式（适合开发测试）和微服务模式（适合生产环境）。微服务模式下，每个核心模块作为独立的 Spring Boot 应用运行，通过 Kafka 或 gRPC 进行通信。

这种架构带来的直接收益是独立伸缩性。例如，当接入设备量激增时，可以单独扩容 Transport 服务实例，而不需要扩容 Rule Engine 或 Web UI。同时，模块间的故障隔离也更为彻底——如果 Rule Engine 因规则链死循环而崩溃，设备接入和遥测存储不会立即中断，Kafka 中的消息会暂存等待恢复。

理解微服务架构需要抓住三个关键抽象：消息（Message）、元数据（Metadata）和Actor 模型。设备上报的数据被封装为消息，携带设备 ID、租户 ID、消息类型（POST_TELEMETRY、POST_ATTRIBUTES、RPC_REQUEST 等）以及负载。Rule Engine 内部采用 Akka Actor 模型，每个规则链节点是一个 Actor，消息在 Actor 之间传递，实现了高并发下的异步处理。

4.2 核心模块职责深度拆解

每个核心模块在架构中扮演不同角色，其内部设计也各有特点。下面逐一分析各模块的职责边界、关键类与扩展点。

4.2.1 Transport 模块：协议接入的桥头堡

Transport 模块负责所有设备接入协议的解析与转换。它支持 MQTT、HTTP、CoAP、LwM2M 等主流 IoT 协议，并提供了统一的 SPI 接口用于自定义协议扩展。该模块的核心类包括 TransportService、TransportAdaptor 和 SessionId。

• 核心职责：维护设备会话、解析协议报文、调用 Device Service 校验设备凭证、将上行数据转换为内部 ProtoBuf 消息并发送到 Kafka。
• 关键扩展点：实现 TransportAdaptor 接口可以接入自定义协议（如 TCP 私有协议、Modbus TCP 等）。
• 性能考量：Transport 是无状态服务，可以水平扩展。每个实例维护 Netty EventLoop 线程池，默认配置为 CPU 核数的两倍。

4.2.2 Rule Engine 模块：智能决策的中枢

Rule Engine 是 ThingsBoard 最强大的特性之一，它允许用户通过可视化规则链（Rule Chain）对消息进行过滤、转换、丰富和路由。规则链由多个节点（Node）组成，每个节点执行特定操作，如“保存到数据库”、“发送邮件”、“调用 REST API”或“设备 RPC 调用”。

规则引擎内部使用 Akka Actor 系统管理节点实例。每个规则链被编译为一个 Actor 树，消息从根节点流入，按照链路配置逐级传递。这种设计保证了高吞吐量，但也带来了调试复杂性——消息在节点间的流转是异步的，需要借助日志或调试模式追踪。

// 自定义规则节点示例：从消息中提取温度值并判断是否超限
@Slf4j
@Component
public class TemperatureFilterNode implements TbNode {
    @Override
    public void onMsg(TbContext ctx, TbMsg msg) {
        JsonNode data = msg.getData();
        double temp = data.get("temperature").asDouble();
        if (temp > 50.0) {
            ctx.tellNext(msg, "High");
        } else {
            ctx.tellNext(msg, "Normal");
        }
    }
}

4.2.3 Web UI 模块：可视化交互的窗口

Web UI 基于 Angular 框架构建，通过 RESTful API 与后端 Core Service 交互。它提供了仪表板（Dashboard）、设备管理、规则链编辑、客户门户等核心界面。对于二次开发而言，Web UI 的定制通常涉及两种路径：一是通过 Angular 组件扩展新页面；二是利用平台内置的“仪表板状态”和“别名”机制，在不修改代码的情况下实现数据可视化。

Web UI 与后端通信采用 JWT 认证，所有 API 请求都经过 /api 前缀路由。前端构建产物为静态文件，由 Nginx 托管，并通过反向代理将 API 请求转发到 Core Service。

4.2.4 Device Service 模块：设备资产的管理者

Device Service 负责设备生命周期管理，包括设备注册、凭证管理（Access 、X.509 证书）、设备属性（Attributes）和遥测数据（Telemetry）的读写。它对外提供 REST API 和 gRPC 接口，供 Transport 和 Rule Engine 调用。

该模块的关键设计是两级缓存：本地 Caffeine 缓存和分布式 Redis 缓存（可选）。设备凭证验证是高频操作，缓存可以显著降低数据库压力。在二次开发中，如果需要对接外部设备管理系统，通常需要扩展 Device Service 的 DeviceService 接口或实现自定义 DeviceCredentialsService。

4.3 消息流转与数据流实战场景

理解架构的最佳方式是追踪一条真实的消息路径。假设有一个温湿度传感器通过 MQTT 协议上报数据，我们逐步分析消息在微服务间的流转过程。

1. 设备接入：传感器通过 MQTT 连接到 Transport 服务的 1883 端口，Topic 为 v1/devices/me/telemetry，携带 Access 作为凭证。
2. 凭证校验：Transport 调用 Device Service 的 gRPC 接口 checkDeviceCredentials()，验证 有效性，并获取设备 ID 和租户 ID。
3. 消息封装：Transport 将 MQTT Payload 转换为 TransportProtos.PostTelemetryMsg ProtoBuf 对象，并添加元数据（设备 ID、时间戳）。
4. Kafka 发布：Transport 将消息发布到 tb-rule-engine Topic，分区键为设备 ID 的哈希值，保证同一设备的消息有序。
5. 规则引擎消费：Rule Engine 的消费者拉取消息，根据设备关联的规则链 ID，将消息注入对应的 Actor 树。
6. 规则链处理：消息经过“保存到数据库”节点，调用 Device Service 的 REST API 将遥测数据写入 Cassandra；同时经过“RPC 下发”节点，向设备发送控制指令。
7. Web UI 展示：前端仪表板通过 WebSocket 订阅设备遥测更新，实时刷新图表。

4.4 常见误区与架构决策复盘

在指导多个企业团队进行 ThingsBoard 二次开发后，我们发现以下误区最为常见：

• 误区一：所有功能都塞进 Rule Engine。有些开发者将复杂的业务逻辑（如订单处理、设备配网）全部用规则链实现，导致规则链节点超过 50 个，难以调试和维护。正确做法是：规则链只做轻量级过滤和路由，复杂业务逻辑应通过自定义节点调用外部微服务。
• 误区二：忽略 Transport 的背压机制。当设备量突增时，Transport 向 Kafka 发送消息的速度可能超过 Rule Engine 的消费能力。如果没有配置背压策略，会导致内存溢出。建议在 Transport 中配置 max.in.flight.requests.per.connection 和客户端超时时间。
• 误区三：直接修改数据库表结构。ThingsBoard 的数据库表结构在版本升级时可能变化，直接修改会导致升级失败。如果需要扩展字段，应使用平台提供的“属性”机制或创建独立的扩展表，通过 Device Service 的 API 进行关联。

总结而言，ThingsBoard 的微服务架构为二次开发提供了清晰的模块边界和丰富的扩展点。开发者需要根据自身业务场景，合理选择扩展方式：协议定制优先考虑 Transport 适配器，业务逻辑集成优先考虑 Rule Engine 自定义节点，管理界面定制则通过 Web UI 的 Angular 组件实现。下一阶段的学习应聚焦于具体模块的源码阅读，建议从 Transport 的 MQTT 适配器开始，逐步深入到 Rule Engine 的 Actor 模型实现。