493 lines
13 KiB
Markdown
493 lines
13 KiB
Markdown
# 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 . |