企业官网建设流程全解析

简介：本资源是一份面向物联网开发工程师与系统部署人员的ThingsBoard开源平台新版安装实战指南，聚焦Windows环境下从零部署到成功启动的全流程问题攻坚。文档覆盖JDK11、PostgreSQL12配置、源码拉取、Maven依赖编译（含代理设置、镜像配置、license屏蔽、跳过测试等关键技巧）、数据库初始化及Web UI访问验证等完整环节，并针对46个依赖下载失败、gradle-tooling-api缺失、文件重命名适配等高频报错提供逐条解决方案，实测可覆盖90%以上安装障碍。资源为单个1.96MB Word文档（.doc格式），结构清晰，含环境准备、编译排错、SQL导入、账号登录等模块化内容，便于按需查阅与复现。目前已有308人学习下载，适合希望快速落地ThingsBoard本地开发环境、规避踩坑并掌握企业级IoT平台部署逻辑的中初级开发者。

1. ThingsBoard 新版本地部署：从 JDK 配置到 Web UI 可访问，全程实测踩坑闭环

你不是没试过 ThingsBoard 安装——而是试了三次，每次卡在不同环节：JDK 版本不兼容导致mvn compile直接报Unsupported class file major version 60；PostgreSQL 创建数据库后，install.bat执行到一半抛出FATAL: database "thingsboard" does not exist；更玄学的是，明明mvn clean install -DskipTests成功了，启动run.bat却提示ClassNotFoundException: org.thingsboard.server.ThingsboardServerApplication。这不是你手生，是新版 ThingsBoard（v3.6+）对 Java 生态、Maven 插件链、SQL 初始化顺序的耦合度远超文档描述。本文记录的是某实验室在 Windows 环境下完整复现 v3.6.3 社区版源码编译 + PostgreSQL 启动的全过程，覆盖 JDK 11.0.13 兼容性边界、PostgreSQL 12 权限链路、Maven 依赖劫持修复、SQL 初始化时机控制、以及最关键的——run.bat启动失败的五类根因定位法。适合正在搭建 IoT 平台原型、需要本地调试 Rule Engine 或 Device API 的开发者，也适合被“官方文档写得对但就是跑不通”折磨过的运维同学。

2. 环境筑基：JDK 11.0.13 + PostgreSQL 12 的硬性约束与验证闭环

ThingsBoard v3.6+ 已彻底放弃对 JDK 8 的支持，且对 JDK 11 的小版本有强校验。很多同学用 JDK 11.0.20 或 11.0.22 安装后，mvn编译阶段看似成功，但运行时org.springframework.boot.loader.JarLauncher会因字节码版本不匹配直接崩溃。这不是警告，是 JVM 层面的拒绝加载。必须锁定 JDK 11.0.13 —— 这个版本在 Spring Boot 2.7.x（ThingsBoard v3.6.x 底层依赖）和 Maven Compiler Plugin 3.10.1 之间达成最稳态兼容。

2.1 JDK 11.0.13 安装与环境变量精准配置

下载 OpenJDK 11.0.13（推荐 Adoptium Temurin 构建版，Windows x64 MSI 安装包），安装路径严禁含空格或中文（如C:\Program Files\Java\或D:\开发工具\jdk-11.0.13均会触发 Maven 插件路径解析异常）。建议固定为C:\jdk-11.0.13。

安装完成后，在 CMD 中执行：

java -version

输出必须严格为：

openjdk version "11.0.13" 2021-10-19 OpenJDK Runtime Environment Temurin-11.0.13+8 (build 11.0.13+8) OpenJDK 64-Bit Server VM Temurin-11.0.13+8 (build 11.0.13+8, mixed mode)

注意：若显示11.0.13+8以外的构建号（如+10），说明系统 PATH 中残留旧 JDK。需手动检查echo %PATH%，删除所有含jdk-或jre-的路径，仅保留C:\jdk-11.0.13\bin。

接着配置系统级环境变量：

