thingsboard/summary/21-镜像交互关系分析.md

ThingsBoard 镜像交互关系分析

1. 概述

本文档基于文档17（Docker镜像分类分析）、文档19（镜像打包命令）以及源码和docker配置文件，详细分析ThingsBoard各个镜像之间的交互关系和依赖关系。

2. 镜像交互架构图

┌─────────────────────────────────────────────────────────────────┐
│                        外部设备/用户                              │
└────────────┬────────────────────────────┬──────────────────────┘
             │                            │
             ▼                            ▼
    ┌─────────────────┐         ┌──────────────────┐
    │   HAProxy       │         │   HAProxy         │
    │  (负载均衡)      │         │  (负载均衡)        │
    └────────┬────────┘         └─────────┬────────┘
             │                              │
             ├──────────────┬───────────────┤
             │              │               │
             ▼              ▼               ▼
    ┌──────────────┐ ┌─────────────┐ ┌──────────────┐
    │ tb-web-ui1   │ │tb-mqtt-trans│ │tb-http-trans │
    │ tb-web-ui2   │ │port1/2       │ │port1/2       │
    └──────┬───────┘ └──────┬──────┘ └──────┬───────┘
           │                │                │
           │                └────────┬────────┘
           │                         │
           ▼                         ▼
    ┌─────────────────────────────────────────┐
    │          Kafka (消息队列)                │
    └──────┬───────────┬──────────────┬───────┘
           │           │              │
           ▼           ▼              ▼
    ┌──────────┐ ┌──────────┐ ┌──────────────┐
    │tb-core1  │ │tb-core2  │ │tb-rule-engine│
    │          │ │          │ │1/2            │
    └────┬─────┘ └────┬─────┘ └──────┬───────┘
         │            │               │
         └────────────┼───────────────┘
                      │
         ┌────────────┼────────────┐
         │            │            │
         ▼            ▼            ▼
    ┌─────────┐ ┌──────────┐ ┌────────────┐
    │PostgreSQL│ │ Cassandra│ │  Valkey    │
    │          │ │          │ │  (缓存)    │
    └─────────┘ └──────────┘ └────────────┘

3. 基础设施镜像交互关系

3.1 ZooKeeper (服务发现)

镜像: zookeeper:3.8.1

被哪些服务依赖:

• ✅ 所有 ThingsBoard 服务（作为服务发现中心）

依赖的镜像:

• 无（基础设施服务）

交互方式:

• 所有 ThingsBoard 服务通过 ZooKeeper 进行服务注册和发现
• 配置: ZOOKEEPER_ENABLED=true, ZOOKEEPER_URL=zookeeper:2181

具体依赖服务列表:

1. tb-core1, tb-core2
2. tb-rule-engine1, tb-rule-engine2
3. tb-mqtt-transport1, tb-mqtt-transport2
4. tb-http-transport1, tb-http-transport2
5. tb-coap-transport
6. tb-lwm2m-transport
7. tb-snmp-transport
8. tb-vc-executor1, tb-vc-executor2
9. tb-edqs1, tb-edqs2（如果启用）

---

3.2 PostgreSQL (SQL数据库)

镜像: postgres:16

被哪些服务依赖:

• ✅ tb-core1, tb-core2（存储实体数据）
• ✅ tb-rule-engine1, tb-rule-engine2（读取实体数据）

依赖的镜像:

• 无（数据库服务）

交互方式:

• JDBC 连接: jdbc:postgresql://postgres:5432/thingsboard
• 配置: DATABASE_TS_TYPE=sql（SQL模式）

用途:

• 存储租户、用户、设备、资产、规则链等实体数据
• 存储时序数据（在SQL模式下）

---

3.3 Cassandra (NoSQL数据库，可选)

镜像: cassandra:5.0

被哪些服务依赖:

• ✅ tb-core1, tb-core2（混合模式下的时序数据存储）
• ✅ tb-rule-engine1, tb-rule-engine2（混合模式）

