ThingsBoard 项目结构介绍（release-4.3）

本文对照 GitHub 分支 release-4.3（根 pom / common 版本号为 4.3.1.8）说明仓库目录与 Maven 模块职责，方便源码阅读与二次开发定位。

建议先完成 Windows上源码编译安装ThingsBoard，本地能跑起来再对照本文翻代码。
官方仓库：https://github.com/thingsboard/thingsboard/tree/release-4.3

1. 先建立整体图

ThingsBoard 是 多模块 Maven 工程：单体部署时，各协议传输、规则引擎、DAO、前端静态资源都打进 application；微服务 / 集群场景再通过 msa、docker 拆成独立进程与镜像。

数据大致路径：

text

设备 → transport（MQTT/HTTP/…）→ queue → Rule Engine / Core
                                      ↓
                              dao / PostgreSQL（+ 可选 Cassandra）
                                      ↓
                              REST / WebSocket → ui-ngx

根 pom.xml 声明的 Maven 模块（release-4.3）：

模块	作用一句话
`netty-mqtt`	自研 MQTT 协议栈（连接、发布、订阅、遗嘱等）
`common`	公共模型、Actor、队列、传输实现、缓存等
`rule-engine`	规则引擎 API + 节点组件
`dao`	数据访问实现（SQL / Cassandra 等）
`edqs`	实体数据查询服务（内存加速仪表盘查询）
`transport`	各协议传输可独立启动的启动器
`ui-ngx`	Web 前端（Angular）
`tools`	压测 / 客户端工具
`application`	主应用：安装、启动、Controller、业务服务
`msa`	微服务镜像与配套工程（JS Executor、Web UI、Transport 等）
`rest-client`	Java REST 客户端封装
`monitoring`	监控相关工程

仓库里还有 docker（Compose / 脚本）、packaging（安装包相关配置）、img（Logo 等资源），不一定都在根 <modules> 里，但二开 / 部署常用。

本地拉取该分支示例：

bash

git clone -b release-4.3 --single-branch https://github.com/thingsboard/thingsboard.git
cd thingsboard

2. 顶层目录速查

路径	类型	作用
`application`	Maven	主程序：`ThingsboardServerApplication` / `ThingsboardInstallApplication`，聚合 REST、Actor、安装升级
`common`	Maven 父模块	平台公共能力（见第 3 节）
`dao`	Maven	DAO 实现；实体模型在 `common/data`，接口在 `common/dao-api`
`rule-engine`	Maven	自研规则引擎（非 Drools）
`transport`	Maven	协议服务启动模块（实现多在 `common/transport`）
`netty-mqtt`	Maven	MQTT 编解码与会话底层
`ui-ngx`	Maven + Angular	管理端 UI（Angular 20，版本与后端同为 4.3.1.8）
`msa`	Maven	微服务构建、黑盒测试、独立组件镜像
`edqs`	Maven	EDQS 服务主体（可选，偏大规模实体查询）
`rest-client`	Maven	调用 ThingsBoard REST API 的 Java 库
`tools`	Maven	MQTT（含 SSL）/ REST 等测试客户端
`monitoring`	Maven	监控相关
`docker`	部署	集群 / 混合库等 Docker Compose 与脚本
`packaging`	打包	deb / 安装脚本等环境相关材料
`img`	资源	文档与产品用图、Logo

读代码建议顺序： common/data → dao → application（controller / service）→ rule-engine → common/transport + transport → ui-ngx。

3. `common`：公共能力层

common/pom.xml 子模块（release-4.3）如下。原稿里把 data 写成「DAO 接口」不准确：接口在 dao-api，领域模型 / DTO 在 data。