• JAVA_HOME = C:\jdk-11.0.13
• PATH开头追加%JAVA_HOME%\bin

验证方式：新开一个 CMD 窗口，执行mvn -v，输出中Java version必须为11.0.13。这是后续所有步骤成立的前提，跳过此步等于埋雷。

2.2 PostgreSQL 12 安装与 thingsboard 数据库初始化

ThingsBoard v3.6+ 要求 PostgreSQL ≥ 12，且必须使用postgres超级用户创建数据库。很多教程说“用 pgAdmin 图形界面创建即可”，但实际install.bat脚本内部调用psql时，会以postgres用户身份连接并执行CREATE DATABASE thingsboard ENCODING 'UTF8' LC_COLLATE 'C' LC_CTYPE 'C' TEMPLATE template0;。若数据库非postgres用户创建，或编码/排序规则不一致，初始化脚本将静默失败。

安装 PostgreSQL 12（推荐 EnterpriseDB 官方 Windows Installer），安装过程勾选 “Initialize database cluster” 和 “Install pgAdmin 4”。安装完成后，启动 pgAdmin 4，用默认用户postgres（密码为你安装时设置的）登录 localhost。

在 pgAdmin 中操作：

1. 展开左侧Servers → PostgreSQL 12 → Databases
2. 右键Databases → Create → Database...
3. Database name: 输入thingsboard
4. Owner: 下拉选择postgres
5. Encoding:UTF8
6. Collation:C
7. Character type:C
8. Template:template0

提示：Collation和Character type必须设为C，这是 PostgreSQL 的 POSIX 标准排序，ThingsBoard SQL 脚本中大量使用ORDER BY和DISTINCT ON，若设为en_US.UTF-8会导致init.sql执行时报invalid locale name。

创建完成后，在 pgAdmin 的 Query Tool 中执行验证语句：

SELECT datname, pg_encoding_to_char(encoding), datcollate, datctype FROM pg_database WHERE datname = 'thingsboard';

结果必须为：

这一步验证通过，才代表数据库层已准备好承接 ThingsBoard 的 schema 初始化。

2.3 Node.js 16.x 与 npm 镜像配置（前端构建必需）

ThingsBoard 的 Web UI 是基于 React + TypeScript 构建的，mvn clean install过程中会自动触发npm install和npm run build。Node.js 版本必须为 16.x（v16.20.2 最稳），严禁使用 Node.js 18+—— v18 的 V8 引擎对某些 Webpack 插件（如terser-webpack-plugin）存在兼容问题，会导致npm run build卡死在Generating browser application bundles...。

安装 Node.js 16.20.2 LTS（Windows Installer），安装后执行：

node -v # 必须输出 v16.20.2 npm -v # 必须输出 8.19.2（Node.js 16.20.2 自带）

由于 ThingsBoard 前端依赖大量 GitHub-hosted 包（如@types/react），国内直连极慢甚至超时。需强制切换 npm 镜像：

npm config set registry https://registry.npmmirror.com npm config set @types:registry https://registry.npmmirror.com npm config set disturl https://npmmirror.com/mirrors/node/

验证镜像生效：

npm config get registry # 输出 https://registry.npmmirror.com

注意：不要使用cnpm或yarn替代npm。ThingsBoard 的pom.xml中frontend-maven-plugin插件硬编码调用npm.cmd，若全局安装yarn并修改maven.frontend.plugin的install-node-and-npm配置，会导致mvn install时插件找不到yarn可执行文件而中断。

3. 源码拉取与 Maven 编译：跳过测试、绕过代理、修复依赖劫持

ThingsBoard 官方 GitHub 仓库（https://github.com/thingsboard/thingsboard）主分支为master，但 v3.6.x 稳定版对应release-3.6分支。直接克隆master会导致pom.xml中 Spring Boot 版本与后端模块不匹配，编译报Could not resolve org.springframework.boot:spring-boot-starter-web:3.0.0（v3.6.x 仍基于 Spring Boot 2.7.x）。