依赖的镜像:

• 无（数据库服务）

交互方式:

• Cassandra 客户端连接
• 配置: DATABASE_TS_TYPE=cassandra（混合模式）

用途:

• 存储时序数据（遥测数据）
• 仅在混合数据库模式下使用（hybrid模式）

---

3.4 Kafka (消息队列)

镜像: bitnamilegacy/kafka:4.0

被哪些服务依赖:

• ✅ tb-core1, tb-core2
• ✅ tb-rule-engine1, tb-rule-engine2
• ✅ tb-mqtt-transport1, tb-mqtt-transport2
• ✅ tb-http-transport1, tb-http-transport2
• ✅ tb-coap-transport
• ✅ tb-lwm2m-transport
• ✅ tb-snmp-transport
• ✅ tb-vc-executor1, tb-vc-executor2
• ✅ tb-js-executor（所有副本）
• ✅ tb-edqs1, tb-edqs2（如果启用）

依赖的镜像:

• 无（消息队列服务）

交互方式:

• Kafka Producer/Consumer API
• 配置: TB_QUEUE_TYPE=kafka, TB_KAFKA_SERVERS=kafka:9092

消息主题类型:

• tb-core.*: 核心服务消息
• tb.rule-engine.*: 规则引擎消息
• tb.transport.*: 传输服务消息
• tb.notifications.*: 通知消息
• tb.js-evaluator.*: JS执行器消息

用途:

• 所有 ThingsBoard 服务间异步通信的中枢
• 实现服务解耦和高可用

---

3.5 Valkey (缓存)

镜像: bitnamilegacy/valkey:8.0 (或 sentinel/cluster 模式)

被哪些服务依赖:

• ✅ tb-core1, tb-core2
• ✅ tb-rule-engine1, tb-rule-engine2
• ✅ tb-mqtt-transport1, tb-mqtt-transport2
• ✅ tb-http-transport1, tb-http-transport2
• ✅ tb-coap-transport
• ✅ tb-lwm2m-transport
• ✅ tb-snmp-transport
• ✅ tb-vc-executor1, tb-vc-executor2

依赖的镜像:

• 无（缓存服务）

交互方式:

• Redis 协议（Valkey兼容Redis协议）
• 配置: CACHE_TYPE=redis, REDIS_HOST=valkey

用途:

• 缓存设备属性
• 缓存会话信息
• 提高查询性能

---

4. ThingsBoard 核心服务镜像交互关系

4.1 tb-core (核心服务)

镜像: thingsboard/tb-node (通过 TB_SERVICE_TYPE=tb-core 区分)

服务实例: tb-core1, tb-core2

依赖的镜像:

1. ✅ ZooKeeper - 服务发现
2. ✅ PostgreSQL - 实体数据存储
3. ✅ Cassandra - 时序数据存储（混合模式）
4. ✅ Kafka - 消息队列通信
5. ✅ Valkey - 缓存
6. ✅ tb-js-executor - JavaScript 执行
7. ✅ tb-rule-engine1, tb-rule-engine2 - 规则引擎（需要规则引擎启动）

被哪些服务依赖:

1. ✅ tb-mqtt-transport1/2 - 接收传输层消息
2. ✅ tb-http-transport1/2 - 接收传输层消息
3. ✅ tb-coap-transport - 接收传输层消息
4. ✅ tb-lwm2m-transport - 接收传输层消息
5. ✅ tb-snmp-transport - 接收传输层消息
6. ✅ tb-vc-executor1/2 - 版本控制执行
7. ✅ tb-web-ui1/2 - 提供 REST API
8. ✅ tb-rule-engine1/2 - 核心服务推送消息到规则引擎
9. ✅ HAProxy - 负载均衡转发请求

交互方式:

接收消息（通过Kafka）:

