THENG
/
thingsboard
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
thingsboard/summary/20-ThingsBoard单镜像部署构建指南.md

13 KiB
Raw Permalink Blame History

ThingsBoard 单镜像部署构建指南

1. 概述

ThingsBoard 提供了单镜像部署模式（Single Docker Image），将应用服务和数据库打包在一个 Docker 镜像中，适合：

  • 快速开发和测试
  • 小型部署
  • 简化运维

2. 单镜像类型

ThingsBoard 提供两种单镜像类型：

2.1 tb-postgres 镜像

  • 镜像名: thingsboard/tb-postgres
  • 数据库: PostgreSQL（实体数据和时序数据都存储在 PostgreSQL）
  • 适用场景: 小规模部署，时序数据量不大

2.2 tb-cassandra 镜像

  • 镜像名: thingsboard/tb-cassandra
  • 数据库: 混合模式（PostgreSQL + Cassandra）
    • PostgreSQL: 存储实体数据（设备、用户、规则等）
    • Cassandra: 存储时序数据（遥测数据）
  • 适用场景: 大规模时序数据场景

注意: README 中还提到了 thingsboard/tb（HSQLDB 嵌入式数据库），但在当前代码中只有上述两种镜像的构建配置。

3. 构建位置

单镜像的构建配置位于：msa/tb/ 目录

msa/tb/
├── pom.xml                      # Maven 构建配置
├── README.md                    # 单镜像使用说明
├── docker/                      # 共享的启动脚本和配置
│   ├── start-tb.sh            # ThingsBoard 启动脚本
│   ├── install-tb.sh          # 安装脚本
│   ├── upgrade-tb.sh          # 升级脚本
│   ├── thingsboard.conf       # 配置文件
│   └── logback.xml            # 日志配置
├── docker-postgres/            # PostgreSQL 版本
│   ├── Dockerfile             # Dockerfile
│   ├── start-db.sh            # PostgreSQL 启动脚本
│   └── stop-db.sh             # PostgreSQL 停止脚本
└── docker-cassandra/          # Cassandra 版本
    ├── Dockerfile             # Dockerfile
    ├── start-db.sh            # 数据库启动脚本（PostgreSQL + Cassandra）
    └── stop-db.sh             # 数据库停止脚本

4. 构建流程

4.0 官网镜像的构建方式

官网提供的 thingsboard/tb-postgres 镜像使用的构建方式与我们本地构建完全相同：

官方构建命令（在 CI/CD 环境中）:

# 从项目根目录执行，构建并推送镜像
mvn clean install -DskipTests \
  -Ddockerfile.skip=false \
  -Dpush-docker-image=true \
  --projects msa/tb \
  --also-make

官方运行命令（官网文档中的示例）:

# 创建数据目录和日志目录
mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data
mkdir -p ~/.mytb-logs && sudo chown -R 799:799 ~/.mytb-logs

# 运行容器（官网示例）
docker run -it \
  -p 8080:9090 \
  -p 7070:7070 \
  -p 1883:1883 \
  -p 5683-5688:5683-5688/udp \
  -v ~/.mytb-data:/data \
  -v ~/.mytb-logs:/var/log/thingsboard \
  --name mytb \
  --restart always \
  thingsboard/tb-postgres

说明:

  • 8080:9090 - 将容器内的 9090 端口映射到宿主机的 8080 端口（HTTP 访问）
  • 7070:7070 - Edge RPC 端口（Edge 设备连接）
  • 5683-5688:5683-5688/udp - CoAP 协议端口范围（包括 LWM2M）
  • --restart always - 容器自动重启策略
  • -v ~/.mytb-logs:/var/log/thingsboard - 挂载日志目录（可选，便于查看日志）

4.1 前置准备

4.1.1 拉取基础镜像

所有 ThingsBoard 镜像都依赖以下基础镜像：

# Java 服务基础镜像
docker pull thingsboard/openjdk17:bookworm-slim

如果网络有问题，可以使用国内镜像源。

4.1.2 获取版本号

查看项目根目录的 pom.xml：

grep "<version>" pom.xml | head -1
# 输出: <version>4.2.1</version>

或者直接查看文件第一行（通常在 23 行左右）：

grep -A 1 "<artifactId>thingsboard</artifactId>" pom.xml | grep version

当前版本：4.2.1

4.2 构建方法

方法1：使用 Maven 直接构建（推荐）

构建 tb-postgres 镜像
# 从项目根目录执行
mvn clean install -DskipTests -Ddockerfile.skip=false --projects msa/tb --also-make

这会同时构建 tb-postgres 和 tb-cassandra 两个镜像。

仅构建单个镜像

由于 msa/tb/pom.xml 同时配置了两个镜像的构建，无法单独构建其中一个。如果需要只构建一个，需要手动构建（见方法2）。

方法2：手动构建（适合 Mac M1 或需要自定义的情况）

步骤1：构建代码和 DEB 包
# 从项目根目录执行，构建依赖的 application 模块
mvn clean install -DskipTests --projects msa/tb --also-make

