thingsboard/summary/20-ThingsBoard单镜像部署构建指南.md

493 lines
13 KiB
Markdown
Raw Permalink Normal View History

2026-01-19 11:50:37 +08:00
# 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 环境中):
```bash
# 从项目根目录执行,构建并推送镜像
mvn clean install -DskipTests \
-Ddockerfile.skip=false \
-Dpush-docker-image=true \
--projects msa/tb \
--also-make
```
**官方运行命令**(官网文档中的示例):
```bash
# 创建数据目录和日志目录
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 镜像都依赖以下基础镜像:
```bash
# Java 服务基础镜像
docker pull thingsboard/openjdk17:bookworm-slim
```
如果网络有问题,可以使用国内镜像源。
#### 4.1.2 获取版本号
查看项目根目录的 `pom.xml`
```bash
grep "<version>" pom.xml | head -1
# 输出: <version>4.2.1</version>
```
或者直接查看文件第一行(通常在 23 行左右):
```bash
grep -A 1 "<artifactId>thingsboard</artifactId>" pom.xml | grep version
```
当前版本:**4.2.1**
### 4.2 构建方法
#### 方法1使用 Maven 直接构建(推荐)
##### 构建 tb-postgres 镜像
```bash
# 从项目根目录执行
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 包
```bash
# 从项目根目录执行,构建依赖的 application 模块
mvn clean install -DskipTests --projects msa/tb --also-make
```
这会:
- ✅ 编译代码
- ✅ 生成 `application/target/thingsboard-4.2.1-boot.deb`
- ✅ 复制 Dockerfile 和启动脚本到构建目录
- ❌ 跳过 Docker 镜像构建(避免插件问题)
##### 步骤2查看构建产物
```bash
# 查看 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 镜像:**
```bash
cd msa/tb/target/docker-postgres
docker build -t thingsboard/tb-postgres:4.2.1 .
```
**构建 tb-cassandra 镜像:**
```bash
cd msa/tb/target/docker-cassandra
docker build -t thingsboard/tb-cassandra:4.2.1 .
```
#### 方法3使用 build.sh不推荐默认跳过 Docker
```bash
./build.sh msa/tb
```
**注意**: `build.sh` 默认跳过 Docker 构建(`dockerfile.skip=true`),需要修改脚本或手动构建。
## 5. 构建验证
### 5.1 查看构建的镜像
```bash
docker images | grep thingsboard/tb
```
应该看到:
```
thingsboard/tb-postgres 4.2.1 ...
thingsboard/tb-cassandra 4.2.1 ...
```
### 5.2 测试运行镜像
#### 测试 tb-postgres 镜像
```bash
# 创建数据目录
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 镜像
```bash
# 创建数据目录
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`
```bash
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 数据库初始化失败
确保数据目录权限正确:
```bash
mkdir -p ~/.mytb-data && sudo chown -R 799:799 ~/.mytb-data
```
## 9. 快速构建命令总结
### 最简单的方式(推荐)
```bash
# 从项目根目录
mvn clean install -DskipTests -Ddockerfile.skip=false --projects msa/tb --also-make
```
### Mac M1 或遇到插件问题的方案
```bash
# 步骤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 官网推荐运行方式(完整配置)
```bash
# 创建数据目录和日志目录使用用户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 简化运行方式
```bash
# 最小配置
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 容器管理
```bash
# 查看日志
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 .