企业官网建设流程全解析

简介：本资源是一份面向物联网开发者与系统部署工程师的新版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 或 13（PostgreSQL 15+ 会触发pg_catalog.pg_type元数据兼容性报错）。这不是单点安装，而是四组件版本对齐的校验过程。本文面向已在 Linux 或 Windows 上部署过旧版 ThingsBoard 的运维/开发人员，也覆盖首次接触 IoT 平台的嵌入式工程师——你不需要懂 Spring Boot 源码，但必须清楚每个组件在 ThingsBoard 启动流程中的不可替代角色：JDK11 提供运行时字节码兼容性，PostgreSQL12 承载设备元数据与遥测历史，Node.js 编译前端资源（tb-web-ui），Maven 则负责将thingsboard-server模块打包为可执行 JAR 并注入数据库初始化脚本。所有步骤均基于 Ubuntu 22.04 / Windows 10 实测验证，跳过官网模糊表述，直击参数级配置。

2. JDK11 与 PostgreSQL12：ThingsBoard 运行时的双基石配置

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 上安装并锁定 JDK11

Ubuntu 22.04 默认源提供的是 OpenJDK 11.0.22，但需确认是否为11.0.22+7（LTS 版本）。执行以下命令验证并安装：

# 卸载可能存在的其他 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-amd64

2.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生效。

3. Node.js 18 与 Maven 3.8.8：前端构建与后端打包的版本锁链

ThingsBoard 的application.yml仅控制后端服务行为，但整个平台包含两个独立构建阶段：前端 UI（tb-web-ui）需 Node.js 编译为静态资源，后端服务（thingsboard-server）需 Maven 打包为可执行 JAR。Node.js 版本错误会导致npm install报node:util does not provide an export named 'promisify'；Maven 版本过低（如 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.2

3.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 # 安装 typescript（ThingsBoard 前端构建必需） npm install -g typescript@4.9.5

3.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 maven（Ubuntu 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.8

3.2.1 配置 Maven 阿里云镜像加速核心仓库

编辑/opt/maven/conf/settings.xml，在<mirrors>节点内添加阿里云镜像（替换默认中央仓库）：

<mirrors> <mirror> <id>aliyunmaven</id> <mirrorOf>*</mirrorOf> <name>阿里云公共仓库</name> <url>https://maven.aliyun.com/repository/public</url> </mirror> </mirrors>

注意：<mirrorOf>*</mirrorOf>表示覆盖所有仓库请求；若已存在其他 mirror，需删除或注释原<mirror>块，避免冲突。配置后执行mvn help:effective-settings验证aliyunmaven是否生效。

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/thingsboard，3.7.2 是当前稳定版。编译前需确保磁盘空间 ≥ 8GB（target/目录约占用 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 -Dincludes=org.slf4j:slf4j-api | grep "slf4j-api" # 应仅出现 1.7.36（ThingsBoard 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.yml

4.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.location=classpath:/thingsboard.yml,/application/src/main/resources/thingsboard-postgres.yml > /var/log/thingsboard.log 2>&1 & # 检查进程 ps aux | grep thingsboard # 查看日志末尾（等待 "Started ThingsboardApplication"） tail -f /var/log/thingsboard.log | grep "Started ThingsboardApplication"

提示：--loadDemo参数会插入 demo 设备与仪表板，首次启动建议保留；若需纯净环境，改为--loadDemo=false。日志中出现Started ThingsboardApplication in X.XXX seconds即表示启动成功。

5. 验证 ThingsBoard 服务可用性与 RPC 下发功能：从登录到子设备指令的端到端测试

安装完成不等于可用。必须验证三个核心能力：Web UI 可访问、管理员账户可登录、RPC 命令能下发至子设备。这三步覆盖了 ThingsBoard 最典型的物联网场景——设备管理、可视化监控、远程控制。

5.1 访问 Web UI 并登录默认管理员账户

ThingsBoard 默认监听8080端口，使用http://<server-ip>:8080访问。首次启动后，系统自动创建超级管理员账户：

• 用户名：sysadmin@thingsboard.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 refused（PostgreSQL 未启动）。

5.1.1 修改默认密码并创建租户

登录后立即修改超级管理员密码（安全基线要求），并创建第一个租户：

1. 点击右上角头像 →Profile Settings→ 修改密码；
2. 左侧菜单 →System Settings→Tenants→Add Tenant；
3. 输入租户名称（如MyCompany），点击Add；
4. 系统自动生成租户管理员账户（邮箱为tenant@mycompany.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"}`

至此，新版 ThingsBoard 在 JDK11、PostgreSQL12、Node.js 18、Maven 3.8.8 四要素协同下，已完成从环境准备、源码编译、数据库初始化到 RPC 指令闭环的全链路验证。后续如需对接真实设备，只需在 Web UI 中创建设备、获取access token，即可复用上述 MQTT 流程。

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