thingsboard/summary/11-Docker-Compose部署配置分析.md

# Docker Compose 部署配置分析

## 1. 配置概述

这是一个 **ThingsBoard CE（社区版）的单体部署配置**，使用 Docker Compose 编排三个核心服务：
- PostgreSQL（数据库）
- Kafka（消息队列）
- ThingsBoard CE（应用服务）

## 2. 部署模式分析

### 2.1 部署架构

```
┌─────────────────────────────────────────┐
│         Docker Compose 网络              │
│                                         │
│  ┌──────────────┐                      │
│  │  PostgreSQL  │                      │
│  │   Port: 5432 │                      │
│  └──────┬───────┘                      │
│         │                               │
│  ┌──────▼───────┐                      │
│  │    Kafka     │                      │
│  │  Port: 9092  │                      │
│  └──────┬───────┘                      │
│         │                               │
│  ┌──────▼──────────────┐              │
│  │  ThingsBoard CE     │              │
│  │  Ports:             │              │
│  │  - 8080 (HTTP)      │              │
│  │  - 7070 (Edge RPC)  │              │
│  │  - 1883 (MQTT)      │              │
│  │  - 8883 (MQTTS)     │              │
│  │  - 5683-5688 (CoAP) │              │
│  └─────────────────────┘              │
└─────────────────────────────────────────┘
```

### 2.2 部署模式：单体模式（Monolith）

**特点**：
- ✅ 单一 ThingsBoard 实例
- ✅ 所有功能在一个容器中运行
- ✅ 配置简单，易于部署
- ❌ 不支持水平扩展
- ❌ 单个故障点

**适用场景**：
- 小型到中型部署
- 开发和测试环境
- 设备数量 < 10,000

## 3. 服务详细分析

### 3.1 PostgreSQL 服务

```yaml
postgres:
  restart: always
  image: "postgres:16"
  ports:
    - "5432"  # 内部端口，不映射到宿主机
  environment:
    POSTGRES_DB: thingsboard
    POSTGRES_PASSWORD: postgres
  volumes:
    - postgres-data:/var/lib/postgresql/data
```

#### 配置说明

1. **数据库版本**: PostgreSQL 16
2. **端口配置**: 
   - 端口 `5432` 只在 Docker 网络内可用
   - 不映射到宿主机，只能容器间访问（安全）
3. **数据持久化**: 
   - 使用命名卷 `postgres-data`
   - 数据存储在 `/var/lib/postgresql/data`
4. **数据库名称**: `thingsboard`
5. **认证**: 用户名 `postgres`，密码 `postgres`（生产环境需修改）

#### 存储的数据

- **实体数据**: 租户、用户、设备、资产等
- **配置数据**: 规则链、仪表板等
- **时序数据**: 如果使用 SQL 模式（`DATABASE_TS_TYPE=sql`）

### 3.2 Kafka 服务

```yaml
kafka:
  restart: always
  image: bitnamilegacy/kafka:4.0
  ports:
    - 9092:9092  # 映射到宿主机（用于外部访问）
    - 9093       # KRaft 控制器端口（仅内部）
  environment:
    ALLOW_PLAINTEXT_LISTENER: "yes"
    KAFKA_CFG_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
    KAFKA_CFG_ADVERTISED_LISTENERS: "PLAINTEXT://:9092"
    # ... 其他配置
```

#### 配置说明

1. **Kafka 版本**: 4.0（使用 legacy 镜像）
2. **KRaft 模式**: 
   - 使用 KRaft（Kafka Raft）模式，不需要 ZooKeeper
   - `KAFKA_CFG_PROCESS_ROLES: "controller,broker"` - 同时充当控制器和代理
   - `KAFKA_CFG_NODE_ID: "0"` - 节点 ID
3. **端口配置**:
   - `9092`: 客户端连接端口（映射到宿主机）
   - `9093`: KRaft 控制器端口（仅内部）
4. **安全配置**:
   - `ALLOW_PLAINTEXT_LISTENER: "yes"` - 允许明文连接（生产环境应使用 SSL）
5. **Topic 配置**:
   - `KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE: "false"` - 禁用自动创建主题
   - `KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"` - 单节点副本因子
6. **日志保留**:
   - `KAFKA_CFG_LOG_RETENTION_MS: "300000"` - 5 分钟（非常短，测试用）
   - `KAFKA_CFG_SEGMENT_BYTES: "26214400"` - 25MB 段大小

#### 注意事项

⚠️ **生产环境警告**:
- 单节点 Kafka（无副本）
- 日志保留时间仅 5 分钟（测试配置）
- 使用明文连接（不安全）
- 不支持高可用

### 3.3 ThingsBoard CE 服务

```yaml
thingsboard-ce:
  restart: always
  image: "thingsboard/tb-node:4.2.1"
  ports:
    - "8080:8080"      # HTTP API
    - "7070:7070"      # Edge RPC
    - "1883:1883"      # MQTT
    - "8883:8883"      # MQTT over SSL
    - "5683-5688:5683-5688/udp"  # CoAP (包含 LWM2M)
  environment:
    TB_SERVICE_ID: tb-ce-node
    SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
    TB_QUEUE_TYPE: kafka
    TB_KAFKA_SERVERS: kafka:9092
```

#### 配置说明

