# ThingsBoard 架构图 Docker 部署方案分析

## 1. 架构图组件映射

根据提供的架构图，各组件在 Docker 部署中的映射关系如下：

```
架构图组件                    →  Docker 服务
─────────────────────────────────────────────────────────
ThingsBoard Transports        →  tb-mqtt-transport (多个实例)
                              →  tb-http-transport (多个实例)
                              →  tb-coap-transport
                              →  tb-lwm2m-transport
                              →  tb-snmp-transport

Queue                        →  kafka (消息队列)
                              →  或 rabbitmq (可选)

ThingsBoard Core             →  tb-core1, tb-core2 (核心服务)

Rule Engine                  →  tb-rule-engine1, tb-rule-engine2

SQL Database                 →  postgres (PostgreSQL)

NoSQL Database               →  cassandra (Cassandra，可选)
                              →  或 timescaledb (PostgreSQL扩展)

ThingsBoard UI               →  tb-web-ui1, tb-web-ui2

External Systems             →  外部系统（不包含在部署中）

ZooKeeper                    →  zookeeper (服务发现)

JS Executor                  →  tb-js-executor (JavaScript执行器)

HAProxy                      →  haproxy (负载均衡器)
```

## 2. 完整 Docker Compose 部署架构

### 2.1 微服务模式部署结构

```yaml
# 完整部署包含以下服务组：

基础设施层:
  - zookeeper          # 服务发现
  - postgres           # SQL数据库（实体数据）
  - cassandra          # NoSQL数据库（时序数据，可选）
  - kafka              # 消息队列
  - valkey/redis       # 缓存

核心服务层:
  - tb-core1, tb-core2          # 核心服务（2个实例，高可用）
  - tb-rule-engine1, tb-rule-engine2  # 规则引擎（2个实例）

传输层服务:
  - tb-mqtt-transport1, tb-mqtt-transport2    # MQTT传输（2个实例）
  - tb-http-transport1, tb-http-transport2   # HTTP传输（2个实例）
  - tb-coap-transport                         # CoAP传输
  - tb-lwm2m-transport                        # LWM2M传输
  - tb-snmp-transport                         # SNMP传输

前端服务:
  - tb-web-ui1, tb-web-ui2       # Web UI（2个实例）

辅助服务:
  - tb-js-executor               # JavaScript执行器（10个副本）
  - tb-vc-executor1, tb-vc-executor2  # 版本控制执行器
  - haproxy                       # 负载均衡器
```

### 2.2 数据流在 Docker 中的实现

```
设备 (Devices)
  ↓
  ├─ 直接连接 ──────────────────────────────┐
  │   (MQTT/HTTP/CoAP/LWM2M/SNMP)          │
  │                                         │
  └─ 通过网关 (Gateways) ──────────────────┤
      (Modbus/OPC-UA/其他协议)              │
      转为 MQTT ────────────────────────────┤
                                            ↓
                            ┌───────────────────────────────┐
                            │  ThingsBoard Transports       │
                            │  (Docker 服务)                 │
                            │  - tb-mqtt-transport1/2       │
                            │  - tb-http-transport1/2       │
                            │  - tb-coap-transport          │
                            │  - tb-lwm2m-transport         │
                            │  - tb-snmp-transport          │
                            └───────────┬───────────────────┘
                                        │
                                        ↓
                            ┌───────────────────────────────┐
                            │  Queue (Kafka)                │
                            │  Docker: kafka                │
                            │  Port: 9092                   │
                            └───────────┬───────────────────┘
                                        │
                                        ↓
                            ┌───────────────────────────────┐
                            │  ThingsBoard Core             │
                            │  Docker: tb-core1, tb-core2   │
                            │  通过 ZooKeeper 服务发现       │
                            └───────────┬───────────────────┘
                                        │
                    ┌───────────────────┴───────────────────┐
                    │                                         │
                    ↓                                         ↓
        ┌───────────────────────┐              ┌───────────────────────┐
        │  SQL Database          │              │  Queue (Kafka)        │
        │  Docker: postgres      │              │  (路由到规则引擎)      │
        │  Port: 5432            │              └───────────┬───────────┘
        │  存储: 实体数据         │                          │
        └────────────────────────┘                          ↓
                                                ┌───────────────────────────────┐
                                                │  Rule Engine                  │
                                                │  Docker: tb-rule-engine1/2   │
                                                └───────────┬───────────────────┘
                                                            │
                                                            ↓
                                                ┌───────────────────────────────┐
                                                │  NoSQL Database               │
                                                │  Docker: cassandra            │
                                                │  Port: 9042                    │
                                                │  存储: 时序数据                │
                                                └───────────────────────────────┘

前端访问:
  ┌───────────────────────────────┐
  │  ThingsBoard UI               │
  │  Docker: tb-web-ui1, tb-web-ui2 │
  │  通过 HAProxy 负载均衡          │
  └───────────┬───────────────────┘
              │
              ↓ REST API / WebSockets
  ┌───────────────────────────────┐
  │  ThingsBoard Core             │
  │  (tb-core1, tb-core2)         │
  └───────────────────────────────┘
```