3.1 拉取 release-3.6 分支源码并校验完整性

在目标目录（如D:\thingsboard）执行：

git clone -b release-3.6 https://github.com/thingsboard/thingsboard.git cd thingsboard git log -n 1 --oneline

输出应类似：

a1b2c3d (HEAD -> release-3.6, origin/release-3.6) Release ThingsBoard v3.6.3

提示：若git log显示master或提交哈希非v3.6.3tag，请立即执行git fetch origin && git checkout release-3.6 && git pull。很多翻车源于拉了错误分支却未察觉。

3.2 Maven settings.xml 定制：屏蔽 license 检查与代理穿透

ThingsBoard 的pom.xml中启用了license-maven-plugin，该插件会在mvn compile阶段扫描所有 Java 文件头部注释，若缺失 Apache License 2.0 声明则报错中断。这不是代码质量问题，是插件策略。必须禁用。

在D:\thingsboard\pom.xml中定位<plugin>块，找到license-maven-plugin，将其<executions>整个块注释掉：

<!-- <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>license-maven-plugin</artifactId> <version>2.0.0</version> <configuration> ... </configuration> <executions> <execution> <id>add-third-party</id> <goals> <goal>add-third-party</goal> </goals> </execution> <execution> <id>update-file-header</id> <goals> <goal>update-file-header</goal> </goals> </execution> </executions> </plugin> -->

若你所在网络需走公司代理才能访问 Maven Central，需在settings.xml中配置 proxy。但 ThingsBoard 依赖大量 GitHub Releases（如hikari-cp、netty），这些地址常被代理拦截。更稳妥的做法是：在settings.xml中为 GitHub 域名显式排除代理。

创建D:\A_rj\maven-3.6.3\conf\thingsboardSettings.xml，内容如下：

<?xml version="1.0" encoding="UTF-8"?> <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> <proxies> <proxy> <id>company-proxy</id> <active>true</active> <protocol>http</protocol> <host>proxy.internal</host> <port>8080</port> <nonProxyHosts>github.com|githubusercontent.com|repo1.maven.org</nonProxyHosts> </proxy> </proxies> </settings>

<nonProxyHosts>是关键：它确保github.com和githubusercontent.com的请求直连，避免代理层 DNS 解析失败或 TLS 握手超时。

3.3 Maven 编译命令与依赖修复四步法

执行编译前，确保当前目录为D:\thingsboard（即pom.xml所在目录）。绝对不要在子模块目录（如application/）下执行mvn，否则会因 parent POM 路径错误导致Could not find artifact org.thingsboard:thingsboard:pom:3.6.3。

标准编译命令（跳过测试、指定 settings）：

mvn clean install -DskipTests --settings D:\A_rj\maven-3.6.3\conf\thingsboardSettings.xml

该命令预期耗时 15–25 分钟（取决于 CPU 和磁盘 I/O）。若中途失败，按以下四步法排查：

步骤一：定位失败模块与报错关键词

Maven 日志末尾会显示Failed to execute goal ...，记下artifactId（如transport-mqtt）和error message（如Could not transfer artifact org.eclipse.paho:org.eclipse.paho.client.mqttv3:pom:1.2.5）。

步骤二：手动下载缺失 JAR 并安装到本地仓库

以org.eclipse.paho:org.eclipse.paho.client.mqttv3:1.2.5为例：

• 访问 https://repo1.maven.org/maven2/org/eclipse/paho/org.eclipse.paho.client.mqttv3/1.2.5/
• 下载org.eclipse.paho.client.mqttv3-1.2.5.jar和org.eclipse.paho.client.mqttv3-1.2.5.pom
• 在 CMD 中执行：

mvn install:install-file -Dfile=org.eclipse.paho.client.mqttv3-1.2.5.jar -DpomFile=org.eclipse.paho.client.mqttv3-1.2.5.pom

步骤三：修复 gradle-tooling-api 6.3 依赖劫持