子模块	作用
`data`	设备、租户、遥测、告警、规则链等领域对象与枚举
`dao-api`	DAO 服务接口定义（实现落在根模块 `dao`）
`proto`	Protobuf 定义与生成代码（集群 / 队列等序列化）
`util`	通用工具
`message`	集群消息、系统消息等消息模型与基础能力
`actor`	Actor 运行时（设备、规则链等异步处理骨架）
`queue`	队列抽象与实现（In-Memory / Kafka 等），对应部署时的 `TB_QUEUE_TYPE`
`transport`	传输层实现与 API（见下）
`cluster-api`	集群协作相关 API
`discovery-api`	服务发现相关 API（`release-4.3` 相对旧资料的新增点）
`stats`	统计指标
`cache`	缓存抽象与实现
`coap-server`	CoAP 服务端基础能力
`edge-api`	ThingsBoard Edge 同步 / 边缘相关 API
`version-control`	实体版本控制（如规则链同步到远程 Git）
`script`	脚本执行相关（与规则引擎 JS 节点配合）
`edqs`	EDQS 相关公共代码（与根模块 `edqs`、`msa/edqs` 配合）

3.1 `common/transport` 再拆一层

路径	作用
`transport-api`	传输层公共接口，供 Core 与独立 Transport 进程共用
`mqtt` / `http` / `coap` / `lwm2m` / `snmp`	各协议业务实现（鉴权、Topic、上报落库入口等）

