thingsboard/summary/04-部署方案分析.md

# ThingsBoard 部署方案分析

## 1. 概述

ThingsBoard 支持两种主要的部署模式：单体模式（Monolith）和微服务模式（Microservices）。此外，还支持 Docker 容器化部署和 Kubernetes 部署。

## 2. 部署模式

### 2.1 单体模式（Monolith）

**适用场景**:
- 小型部署
- 开发和测试环境
- 设备数量较少（< 10,000）

**特点**:
- 所有服务运行在一个进程中
- 配置简单
- 资源占用较少
- 不支持水平扩展

**配置**:
```yaml
service:
  type: monolith
```

**启动方式**:
```bash
java -jar thingsboard.jar
```

### 2.2 微服务模式（Microservices）

**适用场景**:
- 生产环境
- 大规模部署
- 高可用性要求
- 需要水平扩展

**特点**:
- 服务拆分，独立部署
- 支持水平扩展
- 高可用性
- 配置复杂

**服务组件**:
- **tb-core**: 核心服务（设备管理、用户管理、API）
- **tb-rule-engine**: 规则引擎服务
- **tb-transport-***: 传输服务（MQTT、HTTP、CoAP、LWM2M、SNMP）
- **tb-js-executor**: JavaScript 执行器
- **tb-web-ui**: Web UI 服务
- **tb-vc-executor**: 版本控制执行器

**配置**:
```yaml
service:
  type: tb-core  # 或 tb-rule-engine, tb-transport 等
```

## 3. Docker 部署

### 3.1 Docker Compose 配置

**位置**: `docker/docker-compose.yml`

**主要服务**:

```yaml
services:
  # 核心服务
  tb-core1:
    image: "${DOCKER_REPO}/${TB_NODE_DOCKER_NAME}:${TB_VERSION}"
    environment:
      TB_SERVICE_ID: tb-core1
      TB_SERVICE_TYPE: tb-core
    env_file:
      - tb-node.env
    
  tb-core2:
    image: "${DOCKER_REPO}/${TB_NODE_DOCKER_NAME}:${TB_VERSION}"
    environment:
      TB_SERVICE_ID: tb-core2
      TB_SERVICE_TYPE: tb-core
    
  # 规则引擎服务
  tb-rule-engine1:
    image: "${DOCKER_REPO}/${TB_NODE_DOCKER_NAME}:${TB_VERSION}"
    environment:
      TB_SERVICE_ID: tb-rule-engine1
      TB_SERVICE_TYPE: tb-rule-engine
    
  # 传输服务
  tb-mqtt-transport1:
    image: "${DOCKER_REPO}/${MQTT_TRANSPORT_DOCKER_NAME}:${TB_VERSION}"
    environment:
      TB_SERVICE_ID: tb-mqtt-transport1
    ports:
      - "1883"
    
  # Web UI 服务
  tb-web-ui1:
    image: "${DOCKER_REPO}/${WEB_UI_DOCKER_NAME}:${TB_VERSION}"
    
  # 负载均衡器
  haproxy:
    image: thingsboard/haproxy-certbot:2.2.33-alpine
    ports:
      - "80:80"
      - "443:443"
      - "1883:1883"
```

### 3.2 数据库配置

#### PostgreSQL 模式

**配置文件**: `docker/tb-node.postgres.env`

```bash
DATABASE_TS_TYPE=sql
SPRING_DRIVER_CLASS_NAME=org.postgresql.Driver
SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/thingsboard
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=postgres
```

**Docker Compose**: `docker/docker-compose.postgres.yml`

```yaml
services:
  postgres:
    image: postgres:16.6
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
```

#### 混合模式（PostgreSQL + Cassandra）

**配置文件**: `docker/tb-node.hybrid.env`

```bash
DATABASE_TS_TYPE=cassandra
CASSANDRA_CLUSTER_NAME=ThingsBoard Cluster
CASSANDRA_URL=cassandra:9042
```

**Docker Compose**: `docker/docker-compose.hybrid.yml`

