thingsboard/summary/09-构建脚本说明.md

# ThingsBoard 构建脚本说明

## 1. build.sh 文件作用

`build.sh` 是 ThingsBoard 项目的**主构建脚本**，用于从源码构建整个项目。

### 1.1 核心功能

- **一键构建**: 简化 Maven 构建命令
- **环境配置**: 设置构建所需的环境变量
- **选择性构建**: 支持构建特定模块
- **并行构建**: 使用多线程加速构建

## 2. 脚本详解

### 2.1 脚本内容分析

```bash
#!/bin/bash

# 设置错误时退出
set -e

# 可选的构建项目列表（默认空，构建所有项目）
PROJECTS=""

# 如果提供了参数，只构建指定的项目
if [ "$1" ]; then
  PROJECTS="--projects $1"
fi

# 显示帮助信息
echo "Building and pushing [amd64,arm64] projects '$PROJECTS' ..."
echo "HELP: usage ./build.sh [projects]"
echo "HELP: example ./build.sh msa/web-ui,msa/web-report"

# 检查 Java 版本
java -version

# 执行 Maven 构建
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
```

### 2.2 关键参数说明

#### 2.2.1 环境变量

- **MAVEN_OPTS="-Xmx1024m"**: Maven 使用 1GB 内存
- **NODE_OPTIONS="--max_old_space_size=4096"**: Node.js 使用 4GB 内存（用于前端构建）
- **DOCKER_CLI_EXPERIMENTAL=enabled**: 启用 Docker 实验性功能
- **DOCKER_BUILDKIT=0**: 禁用 Docker BuildKit（兼容性考虑）

#### 2.2.2 Maven 参数

- **-T2**: 使用 2 个线程并行构建
- **license:format**: 格式化代码许可证头
- **clean**: 清理之前的构建产物
- **install**: 编译、测试、打包并安装到本地仓库
- **-DskipTests**: 跳过测试（加快构建速度）
- **--also-make**: 同时构建依赖的模块
- **--projects**: 指定要构建的项目（可选）

## 3. 使用方法

### 3.1 构建所有项目

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

**等同于**:
```bash
mvn clean install -DskipTests
```

### 3.2 构建特定项目

```bash
# 构建单个项目
./build.sh msa/tb-node

# 构建多个项目（用逗号分隔）
./build.sh msa/tb-node,msa/web-ui

# 构建传输服务
./build.sh msa/transport/mqtt
```

### 3.3 实际示例

```bash
# 示例1：只构建 Web UI
./build.sh msa/web-ui

# 示例2：构建核心服务和规则引擎
./build.sh msa/tb-node

# 示例3：构建所有传输服务
./build.sh msa/transport
```

## 4. 构建流程

### 4.1 完整构建流程

执行 `./build.sh` 后，Maven 会执行以下步骤：

```
1. license:format
   ↓
   格式化所有文件的许可证头
   
2. clean
   ↓
   清理之前的构建产物（target/ 目录）
   
3. compile
   ↓
   编译所有 Java 源码
   
4. test（跳过，因为 -DskipTests）
   ↓
   
5. package
   ↓
   打包：
   - Java 模块 → JAR 包
   - application 模块 → DEB 包
   - transport 模块 → DEB 包
   - ui-ngx 模块 → JAR 包（包含前端静态资源）
   
6. install
   ↓
   安装到本地 Maven 仓库（~/.m2/repository）
   
7. Docker 构建（如果启用）
   ↓
   构建 Docker 镜像（默认跳过，因为 dockerfile.skip=true）
```

### 4.2 构建产物

构建完成后，会在各模块的 `target/` 目录下生成：

- **JAR 包**: `application/target/thingsboard-4.2.1-boot.jar`
- **DEB 包**: `application/target/thingsboard-4.2.1.deb`
- **Docker 镜像**: `thingsboard/tb-node:4.2.1`（如果启用 Docker 构建）

## 5. 构建选项

### 5.1 构建 Docker 镜像

默认情况下，`build.sh` **不会构建 Docker 镜像**（`dockerfile.skip=true`）。

要构建 Docker 镜像，需要直接使用 Maven：

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

### 5.2 运行测试