若报错含gradle-tooling-api:6.3，说明maven-invoker-plugin（用于集成测试）尝试下载 Gradle SDK，但该版本已被 Gradle 官方归档。解决方案：手动下载gradle-tooling-api-6.3.jar，并安装：

# 下载地址（备用）：https://repo1.maven.org/maven2/org/gradle/gradle-tooling-api/6.3/gradle-tooling-api-6.3.jar mvn install:install-file -Dfile=gradle-tooling-api-6.3.jar -DgroupId=org.gradle -DartifactId=gradle-tooling-api -Dversion=6.3 -Dpackaging=jar

步骤四：强制更新快照依赖

若报错为Could not find artifact ...:3.6.3-SNAPSHOT，说明本地仓库存在损坏的 SNAPSHOT 包。执行：

mvn clean install -DskipTests -U --settings D:\A_rj\maven-3.6.3\conf\thingsboardSettings.xml

-U参数强制更新所有快照依赖。

血泪经验：90% 的mvn install失败源于transport-coap或transport-lwm2m模块的org.eclipse.californium:californium-core依赖下载失败。该包体积大（>10MB），且 Maven 默认连接超时仅 30 秒。解决方法是：在settings.xml的<mirrors>中添加阿里云镜像，并增大超时：

<mirrors> <mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>Aliyun Maven</name> <url>https://maven.aliyun.com/repository/public</url> </mirror> </mirrors> <profiles> <profile> <id>default</id> <activation><activeByDefault>true</activeByDefault></activation> <properties> <maven.wagon.httpconnectionManager.maxPerRoute>10</maven.wagon.httpconnectionManager.maxPerRoute> <maven.wagon.httpconnectionManager.maxTotal>20</maven.wagon.httpconnectionManager.maxTotal> <maven.wagon.http.timeout>60000</maven.wagon.http.timeout> <maven.wagon.http.connectionTimeout>60000</maven.wagon.http.connectionTimeout> </properties> </profile> </profiles>

4. 数据库初始化与启动排障：SQL 脚本执行时机与 run.bat 黑匣子解析

mvn clean install -DskipTests成功后，application/target/thingsboard-3.6.3.jar已生成，但此时直接运行run.bat会报FATAL: database "thingsboard" does not exist或relation "admin_settings" does not exist。这是因为 ThingsBoard 的 schema 初始化并非由 JAR 自动触发，而是依赖外部 SQL 脚本，且执行顺序有严格要求。

4.1 使用 install.bat 执行 SQL 初始化（非 run.bat）

进入D:\thingsboard\application\target\classes目录，此处有install.bat和run.bat。必须先运行install.bat，再运行run.bat。

install.bat的核心逻辑是：

1. 读取thingsboard.yml中的spring.datasource配置（默认指向localhost:5432/thingsboard）
2. 调用psql命令，以postgres用户身份连接数据库
3. 依次执行schema.sql（建表）、system-data.sql（插入 admin 用户）、upgrade/3.6.0.sql（v3.6.0 特有字段）

若install.bat报错，首先检查：

• psql.exe是否在系统 PATH 中？PostgreSQL 安装时默认勾选 “Add to PATH”，若未勾选，需手动将C:\Program Files\PostgreSQL\12\bin加入 PATH。
• thingsboard.yml中spring.datasource.username是否为postgres？默认是postgres，但若你修改过，需确保该用户对thingsboard数据库有CREATE权限。

4.2 手动执行 SQL 脚本的兜底方案

若install.bat因权限或路径问题失败，可手动执行：

1. 将D:\thingsboard\application\src\main\resources\sql目录下的schema.sql、system-data.sql复制到C:\temp\
2. 在 pgAdmin 的 Query Tool 中，连接thingsboard数据库，依次粘贴执行这两个文件内容（注意：schema.sql必须先于system-data.sql）
3. 若执行system-data.sql报duplicate key value violates unique constraint "admin_settings_pkey"，说明admin_settings表已存在数据，跳过该 INSERT 即可（不影响启动）