```yaml
services:
  postgres:
    # PostgreSQL 配置（用于实体数据）
  
  cassandra:
    image: cassandra:4.1
    environment:
      CASSANDRA_CLUSTER_NAME: ThingsBoard Cluster
    volumes:
      - cassandra-data:/var/lib/cassandra
```

### 3.3 缓存配置

#### Valkey Standalone

**配置文件**: `docker/cache-valkey.env`

```bash
CACHE_TYPE=valkey
REDIS_URL=valkey:6379
```

#### Valkey Cluster

**配置文件**: `docker/cache-valkey-cluster.env`

```bash
CACHE_TYPE=valkey-cluster
REDIS_CLUSTER_NODES=valkey-node-1:6379,valkey-node-2:6379,valkey-node-3:6379
```

#### Valkey Sentinel

**配置文件**: `docker/cache-valkey-sentinel.env`

```bash
CACHE_TYPE=valkey-sentinel
REDIS_SENTINEL_MASTER=mymaster
REDIS_SENTINEL_NODES=valkey-sentinel-1:26379,valkey-sentinel-2:26379,valkey-sentinel-3:26379
```

### 3.4 消息队列配置

#### Kafka

**配置文件**: `docker/queue-kafka.env`

```bash
QUEUE_TYPE=kafka
KAFKA_SERVERS=kafka:9092
```

**Docker Compose**: `docker/docker-compose.kafka.yml`

```yaml
services:
  zookeeper:
    image: zookeeper:3.8.1
  
  kafka:
    image: confluentinc/cp-kafka:7.5.0
    depends_on:
      - zookeeper
    environment:
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
```

#### RabbitMQ

**配置文件**: `docker/queue-rabbitmq.env`

```bash
QUEUE_TYPE=rabbitmq
RABBITMQ_URL=amqp://rabbitmq:5672
```

### 3.5 部署步骤

#### 3.5.1 准备环境

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

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

#### 3.5.2 安装

```bash
# 安装 ThingsBoard（包含数据库初始化）
./docker-install-tb.sh --loadDemo
```

#### 3.5.3 启动服务

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

# 查看服务状态
docker-compose ps

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

#### 3.5.4 停止服务

```bash
# 停止服务
./docker-stop-services.sh

# 删除服务
./docker-remove-services.sh
```

#### 3.5.5 更新服务

```bash
# 更新所有服务
./docker-update-service.sh

# 更新特定服务
./docker-update-service.sh tb-core1 tb-mqtt-transport1
```

#### 3.5.6 升级

```bash
# 停止服务
./docker-stop-services.sh

# 执行升级
./docker-upgrade-tb.sh --fromVersion=3.6.0

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

## 4. 单 Docker 镜像部署

### 4.1 适用场景

- 快速测试
- 小型部署
- 开发环境

### 4.2 镜像类型

**位置**: `msa/tb/`

1. **thingsboard/tb**: 使用 HSQLDB（内存数据库）
2. **thingsboard/tb-postgres**: 使用 PostgreSQL
3. **thingsboard/tb-cassandra**: 使用混合模式（PostgreSQL + Cassandra）

### 4.3 运行示例

```bash
# 使用 PostgreSQL
docker run -it -p 9090:9090 -p 1883:1883 \
  -v ~/.mytb-data:/data \
  --name mytb \
  thingsboard/tb-postgres
```

## 5. Kubernetes 部署

### 5.1 服务拆分

在 Kubernetes 中，每个服务可以作为独立的 Deployment：

- **tb-core**: Core Service Deployment
- **tb-rule-engine**: Rule Engine Deployment
- **tb-transport-***: Transport Service Deployments
- **tb-web-ui**: Web UI Deployment

### 5.2 配置示例

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tb-core
spec:
  replicas: 2
  selector:
    matchLabels:
      app: tb-core
  template:
    metadata:
      labels:
        app: tb-core
    spec:
      containers:
      - name: tb-core
        image: thingsboard/tb-node:latest
        env:
        - name: TB_SERVICE_TYPE
          value: "tb-core"
        - name: SPRING_DATASOURCE_URL
          value: "jdbc:postgresql://postgres:5432/thingsboard"
```