• 从传输服务接收: ToCoreMsg 类型消息
  • TransportToDeviceActorMsg: 设备遥测、属性、RPC响应
  • DeviceConnectProto: 设备连接
  • DeviceDisconnectProto: 设备断开

发送消息（通过Kafka）:

• 发送到规则引擎: ToRuleEngineMsg 类型消息
• 发送到传输服务: ToTransportMsg 类型消息
  • ToDeviceRpcRequestMsg: RPC请求
  • AttributeUpdateNotificationMsg: 属性更新通知
  • SessionCloseNotificationProto: 会话关闭

HTTP交互:

• 提供 REST API 供 tb-web-ui 调用
• 端口: 8080 (HTTP API)

数据库交互:

• PostgreSQL: 读写实体数据
• Cassandra: 读写时序数据（混合模式）

缓存交互:

• Valkey: 读写设备属性缓存

---

4.2 tb-rule-engine (规则引擎)

镜像: thingsboard/tb-node (通过 TB_SERVICE_TYPE=tb-rule-engine 区分)

服务实例: tb-rule-engine1, tb-rule-engine2

依赖的镜像:

1. ✅ ZooKeeper - 服务发现
2. ✅ PostgreSQL - 读取实体数据（规则链配置等）
3. ✅ Kafka - 消息队列通信
4. ✅ Valkey - 缓存
5. ✅ tb-js-executor - JavaScript 规则节点执行

被哪些服务依赖:

1. ✅ tb-core1, tb-core2 - 核心服务推送消息到规则引擎
2. ✅ tb-edqs1, tb-edqs2 - 事件驱动查询（可选）

交互方式:

接收消息（通过Kafka）:

• 从核心服务接收: ToRuleEngineMsg 类型消息
  • 设备遥测数据
  • 设备属性更新
  • 设备事件（连接、断开等）

发送消息（通过Kafka）:

• 发送到核心服务: ToCoreMsg 类型消息
  • 规则链处理后的结果（保存数据、触发告警等）

HTTP交互:

• 提供内部 REST API
• 端口: 8080

数据库交互:

• PostgreSQL: 读取规则链配置

缓存交互:

• Valkey: 缓存规则链元数据

---

5. 传输服务镜像交互关系

5.1 tb-mqtt-transport (MQTT传输服务)

镜像: thingsboard/tb-mqtt-transport

服务实例: tb-mqtt-transport1, tb-mqtt-transport2

依赖的镜像:

1. ✅ ZooKeeper - 服务发现
2. ✅ Kafka - 消息队列通信
3. ✅ Valkey - 缓存
4. ✅ tb-core1, tb-core2 - 通过ZooKeeper发现核心服务

被哪些服务依赖:

• ✅ HAProxy - 负载均衡转发MQTT连接（端口1883）

交互方式:

接收消息（从设备）:

• MQTT协议: 端口 1883
• 接收设备遥测、属性、RPC响应

发送消息（通过Kafka）:

• 发送到核心服务: ToCoreMsg 类型消息
  • TransportToDeviceActorMsg: 设备遥测、属性
  • DeviceConnectProto: 设备连接事件
  • DeviceDisconnectProto: 设备断开事件

接收消息（通过Kafka）:

• 从核心服务接收: ToTransportMsg 类型消息
  • ToDeviceRpcRequestMsg: RPC请求
  • AttributeUpdateNotificationMsg: 属性更新通知

缓存交互:

• Valkey: 缓存设备会话信息

---

5.2 tb-http-transport (HTTP传输服务)

镜像: thingsboard/tb-http-transport

服务实例: tb-http-transport1, tb-http-transport2

依赖的镜像:

1. ✅ ZooKeeper - 服务发现
2. ✅ Kafka - 消息队列通信
3. ✅ Valkey - 缓存
4. ✅ tb-core1, tb-core2 - 通过ZooKeeper发现核心服务

被哪些服务依赖:

• ✅ HAProxy - 负载均衡转发HTTP请求（端口8081）

交互方式:

