简介本资源是一份面向物联网开发工程师与系统部署人员的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 60PostgreSQL 创建数据库后install.bat执行到一半抛出FATAL: database thingsboard does not exist更玄学的是明明mvn clean install -DskipTests成功了启动run.bat却提示ClassNotFoundException: org.thingsboard.server.ThingsboardServerApplication。这不是你手生是新版 ThingsBoardv3.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.xThingsBoard 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.138 (build 11.0.138) OpenJDK 64-Bit Server VM Temurin-11.0.138 (build 11.0.138, mixed mode)注意若显示11.0.138以外的构建号如10说明系统 PATH 中残留旧 JDK。需手动检查echo %PATH%删除所有含jdk-或jre-的路径仅保留C:\jdk-11.0.13\bin。接着配置系统级环境变量JAVA_HOME C:\jdk-11.0.13PATH开头追加%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 中操作展开左侧Servers → PostgreSQL 12 → Databases右键Databases → Create → Database...Database name: 输入thingsboardOwner: 下拉选择postgresEncoding:UTF8Collation:CCharacter type:CTemplate: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;结果必须为datnamepg_encoding_to_chardatcollatedatctypethingsboardUTF8CC这一步验证通过才代表数据库层已准备好承接 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.xv16.20.2 最稳严禁使用 Node.js 18—— v18 的 V8 引擎对某些 Webpack 插件如terser-webpack-plugin存在兼容问题会导致npm run build卡死在Generating browser application bundles...。安装 Node.js 16.20.2 LTSWindows Installer安装后执行node -v # 必须输出 v16.20.2 npm -v # 必须输出 8.19.2Node.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.0v3.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 groupIdorg.codehaus.mojo/groupId artifactIdlicense-maven-plugin/artifactId version2.0.0/version configuration ... /configuration executions execution idadd-third-party/id goals goaladd-third-party/goal /goals /execution execution idupdate-file-header/id goals goalupdate-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 version1.0 encodingUTF-8? settings xmlnshttp://maven.apache.org/SETTINGS/1.0.0 xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd proxies proxy idcompany-proxy/id activetrue/active protocolhttp/protocol hostproxy.internal/host port8080/port nonProxyHostsgithub.com|githubusercontent.com|repo1.maven.org/nonProxyHosts /proxy /proxies /settingsnonProxyHosts是关键它确保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。标准编译命令跳过测试、指定 settingsmvn 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 -Dfileorg.eclipse.paho.client.mqttv3-1.2.5.jar -DpomFileorg.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 -Dfilegradle-tooling-api-6.3.jar -DgroupIdorg.gradle -DartifactIdgradle-tooling-api -Dversion6.3 -Dpackagingjar步骤四强制更新快照依赖若报错为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 idaliyunmaven/id mirrorOf*/mirrorOf nameAliyun Maven/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors profiles profile iddefault/id activationactiveByDefaulttrue/activeByDefault/activation properties maven.wagon.httpconnectionManager.maxPerRoute10/maven.wagon.httpconnectionManager.maxPerRoute maven.wagon.httpconnectionManager.maxTotal20/maven.wagon.httpconnectionManager.maxTotal maven.wagon.http.timeout60000/maven.wagon.http.timeout maven.wagon.http.connectionTimeout60000/maven.wagon.http.connectionTimeout /properties /profile /profiles4. 数据库初始化与启动排障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的核心逻辑是读取thingsboard.yml中的spring.datasource配置默认指向localhost:5432/thingsboard调用psql命令以postgres用户身份连接数据库依次执行schema.sql建表、system-data.sql插入 admin 用户、upgrade/3.6.0.sqlv3.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因权限或路径问题失败可手动执行将D:\thingsboard\application\src\main\resources\sql目录下的schema.sql、system-data.sql复制到C:\temp\在 pgAdmin 的 Query Tool 中连接thingsboard数据库依次粘贴执行这两个文件内容注意schema.sql必须先于system-data.sql若执行system-data.sql报duplicate key value violates unique constraint admin_settings_pkey说明admin_settings表已存在数据跳过该 INSERT 即可不影响启动4.3 run.bat 启动失败的五大根因与定位法run.bat启动后黑窗口闪退或日志停在Starting ThingsboardServerApplication on ...无后续常见原因如下现象原因解决控制台输出Error: Could not find or load main class org.thingsboard.server.ThingsboardServerApplicationthingsboard-3.6.3.jar未正确打包或MANIFEST.MF中Main-Class缺失重新执行mvn clean install -DskipTests检查application\target\thingsboard-3.6.3.jar是否 120MB用jar -tf thingsboard-3.6.3.jar | findstr MANIFEST确认META-INF/MANIFEST.MF存在日志卡在Loading XML bean definitions from class path resource [spring/datasource-config.xml]thingsboard.yml中spring.datasource.url的数据库名写错如thingboard少个s或username/password错误检查application\target\classes\thingsboard.yml确认url: jdbc:postgresql://localhost:5432/thingsboard和username: postgres、password: your_password三者完全匹配 pgAdmin 中设置启动后访问http://localhost:8080返回 404Web UI 未构建成功application\target\classes\static目录为空进入D:\thingsboard\ui-ngx目录执行npm install npm run build构建完成后ui-ngx\dist内容会自动拷贝至application\target\classes\static日志报Caused by: java.lang.NoClassDefFoundError: com/fasterxml/jackson/databind/JsonSerializerMaven 依赖冲突jackson-databind版本被其他模块覆盖在pom.xml的dependencyManagement中强制指定version2.13.4.2/versionThingsBoard v3.6.3 兼容版本启动后 CPU 占用 100%日志无错误PostgreSQL 连接池未释放HikariCP配置不当修改thingsboard.yml中spring.datasource.hikari.maximum-pool-size: 5默认 20Windows 2G 内存机器易撑爆避坑总结run.bat不是黑匣子。它的本质是java -Dloader.pathlib -Dspring.config.locationclasspath:/thingsboard.yml -jar thingsboard-3.6.3.jar。若启动失败直接在 CMD 中执行该命令能捕获更详细的堆栈。例如若报java.lang.OutOfMemoryError: Java heap space则需在run.bat中修改JAVA_OPTSset JAVA_OPTS-Xms512M -Xmx1024M -XX:MaxMetaspaceSize256M5. 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.htmlmain.*.jsWebpack 打包后的主 JSruntime.*.jsstyles.*.css若static目录为空或只有index.html说明ui-ngx模块未构建。此时进入D:\thingsboard\ui-ngx执行npm install确保 node_modules 完整执行npm run build耗时约 8–12 分钟CPU 占用高属正常构建成功后ui-ngx\dist内容会自动同步至application\target\classes\static提示npm run build若卡在Generating ES5 bundles for differential loading...是 Angular CLI 默认启用--aot导致。可临时改为npm run build -- --prod --aotfalse加速但生产环境务必开启 AOT。5.2 三类预置账户登录与权限边界ThingsBoard v3.6.3 预置三套账户其权限模型是 Tenant-Based 的典型设计账户类型用户名密码权限范围典型用途系统管理员sysadminthingsboard.orgsysadmin全局管理创建租户、查看所有租户数据、管理系统设置初始配置、租户分发租户管理员tenantthingsboard.orgtenant仅管理本租户创建客户、设备、规则链、仪表盘SaaS 多租户场景下租户 IT 人员使用客户customerthingsboard.orgcustomer仅查看分配给自己的设备和仪表盘不可编辑规则链终端客户查看自身设备状态登录sysadminthingsboard.org后首先进入System Settings → Tenants点击创建新租户如DemoTenant。创建成功后tenantthingsboard.org即可登录并看到该租户。5.3 设备接入验证MQTT Publish/Subscribe 全链路测试ThingsBoard 的核心价值在于设备接入。以最简 MQTT 方式验证使用 MQTT 客户端如 MQTTX 或mosquitto_pub连接localhost:1883发布消息到v1/devices/me/telemetryPayload 为 JSON{temperature: 25.6, humidity: 60}登录tenantthingsboard.org进入Devices → All找到设备Device A默认名称点击进入详情页切换到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 仓库强。希望帮到你。本文还有配套的精品资源点击获取
 - @EventListener注解探究)
