# ThingsBoard Docker 镜像构建流程分析

## 1. 概述

ThingsBoard 的 Docker 镜像构建采用 Maven + Dockerfile 的方式，先通过 Maven 编译源码并打包成 DEB 包，然后使用 Dockerfile 将 DEB 包安装到 Docker 镜像中。

## 2. 构建流程总览

```
源码编译 -> Maven 打包 -> DEB 包生成 -> Dockerfile 构建 -> Docker 镜像
```

## 3. 核心组件构建流程

### 3.1 tb-node (核心服务/规则引擎)

**位置**: `msa/tb-node/`

#### 3.1.1 Maven 构建配置

**文件**: `msa/tb-node/pom.xml`

**关键步骤**:

1. **依赖 DEB 包**:
```xml
<dependencies>
    <dependency>
        <groupId>org.thingsboard</groupId>
        <artifactId>application</artifactId>
        <version>${project.version}</version>
        <classifier>deb</classifier>
        <type>deb</type>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

2. **复制 DEB 包到构建目录**:
```xml
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <executions>
        <execution>
            <id>copy-tb-deb</id>
            <phase>package</phase>
            <goals>
                <goal>copy</goal>
            </goals>
            <configuration>
                <artifactItems>
                    <artifactItem>
                        <groupId>org.thingsboard</groupId>
                        <artifactId>application</artifactId>
                        <classifier>deb</classifier>
                        <type>deb</type>
                        <destFileName>${pkg.name}.deb</destFileName>
                        <outputDirectory>${project.build.directory}</outputDirectory>
                    </artifactItem>
                </artifactItems>
            </configuration>
        </execution>
    </executions>
</plugin>
```

3. **复制 Docker 配置文件**:
```xml
<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>
```

4. **构建 Docker 镜像**:
```xml
<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>
                <verbose>true</verbose>
                <contextDirectory>${project.build.directory}</contextDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>
```

#### 3.1.2 Dockerfile

**文件**: `msa/tb-node/docker/Dockerfile`

```dockerfile
# 基础镜像：OpenJDK 17
FROM thingsboard/openjdk17:bookworm-slim

# 复制文件到临时目录
COPY logback.xml start-tb-node.sh ${pkg.name}.deb /tmp/