• 与 tb-mqtt-transport 类似，但使用 HTTP 协议
• HTTP端口: 8081

---

5.3 tb-coap-transport (CoAP传输服务)

镜像: thingsboard/tb-coap-transport

服务实例: tb-coap-transport

依赖和交互:

• 与 tb-mqtt-transport 类似
• CoAP端口: 5683/udp

---

5.4 tb-lwm2m-transport (LWM2M传输服务)

镜像: thingsboard/tb-lwm2m-transport

服务实例: tb-lwm2m-transport

依赖和交互:

• 与 tb-mqtt-transport 类似
• LWM2M端口: 5685/udp, 5686/udp

---

5.5 tb-snmp-transport (SNMP传输服务)

镜像: thingsboard/tb-snmp-transport

服务实例: tb-snmp-transport

依赖和交互:

• 与 tb-mqtt-transport 类似
• SNMP端口: 1620/udp

---

6. 前端服务镜像交互关系

6.1 tb-web-ui (Web前端)

镜像: thingsboard/tb-web-ui

服务实例: tb-web-ui1, tb-web-ui2

依赖的镜像:

1. ✅ tb-core1, tb-core2 - 通过HTTP REST API交互

被哪些服务依赖:

• ✅ HAProxy - 负载均衡转发HTTP请求（端口80/443）

交互方式:

HTTP交互:

