4、单机部署：使用Docker Compose快速部署ThingsBoard社区版，验证服务启动、登录控制台、配置基础参数

ThingsBoard作为一款开源的物联网平台，其部署方式多种多样，包括源码编译、二进制包安装、Docker容器化部署等。在众多部署方式中，Docker Compose以其声明式配置、一键启动、环境隔离和易于版本管理的特性，成为单机开发环境与生产小规模集群的首选方案。本章将深入剖析使用Docker Compose部署ThingsBoard社区版（TB CE）的完整流程，从核心原理到实战操作，再到参数配置与常见误区，帮助读者建立起一套可复用的标准化部署方法论。

上图清晰地展示了Docker Compose部署ThingsBoard社区版时的组件拓扑关系。从编排层（docker-compose.yml）出发，向下驱动核心容器组（tb-core、tb-node、tb-web-ui、tb-rule），这些容器又依赖底层的中间件服务（PostgreSQL、Cassandra、Redis、Kafka）。最终，用户通过浏览器访问映射端口进入控制台。整个部署验证过程遵循“状态检查→日志排查→端口测试→功能验证”的四步法。下面我们将逐一展开每个环节的详细操作与原理。

4.1 核心原理：Docker Compose如何编排ThingsBoard微服务

ThingsBoard社区版虽然以单体JAR包形式发布，但其内部逻辑上分为多个模块：规则引擎、设备API、Web UI、消息传输等。Docker Compose通过YAML格式的声明式配置，将这些逻辑模块拆分为独立的容器服务，并统一管理其网络、存储和依赖关系。这种做法的核心优势在于：环境一致性（开发、测试、生产使用相同镜像）、依赖隔离（每个容器只包含运行所需的最小依赖）、快速伸缩（通过调整副本数即可水平扩展）。

在单机部署场景下，Compose会创建一个默认的桥接网络，所有容器通过服务名（service name）互相通信。例如，tb-core容器通过JDBC连接PostgreSQL时，数据库地址直接写postgres:5432，而不是IP地址。这种服务发现机制由Docker内置DNS解析完成，无需额外配置。同时，Compose通过volumes指令将容器内的数据目录映射到宿主机，确保容器重建后数据不丢失。

Compose文件中的depends_on指令用于控制容器启动顺序。例如，tb-core必须在postgres健康检查通过后才启动，否则会因数据库连接失败而反复重启。ThingsBoard官方镜像内置了健康检查脚本，Compose会等待依赖服务变为healthy状态。理解这一机制对于排查启动失败问题至关重要。

4.2 操作流程：从编写Compose文件到一键启动

部署的第一步是准备docker-compose.yml文件。官方仓库提供了标准模板，但我们需要根据实际环境调整端口映射、数据卷路径和时区设置。以下是经过生产验证的完整流程：

1. 环境准备：确保Docker Engine版本≥20.10，Docker Compose插件≥2.0。执行docker --version和docker compose version验证。
2. 创建目录结构：建议在/opt/thingsboard下创建data和logs目录，用于持久化存储。
3. 编写Compose文件：定义postgres、tb-core、tb-node三个核心服务（社区版可合并为单节点）。
4. 启动服务：执行docker compose up -d，后台运行所有容器。
5. 验证状态：使用docker compose ps查看容器运行状态，确保均为Up且健康。

以下是一个精简但完整的docker-compose.yml示例，适用于ThingsBoard CE 3.5.x版本：

version: '3.0'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_USER: tb_user
      POSTGRES_PASSWORD: tb_password
    volumes:
      - ./data/db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U tb_user -d thingsboard"]
      interval: 10s
      timeout: 5s
      retries: 5

  tb-core:
    image: thingsboard/tb-postgres:3.5.1
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      TB_QUEUE_TYPE: in-memory
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      SPRING_DATASOURCE_USERNAME: tb_user
      SPRING_DATASOURCE_PASSWORD: tb_password
      TZ: Asia/Shanghai
    ports:
      - "8080:9090"
      - "1883:1883"
      - "5683:5683/udp"
    volumes:
      - ./data/tb:/data
      - ./logs:/var/log/thingsboard
    restart: unless-stopped

