553 lines
16 KiB
Markdown
553 lines
16 KiB
Markdown
# 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 镜像。
|
||
|