Windows上源码编译安装ThingsBoard

上一篇 Windows上安装ThingsBoard 讲的是官方安装包：适合只想用平台、不做二次开发的同学。

如果你是后端开发，想看源码、改 Logo、做二开，就需要掌握本篇：本地拉取源码 → Maven 编译 → IDEA 初始化库表 → 启动服务。

示例环境与专栏 版本与环境对应 对齐：ThingsBoard 源码（建议 4.2 / 4.3 线）+ JDK 17 + Maven 3.6.3 + PostgreSQL 16 + IntelliJ IDEA 2022.3.3+（建议 2023.2+）。
官方构建说明见：Building from source。

和安装包方式怎么选

方式	适合谁	是否需要 Maven / IDEA
Windows 安装包	使用、演示、快速体验	否
本文：源码编译	读源码、二开、改前端/规则等	是

若第一篇已装好 JDK 17 和 PostgreSQL（含库 thingsboard），本篇对应章节可跳过，从 Git / Maven 继续。

1. 前端环境要不要装？

ThingsBoard 源码是前后端一体，前端在 ui-ngx（Angular）。

很多人会去装 Node、Yarn、改版本——源码编译场景下通常不需要手动装前端环境。工程通过 Maven 插件 frontend-maven-plugin 在编译时自动下载 Node / Yarn。

结论：本机不必单独装 Node / npm / Yarn；但编译时需要能访问外网（很多人需要代理 /「梯子」，且最好是系统级代理）。

2. 安装 Git

后续要用 Git 克隆仓库。Windows 安装可参考：菜鸟教程 - Git 安装。

1. 打开官方下载页：https://git-scm.com/install/windows

2. 点击 Click here to download，双击安装包，一路 Next 即可。

安装后可在命令行验证：

git --version

3. 安装 JDK 17

源码编译（4.2 / 4.3 线）需要 JDK 17。推荐 Eclipse Temurin 等官方发行版。

若你已按 第一篇 · 安装 JDK 17 完成，可直接验证：

java --version

看到 Java 17 相关信息即通过。详细安装截图步骤见第一篇，此处不重复展开。

ThingsBoard 4.4 需要 Java 25，并建议 IDEA 2025.2+，见 专栏导读版本表。本篇按 4.2/4.3 + JDK 17 编写。

4. 安装 Maven（源码必做）

本篇示例使用 Maven 3.6.3（官方要求 ≥ 3.1.0，贡献文档常写 ≥ 3.6，与专栏导读一致）。

4.1 下载与解压

下载页：

https://archive.apache.org/dist/maven/maven-3/3.6.3/binaries/

下载 apache-maven-3.6.3-bin.zip 后解压，放到统一目录（示例：D:\yuxinwei\java\apache-maven-3.6.3）。

4.2 本地仓库目录

在同级再建 repository 目录，用于存放下载的依赖（示例：D:\yuxinwei\java\repository）。

编辑 conf\settings.xml，配置 <localRepository> 指向该路径：

<localRepository>D:/yuxinwei/java/repository</localRepository>

4.3 配置 PATH

把 Maven 的 bin 目录加入系统环境变量 Path，例如：

D:\yuxinwei\java\apache-maven-3.6.3\bin

操作路径：此电脑 → 属性 → 高级系统设置 → 环境变量 → 系统变量 Path → 新建 → 粘贴上述路径 → 确定。

4.4 验证

新开一个 cmd 窗口：

mvn -v

能显示 Maven 与 Java 版本即成功。

5. 安装 PostgreSQL 并建库

数据库步骤与第一篇相同。若已完成可跳过；否则请按 第一篇 · PostgreSQL 安装，并用 pgAdmin 创建库：

thingsboard

要点回顾：

项	建议
版本	PostgreSQL 16（示例）
用户	postgres
密码	学习环境可先用 postgres（生产请用强密码）
端口	默认 5432；冲突可改 5433，后面 yml 必须一致
库名	thingsboard

下载页：https://www.enterprisedb.com/downloads/postgres-postgresql-downloads
安装参考：https://www.runoob.com/postgresql/windows-install-postgresql.html

6. 拉取 ThingsBoard 源码

官方构建文档：https://thingsboard.io/docs/user-guide/install/building-from-source/

1. 在本地建一个工程目录（示例：D:\yuxinwei\AE\project）。

2. 在资源管理器地址栏输入 cmd 回车，进入该目录命令行。

3. 确认 Git 可用后克隆（可指定分支 / tag，如 release-4.3 或具体 tag，按你目标版本调整）：

git --version
git clone https://github.com/thingsboard/thingsboard.git

克隆与后续编译都可能需要稳定外网；部分网络环境下需要代理。

7. 编译安装

进入源码根目录（含根 pom.xml 的目录），同样可用地址栏 cmd 打开终端。

先确认环境：

java --version
mvn -v

执行（跳过测试，加快首次编译）：

mvn clean install -DskipTests

• 首次会下载大量依赖，并自动拉 Node / Yarn 构建前端，耗时可很长，请保持网络畅通。
• 看到整体 BUILD SUCCESS 即编译成功。