这会：

  • ✅ 编译代码
  • ✅ 生成 application/target/thingsboard-4.2.1-boot.deb
  • ✅ 复制 Dockerfile 和启动脚本到构建目录
  • ❌ 跳过 Docker 镜像构建（避免插件问题）
步骤2：查看构建产物
# 查看 PostgreSQL 版本的构建目录
ls -la msa/tb/target/docker-postgres/

# 查看 Cassandra 版本的构建目录
ls -la msa/tb/target/docker-cassandra/

构建目录应包含：

  • Dockerfile
  • thingsboard.deb
  • start-tb.sh
  • install-tb.sh
  • upgrade-tb.sh
  • start-db.sh
  • stop-db.sh
  • thingsboard.conf
  • logback.xml
步骤3：手动构建 Docker 镜像

构建 tb-postgres 镜像：

cd msa/tb/target/docker-postgres
docker build -t thingsboard/tb-postgres:4.2.1 .

构建 tb-cassandra 镜像：

cd msa/tb/target/docker-cassandra
docker build -t thingsboard/tb-cassandra:4.2.1 .

方法3：使用 build.sh（不推荐，默认跳过 Docker）

./build.sh msa/tb

注意: build.sh 默认跳过 Docker 构建（dockerfile.skip=true），需要修改脚本或手动构建。

5. 构建验证

5.1 查看构建的镜像

docker images | grep thingsboard/tb

应该看到：

thingsboard/tb-postgres     4.2.1    ...
thingsboard/tb-cassandra    4.2.1    ...

5.2 测试运行镜像

测试 tb-postgres 镜像

# 创建数据目录
mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data

# 运行容器
docker run -it -p 9090:9090 -p 1883:1883 -p 5683:5683/udp \
  -p 5685:5685/udp -p 5686:5686/udp \
  -v ~/.mytb-data:/data \
  --name mytb-postgres \
  thingsboard/tb-postgres:4.2.1

测试 tb-cassandra 镜像

# 创建数据目录
mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data

# 运行容器
docker run -it -p 9090:9090 -p 1883:1883 -p 5683:5683/udp \
  -p 5685:5685/udp -p 5686:5686/udp \
  -v ~/.mytb-data:/data \
  --name mytb-cassandra \
  thingsboard/tb-cassandra:4.2.1

5.3 访问 ThingsBoard

启动后，访问 http://localhost:9090，使用默认账号登录：

  • 系统管理员: sysadmin@thingsboard.org / sysadmin
  • 租户管理员: tenant@thingsboard.org / tenant
  • 客户用户: customer@thingsboard.org / customer

6. 构建原理

6.1 构建流程

源码编译 → application 模块打包 → DEB 包生成 → Dockerfile 构建 → 单镜像

6.2 Dockerfile 特点

tb-postgres Dockerfile 要点：

  1. 基础镜像: thingsboard/openjdk17:bookworm-slim
  2. 安装 PostgreSQL: 在镜像中安装 PostgreSQL 数据库
  3. 安装 DEB 包: 通过 dpkg -i 安装 ThingsBoard DEB 包
  4. 启动脚本:
    • start-db.sh: 启动 PostgreSQL
    • start-tb.sh: 启动 ThingsBoard（会自动先启动数据库）

tb-cassandra Dockerfile 要点：

  1. 基础镜像: thingsboard/openjdk17:bookworm-slim
  2. 安装数据库: 同时安装 PostgreSQL 和 Cassandra
  3. 安装 DEB 包: 安装 ThingsBoard DEB 包
  4. 启动脚本:
    • start-db.sh: 启动 PostgreSQL 和 Cassandra
    • start-tb.sh: 启动 ThingsBoard

6.3 配置文件

单镜像的配置在 msa/tb/docker/thingsboard.conf 中，通过环境变量或配置文件可以调整：

  • HTTP 端口（默认 9090）
  • 数据库连接
  • 日志配置等

7. 与微服务镜像的区别

微服务架构（多镜像）:

  • 每个服务独立镜像：tb-node, tb-web-ui, tb-mqtt-transport 等
  • 需要外部数据库（PostgreSQL、Cassandra）
  • 需要外部消息队列（Kafka）
  • 适合生产环境、大规模部署

单镜像架构:

  • 一个镜像包含所有服务
  • 内置数据库（PostgreSQL 或 PostgreSQL + Cassandra）
  • 使用内存队列（不依赖外部消息队列）
  • 适合开发、测试、小规模部署

8. 常见问题

8.1 Mac M1 架构兼容性问题

如果遇到 UnsatisfiedLinkError: missing compatible architecture 错误，使用方法2（手动构建）。

8.2 内存不足

如果构建时出现 OutOfMemoryError：

MAVEN_OPTS="-Xmx2048m" mvn clean install -DskipTests -Ddockerfile.skip=false --projects msa/tb --also-make

8.3 构建时间过长

单镜像构建包含：

  • 编译 Java 代码
  • 打包 DEB
  • 下载和安装数据库（PostgreSQL、Cassandra）
  • 构建 Docker 镜像

