THENG
/
thingsboard
6
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
thingsboard/summary/13-Transport镜像构建与获取指南.md

553 lines
16 KiB
Markdown
Raw Permalink Normal View History

first commit
2026-01-19 11:50:37 +08:00
# ThingsBoard Transport 镜像构建与获取指南
## 1. Transport 镜像来源
### 1.1 官方镜像位置
ThingsBoard Transport 镜像发布在 **Docker Hub**：
**镜像仓库**: `thingsboard`
**可用镜像列表**:
- `thingsboard/tb-mqtt-transport` - MQTT 传输服务
- `thingsboard/tb-http-transport` - HTTP 传输服务
- `thingsboard/tb-coap-transport` - CoAP 传输服务
- `thingsboard/tb-lwm2m-transport` - LWM2M 传输服务
- `thingsboard/tb-snmp-transport` - SNMP 传输服务
**Docker Hub 地址**:
- https://hub.docker.com/u/thingsboard
- https://hub.docker.com/r/thingsboard/tb-mqtt-transport
- https://hub.docker.com/r/thingsboard/tb-http-transport
- https://hub.docker.com/r/thingsboard/tb-coap-transport
- https://hub.docker.com/r/thingsboard/tb-lwm2m-transport
- https://hub.docker.com/r/thingsboard/tb-snmp-transport
### 1.2 镜像标签
镜像使用版本标签，例如：
- `thingsboard/tb-mqtt-transport:4.2.1` - 特定版本
- `thingsboard/tb-mqtt-transport:latest` - 最新版本
### 1.3 使用官方镜像
直接拉取官方镜像：
```bash
# 拉取 MQTT Transport 镜像
docker pull thingsboard/tb-mqtt-transport:4.2.1
# 拉取 HTTP Transport 镜像
docker pull thingsboard/tb-http-transport:4.2.1
# 拉取 CoAP Transport 镜像
docker pull thingsboard/tb-coap-transport:4.2.1
# 拉取 LWM2M Transport 镜像
docker pull thingsboard/tb-lwm2m-transport:4.2.1
# 拉取 SNMP Transport 镜像
docker pull thingsboard/tb-snmp-transport:4.2.1
```
## 2. Transport 镜像构建流程
### 2.1 构建架构
Transport 镜像的构建采用两阶段流程：
```
阶段1: Transport 模块构建
transport/mqtt/ (源码)
↓ Maven 编译
↓ Gradle 打包
tb-mqtt-transport-{version}.deb (DEB包)
阶段2: Docker 镜像构建
msa/transport/mqtt/ (Docker配置)
↓ 依赖 transport/mqtt 的 DEB 包
↓ Dockerfile 构建
thingsboard/tb-mqtt-transport:{version} (Docker镜像)
```
### 2.2 源码结构
```
thingsboard/
├── transport/ # Transport 模块源码
│ ├── mqtt/ # MQTT Transport 源码
│ │ ├── pom.xml # Maven 配置
│ │ └── src/ # 源代码
│ ├── http/ # HTTP Transport 源码
│ ├── coap/ # CoAP Transport 源码
│ ├── lwm2m/ # LWM2M Transport 源码
│ └── snmp/ # SNMP Transport 源码
│
└── msa/transport/ # Transport Docker 镜像构建
├── mqtt/ # MQTT Transport Docker 配置
│ ├── pom.xml # Maven 配置（依赖 transport/mqtt DEB包）
│ └── docker/
│ ├── Dockerfile # Docker 构建文件
│ └── start-tb-mqtt-transport.sh # 启动脚本
├── http/ # HTTP Transport Docker 配置
├── coap/ # CoAP Transport Docker 配置
├── lwm2m/ # LWM2M Transport Docker 配置
└── snmp/ # SNMP Transport Docker 配置
```
### 2.3 构建步骤详解
#### 步骤1: 构建 Transport 模块 DEB 包
每个 transport 模块都需要先构建 DEB 包：
```bash
# 构建 MQTT Transport DEB 包
cd transport/mqtt
mvn clean package
# 生成的 DEB 包位置
# transport/mqtt/target/tb-mqtt-transport-4.2.1.deb
```
**DEB 包内容**:
- JAR 文件（Spring Boot 打包的应用）
- 配置文件
- 启动脚本
#### 步骤2: 构建 Docker 镜像
`msa/transport/mqtt/pom.xml` 中的配置：
```xml
<dependencies>
<!-- 依赖 transport/mqtt 模块的 DEB 包 -->
<dependency>
<groupId>org.thingsboard.transport</groupId>
<artifactId>mqtt</artifactId>
<version>${project.version}</version>
<classifier>deb</classifier>
<type>deb</type>
<scope>provided</scope>
</dependency>
</dependencies>
<build>
<plugins>
<!-- 复制 DEB 包到构建目录 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<executions>
<execution>
<id>copy-tb-mqtt-transport-deb</id>
<phase>package</phase>
<goals>
<goal>copy</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.thingsboard.transport</groupId>
<artifactId>mqtt</artifactId>
<classifier>deb</classifier>
<type>deb</type>
<destFileName>${pkg.name}.deb</destFileName>
<outputDirectory>${project.build.directory}</outputDirectory>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
<!-- 复制 Docker 配置文件 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<id>copy-docker-config</id>
<phase>process-resources</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}</outputDirectory>
<resources>
<resource>
<directory>docker</directory>
<filtering>true</filtering>
</resource>
</resources>
</configuration>
</execution>
</executions>
</plugin>
<!-- 构建 Docker 镜像 -->
<plugin>
<groupId>com.spotify</groupId>
<artifactId>dockerfile-maven-plugin</artifactId>
<executions>
<execution>
<id>build-docker-image</id>
<phase>pre-integration-test</phase>
<goals>
<goal>build</goal>
</goals>
<configuration>
<skip>${dockerfile.skip}</skip>
<repository>${docker.repo}/${docker.name}</repository>
<contextDirectory>${project.build.directory}</contextDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
```
**Dockerfile** (`msa/transport/mqtt/docker/Dockerfile`):
```dockerfile
FROM thingsboard/openjdk17:bookworm-slim
# 复制启动脚本和 DEB 包
COPY start-tb-mqtt-transport.sh ${pkg.name}.deb /tmp/
# 安装 DEB 包
RUN chmod a+x /tmp/*.sh \
&& mv /tmp/start-tb-mqtt-transport.sh /usr/bin && \
(yes | dpkg -i /tmp/${pkg.name}.deb) && \
rm /tmp/${pkg.name}.deb && \
(systemctl --no-reload disable --now ${pkg.name}.service > /dev/null 2>&1 || :) && \
chmod 555 ${pkg.installFolder}/bin/${pkg.name}.jar
USER ${pkg.user}
CMD ["start-tb-mqtt-transport.sh"]
```
## 3. 如何构建 Transport 镜像
### 3.1 方法1: 使用 Maven 构建（推荐）
#### 3.1.1 构建单个 Transport 镜像
```bash
# 构建 MQTT Transport 镜像
cd msa/transport/mqtt
mvn clean install -DskipTests -Ddockerfile.skip=false
# 构建 HTTP Transport 镜像
cd msa/transport/http
mvn clean install -DskipTests -Ddockerfile.skip=false
# 构建 CoAP Transport 镜像
cd msa/transport/coap
mvn clean install -DskipTests -Ddockerfile.skip=false
# 构建 LWM2M Transport 镜像
cd msa/transport/lwm2m
mvn clean install -DskipTests -Ddockerfile.skip=false
# 构建 SNMP Transport 镜像
cd msa/transport/snmp
mvn clean install -DskipTests -Ddockerfile.skip=false
```
#### 3.1.2 构建所有 Transport 镜像
```bash
# 从项目根目录构建所有 transport 镜像
cd msa/transport
mvn clean install -DskipTests -Ddockerfile.skip=false
# 或者从项目根目录构建整个项目（包括 transport）
cd ../..
mvn clean install -DskipTests -Ddockerfile.skip=false --projects msa/transport
```
#### 3.1.3 构建并推送镜像到 Docker Hub
```bash
# 构建并推送镜像（需要 Docker Hub 认证）
mvn clean install -DskipTests \
-Ddockerfile.skip=false \
-Dpush-docker-image=true \
--projects msa/transport/mqtt
```
**注意**: 推送镜像需要：
1. Docker Hub 账号
2. 登录 Docker Hub: `docker login`
3. 配置 Maven 的 `docker.repo` 属性（默认是 `thingsboard`）
### 3.2 方法2: 使用 build.sh 脚本
```bash
# 构建所有 transport 模块（不包括 Docker 镜像，默认跳过）
./build.sh msa/transport
# 注意：build.sh 默认跳过 Docker 构建（dockerfile.skip=true）
# 需要手动设置环境变量或修改脚本
```
### 3.3 方法3: 直接使用 Dockerfile
如果已经有 DEB 包，可以直接使用 Dockerfile 构建：
```bash
# 1. 准备文件
cd msa/transport/mqtt/target
# 确保以下文件存在：
# - Dockerfile (从 docker/ 目录复制)
# - start-tb-mqtt-transport.sh (从 docker/ 目录复制)
# - tb-mqtt-transport.deb (从 transport/mqtt/target/ 复制)
# 2. 构建镜像
docker build -t thingsboard/tb-mqtt-transport:4.2.1 .
```
## 4. 构建依赖关系
### 4.1 构建顺序
Transport 镜像的构建依赖于以下模块：
```
1. common/* (公共模块)
↓
2. common/transport/* (传输层公共模块)
↓
3. transport/{protocol}/ (Transport 模块源码)
↓ 生成 DEB 包
4. msa/transport/{protocol}/ (Docker 镜像构建)
↓ 使用 DEB 包
5. Docker 镜像
```
### 4.2 正确的构建命令
```bash
# 方式1: 先构建 transport 模块，再构建 Docker 镜像
mvn clean install -DskipTests --projects transport/mqtt
mvn clean install -DskipTests -Ddockerfile.skip=false --projects msa/transport/mqtt
# 方式2: 使用 --also-make 自动构建依赖
mvn clean install -DskipTests -Ddockerfile.skip=false \
--projects msa/transport/mqtt \
--also-make
# 方式3: 从根目录构建整个项目（推荐）
mvn clean install -DskipTests -Ddockerfile.skip=false
```
## 5. 验证构建结果
### 5.1 检查镜像
```bash
# 查看本地镜像
docker images | grep thingsboard/tb-.*-transport
# 应该看到类似输出：
# thingsboard/tb-mqtt-transport 4.2.1 abc123def456 2 hours ago 500MB
# thingsboard/tb-http-transport 4.2.1 def456abc123 2 hours ago 450MB
# thingsboard/tb-coap-transport 4.2.1 ghi789jkl012 2 hours ago 480MB
```
### 5.2 测试镜像
```bash
# 运行 MQTT Transport 容器（测试）
docker run -it --rm \
-e ZOOKEEPER_ENABLED=true \
-e ZOOKEEPER_URL=zookeeper:2181 \
-e TB_QUEUE_TYPE=kafka \
-e TB_KAFKA_SERVERS=kafka:9092 \
thingsboard/tb-mqtt-transport:4.2.1
```
## 6. 官方文档位置
### 6.1 ThingsBoard 官网
**官方网站**: https://thingsboard.io
**文档位置**:
- **安装文档**: https://thingsboard.io/docs/user-guide/install/
- **Docker 部署**: https://thingsboard.io/docs/user-guide/install/docker/
- **微服务部署**: https://thingsboard.io/docs/user-guide/install/microservices-docker/
### 6.2 GitHub 仓库
**源码仓库**: https://github.com/thingsboard/thingsboard
**相关文件**:
- `msa/transport/` - Transport Docker 镜像构建配置
- `transport/` - Transport 模块源码
- `docker/` - Docker Compose 配置示例
### 6.3 Docker Hub
**Docker Hub 组织**: https://hub.docker.com/u/thingsboard
**可用镜像**:
- https://hub.docker.com/r/thingsboard/tb-mqtt-transport
- https://hub.docker.com/r/thingsboard/tb-http-transport
- https://hub.docker.com/r/thingsboard/tb-coap-transport
- https://hub.docker.com/r/thingsboard/tb-lwm2m-transport
- https://hub.docker.com/r/thingsboard/tb-snmp-transport
### 6.4 官方文档搜索关键词
在 ThingsBoard 官方文档中搜索以下关键词：
- "transport" - 传输服务相关文档
- "microservices" - 微服务部署文档
- "docker" - Docker 部署文档
- "MQTT transport" - MQTT 传输服务文档
- "HTTP transport" - HTTP 传输服务文档
## 7. 常见问题
### 7.1 问题1: DEB 包找不到
**错误信息**:
```
Could not find artifact org.thingsboard.transport:mqtt:deb:4.2.1
```
**原因**: Transport 模块的 DEB 包还没有构建
**解决方案**:
```bash
# 先构建 transport 模块
mvn clean install -DskipTests --projects transport/mqtt
# 然后再构建 Docker 镜像
mvn clean install -DskipTests -Ddockerfile.skip=false --projects msa/transport/mqtt
```
### 7.2 问题2: Docker 构建被跳过
**原因**: 默认配置 `dockerfile.skip=true`
**解决方案**:
```bash
# 添加 -Ddockerfile.skip=false 参数
mvn clean install -DskipTests -Ddockerfile.skip=false
```
### 7.3 问题3: 镜像推送到 Docker Hub 失败
**错误信息**:
```
denied: requested access to the resource is denied
```
**原因**: 未登录 Docker Hub 或没有推送权限
**解决方案**:
```bash
# 1. 登录 Docker Hub
docker login
# 2. 确保有推送权限（镜像仓库必须是 your-username/tb-mqtt-transport）
# 或者修改 docker.repo 属性
mvn clean install -DskipTests -Ddockerfile.skip=false \
-Ddocker.repo=your-username \
-Dpush-docker-image=true
```
### 7.4 问题4: 构建时间过长
**原因**: Maven 需要下载依赖和编译代码
**优化方案**:
```bash
# 1. 使用并行构建
mvn clean install -DskipTests -Ddockerfile.skip=false -T4
# 2. 只构建需要的模块
mvn clean install -DskipTests -Ddockerfile.skip=false \
--projects msa/transport/mqtt \
--also-make
# 3. 使用本地 Maven 仓库缓存
# 确保 ~/.m2/repository 中有依赖
```
## 8. 镜像标签和版本
### 8.1 版本标签
镜像使用项目版本作为标签：
```bash
# 查看项目版本（pom.xml）
grep "<version>" pom.xml | head -1
# 镜像标签格式
thingsboard/tb-mqtt-transport:{version}
# 例如：thingsboard/tb-mqtt-transport:4.2.1
```
### 8.2 Latest 标签
构建时会自动创建 `latest` 标签：
```bash
# 推送 latest 标签（在 push-docker-image profile 中）
mvn clean install -DskipTests \
-Ddockerfile.skip=false \
-Dpush-docker-image=true
```
## 9. 构建环境要求
### 9.1 必需工具
- **Java 17**: 编译 Java 代码
- **Maven 3.6+**: 构建工具
- **Docker**: 构建 Docker 镜像
- **Gradle**: 构建 DEB 包（Maven 会自动调用）
### 9.2 系统要求
- **内存**: 至少 4GB（推荐 8GB+）
- **磁盘空间**: 至少 5GB 可用空间
- **操作系统**: Linux/macOS（Windows 需要 WSL）
## 10. 总结
### 10.1 镜像来源
1. **官方镜像**: Docker Hub `thingsboard/tb-{protocol}-transport`
2. **源码构建**: 从 GitHub 源码构建
3. **DEB 包**: 可以单独下载 DEB 包安装
### 10.2 构建方法
1. **Maven 构建**（推荐）: `mvn clean install -DskipTests -Ddockerfile.skip=false`
2. **直接 Dockerfile**: 使用已有的 DEB 包和 Dockerfile
3. **CI/CD**: 集成到持续集成流程
### 10.3 官方文档位置
- **官网**: https://thingsboard.io/docs
- **GitHub**: https://github.com/thingsboard/thingsboard
- **Docker Hub**: https://hub.docker.com/u/thingsboard
### 10.4 关键文件位置
- **Dockerfile**: `msa/transport/{protocol}/docker/Dockerfile`
- **Maven 配置**: `msa/transport/{protocol}/pom.xml`
- **源码**: `transport/{protocol}/`
- **启动脚本**: `msa/transport/{protocol}/docker/start-tb-{protocol}-transport.sh`
通过以上方式，您可以获取或构建 ThingsBoard Transport 的 Docker 镜像。