## 3. Docker Compose 配置文件组合

### 3.1 配置文件组合方式

ThingsBoard 使用多个 Docker Compose 文件组合的方式：

```bash
# 基础服务配置
docker-compose.yml              # 主配置文件（定义所有服务）

# 数据库配置（选择其一）
docker-compose.postgres.yml     # PostgreSQL模式（SQL数据库）
docker-compose.hybrid.yml       # 混合模式（PostgreSQL + Cassandra）

# 消息队列配置（选择其一）
docker-compose.kafka.yml        # Kafka队列
docker-compose.confluent.yml    # Confluent Kafka（生产环境）

# 缓存配置（选择其一）
docker-compose.valkey.yml       # Valkey单节点
docker-compose.valkey-cluster.yml  # Valkey集群
docker-compose.valkey-sentinel.yml # Valkey哨兵模式

# 其他可选配置
docker-compose.edqs.yml         # 事件驱动查询服务
docker-compose.prometheus-grafana.yml  # 监控服务
```

### 3.2 完整部署命令示例

```bash
# 组合所有配置文件启动（PostgreSQL + Kafka + Valkey）
docker-compose \
  -f docker-compose.yml \
  -f docker-compose.postgres.yml \
  -f docker-compose.kafka.yml \
  -f docker-compose.valkey.yml \
  up -d

# 或使用混合模式（PostgreSQL + Cassandra + Kafka）
docker-compose \
  -f docker-compose.yml \
  -f docker-compose.hybrid.yml \
  -f docker-compose.kafka.yml \
  -f docker-compose.valkey-cluster.yml \
  up -d
```

## 4. 各组件详细配置

### 4.1 ThingsBoard Transports（传输层）

#### MQTT Transport

```yaml
tb-mqtt-transport1:
  image: "${DOCKER_REPO}/${MQTT_TRANSPORT_DOCKER_NAME}:${TB_VERSION}"
  ports:
    - "1883"  # MQTT端口
  environment:
    TB_SERVICE_ID: tb-mqtt-transport1
    ZOOKEEPER_ENABLED: "true"
    ZOOKEEPER_URL: zookeeper:2181
    MQTT_BIND_ADDRESS: 0.0.0.0
    MQTT_BIND_PORT: 1883
  env_file:
    - tb-mqtt-transport.env
    - queue-kafka.env  # 队列配置
  depends_on:
    - zookeeper
    - kafka
    - tb-core1
    - tb-core2
```

**端口映射**:
- `1883`: MQTT协议（非加密）
- `8883`: MQTT over SSL（通过配置启用）

