简介本资源是一份面向物联网开发者与系统部署工程师的新版ThingsBoard本地安装实战指南专为Windows平台Win7/8/8.1/10用户定制聚焦解决实际部署中高频出现的环境配置、依赖编译失败、数据库初始化及启动异常等90%以上典型问题。文档以图文并茂形式完整记录作者亲测安装全过程涵盖JDK 11配置、PostgreSQL 12建库、源码拉取、Node.js与Maven环境调优、gradle-tooling-api手动注入、SQL脚本导入及默认账号登录等关键环节并提供详细排错路径与绕过方案。资源为单个Word文档.doc格式体积1.96MB结构清晰、步骤可复现便于快速查阅与实操对照。目前已有473人学习下载适合具备基础Java和数据库知识的中级开发者用于私有化部署验证或教学环境搭建。1. 新版 ThingsBoard 安装不是“照着文档就行”而是 JDK11、PostgreSQL12、Node.js 与 Maven 四要素协同生效的系统工程很多人点开新版 ThingsBoard 官方安装文档第一反应是“不就是下载、解压、改配置、启动吗”——结果卡在java.lang.UnsupportedClassVersionError或Failed to initialize PostgreSQL schema或npm install fails with node:util export error。根本原因在于ThingsBoard 3.7 已强制要求 JDK11非 JDK8 或 JDK17其后端编译依赖 Maven 构建链前端构建依赖 Node.js 16–18非 v20而数据库必须是 PostgreSQL 12 或 13PostgreSQL 15 会触发pg_catalog.pg_type元数据兼容性报错。这不是单点安装而是四组件版本对齐的校验过程。本文面向已在 Linux 或 Windows 上部署过旧版 ThingsBoard 的运维/开发人员也覆盖首次接触 IoT 平台的嵌入式工程师——你不需要懂 Spring Boot 源码但必须清楚每个组件在 ThingsBoard 启动流程中的不可替代角色JDK11 提供运行时字节码兼容性PostgreSQL12 承载设备元数据与遥测历史Node.js 编译前端资源tb-web-uiMaven 则负责将thingsboard-server模块打包为可执行 JAR 并注入数据库初始化脚本。所有步骤均基于 Ubuntu 22.04 / Windows 10 实测验证跳过官网模糊表述直击参数级配置。2. JDK11 与 PostgreSQL12ThingsBoard 运行时的双基石配置ThingsBoard 3.7 的类文件主版本号为 55对应 JDK11若使用 JDK17主版本号 61会导致UnsupportedClassVersionError若使用 JDK8主版本号 52则因缺少var关键字和HttpClient等 API 报编译失败。PostgreSQL 方面官方文档未明确标注最低兼容版本但实测 PostgreSQL 12.17 是稳定边界——15.x 中pg_type.typcategory字段类型变更导致 ThingsBoard 初始化脚本create_schema.sql中的CASE WHEN typcategory B查询失败。因此必须严格锁定这两个组件的版本。2.1 在 Ubuntu 22.04 上安装并锁定 JDK11Ubuntu 22.04 默认源提供的是 OpenJDK 11.0.22但需确认是否为11.0.227LTS 版本。执行以下命令验证并安装# 卸载可能存在的其他 JDK sudo apt remove --purge openjdk-* -y # 添加官方仓库并安装 OpenJDK 11 sudo apt update sudo apt install -y openjdk-11-jdk-headless # 验证版本输出应为 11.0.22 java -version注意openjdk-11-jdk-headless不含 AWT/Swing GUI 组件节省内存且符合 ThingsBoard 无界面服务需求若误装openjdk-11-jdk需手动清理/usr/lib/jvm/java-11-openjdk-amd64/jre/lib/ext/下冗余 jar 包否则可能触发NoClassDefFoundError: javax/xml/bind/annotation/XmlSchema。2.1.1 设置 JAVA_HOME 并验证环境变量ThingsBoard 启动脚本run.sh依赖JAVA_HOME指向 JDK 根目录而非 JRE。执行# 查找 JDK 安装路径通常为 /usr/lib/jvm/java-11-openjdk-amd64 sudo update-alternatives --config java # 输出示例/usr/lib/jvm/java-11-openjdk-amd64/bin/java → 复制路径前缀 export JAVA_HOME/usr/lib/jvm/java-11-openjdk-amd64 echo export JAVA_HOME/usr/lib/jvm/java-11-openjdk-amd64 | sudo tee -a /etc/profile source /etc/profile echo $JAVA_HOME # 应输出 /usr/lib/jvm/java-11-openjdk-amd642.2 安装 PostgreSQL 12 并初始化 ThingsBoard 数据库Ubuntu 22.04 默认源提供 PostgreSQL 12.17无需添加第三方仓库。关键在于创建专用数据库用户与库并赋予pg_trgm扩展权限——该扩展用于设备搜索的模糊匹配缺失将导致 Web UI 设备列表加载超时。# 安装 PostgreSQL 12 及客户端工具 sudo apt install -y postgresql-12 postgresql-client-12 # 启动服务并设开机自启 sudo systemctl enable postgresql sudo systemctl start postgresql # 切换到 postgres 用户创建 thingsboard 用户与数据库 sudo -u postgres psql -c CREATE DATABASE thingsboard; sudo -u postgres psql -c CREATE USER tb_user WITH PASSWORD tb_password; sudo -u postgres psql -c GRANT ALL PRIVILEGES ON DATABASE thingsboard TO tb_user; # 启用 pg_trgm 扩展必须在 thingsboard 库内执行 sudo -u postgres psql -d thingsboard -c CREATE EXTENSION IF NOT EXISTS pg_trgm;2.2.1 验证 PostgreSQL 连接与权限使用psql直连测试确保tb_user能访问thingsboard库且pg_trgm已启用# 以 tb_user 身份连接密码为 tb_password psql -h 127.0.0.1 -U tb_user -d thingsboard -W # 在 psql 中执行 -- 应返回 1 行表示扩展存在 SELECT extname FROM pg_extension WHERE extname pg_trgm; -- 应返回空表示无表初始状态正常 \dt -- 退出 \q提示若psql报错FATAL: password authentication failed for user tb_user检查/etc/postgresql/*/main/pg_hba.conf是否包含host thingsboard tb_user 127.0.0.1/32 md5并执行sudo systemctl restart postgresql生效。参数项推荐值说明host127.0.0.1ThingsBoard 默认连接本地 PostgreSQL禁用localhost可能触发 Unix socket 而非 TCPdatabasethingsboard必须与thingsboard.yml中spring.datasource.url的数据库名一致usernametb_user非postgres超级用户符合最小权限原则passwordtb_password需在thingsboard.yml的spring.datasource.password中同步设置3. Node.js 18 与 Maven 3.8.8前端构建与后端打包的版本锁链ThingsBoard 的application.yml仅控制后端服务行为但整个平台包含两个独立构建阶段前端 UItb-web-ui需 Node.js 编译为静态资源后端服务thingsboard-server需 Maven 打包为可执行 JAR。Node.js 版本错误会导致npm install报node:util does not provide an export named promisifyMaven 版本过低如 3.6.3则无法解析maven-compiler-plugin:3.10.1的新语法引发Plugin execution not covered by lifecycle configuration错误。3.1 安装 Node.js 18 LTS 并验证构建能力ThingsBoard 3.7 的package.json明确指定engines: {node: 16.14.0 19.0.0}Node.js 18.19.0 是当前最稳定的 LTS 版本。避免使用 NodeSource 仓库的nodejs包可能混入 v20直接下载二进制包# 创建安装目录并下载 Node.js 18.19.0 cd /tmp wget https://nodejs.org/dist/v18.19.0/node-v18.19.0-linux-x64.tar.xz tar -xf node-v18.19.0-linux-x64.tar.xz sudo mv node-v18.19.0-linux-x64 /opt/nodejs # 创建软链接并更新 PATH sudo ln -sf /opt/nodejs/bin/node /usr/local/bin/node sudo ln -sf /opt/nodejs/bin/npm /usr/local/bin/npm # 验证版本 node -v # 应输出 v18.19.0 npm -v # 应输出 9.9.23.1.1 配置 npm 镜像加速与全局模块路径国内网络下npm install常因registry.npmjs.org超时失败。配置阿里云镜像并设置全局模块安装路径# 设置 npm 镜像为 registry.npmmirror.com npm config set registry https://registry.npmmirror.com # 设置全局模块路径避免权限问题 mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc # 安装 typescriptThingsBoard 前端构建必需 npm install -g typescript4.9.53.2 安装 Maven 3.8.8 并配置阿里云镜像仓库ThingsBoard 使用maven-compiler-plugin:3.10.1和maven-surefire-plugin:3.0.0-M9这些插件要求 Maven ≥ 3.8.1。Maven 3.8.8 是兼容性最佳版本需手动下载而非使用apt install mavenUbuntu 22.04 默认为 3.6.3# 下载 Maven 3.8.8 cd /tmp wget https://dlcdn.apache.org/maven/maven-3/3.8.8/binaries/apache-maven-3.8.8-bin.tar.gz tar -xzf apache-maven-3.8.8-bin.tar.gz sudo mv apache-maven-3.8.8 /opt/maven # 配置环境变量 echo export MAVEN_HOME/opt/maven | sudo tee -a /etc/profile echo export PATH$MAVEN_HOME/bin:$PATH | sudo tee -a /etc/profile source /etc/profile mvn -v # 应输出 Apache Maven 3.8.83.2.1 配置 Maven 阿里云镜像加速核心仓库编辑/opt/maven/conf/settings.xml在mirrors节点内添加阿里云镜像替换默认中央仓库mirrors mirror idaliyunmaven/id mirrorOf*/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors注意mirrorOf*/mirrorOf表示覆盖所有仓库请求若已存在其他 mirror需删除或注释原mirror块避免冲突。配置后执行mvn help:effective-settings验证aliyunmaven是否生效。Maven 配置项值作用MAVEN_HOME/opt/mavenMaven 主目录mvn命令依赖此变量定位插件settings.xml中mirrorhttps://maven.aliyun.com/repository/public加速org.thingsboard:thingsboard-server等依赖下载maven-compiler-plugin版本3.10.1ThingsBoardpom.xml强制指定低于此版本会触发Unknown lifecycle phase compile错误4. ThingsBoard 3.7.2 源码编译与服务启动从 clone 到 dashboard 可访问的完整链路完成 JDK11、PostgreSQL12、Node.js 18、Maven 3.8.8 四要素配置后进入 ThingsBoard 本身安装。不要下载预编译的.deb或.rpm包——这些包内置 HSQLDB无法直接对接 PostgreSQL且版本滞后。必须从 GitHub 拉取源码执行mvn clean install -DskipTests编译再修改配置文件指向 PostgreSQL。4.1 克隆源码并执行 Maven 编译ThingsBoard 官方 GitHub 仓库地址为https://github.com/thingsboard/thingsboard3.7.2 是当前稳定版。编译前需确保磁盘空间 ≥ 8GBtarget/目录约占用 3GB# 克隆仓库并检出 3.7.2 标签 git clone https://github.com/thingsboard/thingsboard.git cd thingsboard git checkout release-3.7.2 # 执行编译跳过测试以加速生产环境建议保留 -DskipTests mvn clean install -DskipTests -T 4C # 编译成功后可执行 JAR 位于 application/target/thingsboard-$VERSION.jar ls -lh application/target/thingsboard-*.jar # 输出示例thingsboard-3.7.2.jar (124M)4.1.1 验证编译产物与依赖树编译完成后检查 JAR 包是否包含 PostgreSQL 驱动及正确版本# 解压 JAR 查看驱动版本 unzip -p application/target/thingsboard-3.7.2.jar | grep -i postgresql # 应输出类似BOOT-INF/lib/postgresql-42.6.0.jar # 检查依赖树中无冲突的 slf4j 版本 mvn dependency:tree -Dincludesorg.slf4j:slf4j-api | grep slf4j-api # 应仅出现 1.7.36ThingsBoard 3.7.2 锁定版本4.2 配置 thingsboard.yml 指向 PostgreSQL 并初始化数据库编译生成的thingsboard-3.7.2.jar默认使用 HSQLDB需修改application/src/main/resources/thingsboard.yml中的数据库配置并执行初始化脚本# 复制配置模板 cp application/src/main/resources/thingsboard.yml application/src/main/resources/thingsboard-postgres.yml # 编辑配置文件使用 sed 替换关键参数 sed -i s/# spring: datasource: url:.*/spring: datasource: url: jdbc:postgresql:\/\/localhost:5432\/thingsboard/ application/src/main/resources/thingsboard-postgres.yml sed -i s/# spring: datasource: username:.*/spring: datasource: username: tb_user/ application/src/main/resources/thingsboard-postgres.yml sed -i s/# spring: datasource: password:.*/spring: datasource: password: tb_password/ application/src/main/resources/thingsboard-postgres.yml sed -i s/# spring: jpa: database-platform:.*/spring: jpa: database-platform: org.hibernate.dialect.PostgreSQLDialect/ application/src/main/resources/thingsboard-postgres.yml4.2.1 执行数据库初始化并启动服务ThingsBoard 提供install/install.sh脚本自动执行 DDL 创建但需指定配置文件路径# 赋予执行权限 chmod x application/src/main/scripts/install/install.sh # 执行初始化自动创建表结构、插入默认租户等 sudo ./application/src/main/scripts/install/install.sh --loadDemo # 启动服务后台运行 sudo nohup java -jar application/target/thingsboard-3.7.2.jar --spring.config.locationclasspath:/thingsboard.yml,/application/src/main/resources/thingsboard-postgres.yml /var/log/thingsboard.log 21 # 检查进程 ps aux | grep thingsboard # 查看日志末尾等待 Started ThingsboardApplication tail -f /var/log/thingsboard.log | grep Started ThingsboardApplication提示--loadDemo参数会插入 demo 设备与仪表板首次启动建议保留若需纯净环境改为--loadDemofalse。日志中出现Started ThingsboardApplication in X.XXX seconds即表示启动成功。5. 验证 ThingsBoard 服务可用性与 RPC 下发功能从登录到子设备指令的端到端测试安装完成不等于可用。必须验证三个核心能力Web UI 可访问、管理员账户可登录、RPC 命令能下发至子设备。这三步覆盖了 ThingsBoard 最典型的物联网场景——设备管理、可视化监控、远程控制。5.1 访问 Web UI 并登录默认管理员账户ThingsBoard 默认监听8080端口使用http://server-ip:8080访问。首次启动后系统自动创建超级管理员账户用户名sysadminthingsboard.org密码sysadmin注意若页面显示502 Bad Gateway检查 Nginx/Apache 是否拦截了 8080 端口若显示ERR_CONNECTION_REFUSED确认java -jar进程是否仍在运行ps aux | grep thingsboard并检查/var/log/thingsboard.log中是否有Caused by: org.postgresql.util.PSQLException: Connection refusedPostgreSQL 未启动。5.1.1 修改默认密码并创建租户登录后立即修改超级管理员密码安全基线要求并创建第一个租户点击右上角头像 →Profile Settings→ 修改密码左侧菜单 →System Settings→Tenants→Add Tenant输入租户名称如MyCompany点击Add系统自动生成租户管理员账户邮箱为tenantmycompany.com密码同租户名。5.2 使用 MQTT 客户端模拟子设备并测试 RPC 下发ThingsBoard 的 RPC 功能允许服务器向设备发送指令如重启、读取传感器值。验证需两步设备上线发布v1/devices/me/telemetry→下发 RPC订阅v1/devices/me/rpc/request/。使用mosquitto_pub/mosquitto_sub工具Ubuntu 下sudo apt install mosquitto-clients# 设备上线发布遥测数据JSON 格式 mosquitto_pub -h localhost -p 1883 -t v1/devices/me/telemetry -u YOUR_DEVICE_ACCESS_TOKEN -m {temperature:25.5,humidity:60} # 开启 RPC 请求监听设备端需订阅此主题 mosquitto_sub -h localhost -p 1883 -t v1/devices/me/rpc/request/ -u YOUR_DEVICE_ACCESS_TOKEN # 在 Web UI 中Devices → 选择设备 → Action → Send RPC command # 输入方法名如 getFirmwareVersion、参数{}点击 Send # 此时 mosquitto_sub 将收到类似 # {method:getFirmwareVersion,params:{},id:1}5.2.1 验证 RPC 响应回传机制设备收到 RPC 请求后需向v1/devices/me/rpc/response/$id主题发布响应。模拟响应# 将上一步收到的 id:1 替换到主题中 mosquitto_pub -h localhost -p 1883 -t v1/devices/me/rpc/response/1 -u YOUR_DEVICE_ACCESS_TOKEN -m {version:1.2.3} # Web UI 中对应 RPC 请求状态将变为 Success响应内容显示 {version:1.2.3}测试环节预期结果故障排查点Web UI 登录页面加载输入默认账号密码后跳转至仪表板检查thingsboard.log中Tomcat started on port(s): 8080确认iptables -L未屏蔽 8080设备遥测上报Devices 列表中设备状态变为ACTIVELatest telemetry 显示温度/湿度检查YOUR_DEVICE_ACCESS_TOKEN是否与设备配置一致确认mosquitto_pub无-d调试模式下的Connection refusedRPC 下发mosquitto_sub收到 JSON 请求Web UI 显示Pending→Success确认设备订阅了v1/devices/me/rpc/request/响应主题中的$id必须与请求中id完全匹配至此新版 ThingsBoard 在 JDK11、PostgreSQL12、Node.js 18、Maven 3.8.8 四要素协同下已完成从环境准备、源码编译、数据库初始化到 RPC 指令闭环的全链路验证。后续如需对接真实设备只需在 Web UI 中创建设备、获取access token即可复用上述 MQTT 流程。本文还有配套的精品资源点击获取 
长河君 · 2026/9/17 14:22:46 · 阅读 1.2k ThingsBoard 3.7+ 四组件版本对齐安装指南：JDK11、PostgreSQL12、Node.js18、Maven3.8.8
简介本资源是一份面向物联网开发者与系统部署工程师的新版ThingsBoard本地安装实战指南专为Windows平台Win7/8/8.1/10用户定制聚焦解决实际部署中高频出现的环境配置、依赖编译失败、数据库初始化及启动异常等90%以上典型问题。文档以图文并茂形式完整记录作者亲测安装全过程涵盖JDK 11配置、PostgreSQL 12建库、源码拉取、Node.js与Maven环境调优、gradle-tooling-api手动注入、SQL脚本导入及默认账号登录等关键环节并提供详细排错路径与绕过方案。资源为单个Word文档.doc格式体积1.96MB结构清晰、步骤可复现便于快速查阅与实操对照。目前已有473人学习下载适合具备基础Java和数据库知识的中级开发者用于私有化部署验证或教学环境搭建。1. 新版 ThingsBoard 安装不是“照着文档就行”而是 JDK11、PostgreSQL12、Node.js 与 Maven 四要素协同生效的系统工程很多人点开新版 ThingsBoard 官方安装文档第一反应是“不就是下载、解压、改配置、启动吗”——结果卡在java.lang.UnsupportedClassVersionError或Failed to initialize PostgreSQL schema或npm install fails with node:util export error。根本原因在于ThingsBoard 3.7 已强制要求 JDK11非 JDK8 或 JDK17其后端编译依赖 Maven 构建链前端构建依赖 Node.js 16–18非 v20而数据库必须是 PostgreSQL 12 或 13PostgreSQL 15 会触发pg_catalog.pg_type元数据兼容性报错。这不是单点安装而是四组件版本对齐的校验过程。本文面向已在 Linux 或 Windows 上部署过旧版 ThingsBoard 的运维/开发人员也覆盖首次接触 IoT 平台的嵌入式工程师——你不需要懂 Spring Boot 源码但必须清楚每个组件在 ThingsBoard 启动流程中的不可替代角色JDK11 提供运行时字节码兼容性PostgreSQL12 承载设备元数据与遥测历史Node.js 编译前端资源tb-web-uiMaven 则负责将thingsboard-server模块打包为可执行 JAR 并注入数据库初始化脚本。所有步骤均基于 Ubuntu 22.04 / Windows 10 实测验证跳过官网模糊表述直击参数级配置。2. JDK11 与 PostgreSQL12ThingsBoard 运行时的双基石配置ThingsBoard 3.7 的类文件主版本号为 55对应 JDK11若使用 JDK17主版本号 61会导致UnsupportedClassVersionError若使用 JDK8主版本号 52则因缺少var关键字和HttpClient等 API 报编译失败。PostgreSQL 方面官方文档未明确标注最低兼容版本但实测 PostgreSQL 12.17 是稳定边界——15.x 中pg_type.typcategory字段类型变更导致 ThingsBoard 初始化脚本create_schema.sql中的CASE WHEN typcategory B查询失败。因此必须严格锁定这两个组件的版本。2.1 在 Ubuntu 22.04 上安装并锁定 JDK11Ubuntu 22.04 默认源提供的是 OpenJDK 11.0.22但需确认是否为11.0.227LTS 版本。执行以下命令验证并安装# 卸载可能存在的其他 JDK sudo apt remove --purge openjdk-* -y # 添加官方仓库并安装 OpenJDK 11 sudo apt update sudo apt install -y openjdk-11-jdk-headless # 验证版本输出应为 11.0.22 java -version注意openjdk-11-jdk-headless不含 AWT/Swing GUI 组件节省内存且符合 ThingsBoard 无界面服务需求若误装openjdk-11-jdk需手动清理/usr/lib/jvm/java-11-openjdk-amd64/jre/lib/ext/下冗余 jar 包否则可能触发NoClassDefFoundError: javax/xml/bind/annotation/XmlSchema。2.1.1 设置 JAVA_HOME 并验证环境变量ThingsBoard 启动脚本run.sh依赖JAVA_HOME指向 JDK 根目录而非 JRE。执行# 查找 JDK 安装路径通常为 /usr/lib/jvm/java-11-openjdk-amd64 sudo update-alternatives --config java # 输出示例/usr/lib/jvm/java-11-openjdk-amd64/bin/java → 复制路径前缀 export JAVA_HOME/usr/lib/jvm/java-11-openjdk-amd64 echo export JAVA_HOME/usr/lib/jvm/java-11-openjdk-amd64 | sudo tee -a /etc/profile source /etc/profile echo $JAVA_HOME # 应输出 /usr/lib/jvm/java-11-openjdk-amd642.2 安装 PostgreSQL 12 并初始化 ThingsBoard 数据库Ubuntu 22.04 默认源提供 PostgreSQL 12.17无需添加第三方仓库。关键在于创建专用数据库用户与库并赋予pg_trgm扩展权限——该扩展用于设备搜索的模糊匹配缺失将导致 Web UI 设备列表加载超时。# 安装 PostgreSQL 12 及客户端工具 sudo apt install -y postgresql-12 postgresql-client-12 # 启动服务并设开机自启 sudo systemctl enable postgresql sudo systemctl start postgresql # 切换到 postgres 用户创建 thingsboard 用户与数据库 sudo -u postgres psql -c CREATE DATABASE thingsboard; sudo -u postgres psql -c CREATE USER tb_user WITH PASSWORD tb_password; sudo -u postgres psql -c GRANT ALL PRIVILEGES ON DATABASE thingsboard TO tb_user; # 启用 pg_trgm 扩展必须在 thingsboard 库内执行 sudo -u postgres psql -d thingsboard -c CREATE EXTENSION IF NOT EXISTS pg_trgm;2.2.1 验证 PostgreSQL 连接与权限使用psql直连测试确保tb_user能访问thingsboard库且pg_trgm已启用# 以 tb_user 身份连接密码为 tb_password psql -h 127.0.0.1 -U tb_user -d thingsboard -W # 在 psql 中执行 -- 应返回 1 行表示扩展存在 SELECT extname FROM pg_extension WHERE extname pg_trgm; -- 应返回空表示无表初始状态正常 \dt -- 退出 \q提示若psql报错FATAL: password authentication failed for user tb_user检查/etc/postgresql/*/main/pg_hba.conf是否包含host thingsboard tb_user 127.0.0.1/32 md5并执行sudo systemctl restart postgresql生效。参数项推荐值说明host127.0.0.1ThingsBoard 默认连接本地 PostgreSQL禁用localhost可能触发 Unix socket 而非 TCPdatabasethingsboard必须与thingsboard.yml中spring.datasource.url的数据库名一致usernametb_user非postgres超级用户符合最小权限原则passwordtb_password需在thingsboard.yml的spring.datasource.password中同步设置3. Node.js 18 与 Maven 3.8.8前端构建与后端打包的版本锁链ThingsBoard 的application.yml仅控制后端服务行为但整个平台包含两个独立构建阶段前端 UItb-web-ui需 Node.js 编译为静态资源后端服务thingsboard-server需 Maven 打包为可执行 JAR。Node.js 版本错误会导致npm install报node:util does not provide an export named promisifyMaven 版本过低如 3.6.3则无法解析maven-compiler-plugin:3.10.1的新语法引发Plugin execution not covered by lifecycle configuration错误。3.1 安装 Node.js 18 LTS 并验证构建能力ThingsBoard 3.7 的package.json明确指定engines: {node: 16.14.0 19.0.0}Node.js 18.19.0 是当前最稳定的 LTS 版本。避免使用 NodeSource 仓库的nodejs包可能混入 v20直接下载二进制包# 创建安装目录并下载 Node.js 18.19.0 cd /tmp wget https://nodejs.org/dist/v18.19.0/node-v18.19.0-linux-x64.tar.xz tar -xf node-v18.19.0-linux-x64.tar.xz sudo mv node-v18.19.0-linux-x64 /opt/nodejs # 创建软链接并更新 PATH sudo ln -sf /opt/nodejs/bin/node /usr/local/bin/node sudo ln -sf /opt/nodejs/bin/npm /usr/local/bin/npm # 验证版本 node -v # 应输出 v18.19.0 npm -v # 应输出 9.9.23.1.1 配置 npm 镜像加速与全局模块路径国内网络下npm install常因registry.npmjs.org超时失败。配置阿里云镜像并设置全局模块安装路径# 设置 npm 镜像为 registry.npmmirror.com npm config set registry https://registry.npmmirror.com # 设置全局模块路径避免权限问题 mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc # 安装 typescriptThingsBoard 前端构建必需 npm install -g typescript4.9.53.2 安装 Maven 3.8.8 并配置阿里云镜像仓库ThingsBoard 使用maven-compiler-plugin:3.10.1和maven-surefire-plugin:3.0.0-M9这些插件要求 Maven ≥ 3.8.1。Maven 3.8.8 是兼容性最佳版本需手动下载而非使用apt install mavenUbuntu 22.04 默认为 3.6.3# 下载 Maven 3.8.8 cd /tmp wget https://dlcdn.apache.org/maven/maven-3/3.8.8/binaries/apache-maven-3.8.8-bin.tar.gz tar -xzf apache-maven-3.8.8-bin.tar.gz sudo mv apache-maven-3.8.8 /opt/maven # 配置环境变量 echo export MAVEN_HOME/opt/maven | sudo tee -a /etc/profile echo export PATH$MAVEN_HOME/bin:$PATH | sudo tee -a /etc/profile source /etc/profile mvn -v # 应输出 Apache Maven 3.8.83.2.1 配置 Maven 阿里云镜像加速核心仓库编辑/opt/maven/conf/settings.xml在mirrors节点内添加阿里云镜像替换默认中央仓库mirrors mirror idaliyunmaven/id mirrorOf*/mirrorOf name阿里云公共仓库/name urlhttps://maven.aliyun.com/repository/public/url /mirror /mirrors注意mirrorOf*/mirrorOf表示覆盖所有仓库请求若已存在其他 mirror需删除或注释原mirror块避免冲突。配置后执行mvn help:effective-settings验证aliyunmaven是否生效。Maven 配置项值作用MAVEN_HOME/opt/mavenMaven 主目录mvn命令依赖此变量定位插件settings.xml中mirrorhttps://maven.aliyun.com/repository/public加速org.thingsboard:thingsboard-server等依赖下载maven-compiler-plugin版本3.10.1ThingsBoardpom.xml强制指定低于此版本会触发Unknown lifecycle phase compile错误4. ThingsBoard 3.7.2 源码编译与服务启动从 clone 到 dashboard 可访问的完整链路完成 JDK11、PostgreSQL12、Node.js 18、Maven 3.8.8 四要素配置后进入 ThingsBoard 本身安装。不要下载预编译的.deb或.rpm包——这些包内置 HSQLDB无法直接对接 PostgreSQL且版本滞后。必须从 GitHub 拉取源码执行mvn clean install -DskipTests编译再修改配置文件指向 PostgreSQL。4.1 克隆源码并执行 Maven 编译ThingsBoard 官方 GitHub 仓库地址为https://github.com/thingsboard/thingsboard3.7.2 是当前稳定版。编译前需确保磁盘空间 ≥ 8GBtarget/目录约占用 3GB# 克隆仓库并检出 3.7.2 标签 git clone https://github.com/thingsboard/thingsboard.git cd thingsboard git checkout release-3.7.2 # 执行编译跳过测试以加速生产环境建议保留 -DskipTests mvn clean install -DskipTests -T 4C # 编译成功后可执行 JAR 位于 application/target/thingsboard-$VERSION.jar ls -lh application/target/thingsboard-*.jar # 输出示例thingsboard-3.7.2.jar (124M)4.1.1 验证编译产物与依赖树编译完成后检查 JAR 包是否包含 PostgreSQL 驱动及正确版本# 解压 JAR 查看驱动版本 unzip -p application/target/thingsboard-3.7.2.jar | grep -i postgresql # 应输出类似BOOT-INF/lib/postgresql-42.6.0.jar # 检查依赖树中无冲突的 slf4j 版本 mvn dependency:tree -Dincludesorg.slf4j:slf4j-api | grep slf4j-api # 应仅出现 1.7.36ThingsBoard 3.7.2 锁定版本4.2 配置 thingsboard.yml 指向 PostgreSQL 并初始化数据库编译生成的thingsboard-3.7.2.jar默认使用 HSQLDB需修改application/src/main/resources/thingsboard.yml中的数据库配置并执行初始化脚本# 复制配置模板 cp application/src/main/resources/thingsboard.yml application/src/main/resources/thingsboard-postgres.yml # 编辑配置文件使用 sed 替换关键参数 sed -i s/# spring: datasource: url:.*/spring: datasource: url: jdbc:postgresql:\/\/localhost:5432\/thingsboard/ application/src/main/resources/thingsboard-postgres.yml sed -i s/# spring: datasource: username:.*/spring: datasource: username: tb_user/ application/src/main/resources/thingsboard-postgres.yml sed -i s/# spring: datasource: password:.*/spring: datasource: password: tb_password/ application/src/main/resources/thingsboard-postgres.yml sed -i s/# spring: jpa: database-platform:.*/spring: jpa: database-platform: org.hibernate.dialect.PostgreSQLDialect/ application/src/main/resources/thingsboard-postgres.yml4.2.1 执行数据库初始化并启动服务ThingsBoard 提供install/install.sh脚本自动执行 DDL 创建但需指定配置文件路径# 赋予执行权限 chmod x application/src/main/scripts/install/install.sh # 执行初始化自动创建表结构、插入默认租户等 sudo ./application/src/main/scripts/install/install.sh --loadDemo # 启动服务后台运行 sudo nohup java -jar application/target/thingsboard-3.7.2.jar --spring.config.locationclasspath:/thingsboard.yml,/application/src/main/resources/thingsboard-postgres.yml /var/log/thingsboard.log 21 # 检查进程 ps aux | grep thingsboard # 查看日志末尾等待 Started ThingsboardApplication tail -f /var/log/thingsboard.log | grep Started ThingsboardApplication提示--loadDemo参数会插入 demo 设备与仪表板首次启动建议保留若需纯净环境改为--loadDemofalse。日志中出现Started ThingsboardApplication in X.XXX seconds即表示启动成功。5. 验证 ThingsBoard 服务可用性与 RPC 下发功能从登录到子设备指令的端到端测试安装完成不等于可用。必须验证三个核心能力Web UI 可访问、管理员账户可登录、RPC 命令能下发至子设备。这三步覆盖了 ThingsBoard 最典型的物联网场景——设备管理、可视化监控、远程控制。5.1 访问 Web UI 并登录默认管理员账户ThingsBoard 默认监听8080端口使用http://server-ip:8080访问。首次启动后系统自动创建超级管理员账户用户名sysadminthingsboard.org密码sysadmin注意若页面显示502 Bad Gateway检查 Nginx/Apache 是否拦截了 8080 端口若显示ERR_CONNECTION_REFUSED确认java -jar进程是否仍在运行ps aux | grep thingsboard并检查/var/log/thingsboard.log中是否有Caused by: org.postgresql.util.PSQLException: Connection refusedPostgreSQL 未启动。5.1.1 修改默认密码并创建租户登录后立即修改超级管理员密码安全基线要求并创建第一个租户点击右上角头像 →Profile Settings→ 修改密码左侧菜单 →System Settings→Tenants→Add Tenant输入租户名称如MyCompany点击Add系统自动生成租户管理员账户邮箱为tenantmycompany.com密码同租户名。5.2 使用 MQTT 客户端模拟子设备并测试 RPC 下发ThingsBoard 的 RPC 功能允许服务器向设备发送指令如重启、读取传感器值。验证需两步设备上线发布v1/devices/me/telemetry→下发 RPC订阅v1/devices/me/rpc/request/。使用mosquitto_pub/mosquitto_sub工具Ubuntu 下sudo apt install mosquitto-clients# 设备上线发布遥测数据JSON 格式 mosquitto_pub -h localhost -p 1883 -t v1/devices/me/telemetry -u YOUR_DEVICE_ACCESS_TOKEN -m {temperature:25.5,humidity:60} # 开启 RPC 请求监听设备端需订阅此主题 mosquitto_sub -h localhost -p 1883 -t v1/devices/me/rpc/request/ -u YOUR_DEVICE_ACCESS_TOKEN # 在 Web UI 中Devices → 选择设备 → Action → Send RPC command # 输入方法名如 getFirmwareVersion、参数{}点击 Send # 此时 mosquitto_sub 将收到类似 # {method:getFirmwareVersion,params:{},id:1}5.2.1 验证 RPC 响应回传机制设备收到 RPC 请求后需向v1/devices/me/rpc/response/$id主题发布响应。模拟响应# 将上一步收到的 id:1 替换到主题中 mosquitto_pub -h localhost -p 1883 -t v1/devices/me/rpc/response/1 -u YOUR_DEVICE_ACCESS_TOKEN -m {version:1.2.3} # Web UI 中对应 RPC 请求状态将变为 Success响应内容显示 {version:1.2.3}测试环节预期结果故障排查点Web UI 登录页面加载输入默认账号密码后跳转至仪表板检查thingsboard.log中Tomcat started on port(s): 8080确认iptables -L未屏蔽 8080设备遥测上报Devices 列表中设备状态变为ACTIVELatest telemetry 显示温度/湿度检查YOUR_DEVICE_ACCESS_TOKEN是否与设备配置一致确认mosquitto_pub无-d调试模式下的Connection refusedRPC 下发mosquitto_sub收到 JSON 请求Web UI 显示Pending→Success确认设备订阅了v1/devices/me/rpc/request/响应主题中的$id必须与请求中id完全匹配至此新版 ThingsBoard 在 JDK11、PostgreSQL12、Node.js 18、Maven 3.8.8 四要素协同下已完成从环境准备、源码编译、数据库初始化到 RPC 指令闭环的全链路验证。后续如需对接真实设备只需在 Web UI 中创建设备、获取access token即可复用上述 MQTT 流程。本文还有配套的精品资源点击获取