4. 单机部署-源码编译：从 GitHub 克隆 ThingsBoard 源码、Maven 编译打包、构建产物说明
在生产环境或定制化需求场景下，直接使用官方预编译包往往无法满足特定功能修改或二次开发的需要。本章节将详细讲解从 GitHub 克隆 ThingsBoard 源码、使用 Maven 进行编译打包，以及最终构建产物的结构说明。掌握这一流程是后续进行单机部署、集群扩展及源码级调试的基础。
4.1 环境准备与前置依赖
在开始编译前，请确保你的构建环境满足以下最低要求。建议使用 Linux 或 macOS 系统，Windows 环境下需额外配置 WSL 或 Cygwin。
| 依赖项 | 版本要求 | 说明 |
|---|---|---|
| Java JDK | 11 (推荐 OpenJDK 11.0.x) | ThingsBoard 3.x 系列强制要求 JDK 11 |
| Apache Maven | 3.6.3 及以上 | 用于项目构建与依赖管理 |
| Git | 2.x | 用于克隆源码仓库 |
| Node.js & npm | Node 12.x / npm 6.x | 用于编译前端 UI 模块 |
| 磁盘空间 | 至少 10 GB 空闲 | 包含依赖下载与构建缓存 |
版本兼容性提示： 如果你计划部署 ThingsBoard 3.4 及以上版本，请务必使用 JDK 11。JDK 8 已不再被官方支持，强行使用会导致编译失败或运行时异常。
4.2 从 GitHub 克隆源码
ThingsBoard 官方仓库托管在 GitHub 上。我们使用 git clone 命令获取最新稳定分支的源码。建议克隆 release-3.x 分支而非 master 分支，以确保代码的稳定性。
# 克隆主仓库（以 release-3.5 为例）
git clone -b release-3.5 https://github.com/thingsboard/thingsboard.git
cd thingsboard
# 查看分支确认
git branch -a克隆完成后，项目目录结构如下（仅列出核心模块）：
- application/ — 主应用模块，包含核心业务逻辑与 REST API
- common/ — 公共工具类与数据模型
- dao/ — 数据访问层，封装数据库与消息队列操作
- rule-engine/ — 规则引擎模块
- transport/ — 协议适配层（MQTT、HTTP、CoAP）
- ui-ngx/ — 基于 Angular 的前端工程
- msa/ — 微服务架构相关配置与启动器
4.3 Maven 编译打包流程
ThingsBoard 采用 Maven 多模块构建。编译过程分为两个主要阶段：先编译后端 Java 代码，再编译前端 Angular 应用。我们使用 mvn clean install 命令一次性完成全量构建。
网络与内存注意： 首次编译需要下载大量 Maven 依赖（约 2-3 GB），请确保网络稳定。同时建议为 Maven 分配至少 2 GB 堆内存，避免构建过程中 OOM。
# 执行全量编译（跳过单元测试以加快速度）
mvn clean install -DskipTests -Dnpm.test.script=build:prod
# 如果只需要后端 jar 包，可以只编译 application 模块
mvn clean install -pl application -am -DskipTests编译过程中的关键参数说明：
| 参数 | 作用 |
|---|---|
-DskipTests |
跳过单元测试执行，大幅缩短编译时间 |
-Dnpm.test.script=build:prod |
指定前端构建模式为生产环境（压缩混淆） |
-pl application -am |
仅编译 application 模块及其依赖模块 |
-T 4 |
启用 4 线程并行编译（可选，加速多核机器） |
4.4 构建产物说明
编译成功后，核心产物位于 application/target/ 目录下。以下是主要产物的用途说明：
| 产物文件 | 类型 | 说明 |
|---|---|---|
thingsboard-3.5.1-boot.jar |
可执行 JAR | Spring Boot 打包的独立运行包，包含内嵌 Tomcat |
thingsboard-3.5.1.jar |
普通 JAR | 不含内嵌容器的标准 jar，用于外部容器部署 |
thingsboard-3.5.1.war |
WAR 包 | 适用于传统 Servlet 容器（如 Tomcat 外部部署） |
pom.xml |
构建描述 | 模块的 Maven 构建配置 |
推荐使用 boot JAR： 在单机部署场景下，
thingsboard-*-boot.jar 是最便捷的选择。它内嵌了 Tomcat 和所有依赖，只需一条 java -jar 命令即可启动，无需额外配置外部容器。
4.5 编译流程可视化
下图展示了从源码克隆到最终产物的完整编译流程，帮助理解各阶段的任务与产出关系。
4.6 常见编译问题与解决方案
在编译过程中，开发者常遇到以下几类问题。提前了解可有效缩短排错时间。
- Maven 依赖下载失败： 检查 settings.xml 中的镜像配置，建议使用阿里云 Maven 镜像（
https://maven.aliyun.com/repository/public）。 - 前端编译报错（Node 版本不兼容）： ThingsBoard 3.x 要求 Node 12.x，使用
nvm切换版本。 - 内存溢出（OutOfMemoryError）： 在 MAVEN_OPTS 中增加
-Xmx2048m参数。 - 测试用例失败： 使用
-DskipTests跳过测试阶段，后续单独调试。
加速编译小技巧： 在
~/.m2/settings.xml 中配置 <parallel>true</parallel> 并增加 -T 4 参数，利用多核 CPU 并行编译，可节省 30%-50% 的编译时间。
4.7 验证编译结果
编译完成后，通过以下命令验证产物是否完整：
# 检查 boot JAR 是否存在
ls -lh application/target/thingsboard-*-boot.jar
# 查看 JAR 包内嵌的版本信息
java -jar application/target/thingsboard-*-boot.jar --version
# 快速启动验证（使用默认内存配置）
java -Xmx512m -jar application/target/thingsboard-*-boot.jar如果控制台输出 ThingsBoard 启动日志且无异常堆栈，则说明编译成功，产物可正常使用。