**数据流**:
```
设备 (MQTT客户端)
  ↓ 连接
tb-mqtt-transport (接收MQTT消息)
  ↓ 认证设备
  ↓ 解析消息
  ↓ 发送到队列
Kafka Queue
  ↓ 消费
tb-core (处理设备数据)
```

#### HTTP Transport

```yaml
tb-http-transport1:
  image: "${DOCKER_REPO}/${HTTP_TRANSPORT_DOCKER_NAME}:${TB_VERSION}"
  ports:
    - "8081"  # HTTP API端口
  environment:
    TB_SERVICE_ID: tb-http-transport1
    HTTP_BIND_PORT: 8081
  depends_on:
    - zookeeper
    - kafka
    - tb-core1
    - tb-core2
```

#### CoAP Transport

```yaml
tb-coap-transport:
  image: "${DOCKER_REPO}/${COAP_TRANSPORT_DOCKER_NAME}:${TB_VERSION}"
  ports:
    - "5683:5683/udp"  # CoAP端口（UDP）
  environment:
    TB_SERVICE_ID: tb-coap-transport
  depends_on:
    - zookeeper
    - kafka
    - tb-core1
    - tb-core2
```

#### LWM2M Transport

```yaml
tb-lwm2m-transport:
  image: "${DOCKER_REPO}/${LWM2M_TRANSPORT_DOCKER_NAME}:${TB_VERSION}"
  ports:
    - "5685:5685/udp"  # LWM2M非加密
    - "5686:5686/udp"  # LWM2M over DTLS
  environment:
    TB_SERVICE_ID: tb-lwm2m-transport
```

#### SNMP Transport

```yaml
tb-snmp-transport:
  image: "${DOCKER_REPO}/${SNMP_TRANSPORT_DOCKER_NAME}:${TB_VERSION}"
  ports:
    - "1620:1620/udp"  # SNMP Trap端口
  environment:
    TB_SERVICE_ID: tb-snmp-transport
```

### 4.2 Queue（消息队列）

#### Kafka 配置

```yaml
kafka:
  image: "bitnamilegacy/kafka:4.0"
  ports:
    - "9092:9092"  # Kafka Broker端口
  environment:
    KAFKA_CFG_LISTENERS: "PLAINTEXT://:9092"
    KAFKA_CFG_ADVERTISED_LISTENERS: "PLAINTEXT://:9092"
    KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
  env_file:
    - kafka.env
  depends_on:
    - zookeeper
```

**队列主题**:
- `tb.rule-engine.*`: 规则引擎消息
- `tb.core.*`: 核心服务消息
- `tb.transport.*`: 传输层消息

**服务连接配置**:
```bash
# queue-kafka.env
TB_QUEUE_TYPE=kafka
TB_KAFKA_SERVERS=kafka:9092
```

### 4.3 ThingsBoard Core（核心服务）

```yaml
tb-core1:
  image: "${DOCKER_REPO}/${TB_NODE_DOCKER_NAME}:${TB_VERSION}"
  ports:
    - "8080"  # HTTP API端口
    - "7070"  # Edge RPC端口
  environment:
    TB_SERVICE_ID: tb-core1
    TB_SERVICE_TYPE: tb-core  # 核心服务类型
    ZOOKEEPER_ENABLED: "true"
    ZOOKEEPER_URL: zookeeper:2181
    TRANSPORT_TYPE: remote  # 使用远程传输服务
    JS_EVALUATOR: remote    # 使用远程JS执行器
  env_file:
    - tb-node.env
    - tb-node.postgres.env  # 数据库配置
    - queue-kafka.env       # 队列配置
  depends_on:
    - zookeeper
    - postgres
    - kafka
    - tb-js-executor
```

**核心功能**:
- 设备管理
- 用户和租户管理
- REST API服务
- Actor系统管理
- 与传输层和规则引擎通信

### 4.4 Rule Engine（规则引擎）

