3. 源码获取与编译

ThingsBoard 作为一款开源物联网平台，其二次开发的第一步便是获取源码并成功编译运行。本章将带领你从 GitHub 拉取 ThingsBoard 源码，配置本地 Maven 环境，完成多模块项目的编译打包，并针对高频编译错误提供系统性的排查与解决方案。掌握本章内容，是后续进行功能扩展、协议适配和前端定制的基础前提。

3.1 源码获取：从 GitHub 拉取 ThingsBoard

ThingsBoard 的官方源码托管在 GitHub 的 thingsboard/thingsboard 仓库中。获取源码有两种常见方式：直接 Clone 官方仓库，或先 Fork 到个人账号下再 Clone。对于二次开发而言，推荐后者，便于后续提交自定义修改并同步上游更新。

3.1.1 核心原理：分支策略与版本选择

ThingsBoard 采用 Git Flow 风格的分支管理。主分支 master 对应最新开发版，功能最新但稳定性稍弱；release-3.x 系列分支为稳定发布版，适合生产环境二次开发。以 3.6 版本为例，应选择 release-3.6 分支。此外还有 hotfix/* 和 feature/* 临时分支，一般无需关注。

3.1.2 操作流程：Clone 与分支切换

# 方式一：直接克隆官方仓库（只取指定分支，减少下载量）
git clone -b release-3.6 --single-branch https://github.com/thingsboard/thingsboard.git

# 方式二：先 Fork 再克隆（推荐二次开发）
# 在 GitHub 网页端 Fork 到个人账号后执行：
git clone https://github.com/<your-username>/thingsboard.git
cd thingsboard
git checkout -b release-3.6 origin/release-3.6

# 查看当前分支确认
git branch -a

3.1.3 实战场景：源码目录结构认知

Clone 完成后，建议先花 10 分钟浏览顶层目录结构，这对后续定位代码位置至关重要。核心目录如下：

3.2 环境准备：JDK 与 Maven 的精确配置

ThingsBoard 3.x 系列要求 JDK 11（部分新版本已支持 JDK 17），Maven 3.6.3 及以上版本。环境配置不当是编译失败的首要原因，尤其是 JDK 版本不匹配和 Maven 镜像缺失。

3.2.1 核心原理：Maven 多模块构建机制

ThingsBoard 是一个典型的 Maven 多模块项目，父 POM 通过 <modules> 标签聚合所有子模块。构建时 Maven 会按照模块间的依赖关系自动排序，先编译 dao、common 等基础模块，再编译 rule-engine、application 等上层模块。理解这一机制有助于定位编译错误发生的模块层级。

3.2.2 操作流程：环境变量与 Maven 镜像配置

# 1. 检查 JDK 版本（必须为 11 或 17）
java -version

# 2. 配置 Maven 阿里云镜像（编辑 ~/.m2/settings.xml）
<mirrors>
  <mirror>
    <id>aliyunmaven</id>
    <mirrorOf>central</mirrorOf>
    <name>阿里云公共仓库</name>
    <url>https://maven.aliyun.com/repository/public</url>
  </mirror>
</mirrors>

# 3. 设置 MAVEN_OPTS 避免内存溢出（编辑 ~/.m2/settings.xml 或环境变量）
export MAVEN_OPTS="-Xms1024m -Xmx4096m -XX:MaxMetaspaceSize=512m"

3.2.3 案例拆解：一次因 JDK 版本导致的编译失败

背景： 某开发者在 Windows 机器上使用默认 JDK 8 执行 mvn clean install，编译到 dao 模块时抛出大量 cannot find symbol 错误，指向 java.time 包下的类。

分析过程： 查看错误日志发现 LocalDateTime 等类无法解析。JDK 8 虽然包含 java.time 包，但 ThingsBoard 的某些依赖（如 Hibernate 6.x）在编译期使用了 JDK 11 才有的 API。通过 mvn -version 确认 Maven 使用的是 JDK 8。

解决步骤：

1. 安装 JDK 11（推荐 Eclipse Temurin 或 AdoptOpenJDK）
2. 修改 JAVA_HOME 环境变量指向 JDK 11 安装目录
3. 在 IDE 中同步修改 Project SDK 和 Maven Runner 的 JRE 设置
4. 重新执行编译，错误消失

复盘经验： 编译前务必执行 mvn -version 确认 Maven 使用的 JDK 版本，而非仅检查 java -version。因为 Maven 可能通过 JAVA_HOME 指向了不同的 JDK。

3.3 Maven 编译打包：完整命令与参数解析

编译 ThingsBoard 全量模块需要较长时间（视网络和机器性能，约 15-40 分钟）。掌握正确的命令参数可以避免无效构建，并快速定位问题。

3.3.1 核心原理：编译生命周期与跳过策略

Maven 的 install 命令会依次执行 validate → compile → test → package → install 等阶段。ThingsBoard 的单元测试较多，且部分集成测试需要数据库环境，因此二次开发编译时通常跳过测试以节省时间。同时，前端模块 ui-ngx 使用 npm 构建，可通过 -pl 参数排除。

3.3.2 操作流程：标准编译命令

# 进入源码根目录
cd thingsboard

# 标准编译（跳过测试，排除前端模块）
mvn clean install -DskipTests -pl '!ui-ngx'

# 如需同时编译前端（耗时较长，需 Node.js 环境）
mvn clean install -DskipTests

# 仅编译并启动后端（开发调试时使用）
mvn clean compile -pl application -am -DskipTests

3.3.3 参数说明与选择建议

3.4 常见编译错误排查与解决

即使环境配置正确，编译过程中仍可能遇到各种问题。以下按出现频率排序，给出系统性排查方案。

3.4.1 依赖下载失败或超时

现象： 编译早期阶段报 Could not resolve dependencies 或 Connection timed out。

原因： 默认 Maven 中央仓库访问不稳定，或某些依赖（如 ThingsBoard 自研组件）仅在特定仓库发布。

解决方案：

1. 配置阿里云镜像（见 3.2.2）
2. 检查 ~/.m2/repository 下是否有残留的 .lastUpdated 文件，如有则删除后重试
3. 使用 mvn -U 强制更新快照版本

3.4.2 Lombok 注解处理器异常

现象： 编译时提示 java: package lombok does not exist 或 NoSuchMethodError。

原因： Lombok 版本与 JDK 版本不兼容。例如 JDK 17 需要 Lombok 1.18.20+。

解决方案： 在父 POM 中检查 lombok.version 属性，若使用 JDK 17 则手动升级到 1.18.30 及以上。修改后执行 mvn clean 再重新编译。

3.4.3 内存溢出（OutOfMemoryError）

现象： 编译到 rule-engine 或 application 模块时，报 Java heap space 或 GC overhead limit exceeded。

原因： ThingsBoard 模块众多，Maven 默认堆内存不足以支撑多模块并行编译。

解决方案： 设置 MAVEN_OPTS 环境变量，建议 -Xms1024m -Xmx4096m -XX:MaxMetaspaceSize=512m。同时避免在 IDE 中直接使用默认配置编译，推荐使用命令行。

3.4.4 前端模块编译失败（Node 相关）

现象： 编译 ui-ngx 时提示 Node.js version must be >= 14 或 npm 安装依赖失败。

原因： ThingsBoard 前端使用 Angular，对 Node.js 版本有明确要求。

解决方案： 使用 nvm 安装指定版本 Node.js（如 16.x），并确保 npm 使用国内镜像：npm config set registry https://registry.npmmirror.com。

3.4.5 案例拆解：一次完整的排障闭环

背景： 某团队在 CentOS 7 服务器上编译 ThingsBoard 3.5，执行 mvn clean install -DskipTests 后，在 dao 模块报错：Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.10.1:compile，错误信息指向 com.datastax.oss.driver.api.core.ConsistencyLevel 类找不到。

初始现象： 编译中断，无 BUILD SUCCESS 输出。

关键输入数据： Maven 版本 3.8.5，JDK 版本 11.0.18，网络环境为内网（需通过代理访问外网）。

分析判断过程：

1. 首先检查 dao/pom.xml 中 Cassandra 驱动依赖版本，发现为 4.15.0
2. 检查本地仓库 ~/.m2/repository/com/datastax/oss/java-driver-core/4.15.0，发现 jar 包存在但大小为 0KB
3. 判断为依赖下载不完整，可能是内网代理中断导致

实际操作步骤：

# 删除损坏的依赖目录
rm -rf ~/.m2/repository/com/datastax/oss/java-driver-core/4.15.0

# 配置 Maven 代理（settings.xml）
<proxies>
  <proxy>
    <id>internal-proxy</id>
    <active>true</active>
    <protocol>http</protocol>
    <host>proxy.company.com</host>
    <port>8080</port>
  </proxy>
</proxies>

# 重新编译
mvn clean install -DskipTests -pl dao -am

结果对比： 重新编译后 dao 模块成功，继续执行全量编译，最终 BUILD SUCCESS。

风险与代价： 内网环境编译需额外配置代理，且代理不稳定会导致依赖下载不完整。建议在 CI 服务器上提前预热依赖缓存。

复盘经验： 遇到类找不到错误时，优先检查本地仓库对应 jar 包是否完整（大小是否正常），而非盲目修改代码或依赖版本。

3.5 编译产物验证与启动测试

编译成功后，需要验证产物可正常运行。ThingsBoard 支持多种启动方式，这里介绍最直接的 JAR 包启动法。

3.5.1 核心原理：Spring Boot 可执行 JAR

application/target 目录下生成的 thingsboard-*.jar 是 Spring Boot 的可执行 JAR，内嵌 Tomcat 和所有依赖。启动时会自动加载 application/src/main/resources 下的配置文件，并连接数据库（默认使用 PostgreSQL 或 Cassandra）。

3.5.2 操作流程：启动与验证

# 1. 准备数据库（以 PostgreSQL 为例）
CREATE DATABASE thingsboard;
CREATE USER tb_user WITH PASSWORD 'tb_password';
GRANT ALL PRIVILEGES ON DATABASE thingsboard TO tb_user;

# 2. 修改配置（application/src/main/resources/thingsboard.yml）
# 设置数据库连接信息

# 3. 启动服务
java -jar application/target/thingsboard-3.6.1-boot.jar

# 4. 验证启动成功
# 看到 "Started ThingsboardApplication" 日志
# 浏览器访问 http://localhost:8080
# 默认账号：sysadmin@thingsboard.org / sysadmin

3.6 总结与最佳实践

本章完整覆盖了 ThingsBoard 源码获取、环境配置、编译打包和错误排查的全流程。以下为关键要点总结：