1. **镜像**: `thingsboard/tb-node:4.2.1` - ThingsBoard 节点镜像
2. **服务类型**: 
   - `TB_SERVICE_ID: tb-ce-node` - 单体模式节点
   - 默认 `TB_SERVICE_TYPE: tb-core`（未指定，使用默认值）
3. **端口映射**:
   - **8080**: HTTP REST API 和 Web UI
   - **7070**: Edge 设备 RPC 通信
   - **1883**: MQTT 协议（非加密）
   - **8883**: MQTT over SSL/TLS
   - **5683-5688**: CoAP 协议（UDP）
     - 5683: CoAP
     - 5685: LWM2M（非加密）
     - 5686: LWM2M over DTLS
4. **数据库连接**:
   - `SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard`
   - 通过 Docker 网络连接到 PostgreSQL
5. **消息队列**:
   - `TB_QUEUE_TYPE: kafka`
   - `TB_KAFKA_SERVERS: kafka:9092`
   - 使用 Kafka 作为消息队列

#### 日志配置

```yaml
logging:
  driver: "json-file"
  options:
    max-size: "100m"    # 单个日志文件最大 100MB
    max-file: "10"      # 保留 10 个日志文件
```

**日志轮转**: 最大日志大小 1GB（100MB × 10）

## 4. 数据存储模式

### 4.1 数据库配置

**未指定 `DATABASE_TS_TYPE`**，使用默认值：
- **默认**: SQL 模式（PostgreSQL）
- **时序数据**: 存储在 PostgreSQL 中

### 4.2 数据持久化

```yaml
volumes:
  postgres-data:
    name: tb-postgres-data
    driver: local
  kafka-data:
    name: tb-ce-kafka-data
    driver: local
```

- **PostgreSQL 数据**: 持久化到 `tb-postgres-data` 卷
- **Kafka 数据**: 持久化到 `tb-ce-kafka-data` 卷

## 5. 网络配置

### 5.1 Docker 网络

所有服务在同一个 Docker Compose 网络中：
- 服务间通过服务名访问（`postgres`, `kafka`, `thingsboard-ce`）
- 不需要额外的网络配置

### 5.2 服务发现

- ThingsBoard → PostgreSQL: `postgres:5432`
- ThingsBoard → Kafka: `kafka:9092`

## 6. 启动顺序

```yaml
depends_on:
  - postgres
  - kafka
```

ThingsBoard 会在 PostgreSQL 和 Kafka 启动后启动。

## 7. 优缺点分析

### 7.1 优点

✅ **简单易用**: 
- 三个服务，配置简单
- 一键启动：`docker-compose up -d`

✅ **资源占用少**: 
- 适合小型部署
- 单机即可运行

✅ **易于维护**: 
- 日志集中管理
- 配置统一

✅ **开发友好**: 
- 适合本地开发
- 快速启动

### 7.2 缺点

❌ **单点故障**: 
- 单个 ThingsBoard 实例
- 故障影响整个系统

❌ **无法扩展**: 
- 不支持水平扩展
- 性能受限于单机

❌ **Kafka 配置不适合生产**: 
- 单节点无副本
- 日志保留时间太短

❌ **安全配置不足**: 
- 明文密码
- 明文 MQTT/Kafka 连接

## 8. 改进建议

### 8.1 生产环境改进

1. **Kafka 配置**:
```yaml
KAFKA_CFG_LOG_RETENTION_MS: "2592000000"  # 30 天
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "3"  # 多副本
```

2. **安全配置**:
```yaml
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}  # 使用环境变量
ALLOW_PLAINTEXT_LISTENER: "no"  # 禁用明文
```

3. **高可用部署**:
- 使用微服务模式
- 多个 ThingsBoard 实例
- Kafka 集群

### 8.2 数据库选择

如需更好的时序数据性能，可以使用混合模式：

```yaml
environment:
  DATABASE_TS_TYPE: cassandra
  CASSANDRA_URL: cassandra:9042
```

需要添加 Cassandra 服务。

## 9. 使用场景

### 9.1 适合的场景

- ✅ 小型 IoT 项目（< 1,000 设备）
- ✅ 开发和测试环境
- ✅ 概念验证（PoC）
- ✅ 个人学习项目

### 9.2 不适合的场景

- ❌ 大规模生产环境（> 10,000 设备）
- ❌ 高可用性要求
- ❌ 需要水平扩展
- ❌ 高性能要求

## 10. 启动命令

```bash
# 启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f thingsboard-ce

# 停止服务
docker-compose down

# 停止并删除数据卷（谨慎使用）
docker-compose down -v
```

## 11. 访问地址

启动后可以通过以下地址访问：

- **Web UI**: http://localhost:8080
- **MQTT**: mqtt://localhost:1883
- **MQTT over SSL**: mqtts://localhost:8883
- **CoAP**: coap://localhost:5683

## 12. 总结

这是一个 **ThingsBoard CE 单体部署配置**，特点：

1. **部署模式**: 单体模式（Monolith）
2. **数据库**: PostgreSQL（SQL 模式）
3. **消息队列**: Kafka（KRaft 模式，单节点）
4. **适用场景**: 小型部署、开发测试
5. **优点**: 简单、易用、资源占用少
6. **缺点**: 无法扩展、单点故障、配置不适合生产

这是一个**开发/测试环境的典型配置**，不适合大规模生产环境使用。