默认跳过测试（`-DskipTests`），要运行测试：

```bash
# 运行测试
mvn clean install

# 或只运行特定模块的测试
mvn clean install --projects application
```

### 5.3 离线构建

```bash
# 使用本地仓库，不下载依赖
mvn clean install -DskipTests --offline
```

## 6. 其他构建脚本

### 6.1 build_proto.sh

**位置**: `build_proto.sh`

**作用**: 只构建包含 Protobuf 的模块

```bash
#!/bin/bash
echo "Building ThingsBoard protobuf-containing packages..."
mvn clean compile -T4 --also-make --projects='
common/cluster-api,
common/edge-api,
common/transport/coap,
common/transport/mqtt,
common/transport/transport-api'
```

**使用场景**: 
- 修改了 `.proto` 文件后
- 需要重新生成 Protobuf Java 代码时

**使用方法**:
```bash
./build_proto.sh
```

## 7. 构建时间优化

### 7.1 并行构建

```bash
# 使用更多线程（根据 CPU 核心数调整）
mvn -T4 clean install -DskipTests
```

### 7.2 增量构建

```bash
# 只构建变更的模块
./build.sh msa/tb-node  # 只构建 tb-node
```

### 7.3 跳过前端构建

```bash
# 如果不需要前端，可以跳过 ui-ngx 模块
mvn clean install -DskipTests --projects '!ui-ngx'
```

## 8. 常见问题

### 8.1 内存不足

**问题**: `java.lang.OutOfMemoryError`

**解决**: 增加 Maven 内存
```bash
MAVEN_OPTS="-Xmx2048m" ./build.sh
```

### 8.2 Node.js 内存不足

**问题**: 前端构建时内存不足

**解决**: 增加 Node.js 内存
```bash
NODE_OPTIONS="--max_old_space_size=8192" ./build.sh
```

### 8.3 构建失败

**检查**:
1. Java 版本是否正确（需要 Java 17）
2. Maven 版本（需要 3.6+）
3. 网络连接（需要下载依赖）
4. 磁盘空间是否充足

### 8.4 依赖下载失败

**解决**:
```bash
# 清理本地仓库后重试
rm -rf ~/.m2/repository/org/thingsboard
./build.sh
```

## 9. 构建脚本 vs 直接使用 Maven

### 9.1 使用 build.sh

**优点**:
- ✅ 统一的构建入口
- ✅ 预设了最佳实践的环境变量
- ✅ 简化命令

**示例**:
```bash
./build.sh msa/tb-node
```

### 9.2 直接使用 Maven

**优点**:
- ✅ 更灵活的控制
- ✅ 可以使用所有 Maven 选项

**示例**:
```bash
mvn clean install -DskipTests --projects msa/tb-node --also-make
```

## 10. CI/CD 集成

### 10.1 在 CI 中使用

```yaml
# GitHub Actions 示例
- name: Build ThingsBoard
  run: |
    chmod +x build.sh
    ./build.sh
    
- name: Build specific modules
  run: |
    ./build.sh msa/tb-node,msa/web-ui
```

### 10.2 构建 Docker 镜像

```bash
# 在 CI 中构建并推送 Docker 镜像
mvn clean install -DskipTests \
  -Ddockerfile.skip=false \
  -Dpush-docker-image=true \
  -Ddocker.repo=your-registry/thingsboard
```

## 11. 总结

### 11.1 build.sh 的作用

1. **简化构建**: 一键构建整个项目
2. **环境配置**: 设置合适的内存和构建选项
3. **选择性构建**: 支持构建特定模块
4. **标准化**: 统一的构建方式

### 11.2 核心命令

```bash
# 构建所有项目
./build.sh

# 构建特定项目
./build.sh msa/tb-node

# 构建多个项目
./build.sh msa/tb-node,msa/web-ui,msa/transport/mqtt
```

### 11.3 实际等效命令

`./build.sh` 实际执行的是：

```bash
MAVEN_OPTS="-Xmx1024m" \
NODE_OPTIONS="--max_old_space_size=4096" \
mvn -T2 license:format clean install -DskipTests --also-make
```

**所以 `build.sh` 本质上是一个 Maven 构建的便捷包装脚本！**