2. ThingsBoard 安装部署：Docker 方式安装、PostgreSQL 配置、初始化与启动、访问控制台

本章将带领你使用 Docker 容器化方式完成 ThingsBoard 的完整部署。Docker 方式具有环境隔离、依赖自动解决、升级回滚便捷等优势，是生产环境与开发环境中最推荐的部署方案。我们将依次完成 PostgreSQL 数据库配置、ThingsBoard 服务初始化、启动以及首次访问控制台验证。

2.1 部署架构概览

ThingsBoard 采用微服务架构，核心组件包括 ThingsBoard 服务节点、数据库（PostgreSQL + Cassandra/TimescaleDB）、消息队列（Kafka/RabbitMQ）以及 Web UI 控制台。本章使用单节点 Docker Compose 部署，包含以下核心容器：

  • thingsboard/tb-postgres：集成 PostgreSQL 数据库的 ThingsBoard 单节点镜像
  • postgres：独立 PostgreSQL 数据库容器（可选分离部署）
  • redis：缓存服务，用于提升系统响应速度
版本说明： 本教程基于 ThingsBoard 3.6.x 版本，Docker Compose 文件使用 v3.8 格式。建议使用 Docker 24+ 和 Docker Compose 2.20+ 以获得最佳兼容性。
ThingsBoard Docker 部署架构图 ThingsBoard Docker 部署架构图 Docker 主机 Docker Compose 编排 ThingsBoard 服务 tb-postgres:3.6.x PostgreSQL 端口 5432 Redis 缓存 端口 6379 JDBC 连接 缓存读写 Web UI :8080 HTTP 访问

2.2 环境准备与前提条件

在开始部署之前，请确保你的服务器或开发机满足以下最低要求：

资源项 最低配置 推荐配置 说明
CPU 2 核 4 核 ThingsBoard 服务与数据库并行运行
内存 4 GB 8 GB PostgreSQL 与 Redis 占用较大内存
磁盘 20 GB 50 GB SSD 数据库持久化与日志存储
Docker 24.0+ 26.0+ 支持 Compose v3.8
操作系统 Ubuntu 20.04 / CentOS 7+ Ubuntu 22.04 Linux 内核 4.0+
重要提示： 如果使用 Windows 或 macOS，请确保 Docker Desktop 已启用 WSL2 后端（Windows）或 HyperKit（macOS），并分配至少 4 GB 内存给 Docker 虚拟机。生产环境建议使用 Linux 服务器。

2.3 获取 Docker Compose 部署文件

ThingsBoard 官方提供了多种部署模板。我们使用集成 PostgreSQL 的单节点版本，该版本适合中小规模项目（设备数 < 10,000）。

步骤 1：创建部署目录

mkdir -p ~/thingsboard-deploy
cd ~/thingsboard-deploy

步骤 2：下载 Docker Compose 文件

wget https://raw.githubusercontent.com/thingsboard/thingsboard/release-3.6/docker/docker-compose-postgres.yml -O docker-compose.yml

如果无法访问 GitHub，也可以使用以下命令直接创建 docker-compose.yml 文件：

cat << 'EOF' > docker-compose.yml
version: '3.8'
services:
  mytb:
    restart: always
    image: "thingsboard/tb-postgres:3.6.2"
    ports:
      - "8080:9090"
      - "1883:1883"
      - "5683:5683/udp"
    environment:
      TB_QUEUE_TYPE: in-memory
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      SPRING_DATASOURCE_USERNAME: postgres
      SPRING_DATASOURCE_PASSWORD: postgres
    volumes:
      - tb-data:/data
      - tb-logs:/var/log/thingsboard
    depends_on:
      - postgres
    networks:
      - tb-net

  postgres:
    restart: always
    image: "postgres:15"
    ports:
      - "5432:5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - tb-net

  redis:
    restart: always
    image: "redis:7-alpine"
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    networks:
      - tb-net

volumes:
  tb-data:
  tb-logs:
  postgres-data:
  redis-data:

networks:
  tb-net:
    driver: bridge
EOF
关键参数说明：
  • TB_QUEUE_TYPE: in-memory — 使用内存队列，适合单节点测试环境；生产环境建议改为 kafka 或 rabbitmq。
  • SPRING_DATASOURCE_URL — 指定 PostgreSQL 连接地址，容器间使用服务名 postgres 通信。
  • volumes — 持久化数据卷，确保容器重启后数据不丢失。

2.4 PostgreSQL 配置详解

PostgreSQL 是 ThingsBoard 的核心元数据存储。在 Docker Compose 中，我们通过环境变量完成基础配置：

环境变量 值 作用
POSTGRES_DB thingsboard 指定初始数据库名称
POSTGRES_USER postgres 数据库超级用户
POSTGRES_PASSWORD postgres 数据库密码（生产环境请修改为强密码）