整个流程可能需要 10-30 分钟，请耐心等待。

8.4 数据库初始化失败

确保数据目录权限正确：

mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data

9. 快速构建命令总结

最简单的方式（推荐）

# 从项目根目录
mvn clean install -DskipTests -Ddockerfile.skip=false --projects msa/tb --also-make

Mac M1 或遇到插件问题的方案

# 步骤1：构建代码
mvn clean install -DskipTests --projects msa/tb --also-make

# 步骤2：构建 PostgreSQL 镜像
cd msa/tb/target/docker-postgres && docker build -t thingsboard/tb-postgres:4.2.1 .

# 步骤3：构建 Cassandra 镜像
cd ../../docker-cassandra && docker build -t thingsboard/tb-cassandra:4.2.1 .

10. 镜像使用

10.1 官网推荐运行方式（完整配置）

# 创建数据目录和日志目录（使用用户ID 799，这是容器内的 thingsboard 用户）
mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data
mkdir -p ~/.mytb-logs && sudo chown -R 799:799 ~/.mytb-logs

# 运行容器（官网推荐配置）
docker run -it \
  -p 8080:9090 \
  -p 7070:7070 \
  -p 1883:1883 \
  -p 5683-5688:5683-5688/udp \
  -v ~/.mytb-data:/data \
  -v ~/.mytb-logs:/var/log/thingsboard \
  --name mytb \
  --restart always \
  thingsboard/tb-postgres:4.2.1

10.2 简化运行方式

# 最小配置
mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data

docker run -d \
  -p 9090:9090 -p 1883:1883 -p 5683:5683/udp \
  -v ~/.mytb-data:/data \
  --name mytb \
  thingsboard/tb-postgres:4.2.1

10.3 容器管理

# 查看日志
docker logs -f mytb

# 停止
docker stop mytb

# 启动
docker start mytb

# 重启
docker restart mytb

# 删除容器
docker rm mytb

10.4 端口说明

  • 9090 - HTTP 端口（Web UI 和 REST API）
  • 7070 - Edge RPC 端口（Edge 设备远程连接）
  • 1883 - MQTT 端口
  • 5683 - CoAP 端口
  • 5685 - CoAP DTLS 端口（LWM2M）
  • 5686 - CoAP DTLS 端口（LWM2M secure）

注意: 官网示例使用 8080:9090，将容器内 9090 端口映射到宿主机 8080，访问时使用 http://localhost:8080。

参考

  • 单镜像说明文档: msa/tb/README.md
  • 微服务镜像构建: summary/19-ThingsBoard所有镜像打包命令.md
  • 项目版本: 4.2.1

cd /Users/sunpeng/workspace/things/thingsboard MAVEN_OPTS="-Xmx2048m" mvn clean install -DskipTests --projects msa/tb --also-make

检查 PostgreSQL 版本的构建目录

ls -la msa/tb/target/docker-postgres/

应该看到以下文件：

- Dockerfile

- thingsboard.deb

- start-tb.sh

- install-tb.sh

- start-db.sh

- stop-db.sh

- thingsboard.conf

- logback.xml

docker pull thingsboard/openjdk17:bookworm-slim

进入构建目录

cd msa/tb/target/docker-postgres

使用 Dockerfile.custom 构建（从源码目录复制过来，避免被 clean 删除）

docker build -f ../../docker-postgres/Dockerfile.custom -t thingsboard/tb-postgres:4.2.2 .

构建镜像（版本号是 4.2.1，可根据实际情况调整）

docker build -t thingsboard/tb-postgres:4.2.2 .

或者构建 latest 标签

docker build -t thingsboard/tb-postgres:latest .

mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data mkdir -p ~/.mytb-logs && sudo chown -R 799:799 ~/.mytb-logs docker run -it -p 8080:9090 -p 7070:7070 -p 1883:1883 -p 5683-5688:5683-5688/udp -v ~/.mytb-data:/data
-v ~/.mytb-logs:/var/log/thingsboard --name mytb --restart always thingsboard/tb-postgres:4.2.2




docker volume create mytb-data
docker volume create mytb-logs

# 运行容器
# 后台运行（推荐生产环境）
docker run -d -p 8080:9090 -p 7070:7070 -p 1883:1883 \
  -p 5683-5688:5683-5688/udp \
  -v mytb-data:/data \
  -v mytb-logs:/var/log/thingsboard \
  --name mytb \
  --restart always \
  thingsboard/tb-postgres:4.2.2

# 前台运行（调试时使用，可以看到日志输出）
# docker run -it -p 8080:9090 -p 7070:7070 -p 1883:1883 \
#   -p 5683-5688:5683-5688/udp \
#   -v mytb-data:/data \
#   -v mytb-logs:/var/log/thingsboard \
#   --name mytb \
#   --restart always \
#   thingsboard/tb-postgres:4.2.2


#打包网关
cd /Users/sunpeng/workspace/things/thingsboard-gateway

# 直接构建，无需预先编译
./docker_build_multiarch.sh
# 或
docker build -f docker/Dockerfile -t tb-gateway:3.7.9 .