# 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 镜像。