```yaml
tb-rule-engine1:
  image: "${DOCKER_REPO}/${TB_NODE_DOCKER_NAME}:${TB_VERSION}"
  ports:
    - "8080"  # HTTP端口（用于管理）
  environment:
    TB_SERVICE_ID: tb-rule-engine1
    TB_SERVICE_TYPE: tb-rule-engine  # 规则引擎类型
    ZOOKEEPER_ENABLED: "true"
    ZOOKEEPER_URL: zookeeper:2181
  env_file:
    - tb-node.env
    - tb-node.postgres.env
    - queue-kafka.env
  depends_on:
    - zookeeper
    - postgres
    - kafka
    - tb-js-executor
```

**数据流**:
```
tb-core (处理设备数据)
  ↓ 发送消息到队列
Kafka Queue (tb.rule-engine.*)
  ↓ 消费消息
tb-rule-engine (执行规则链)
  ↓ 保存时序数据
Cassandra/PostgreSQL (时序数据库)
  ↓ 触发动作
External Systems (HTTP/Email/RPC等)
```

### 4.5 SQL Database（PostgreSQL）

```yaml
postgres:
  image: "postgres:16"
  ports:
    - "5432"  # 仅内部访问
  environment:
    POSTGRES_DB: thingsboard
    POSTGRES_PASSWORD: postgres
  volumes:
    - ./tb-node/postgres:/var/lib/postgresql/data
```

**存储内容**:
- 租户、用户、设备等实体数据
- 设备配置和属性
- 规则链配置
- 仪表板配置
- 如果使用SQL模式，还存储时序数据

### 4.6 NoSQL Database（Cassandra）

```yaml
cassandra:
  image: "cassandra:5.0"
  ports:
    - "9042"  # CQL端口
  volumes:
    - ./tb-node/cassandra:/var/lib/cassandra
```

**存储内容**:
- 设备遥测数据（时序数据）
- 高写入性能
- 适合大规模时序数据存储

**配置**:
```bash
# tb-node.hybrid.env
DATABASE_TS_TYPE=cassandra
CASSANDRA_CLUSTER_NAME=ThingsBoard Cluster
CASSANDRA_URL=cassandra:9042
```

### 4.7 ThingsBoard UI（前端）

```yaml
tb-web-ui1:
  image: "${DOCKER_REPO}/${WEB_UI_DOCKER_NAME}:${TB_VERSION}"
  ports:
    - "8080"  # HTTP端口
  env_file:
    - tb-web-ui.env
  depends_on:
    - tb-core1
    - tb-core2
```

**功能**:
- 提供Web用户界面
- 通过REST API与tb-core通信
- 通过WebSocket接收实时数据

**负载均衡**:
通过HAProxy在多个UI实例间负载均衡。

### 4.8 ZooKeeper（服务发现）

```yaml
zookeeper:
  image: "zookeeper:3.8.1"
  ports:
    - "2181"  # ZooKeeper端口
  environment:
    ZOO_MY_ID: 1
    ZOO_SERVERS: server.1=zookeeper:2888:3888;zookeeper:2181
```

**作用**:
- 服务注册与发现
- 负载均衡
- 服务健康检查
- 分区管理

### 4.9 JS Executor（JavaScript执行器）

```yaml
tb-js-executor:
  image: "${DOCKER_REPO}/${JS_EXECUTOR_DOCKER_NAME}:${TB_VERSION}"
  deploy:
    replicas: 10  # 10个副本
  env_file:
    - tb-js-executor.env
```

**作用**:
- 执行规则引擎中的JavaScript代码
- 数据处理和转换
- 支持高并发执行

### 4.10 HAProxy（负载均衡器）