注意，TB_QUEUE_TYPE=in-memory表示使用内存队列，适合单机测试；生产环境应改为kafka或rabbitmq。端口映射中，8080:9090将容器内的9090端口（ThingsBoard默认HTTP端口）映射到宿主机的8080，方便访问。

4.3 案例拆解：一次完整的部署验证与基础参数配置

我们以一个实际项目为例：某智慧园区项目需要快速搭建ThingsBoard开发环境，用于接入100个温湿度传感器和50个智能电表。硬件资源为4核8GB内存的Ubuntu 22.04服务器。初始目标是：在30分钟内完成部署，并验证设备接入能力。

部署过程：按照4.2节的流程，我们编写了Compose文件并执行docker compose up -d。首次启动需要拉取镜像，耗时约5分钟（取决于网络带宽）。启动后执行docker compose ps，发现tb-core容器处于Restarting状态。查看日志：

docker compose logs tb-core | tail -50
# 关键错误信息：
# Caused by: org.postgresql.util.PSQLException: FATAL: password authentication failed for user "tb_user"

问题分析：密码认证失败，说明PostgreSQL容器中的用户密码与ThingsBoard配置不一致。检查发现，Compose文件中POSTGRES_PASSWORD设置为tb_password，但SPRING_DATASOURCE_PASSWORD误写为tb_passwd（拼写错误）。修正后重新启动：

docker compose down
# 修改docker-compose.yml中的密码
docker compose up -d

这次启动成功。等待约2分钟（ThingsBoard初始化数据库结构），访问http://192.168.1.100:8080，出现登录页面。使用默认管理员账号sysadmin@thingsboard.org / sysadmin登录，首次登录会强制修改密码。

基础参数配置：登录后，进入"系统设置"菜单，进行以下关键配置：

配置项	推荐值	说明
时区	Asia/Shanghai	影响遥测数据的时间戳显示
基础URL	http://192.168.1.100:8080	用于生成设备连接URL和邮件链接
邮件服务器	SMTP配置（可选）	用于告警通知，开发环境可跳过
设备默认凭据	启用"允许设备自动生成访问令牌"	简化设备接入流程

验证设备接入：在控制台创建一个测试设备，获取其访问令牌。使用MQTT客户端模拟上报数据：

mosquitto_pub -h 192.168.1.100 -p 1883 -t "v1/devices/me/telemetry" -u "TEST_" -m '{"temperature":25.5,"humidity":60}'

回到控制台，在"最新遥测数据"中看到temperature和humidity的值，说明设备接入链路完全打通。整个部署验证过程耗时约20分钟，达到了预期目标。

4.4 常见误区与总结复盘

在指导多个团队完成ThingsBoard部署后，我总结了以下高频误区和应对策略：

• 误区一：盲目使用最新镜像。最新标签（latest）可能包含未充分测试的版本。建议锁定具体版本号（如3.5.1），并在升级前阅读官方升级指南。
• 误区二：忽略健康检查。没有配置healthcheck的PostgreSQL会导致ThingsBoard在数据库未就绪时反复重启。务必使用pg_isready作为健康检查命令。
• 误区三：端口映射冲突。1883（MQTT）和5683（CoAP）是物联网常用端口，宿主机上可能已有其他服务占用。部署前统一规划端口使用表。
• 误区四：数据卷权限问题。容器内运行用户（通常是thingsboard用户，UID=799）需要宿主机数据目录的写权限。如果遇到Permission denied，执行chown -R 799:799 ./data。
• 误区五：内存分配不足。ThingsBoard默认JVM堆内存为512MB，加上PostgreSQL和系统开销，建议宿主机至少4GB可用内存。内存不足时会出现OOM Killer导致容器退出。

总结：Docker Compose部署ThingsBoard社区版是一个"声明式配置+自动化编排"的过程。核心要点在于：理解服务依赖关系、正确配置环境变量、规划持久化存储、掌握日志排障方法。通过本章的实战演练，读者应能独立完成从零到一的部署，并具备基本的故障排查能力。在后续章节中，我们将深入探讨设备接入协议、数据可视化以及二次开发框架，这些内容都建立在稳定运行的平台基础之上。