• 前端通过HTTP REST API调用核心服务
• API路径: /api/*
• 核心服务端口: 8080

WebSocket交互:

• 建立WebSocket连接到核心服务
• 接收实时数据推送（设备遥测、属性更新）

说明:

• tb-web-ui 不直接依赖 ZooKeeper、Kafka、数据库
• 所有与后端的交互都通过 tb-core 的 REST API 和 WebSocket

---

7. 辅助服务镜像交互关系

7.1 tb-js-executor (JavaScript执行器)

镜像: thingsboard/tb-js-executor

服务实例: tb-js-executor (10个副本)

依赖的镜像:

1. ✅ Kafka - 接收JavaScript执行请求

被哪些服务依赖:

1. ✅ tb-core1, tb-core2 - 执行JavaScript规则节点
2. ✅ tb-rule-engine1, tb-rule-engine2 - 执行JavaScript规则节点

交互方式:

接收消息（通过Kafka）:

• Kafka主题: tb.js-evaluator.*
• 接收JavaScript执行请求（来自规则引擎）

发送消息（通过Kafka）:

• 返回JavaScript执行结果

说明:

• tb-js-executor 不依赖 ZooKeeper（通过Kafka主题直接通信）
• 配置: JS_EVALUATOR=remote

---

7.2 tb-vc-executor (版本控制执行器)

镜像: thingsboard/tb-vc-executor

服务实例: tb-vc-executor1, tb-vc-executor2

依赖的镜像:

1. ✅ ZooKeeper - 服务发现
2. ✅ Kafka - 消息队列通信
3. ✅ Valkey - 缓存
4. ✅ tb-core1, tb-core2 - 接收版本控制请求

被哪些服务依赖:

• ✅ tb-core1, tb-core2 - 版本控制功能

交互方式:

• 通过Kafka接收版本控制相关的消息
• 处理规则链、脚本等资源的版本控制

---

7.3 tb-edqs (事件驱动查询服务)

镜像: thingsboard/tb-edqs

服务实例: tb-edqs1, tb-edqs2 (可选)

依赖的镜像:

1. ✅ ZooKeeper - 服务发现
2. ✅ Kafka - 消息队列通信

被哪些服务依赖:

1. ✅ tb-core1, tb-core2 - 可选，用于高性能查询
2. ✅ tb-rule-engine1, tb-rule-engine2 - 可选，用于高性能查询

交互方式:

• 通过Kafka接收查询请求
• 提供高性能的事件驱动查询服务

说明:

• 这是可选服务，仅在启用EDQS功能时使用
• 配置文件: tb-core-edqs.env, tb-rule-engine-edqs.env

---

8. 负载均衡镜像交互关系

8.1 HAProxy

镜像: thingsboard/haproxy-certbot:2.2.33-alpine

依赖的镜像:

• 无（基础设施服务）

被哪些服务依赖:

• ✅ 外部用户/设备 - 通过HAProxy访问ThingsBoard服务

交互的后端服务:

1. ✅ tb-core1, tb-core2 - API请求（/api/*）
2. ✅ tb-web-ui1, tb-web-ui2 - Web UI请求
3. ✅ tb-mqtt-transport1, tb-mqtt-transport2 - MQTT连接（端口1883）
4. ✅ tb-http-transport1, tb-http-transport2 - HTTP传输（端口8081）
5. ✅ tb-core1, tb-core2 - Edges RPC（端口7070）

端口映射:

• 80 → Web UI (HTTP)
• 443 → Web UI (HTTPS)
• 1883 → MQTT Transport
• 7070 → Edges RPC
• 9999 → HAProxy Stats

配置方式:

• 通过 links 配置后端服务
• 配置文件: haproxy/config/haproxy.cfg

---

9. 消息流向分析

9.1 设备数据流（上行）

设备 
  → tb-mqtt-transport (MQTT协议)
  → Kafka (ToCoreMsg)
  → tb-core (处理设备数据)
  → Kafka (ToRuleEngineMsg)
  → tb-rule-engine (规则链处理)
  → PostgreSQL/Cassandra (存储数据)
  → Kafka (ToTransportMsg, 如果需要推送到设备)
  → tb-mqtt-transport
  → 设备

9.2 Web UI数据流

用户浏览器
  → HAProxy (负载均衡)
  → tb-web-ui (前端服务)
  → HTTP REST API
  → tb-core (处理API请求)
  → PostgreSQL (读取/写入数据)
  → tb-core (返回结果)
  → tb-web-ui (渲染页面)
  → 用户浏览器

9.3 规则引擎数据流

tb-core
  → Kafka (ToRuleEngineMsg)
  → tb-rule-engine (接收消息)
  → tb-js-executor (执行JavaScript, 如果需要)
  → Kafka (JavaScript执行结果)
  → tb-rule-engine (规则链处理)
  → PostgreSQL/Cassandra (保存处理结果)
  → Kafka (ToCoreMsg, 如果需要通知核心服务)
  → tb-core

9.4 RPC请求流（下行）

用户/规则引擎
  → tb-core (接收RPC请求)
  → Kafka (ToTransportMsg - ToDeviceRpcRequestMsg)
  → tb-mqtt-transport (接收RPC请求)
  → 设备 (MQTT协议)
  → tb-mqtt-transport (接收RPC响应)
  → Kafka (ToCoreMsg - FromDeviceRpcResponse)
  → tb-core (返回RPC响应)
  → 用户/规则引擎

---

10. 依赖关系总结表

10.1 直接依赖关系（depends_on）

服务	依赖的基础设施	依赖的ThingsBoard服务
tb-core1/2	ZooKeeper, PostgreSQL, Kafka, Valkey	tb-js-executor, tb-rule-engine1/2
tb-rule-engine1/2	ZooKeeper, PostgreSQL, Kafka, Valkey	tb-js-executor
tb-mqtt-transport1/2	ZooKeeper, Kafka, Valkey	tb-core1/2
tb-http-transport1/2	ZooKeeper, Kafka, Valkey	tb-core1/2
tb-coap-transport	ZooKeeper, Kafka, Valkey	tb-core1/2
tb-lwm2m-transport	ZooKeeper, Kafka, Valkey	tb-core1/2
tb-snmp-transport	ZooKeeper, Kafka, Valkey	tb-core1/2
tb-web-ui1/2	无	tb-core1/2 (通过HTTP)
tb-js-executor	Kafka	无
tb-vc-executor1/2	ZooKeeper, Kafka, Valkey	tb-core1/2
tb-edqs1/2	ZooKeeper, Kafka	tb-core1/2, tb-rule-engine1/2
HAProxy	无	tb-core1/2, tb-web-ui1/2, tb-mqtt-transport1/2, tb-http-transport1/2

10.2 通过Kafka的间接依赖关系

所有 ThingsBoard 服务都通过 Kafka 进行消息通信:

• tb-mqtt-transport → Kafka → tb-core → Kafka → tb-rule-engine → Kafka → tb-js-executor

10.3 通过数据库的间接依赖关系

• tb-core, tb-rule-engine → PostgreSQL (实体数据)
• tb-core → Cassandra (时序数据，混合模式)

10.4 通过缓存的间接依赖关系

• tb-core, tb-rule-engine, 传输服务, tb-vc-executor → Valkey (属性缓存)

---

11. 关键交互协议

11.1 服务发现协议

• ZooKeeper: 所有ThingsBoard服务通过ZooKeeper进行服务注册和发现
• 配置: ZOOKEEPER_URL=zookeeper:2181

11.2 消息通信协议

• Kafka: 所有ThingsBoard服务间异步消息通信
• 消息格式: Protobuf 序列化
• 配置: TB_QUEUE_TYPE=kafka, TB_KAFKA_SERVERS=kafka:9092

11.3 数据访问协议

• PostgreSQL: JDBC协议 (jdbc:postgresql://postgres:5432/thingsboard)
• Cassandra: Cassandra客户端协议（混合模式）

11.4 缓存协议

• Valkey: Redis协议 (REDIS_HOST=valkey:6379)

11.5 HTTP协议

• tb-web-ui → tb-core: HTTP REST API (/api/*)
• WebSocket: 实时数据推送

---

12. 启动顺序建议

基于依赖关系，建议的启动顺序：

1. 基础设施层:

   • ZooKeeper
   • PostgreSQL / Cassandra
   • Kafka
   • Valkey

2. 辅助服务层:

   • tb-js-executor (10个副本)

3. 核心服务层:

   • tb-rule-engine1, tb-rule-engine2
   • tb-core1, tb-core2

4. 传输服务层:

   • tb-mqtt-transport1/2
   • tb-http-transport1/2
   • tb-coap-transport
   • tb-lwm2m-transport
   • tb-snmp-transport

5. 前端服务层:

   • tb-web-ui1, tb-web-ui2

6. 负载均衡层:

   • HAProxy

7. 可选服务 (如果需要):

   • tb-vc-executor1/2
   • tb-edqs1/2

---

13. 总结

13.1 核心交互模式

1. 所有ThingsBoard服务 → ZooKeeper (服务发现)
2. 所有ThingsBoard服务 → Kafka (异步消息通信)
3. 传输服务 → Kafka → tb-core → Kafka → tb-rule-engine
4. tb-core, tb-rule-engine → PostgreSQL (实体数据)
5. tb-core, tb-rule-engine, 传输服务 → Valkey (缓存)
6. tb-web-ui → HTTP → tb-core (REST API)
7. tb-core, tb-rule-engine → Kafka → tb-js-executor (JavaScript执行)

13.2 关键发现

1. Kafka是核心通信枢纽: 所有ThingsBoard服务间通信都通过Kafka
2. ZooKeeper是服务发现中心: 所有ThingsBoard服务都需要ZooKeeper进行服务注册和发现
3. tb-core是核心服务: 连接传输层、规则引擎、数据库和前端
4. 传输服务直接与设备通信: 通过MQTT/HTTP/CoAP等协议
5. tb-web-ui通过HTTP与tb-core交互: 不直接访问数据库或Kafka
6. tb-js-executor是异步服务: 通过Kafka接收执行请求，不依赖ZooKeeper

---

14. 参考文档

• 17-Docker镜像分类分析.md
• 19-ThingsBoard所有镜像打包命令.md
• 02-模块交互与通信机制.md