```yaml
haproxy:
  image: thingsboard/haproxy-certbot:2.2.33-alpine
  ports:
    - "80:80"      # HTTP
    - "443:443"    # HTTPS
    - "1883:1883"  # MQTT
    - "7070:7070"  # Edge RPC
  environment:
    HTTP_PORT: 80
    HTTPS_PORT: 443
    MQTT_PORT: 1883
    EDGES_RPC_PORT: 7070
  links:
    - tb-core1
    - tb-core2
    - tb-web-ui1
    - tb-web-ui2
    - tb-mqtt-transport1
    - tb-mqtt-transport2
```

**功能**:
- HTTP/HTTPS负载均衡（Web UI和API）
- MQTT连接负载均衡
- Edge RPC负载均衡
- SSL/TLS终止

## 5. 部署步骤

### 5.1 准备环境

```bash
# 1. 创建日志目录
cd docker
./docker-create-log-folders.sh

# 2. 配置环境变量（.env文件）
DATABASE=hybrid  # 或 postgres
CACHE=valkey-cluster  # 或 valkey, valkey-sentinel
QUEUE=kafka  # 或 rabbitmq
```

### 5.2 安装数据库

```bash
# 安装并初始化数据库
./docker-install-tb.sh --loadDemo
```

这会：
- 启动PostgreSQL（和Cassandra，如果使用混合模式）
- 初始化数据库schema
- 加载演示数据（如果使用--loadDemo）

### 5.3 启动所有服务

```bash
# 启动所有服务
./docker-start-services.sh
```

实际执行的命令：
```bash
docker-compose \
  -f docker-compose.yml \
  -f docker-compose.hybrid.yml \
  -f docker-compose.kafka.yml \
  -f docker-compose.valkey-cluster.yml \
  up -d
```

### 5.4 验证部署

```bash
# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f tb-core1

# 访问Web UI
# http://localhost (通过HAProxy)
```

## 6. 架构图流程在Docker中的完整实现

### 6.1 设备直接连接流程

```
设备 (MQTT客户端)
  ↓ 连接 mqtt://localhost:1883
HAProxy (负载均衡)
  ↓ 分发到
tb-mqtt-transport1 或 tb-mqtt-transport2
  ↓ 认证设备（通过tb-core）
  ↓ 接收遥测数据
  ↓ 发送到Kafka队列 (tb.transport.telemetry)
Kafka Queue
  ↓ 消费消息
tb-core1 或 tb-core2 (通过ZooKeeper服务发现)
  ↓ 处理设备数据
  ↓ 保存实体数据到PostgreSQL
  ↓ 发送到规则引擎队列 (tb.rule-engine.*)
Kafka Queue (规则引擎队列)
  ↓ 消费消息
tb-rule-engine1 或 tb-rule-engine2
  ↓ 执行规则链
  ↓ 保存时序数据到Cassandra
  ↓ 触发动作（HTTP/Email等）
External Systems
```

### 6.2 网关连接流程

```
设备 (Modbus/OPC-UA)
  ↓ 连接
ThingsBoard Gateway (边缘设备，独立部署)
  ↓ 转换为MQTT
  ↓ 连接 mqtt://localhost:1883
HAProxy
  ↓ 分发
tb-mqtt-transport1/2
  ↓ (后续流程同上)
```

### 6.3 前端访问流程

```
用户浏览器
  ↓ 访问 http://localhost
HAProxy (负载均衡)
  ↓ 分发到
tb-web-ui1 或 tb-web-ui2
  ↓ REST API调用
tb-core1 或 tb-core2 (通过ZooKeeper发现)
  ↓ 查询PostgreSQL
  ↓ 返回数据
tb-web-ui
  ↓ 展示数据
用户浏览器

实时数据:
tb-web-ui
  ↓ WebSocket连接
tb-core
  ↓ 推送实时数据
tb-web-ui (实时更新)
```

## 7. 高可用性配置

### 7.1 服务冗余

- **tb-core**: 2个实例（tb-core1, tb-core2）
- **tb-rule-engine**: 2个实例（tb-rule-engine1, tb-rule-engine2）
- **tb-mqtt-transport**: 2个实例（负载均衡）
- **tb-http-transport**: 2个实例（负载均衡）
- **tb-web-ui**: 2个实例（负载均衡）