## 6. 监控配置

### 6.1 Prometheus + Grafana

**启用监控**:

```bash
# 设置环境变量
export MONITORING_ENABLED=true
```

**访问地址**:
- Prometheus: `http://localhost:9090`
- Grafana: `http://localhost:3000` (默认用户名: admin, 密码: foobar)

**配置文件**:
- Prometheus: `docker/monitoring/prometheus/prometheus.yml`
- Grafana: `docker/monitoring/grafana/provisioning/dashboards/`

## 7. 高可用性配置

### 7.1 服务冗余

- **tb-core**: 至少 2 个实例
- **tb-rule-engine**: 至少 2 个实例
- **tb-transport-***: 至少 2 个实例（每个传输协议）

### 7.2 数据库高可用

- **PostgreSQL**: 使用主从复制或集群模式
- **Cassandra**: 使用集群模式（至少 3 个节点）

### 7.3 缓存高可用

- **Valkey Cluster**: 3 主 3 从
- **Valkey Sentinel**: 1 主 1 从 1 哨兵

### 7.4 消息队列高可用

- **Kafka**: 使用集群模式（至少 3 个 broker）
- **RabbitMQ**: 使用集群模式或镜像队列

## 8. 负载均衡

### 8.1 HAProxy 配置

**位置**: `docker/haproxy/config/`

HAProxy 负责：
- HTTP/HTTPS 流量负载均衡
- MQTT 连接负载均衡
- WebSocket 连接负载均衡

### 8.2 端口映射

- **80/443**: HTTP/HTTPS
- **1883**: MQTT
- **7070**: Edge RPC
- **9999**: HAProxy 统计

## 9. 网络配置

### 9.1 服务发现

使用 ZooKeeper 进行服务发现：

```yaml
services:
  zookeeper:
    image: zookeeper:3.8.1
    ports:
      - "2181"
```

### 9.2 内部通信

服务间通过消息队列和 ZooKeeper 进行通信，不需要直接网络连接。

## 10. 存储配置

### 10.1 数据持久化

使用 Docker Volumes 持久化数据：

```yaml
volumes:
  postgres-data:
  cassandra-data:
  tb-logs:
```

### 10.2 日志管理

日志目录映射到宿主机：

```yaml
volumes:
  - ./tb-node/log:/var/log/thingsboard
```

## 11. 安全配置

### 11.1 SSL/TLS

**位置**: `docker/haproxy/config/`

配置 SSL 证书：

```bash
# Let's Encrypt 证书
- ./haproxy/letsencrypt:/etc/letsencrypt

# 自定义证书
- ./haproxy/certs.d:/usr/local/etc/haproxy/certs.d
```

### 11.2 防火墙

建议只开放必要端口：
- 80/443: HTTP/HTTPS
- 1883: MQTT
- 5683: CoAP

## 12. 性能调优

### 12.1 JVM 参数

```bash
JAVA_OPTS="-Xms512m -Xmx2048m -XX:+UseG1GC"
```

### 12.2 数据库连接池

```yaml
spring:
  datasource:
    hikari:
      maximum-pool-size: 50
      minimum-idle: 10
```

### 12.3 消息队列配置

```yaml
queue:
  core:
    pack-processing-timeout: 3000
    poll-interval: 25
```

## 13. 总结

ThingsBoard 的部署方案具有以下特点：

1. **灵活的部署模式**: 支持单体和微服务两种模式
2. **容器化支持**: 完整的 Docker 和 Kubernetes 支持
3. **数据库选择**: 支持 PostgreSQL、TimescaleDB、Cassandra
4. **高可用性**: 支持服务冗余和数据库集群
5. **监控集成**: 内置 Prometheus 和 Grafana 支持
6. **易于扩展**: 微服务模式支持水平扩展

根据实际需求选择合适的部署方案：
- **小型部署**: 单体模式 + Docker
- **中型部署**: 微服务模式 + Docker Compose
- **大型部署**: 微服务模式 + Kubernetes