8. 用 IDEA 打开工程并初始化

8.1 IDEA 与插件

• 请使用 IntelliJ IDEA 2022.3.3 及以上（对齐 JDK 17；更推荐专栏导读中的 2023.2+）。
• 安装插件：Lombok、Protocol Buffers（Protobuf）。

8.2 指定 JDK 与 Maven

在 IDEA 中为项目指定 JDK 17，并指向你本机 Maven 与 settings.xml / 本地仓库。

8.3 修改 thingsboard.yml 数据源

在工程中找到 thingsboard.yml（可用全局搜索）。

Ctrl + F 搜索 jpa / datasource，将连接改为与本机 PostgreSQL 一致，例如：

url: jdbc:postgresql://localhost:5432/thingsboard
username: postgres
password: postgres

• localhost:5432：本机地址与端口（改过端口要同步改）
• /thingsboard：pgAdmin 中的库名
• 用户名 / 密码：与安装 PostgreSQL 时一致

8.4 拷贝初始化脚本到 application/data

将 dao 模块下的数据库初始化相关脚本，拷贝到 application 模块的 src/main/data（或文档截图所示的 data 目录）下，保证安装程序能找到 schema / 演示数据文件。

不同小版本目录细节可能略有差异，以你当前分支仓库结构为准；原则是：Install 启动类能读到 data 目录中的脚本。

8.5 运行 ThingsboardInstallApplication

找到启动类 ThingsboardInstallApplication，点击绿色运行。

若提示启用 Lombok，按提示开启。

若提示 Shorten the command line：

1. Edit Configurations → Modify options → 勾选 Shorten command line
2. 选择 JAR manifest
3. Apply → OK

再配置 Environment variables。先对 application 下的 data 目录 Copy Path / Absolute Path，拼成（路径改成你的绝对路径）：

install.data_dir=D:\yuxinwei\AE\project\thingsboard\application\src\main\data;install.load_demo=true

• install.data_dir：data 目录绝对路径
• install.load_demo=true：加载演示数据（不需要可改为 false）

粘贴到 Environment variables → Apply → OK，再次运行 Install。

初始化失败时

若报错，可尝试：

1. 在 pgAdmin 中删除库 thingsboard 后重建同名空库。
2. 在 IDEA Terminal 执行：

mvn spring-boot:build-info

看到 BUILD SUCCESS 后，再重新运行 ThingsboardInstallApplication。

Install 启动类只需在安装 / 重建库时跑一次；日常开发启动用下一节的 Server 类。

9. 启动服务

使用启动类 ThingsboardServerApplication。

同样可能需要：

• Shorten command line → JAR manifest
• Environment variables（可与 Install 相同的 install.data_dir / install.load_demo 配置，按你工程需要保留）

install.data_dir=D:\yuxinwei\AE\project\thingsboard\application\src\main\data;install.load_demo=true

启动后日志出现服务就绪相关输出，即表示启动成功。

10. 访问 Web

默认端口 8080。请确认防火墙放行，浏览器打开：

http://localhost:8080

加载了 demo 时，常用默认账号（登录后请立刻改密）：

角色	邮箱	密码
系统管理员	sysadmin@thingsboard.org	sysadmin
租户管理员	tenant@thingsboard.org	tenant

系统管理员管理租户；租户可理解为「子公司」空间。可在租户列表中查看 / 跳转到租户管理员。

11. 用 MQTTX 模拟上报（验收）

1. 在设备管理中创建测试设备。

2. 安装 MQTTX，新建客户端。

3. 复制设备 Access Token，填到 MQTT 连接的 Username（ThingsBoard Token 认证常见用法），Host 用本机，端口默认 1883。

4. 连接成功后，在 ThingsBoard 刷新设备，应显示在线；再向设备遥测 Topic 发布 JSON，在 Latest telemetry 中确认入库。

Topic / Payload 细节可继续对照官方文档：MQTT Device API。

12. 小结与排错

步骤	关键点
前端	一般不手动装 Node；靠 frontend-maven-plugin
Git / JDK / Maven / PG	源码路径必备；JDK/PG 可复用第一篇
编译	mvn clean install -DskipTests，需外网
IDEA	Lombok + Protobuf；JDK17；缩短命令行
初始化	ThingsboardInstallApplication + install.data_dir
日常启动	ThingsboardServerApplication
验收	http://localhost:8080 + MQTTX

常见问题：

现象	处理
编译卡在前端 / 依赖下载失败	检查代理是否全局、DNS、重试 Maven
Install 失败	重建空库 thingsboard；执行 mvn spring-boot:build-info 后重跑
命令行过长	Shorten command line → JAR manifest
8080 打不开	看 Server 是否起来、防火墙、端口占用（第一篇有同类排查）
设备不上线	Token、1883、Username 是否填 Token

下一步

• 若只需安装包方式，见：Windows上安装ThingsBoard
• 回到 专栏导读 核对版本表后再升级大版本