### 7.2 数据库高可用

- **PostgreSQL**: 可以配置主从复制
- **Cassandra**: 集群模式（多节点）
- **Kafka**: 集群模式（多broker）

### 7.3 负载均衡

- **HAProxy**: 统一入口，分发请求到多个服务实例
- **ZooKeeper**: 服务发现和负载均衡

## 8. 网络配置

### 8.1 Docker网络

所有服务在同一个Docker Compose网络中，通过服务名访问：

```
zookeeper:2181          # ZooKeeper
postgres:5432           # PostgreSQL
cassandra:9042          # Cassandra
kafka:9092              # Kafka
tb-core1:8080          # Core服务1
tb-core2:8080          # Core服务2
```

### 8.2 端口映射

**对外暴露的端口**（通过HAProxy）:
- `80`: HTTP
- `443`: HTTPS
- `1883`: MQTT
- `7070`: Edge RPC

**内部端口**（不映射到宿主机）:
- `5432`: PostgreSQL
- `9042`: Cassandra
- `9092`: Kafka
- `2181`: ZooKeeper

## 9. 监控配置

### 9.1 Prometheus + Grafana

```bash
# 启用监控
export MONITORING_ENABLED=true

# 启动监控服务
docker-compose -f docker-compose.prometheus-grafana.yml up -d
```

**访问地址**:
- Prometheus: `http://localhost:9090`
- Grafana: `http://localhost:3000`

### 9.2 指标暴露

所有服务都启用了Prometheus指标：
```yaml
environment:
  METRICS_ENABLED: "true"
  METRICS_ENDPOINTS_EXPOSE: prometheus
```

## 10. 总结

### 10.1 架构图到Docker的映射

| 架构图组件 | Docker服务 | 镜像 | 端口 |
|-----------|-----------|------|------|
| ThingsBoard Transports | tb-mqtt-transport* | thingsboard/tb-mqtt-transport | 1883 |
| | tb-http-transport* | thingsboard/tb-http-transport | 8081 |
| | tb-coap-transport | thingsboard/tb-coap-transport | 5683 |
| | tb-lwm2m-transport | thingsboard/tb-lwm2m-transport | 5685/5686 |
| | tb-snmp-transport | thingsboard/tb-snmp-transport | 1620 |
| Queue | kafka | bitnamilegacy/kafka | 9092 |
| ThingsBoard Core | tb-core* | thingsboard/tb-node | 8080/7070 |
| Rule Engine | tb-rule-engine* | thingsboard/tb-node | 8080 |
| SQL Database | postgres | postgres:16 | 5432 |
| NoSQL Database | cassandra | cassandra:5.0 | 9042 |
| ThingsBoard UI | tb-web-ui* | thingsboard/tb-web-ui | 8080 |
| ZooKeeper | zookeeper | zookeeper:3.8.1 | 2181 |
| JS Executor | tb-js-executor | thingsboard/tb-js-executor | - |
| Load Balancer | haproxy | thingsboard/haproxy-certbot | 80/443/1883 |

### 10.2 部署特点

1. **微服务架构**: 每个组件独立部署，可单独扩展
2. **高可用性**: 关键服务多实例部署
3. **负载均衡**: HAProxy统一入口，ZooKeeper服务发现
4. **可扩展性**: 支持水平扩展各个服务
5. **灵活性**: 可选择不同的数据库和队列配置

### 10.3 数据流总结

```
设备数据流:
设备 → Transport → Kafka → Core → Kafka → Rule Engine → Cassandra

控制流:
UI → HAProxy → Core → PostgreSQL

实时流:
UI ← WebSocket ← Core ← Transport ← 设备
```

通过Docker Compose的组合配置，可以实现架构图中展示的完整数据流和处理流程。