# 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 "" pom.xml | head -1 # 输出: 4.2.1 ``` 或者直接查看文件第一行（通常在 23 行左右）： ```bash grep -A 1 "thingsboard" 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 .