MQTT 底层协议细节还依赖根模块 netty-mqtt；真正「可单独起进程」的入口在根模块 transport/*。

4. `application`：主应用入口

单体模式下几乎所有能力都从这里启动。

关键类 / 包	作用
`ThingsboardServerApplication`	正常启动入口（日志里的 `Started ThingsboardServerApplication`）
`ThingsboardInstallApplication`	安装 / 初始化库表与系统资源（对应 Docker 的 `INSTALL_TB`）
`controller`	REST API
`service`	业务服务（设备、遥测、告警、队列桥接等）
`actors`	应用侧 Actor（设备 Actor、规则链 Actor 等）
`install`	安装、升级、导入系统数据
`config`	Spring / 安全等配置

二开常见入口：

改 REST：application/.../controller
改业务编排：application/.../service + rule-engine
改库表逻辑：dao + common/data

5. `dao`：数据访问实现

职责： 实现 common/dao-api，把实体、关系、时序、属性写入 PostgreSQL（以及混合模式下的 Cassandra）。
和 data 的关系： 改字段 / 实体结构先动 common/data，再改 dao 映射与 SQL；不要把业务逻辑堆在 DAO。
混合库： 实体仍在 SQL，时序可走 Cassandra（部署见 Ubuntu 部署文方式 C/D）。

6. `rule-engine`：自研规则引擎

ThingsBoard 没有用 Drools，而是自研规则链。rule-engine 下主要两块：

子模块	作用
`rule-engine-api`	节点、上下文、消息类型等 API / SPI
`rule-engine-components`	内置节点：过滤、变换、脚本、延时、RPC、邮件、队列、外部调用等

消息经 Transport → Queue → Rule Engine 节点链处理，再写库、下发 RPC 或通知。自定义节点通常基于 rule-engine-api 扩展，并在组件模块中注册。

脚本节点可走内嵌或远程 msa/js-executor（Node.js 沙箱）。

7. `transport` 与 `netty-mqtt`

模块	作用
`transport/mqtt` 等	各协议 Spring Boot 启动器；微服务时可单独扩容
`common/transport/*`	协议业务实现
`netty-mqtt`	MQTT 协议本身（连接生命周期、发布订阅等）

五种传输启动器：

transport/mqtt
transport/http
transport/coap
transport/lwm2m
transport/snmp

单体安装时这些能力常打进 application；集群时可按 msa/transport 拆成独立容器。

8. `ui-ngx`：前端

目录名是 ui-ngx（不是旧文里的 ui-nginx）。
技术栈：Angular（release-4.3 上为 Angular 20），配合 Material、NgRx、仪表盘组件等；不是旧版 AngularJS + React 混写说法。
源码编译时一般由 Maven frontend-maven-plugin 拉 Node/Yarn，见源码编译文。
改 Logo、菜单、仪表盘壳子，优先从这里入手；微服务场景还可用 msa/web-ui 单独出镜像。

9. `msa`：微服务与配套组件

子目录	作用
`tb`	单体式 TB 镜像 / 应用打包配置
`tb-node`	节点镜像（Core / Rule Engine 等角色常用）
`transport`	各协议 Transport 的 Docker 构建
`web-ui`	前端静态资源 + HTTP 服务镜像
`js-executor`	规则引擎 JS 远程执行（Node.js 沙箱）
`vc-executor` / `vc-executor-docker`	版本控制执行器及其镜像
`edqs`	EDQS 微服务镜像构建
`monitoring`	监控相关 MSA 工程
`black-box-tests`	黑盒 / 端到端测试

本地学习单体足够；上生产集群再深入 msa + 仓库根目录 docker。

10. `edqs`：实体数据查询服务（4.x 重点）

EDQS（Entity Data Query Service） 用于加速仪表盘等场景下的实体过滤 / 计数 / 分页查询：

可选组件；设备规模大、仪表盘读多时收益明显。
通过 Kafka 与 Core 同步实体状态，查询尽量走 内存结构（并可落盘恢复），减轻 SQL 读压力。
代码分布：根模块 edqs、common/edqs、msa/edqs。

官方介绍：Introducing EDQS。小规模 PoC 可先忽略，读仪表盘查询相关代码时再回来看。

11. 其它实用模块

模块	作用
`rest-client`	Java 封装 REST，适合外部系统对接或自动化脚本
`tools`	MQTT（含 SSL）、REST 等压测 / 演示客户端
`monitoring`	平台监控相关
`docker`	官方 Compose（含 postgres / hybrid 等），与文档部署强相关
`packaging`	系统包、安装脚本相关材料

12. 二开怎么选目录（速查）

你想改什么	优先看
实体字段、DTO	`common/data` → `dao`
REST 接口	`application/.../controller`
设备上报协议逻辑	`common/transport/<协议>`、`transport/<协议>`、`netty-mqtt`（MQTT）
规则链节点	`rule-engine/rule-engine-api`、`rule-engine-components`
队列 / 集群消息	`common/queue`、`common/message`、`common/cluster-api`
前端页面 / 仪表盘壳	`ui-ngx`
安装初始化流程	`application` 的 `install`、`ThingsboardInstallApplication`
独立部署镜像	`msa/*`、`docker`
大规模实体查询	`edqs`、`common/edqs`

13. 与旧笔记的差异（基于 release-4.3 校正）

对照仓库现状，相对常见旧稿需注意：

前端目录是 ui-ngx，技术栈为 Angular 20，不是 ui-nginx / AngularJS。
common/data ≠ DAO 接口；接口在 dao-api，实现在 dao。
根模块新增 / 强调：edqs、monitoring；common 下有 proto、discovery-api、edqs。
msa 中正确拼写为 js-executor；并有 edqs、monitoring。
rule-engine 在 release-4.3 主要为 rule-engine-api + rule-engine-components 两套（旧文「3 个组件」说法可忽略，以仓库为准）。

14. 小结

application + common + dao + rule-engine + transport + ui-ngx 构成日常二开主路径。
协议实现在 common/transport，启动器在 transport，MQTT 底层在 netty-mqtt。
msa / docker / edqs 面向微服务、集群与大规模查询，单体先跑通再深入。
读结构请以分支 release-4.3 目录与 pom.xml 为准。

ThingsBoard 项目结构介绍（release-4.3） ​

1. 先建立整体图 ​

2. 顶层目录速查 ​

3. common：公共能力层 ​

3.1 common/transport 再拆一层 ​

4. application：主应用入口 ​

5. dao：数据访问实现 ​

6. rule-engine：自研规则引擎 ​

7. transport 与 netty-mqtt ​

8. ui-ngx：前端 ​

9. msa：微服务与配套组件 ​

10. edqs：实体数据查询服务（4.x 重点） ​

11. 其它实用模块 ​

12. 二开怎么选目录（速查） ​

13. 与旧笔记的差异（基于 release-4.3 校正） ​

14. 小结 ​

下一步 ​