生产环境 PostgreSQL 优化建议：

  • 修改默认密码：使用 openssl rand -base64 16 生成随机密码。
  • 限制端口暴露：仅允许 ThingsBoard 容器访问，避免 0.0.0.0:5432 暴露到公网。
  • 调整共享缓冲区：在 postgres 服务中添加 command: postgres -c shared_buffers=256MB -c effective_cache_size=768MB。
  • 启用 SSL 连接：生产环境建议配置 PostgreSQL SSL 证书。

2.5 初始化与启动服务

完成配置后，按照以下步骤启动 ThingsBoard 服务：

步骤 1：拉取镜像

docker compose pull

步骤 2：启动所有服务（后台模式）

docker compose up -d

步骤 3：查看启动日志

docker compose logs -f mytb

首次启动时，ThingsBoard 会自动执行数据库初始化脚本（创建表结构、索引、默认数据）。该过程通常需要 2~5 分钟，日志中出现以下内容表示初始化完成：

2024-01-15 10:23:45.678  INFO 1 --- [main] o.t.s.ThingsboardServerApplication : Started ThingsboardServerApplication in 142.567 seconds
2024-01-15 10:23:46.012  INFO 1 --- [main] o.t.s.ThingsboardServerApplication : ThingsBoard Web UI available at http://localhost:9090
快速检查： 使用 docker compose ps 查看所有容器状态，确保 mytb、postgres、redis 均为 Up 状态。如果 mytb 反复重启，使用 docker compose logs mytb 查看错误详情。
ThingsBoard 启动与初始化流程图 ThingsBoard 启动与初始化流程图 1. 拉取镜像 docker compose pull 2. 启动容器 docker compose up -d 3. 数据库初始化 自动建表 & 索引 4. 服务就绪 端口 9090 监听中 5. 访问控制台 http://localhost:8080 提示：首次启动数据库初始化约 2~5 分钟，请耐心等待日志中出现 "Started ThingsboardServerApplication"

2.6 访问控制台与初始配置

服务启动成功后，通过浏览器访问 ThingsBoard Web 控制台：

访问地址： http://<服务器IP>:8080

默认登录凭据：

角色 用户名 密码 说明
系统管理员 sysadmin@thingsboard.org sysadmin 最高权限，可管理租户与系统设置
租户管理员 tenant@thingsboard.org tenant 管理设备、仪表板、规则链等
客户用户 customer@thingsboard.org customer 查看分配的仪表板与设备数据
安全提醒： 首次登录后，请立即修改默认密码！建议使用 12 位以上包含大小写字母、数字和特殊字符的强密码。生产环境还应启用 HTTPS（配置 SSL 证书）和双因素认证。

验证部署是否成功：

  1. 使用 sysadmin@thingsboard.org / sysadmin 登录。
  2. 检查左侧菜单是否完整显示：仪表组、设备、资产、规则链、客户等。
  3. 点击“设备”页面，确认页面正常加载且无报错。
  4. 点击“仪表板”页面，查看是否有预置的“温度湿度演示”仪表板。

2.7 常见问题与故障排除

问题现象 可能原因 解决方案
容器反复重启 数据库连接失败或端口冲突 检查 docker compose logs mytb 中数据库连接错误；确保 8080/1883/5683 端口未被占用
控制台无法访问 防火墙未放行 8080 端口 执行 sudo ufw allow 8080/tcp 或在云平台安全组添加入站规则
数据库初始化超时 服务器性能不足或磁盘 I/O 瓶颈 增加 Docker 资源限制；使用 SSD 磁盘；适当增加 spring.datasource.hikari.connection-timeout 值
登录后页面空白 浏览器缓存或 WebSocket 连接失败 清除浏览器缓存；检查网络是否阻止 WebSocket（端口 9090）
快速诊断命令： 
# 查看所有容器状态
docker compose ps

# 查看 ThingsBoard 实时日志
docker compose logs -f --tail=100 mytb

# 测试数据库连接
docker exec -it thingsboard-deploy-postgres-1 psql -U postgres -d thingsboard -c "\dt"

# 检查端口监听
ss -tlnp | grep -E '8080|5432|6379'

2.8 本章小结

通过本章的学习，你已经完成了 ThingsBoard 的 Docker 部署全流程：

  • 理解了 ThingsBoard 的容器化部署架构与组件关系
  • 掌握了 Docker Compose 文件的编写与关键参数配置
  • 完成了 PostgreSQL 数据库的初始化与优化配置
  • 成功启动服务并首次访问 ThingsBoard Web 控制台
  • 学会了常见故障的排查方法
← 上一章 📖 返回目录 下一章 →