# 安装 DEB 包并配置
RUN chmod a+x /tmp/*.sh \
    && mv /tmp/start-tb-node.sh /usr/bin && \
    (yes | dpkg -i /tmp/${pkg.name}.deb) && \
    rm /tmp/${pkg.name}.deb && \
    mv /tmp/logback.xml ${pkg.installFolder}/conf && \
    chown -R ${pkg.user}:${pkg.user} ${pkg.installFolder}/conf/logback.xml && \
    (systemctl --no-reload disable --now ${pkg.name}.service > /dev/null 2>&1 || :) && \
    chown -R ${pkg.user}:${pkg.user} /tmp && \
    chmod 555 ${pkg.installFolder}/bin/${pkg.name}.jar

USER ${pkg.user}

CMD ["start-tb-node.sh"]
```

**关键点**:
- 使用 `dpkg -i` 安装 DEB 包
- DEB 包会将应用安装到 `/usr/share/thingsboard/`
- 复制启动脚本和配置文件
- 设置正确的用户权限

#### 3.1.3 DEB 包生成

**位置**: `application/pom.xml` 和 `packaging/java/`

DEB 包是通过 Gradle 构建的：

1. **Gradle 构建脚本**: `packaging/java/build.gradle`
2. **构建阶段**: 在 Maven 的 `package` 阶段调用 Gradle
3. **输出**: `application/target/thingsboard-{version}-boot.deb`

DEB 包包含：
- JAR 文件（Spring Boot 打包的应用）
- 配置文件
- 启动脚本
- 系统服务文件

### 3.2 传输服务 (MQTT/HTTP/CoAP/LWM2M/SNMP)

**位置**: `msa/transport/{protocol}/`

#### 3.2.1 Maven 构建配置

**文件**: `msa/transport/mqtt/pom.xml` (以 MQTT 为例)

**关键步骤**:

1. **依赖传输模块的 DEB 包**:
```xml
<dependencies>
    <dependency>
        <groupId>org.thingsboard.transport</groupId>
        <artifactId>mqtt</artifactId>
        <version>${project.version}</version>
        <classifier>deb</classifier>
        <type>deb</type>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

2. **复制 DEB 包**:
```xml
<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>
```

3. **构建 Docker 镜像**: 与 tb-node 类似

#### 3.2.2 传输模块 DEB 包生成

**位置**: `transport/mqtt/pom.xml`

传输模块的 DEB 包也是通过 Gradle 构建的，构建流程与 application 模块类似。

### 3.3 Web UI 服务

**位置**: `msa/web-ui/`

#### 3.3.1 构建流程

**文件**: `msa/web-ui/pom.xml`

**关键步骤**:

1. **前端构建**:
```xml
<plugin>
    <groupId>com.github.eirslett</groupId>
    <artifactId>frontend-maven-plugin</artifactId>
    <executions>
        <!-- 安装 Node.js 和 Yarn -->
        <execution>
            <id>install node and yarn</id>
            <goals>
                <goal>install-node-and-yarn</goal>
            </goals>
            <configuration>
                <nodeVersion>v22.18.0</nodeVersion>
                <yarnVersion>v1.22.22</yarnVersion>
            </configuration>
        </execution>
        
        <!-- 安装依赖 -->
        <execution>
            <id>yarn install</id>
            <goals>
                <goal>yarn</goal>
            </goals>
            <configuration>
                <arguments>install --non-interactive</arguments>
            </configuration>
        </execution>
        
        <!-- 构建前端 -->
        <execution>
            <id>yarn pkg</id>
            <goals>
                <goal>yarn</goal>
            </goals>
            <phase>compile</phase>
            <configuration>
                <arguments>run pkg</arguments>
            </configuration>
        </execution>
    </executions>
</plugin>
```

2. **提取 UI 文件**:
```xml
<execution>
    <id>extract-web-ui</id>
    <goals>
        <goal>unpack</goal>
    </goals>
    <configuration>
        <artifactItems>
            <artifactItem>
                <groupId>org.thingsboard</groupId>
                <artifactId>ui-ngx</artifactId>
                <type>jar</type>
                <outputDirectory>${project.build.directory}/web</outputDirectory>
            </artifactItem>
        </artifactItems>
    </configuration>
</execution>
```

3. **Dockerfile**: 使用 Node.js 基础镜像，运行前端服务

### 3.4 JS Executor 服务

**位置**: `msa/js-executor/`

#### 3.4.1 Dockerfile

**文件**: `msa/js-executor/docker/Dockerfile`

```dockerfile
FROM thingsboard/node:22.18.0-bookworm-slim

ENV NODE_ENV production
ENV DOCKER_MODE true

COPY start-js-executor.sh /tmp/

WORKDIR ${pkg.installFolder}

# 复制源代码和配置文件
COPY ["src/package.json", "src/yarn.lock", "./"]
COPY package/linux/conf ./conf
COPY package/linux/conf ./config
COPY src/api ./api
COPY src/queue ./queue
COPY src/config ./config
COPY src/server.js ./

# 安装依赖并设置权限
RUN chmod a+x /tmp/*.sh \
    && mv /tmp/start-js-executor.sh /usr/bin \
    && chown -R node:node ${pkg.installFolder} \
    && yarn install --production --non-interactive \
    && yarn cache clean --all

USER node

CMD ["start-js-executor.sh"]
```

**特点**: JS Executor 直接复制源代码，不需要 DEB 包。

## 4. 完整构建命令

### 4.1 构建所有组件

```bash
# 从项目根目录执行
./build.sh

# 或者使用 Maven
mvn clean install -DskipTests
```

### 4.2 构建特定组件

```bash
# 构建特定模块
./build.sh msa/tb-node,msa/web-ui

# 或者
mvn clean install -DskipTests --projects msa/tb-node,msa/web-ui
```

### 4.3 构建并推送 Docker 镜像

```bash
# 构建并推送镜像
mvn clean install -DskipTests -Ddockerfile.skip=false -Dpush-docker-image=true
```

## 5. 构建依赖关系

### 5.1 模块依赖顺序

```
1. common/* (公共模块)
   ↓
2. dao (数据访问层)
   ↓
3. application (主应用)
   ↓
4. transport/* (传输模块)
   ↓
5. ui-ngx (前端)
   ↓
6. msa/* (微服务镜像)
```

### 5.2 DEB 包生成顺序

1. **application 模块**: 生成 `thingsboard-{version}-boot.deb`
2. **transport 模块**: 生成 `tb-{protocol}-transport-{version}.deb`
3. **ui-ngx 模块**: 生成 JAR 包（包含前端静态资源）

## 6. 构建产物位置

### 6.1 DEB 包

- **Application**: `application/target/thingsboard-{version}-boot.deb`
- **Transport**: `transport/{protocol}/target/tb-{protocol}-transport-{version}.deb`

### 6.2 Docker 镜像构建上下文

- **tb-node**: `msa/tb-node/target/`
  - 包含: Dockerfile, DEB 包, 启动脚本, 配置文件
- **传输服务**: `msa/transport/{protocol}/target/`
  - 包含: Dockerfile, DEB 包, 启动脚本

### 6.3 Docker 镜像

构建完成后，Docker 镜像会保存在本地：
- `thingsboard/tb-node:{version}`
- `thingsboard/tb-mqtt-transport:{version}`
- `thingsboard/tb-web-ui:{version}`
- 等等

## 7. 构建脚本详解

### 7.1 build.sh

**位置**: `build.sh`

```bash
#!/bin/bash

# 设置错误时退出
set -e

# 可以指定要构建的项目
PROJECTS=""

if [ "$1" ]; then
  PROJECTS="--projects $1"
fi

# 构建命令
MAVEN_OPTS="-Xmx1024m" NODE_OPTIONS="--max_old_space_size=4096" \
DOCKER_CLI_EXPERIMENTAL=enabled DOCKER_BUILDKIT=0 \
mvn -T2 license:format clean install -DskipTests \
  $PROJECTS --also-make
```

**关键参数**:
- `-T2`: 使用 2 个线程并行构建
- `--also-make`: 同时构建依赖模块
- `-DskipTests`: 跳过测试（加快构建速度）

## 8. 构建环境要求

### 8.1 必需工具

- **Java 17**: 编译 Java 代码
- **Maven 3.6+**: 构建工具
- **Docker**: 构建 Docker 镜像
- **Node.js 22.18.0**: 构建前端（web-ui）
- **Yarn 1.22.22**: 前端包管理

### 8.2 系统要求

- **内存**: 至少 4GB（推荐 8GB+）
- **磁盘空间**: 至少 10GB 可用空间
- **操作系统**: Linux/macOS（Windows 需要 WSL）

## 9. 构建优化

### 9.1 并行构建

```bash
# 使用多线程构建
mvn -T4 clean install -DskipTests
```

### 9.2 跳过 Docker 构建

```bash
# 只构建代码，不构建 Docker 镜像
mvn clean install -DskipTests -Ddockerfile.skip=true
```

### 9.3 增量构建

```bash
# 只构建变更的模块
mvn clean install -DskipTests --projects msa/tb-node
```

## 10. 常见问题

### 10.1 DEB 包找不到

**原因**: application 模块没有先构建

**解决**: 先构建 application 模块
```bash
mvn clean install -DskipTests --projects application
```

### 10.2 Docker 构建失败

**原因**: Docker daemon 未运行或权限不足

**解决**: 
```bash
# 检查 Docker 状态
docker ps

# 确保用户在 docker 组中
sudo usermod -aG docker $USER
```

### 10.3 前端构建失败

**原因**: Node.js 版本不匹配或网络问题

**解决**:
```bash
# 使用正确的 Node.js 版本
nvm use 22.18.0

# 清理缓存重试
cd ui-ngx && rm -rf node_modules && yarn install
```

## 11. 总结

ThingsBoard 的 Docker 镜像构建流程：

1. **源码编译**: Maven 编译 Java 代码
2. **打包**: 使用 Gradle 打包成 DEB 包（Java 服务）或 JAR 包（前端）
3. **Docker 构建**: 使用 dockerfile-maven-plugin 调用 Dockerfile 构建镜像
4. **镜像生成**: 最终生成 Docker 镜像

**关键特点**:
- 使用 DEB 包作为中间产物，便于安装和配置
- 采用 Maven 多模块项目结构，支持并行构建
- 前端和 Java 服务采用不同的构建方式
- 支持构建特定模块，提高构建效率

通过这个流程，ThingsBoard 可以将复杂的多模块项目统一构建成 Docker 镜像，便于部署和管理。