4.3 run.bat 启动失败的五大根因与定位法

run.bat启动后黑窗口闪退或日志停在Starting ThingsboardServerApplication on ...无后续，常见原因如下：

避坑总结：run.bat不是黑匣子。它的本质是java -Dloader.path=lib -Dspring.config.location=classpath:/thingsboard.yml -jar thingsboard-3.6.3.jar。若启动失败，直接在 CMD 中执行该命令，能捕获更详细的堆栈。例如，若报java.lang.OutOfMemoryError: Java heap space，则需在run.bat中修改JAVA_OPTS：

set JAVA_OPTS=-Xms512M -Xmx1024M -XX:MaxMetaspaceSize=256M

5. Web UI 访问与账户体系验证：从 sysadmin 登录到设备接入全流程

run.bat启动成功后，CMD 窗口会持续滚动日志，最终出现Started ThingsboardServerApplication in X.XXX seconds。此时打开浏览器访问http://localhost:8080，应看到 ThingsBoard 登录页。若页面空白或加载失败，99% 是前端资源未就位。

5.1 验证前端静态资源是否加载成功

ThingsBoard 的 Web UI 资源位于application\target\classes\static目录。该目录下必须包含：

• index.html
• main.*.js（Webpack 打包后的主 JS）
• runtime.*.js
• styles.*.css

若static目录为空或只有index.html，说明ui-ngx模块未构建。此时：

1. 进入D:\thingsboard\ui-ngx
2. 执行npm install（确保 node_modules 完整）
3. 执行npm run build（耗时约 8–12 分钟，CPU 占用高属正常）
4. 构建成功后，ui-ngx\dist内容会自动同步至application\target\classes\static

提示：npm run build若卡在Generating ES5 bundles for differential loading...，是 Angular CLI 默认启用--aot导致。可临时改为npm run build -- --prod --aot=false加速，但生产环境务必开启 AOT。

5.2 三类预置账户登录与权限边界

ThingsBoard v3.6.3 预置三套账户，其权限模型是 Tenant-Based 的典型设计：

登录sysadmin@thingsboard.org后，首先进入System Settings → Tenants，点击+创建新租户（如DemoTenant）。创建成功后，tenant@thingsboard.org即可登录并看到该租户。

5.3 设备接入验证：MQTT Publish/Subscribe 全链路测试

ThingsBoard 的核心价值在于设备接入。以最简 MQTT 方式验证：

1. 使用 MQTT 客户端（如 MQTTX 或mosquitto_pub）连接localhost:1883
2. 发布消息到v1/devices/me/telemetry，Payload 为 JSON：

{"temperature": 25.6, "humidity": 60}

3. 登录tenant@thingsboard.org，进入Devices → All，找到设备Device A（默认名称），点击进入详情页
4. 切换到Latest telemetry标签，应实时显示temperature和humidity的最新值

若 telemetry 无数据：

• 检查thingsboard.yml中mqtt.bind_address是否为0.0.0.0（而非127.0.0.1），否则外部客户端无法连接
• 检查 Windows 防火墙是否阻止了 1883 端口（临时关闭防火墙测试）
• 在 ThingsBoard 日志中搜索MQTT transport started，确认 MQTT 服务已启动

进阶技巧：Rule Chain 调试
在tenant视角下，进入Rule Chains → Root rule chain，点击任意节点（如Save Timeseries），右侧Debug开关设为ON。此时设备上报数据，日志中会输出DEBUG: RuleChain [Root rule chain] processed message...，可直观看到数据流经每个节点的耗时与结果。这是排查规则链逻辑错误的后悔药。

从那以后我每次部署 ThingsBoard，都强制走一遍「JDK 版本验证 → PostgreSQL 数据库编码检查 →install.bat手动执行 →run.bat命令行直启捕获堆栈」四步闭环。哪怕多花 10 分钟，也比在ClassNotFoundException里反复重装 Maven 仓库强。希望帮到你。

本文还有配套的精品资源，点击获取