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 服务

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 服务

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 服务

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 作为消息队列

日志配置

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 数据持久化

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. 启动顺序

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 配置:

KAFKA_CFG_LOG_RETENTION_MS: "2592000000"  # 30 天
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "3"  # 多副本

2. 安全配置:

POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}  # 使用环境变量
ALLOW_PLAINTEXT_LISTENER: "no"  # 禁用明文

3. 高可用部署:

• 使用微服务模式
• 多个 ThingsBoard 实例
• Kafka 集群

8.2 数据库选择

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

environment:
  DATABASE_TS_TYPE: cassandra
  CASSANDRA_URL: cassandra:9042

需要添加 Cassandra 服务。

9. 使用场景

9.1 适合的场景

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

9.2 不适合的场景

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

10. 启动命令

# 启动所有服务
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. 缺点: 无法扩展、单点故障、配置不适合生产

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