简介面向物联网平台二次开发者与运维工程师的ThingsBoard 3.4.4源码编译安装资料涵盖JDK/Maven环境变量配置、Node与Yarn版本对齐、PostgreSQL安装、依赖组件获取、编译打包、数据库初始化及最终部署等完整链路并将实际操作中遇到的版本不一致、平台差异等问题一并记录适合需要从源码定制物联网平台的初中级开发者参考。资源包共129个文件约784.41MB以dll动态库、exe/msi安装程序、txt操作说明以及xml/json配置为主同时包含Windows与Linux两套fetched运行组件便于跨平台对照使用整体目录结构按步骤组织可快速定位到对应环节。这套资料已在真实线上服务器完整跑通读者可据此规避依赖缺失、版本漂移、初始化失败等常见编译部署陷阱获得可复现的排错思路与部署经验。目前已有626人学习下载。 自己从零编译过一遍 ThingsBoard 3.4.4 的人应该都有同感这东西不像普通 Java 项目clone 下来 mvn package 就完事。它涉及 Maven 多模块、Angular 前端、数据库初始化、Python 脚本打包等多个环节任何一个版本对应不上都会卡住。这篇博客我就把自己在 3.4.4 源码编译安装过程中踩过的坑、验证过的步骤完整记录下来从环境准备到编译打包再到数据库初始化和用 MqttFX 上报遥测验证全链路可用适合刚接触 ThingsBoard 源码、想自己掌控整套平台构建流程的物联网开发者参考。1. 为什么非得从源码编译安装 ThingsBoard1.1 源码编译与官方包的根本差异ThingsBoard 官方提供了三种安装方式现成的 Docker 镜像、Deb/RPM 安装包、源码编译安装。前两种方式对大多数场景都够用拉个镜像、解压一个 deb 包几分钟就能跑起来。那为什么还要折磨自己从源码编译因为源码编译是唯一能让你改平台本身的方式。我遇到过几个需求场景用官方包根本没法解决想修改 MQTT 传输层的报文处理逻辑比如自定义 topic 规则、调整设备接入的鉴权方式。想裁剪模块。默认包会把 rule-engine、edge、transportHTTP/MQTT/CoAP全部打进去但某些内部项目只需要 MQTT 接入此时需要自定义构建。想给前端加定制化页面比如品牌 logo、默认主题、自定义仪表盘组件。前端源码ui-ngx在编译过程中会一并打包改起来更顺手。部署环境是内网离线环境需要一次性拿到完整的部署包后续离线分发。另外源码编译能帮你更深地理解 ThingsBoard 的模块结构。你知道 application 目录下的东西是主服务transport 目录是各种协议接入层但通过编译日志和构建顺序你会对模块间依赖关系有更直观的感受。这对后续二次开发非常重要。1.2 3.4.4 的模块架构与编译产物ThingsBoard 3.4.4 的源码根目录下有几个核心模块需要搞清楚模块作用application主应用包含规则引擎、设备管理、安全认证、REST API 等核心逻辑最终打包为可执行 jarui-ngxAngular 前端工程编译产物是静态资源会被复制到主应用包中transport设备接入层含 mqtt、http、coap 三个子模块rule-engine规则引擎服务负责数据流处理和告警规则data数据库相关脚本和初始化数据dao数据访问层支持 PostgreSQL 和 Cassandra 两种后端存储netty-mqttThingsBoard 自己维护的 MQTT 协议实现基于 Netty整个编译过程就是先把这些模块编译、安装到本地 Maven 仓库最后在 distributions 模块把启动脚本、配置、前端资源、jar 包全部组装成一个 tar.gz 或 deb 包。编译顺利的话最终会在target/distributions或类似目录下生成可部署的产物。必须强调一点3.4.4 的编译依赖 JDK 8 或 11、Maven 3.6、Node.js 14/16版本错一个就会在某个环节冒出一堆莫名其妙的报错下文会重点讲到版本匹配这件事。2. 编译前的环境准备版本与坑一次说清2.1 依赖清单与版本对照表这是我在 3.4.4 上实际编译验证过的依赖环境直接对照着装就行依赖项推荐版本说明JDKOpenJDK 118 也可以编译但运行期建议 11ThingsBoard 3.4.x 对 JDK 8/11 都兼容JDK 11 更稳Maven3.6.3 或 3.8.x3.6.3 是官方 CI 使用的版本3.8 实测也没问题Node.js14.x 或 16.x用于编译前端 ui-ngx 模块版本太新可能引发 OpenSSL 报错npm随 Node.js 附带前端资源安装依赖时使用PostgreSQL12 或 13生产建议 12 以上3.4.4 默认数据源是 PostgreSQL也可以用 CassandraGit2.x拉取源码用内存建议 8GB 以上编译前端 Angular 项目极吃内存4GB 机器容易 OOM2.2 JDK、Maven、Node.js 逐项安装要点以 Ubuntu 20.04 环境为例简单说一下关键操作和几个我踩过的坑。JDK 安装sudo apt update sudo apt install openjdk-11-jdk java -version # 确认输出为 openjdk version 11.0.xx需要注意编译时如果用的是 JDK 11javac会默认带上模块化参数但 ThingsBoard 3.4.4 有些老模块未必兼容。实测中我没有遇到问题但如果你用 JDK 17 编译UnsupportedClassVersionError和java.lang.reflect.InaccessibleObjectException会接踵而来强烈不建议用 JDK 17。Maven 安装sudo apt install maven不过 apt 源里的 Maven 版本可能偏旧建议手动下载二进制包并配置环境变量wget https://archive.apache.org/dist/maven/maven-3/3.6.3/binaries/apache-maven-3.6.3-bin.tar.gz tar -zxvf apache-maven-3.6.3-bin.tar.gz -C /opt/ echo export MAVEN_HOME/opt/apache-maven-3.6.3 ~/.bashrc echo export PATH$MAVEN_HOME/bin:$PATH ~/.bashrc source ~/.bashrc mvn -versionNode.js 安装curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash - sudo apt install -y nodejs node -v npm -v这里有个关键点不要用最新的 Node 20。Angular 老版本构建时依赖的node-sass之类的原生模块对 Node 版本非常敏感Node 太新会直接收到Error: Node Sass does not yet support your current environment的报错。3.4.4 的 ui-ngx 是 Angular 13 左右的版本Node 14/16 是安全区间。2.3 Maven 仓库与镜像配置国内环境拉 Maven 依赖必须有镜像加速否则编译到一半会因为网速让人崩溃。在~/.m2/settings.xml里加上阿里云镜像mirrors mirror idaliyunmaven/id namealiyun maven mirror/name urlhttps://maven.aliyun.com/repository/public/url mirrorOfcentral/mirrorOf /mirror /mirrorsnpm 的镜像也要配置好否则前端依赖那一堆包会等到怀疑人生npm config set registry https://registry.npmmirror.com另外编译期间 Maven 会从网上拉取数十个插件和依赖包建议提前确认服务器能访问外网。如果完全离线就需要在另一台联网机器上先确认依赖都进了本地仓库再把整个~/.m2拷过去这个方案我后面会专门说。3. 源码编译完整流程从克隆到打包3.1 拉取源码与切换版本分支首先把源码拉下来并切到 3.4.4 对应的 taggit clone https://github.com/thingsboard/thingsboard.git cd thingsboard git checkout v3.4.4注意几点直接 clone 默认分支是 master 或 develop不要用这个来编译版本不对。一定要切到v3.4.4这个 tag。如果公司内网没法访问 GitHub可以用 Gitee 上的镜像仓库或者在某台能访问外网的机器上先 clone 再打包传进内网。切完 tag 后建议执行git status确认当前在 detached HEAD 状态只要能看到HEAD detached at v3.4.4就说明切对了。3.2 Maven 编译命令与参数逐项解释编译命令是整篇博客的核心直接给结论mvn clean install -DskipTests -Dlicense.skiptrue -Dblackbox.skiptrue解释一下每个关键参数-DskipTests跳过单元测试。ThingsBoard 的测试体量不小跑一遍要很久自己编译部署不需要也没必要跑测试。-Dlicense.skiptrue跳过 license 检查。ThingsBoard 的构建流程强制检查源码文件头部的 license不跳过会在 checkstyle 阶段直接失败。-Dblackbox.skiptrue跳过黑盒测试同样是避免不必要的构建阻断。还有一个参数需要视情况加上mvn clean install -DskipTests -Dlicense.skiptrue -Dblackbox.skiptrue -Dnpm.skiptrue如果你不想重新编译前端比如只改了后端逻辑那-Dnpm.skiptrue可以跳过 npm install 和 ng build构建速度会快很多。但第一次完整编译时建议不要跳过因为前端资源需要一起打包进最终产物里。整个编译过程非常漫长。在一台 8 核 16GB 内存的机器上首次编译耗时大约 20~40 分钟取决于网速和机器性能。期间 Maven 会依次构建 dao、rule-engine、transport 等子模块最后在 distributions 模块组装安装包。中途如果某个模块失败重新执行同一条命令即可Maven 会跳过已经成功的模块。3.3 前端资源构建与产物整理前端 ui-ngx 是编译过程中最容易出问题的环节。它的大致流程是Maven 通过 frontend-maven-plugin 在ui-ngx目录下执行npm install。安装完依赖后执行ng build把 Angular 项目编译成静态文件。静态文件会被复制到 application 模块的target/classes/static目录下随主程序一起打进 jar 包。如果前端构建失败常见原因就两个npm 依赖拉不下来或者 Node 版本不兼容。前者换镜像源解决后者换 Node 版本。编译成功以后最终的可部署包通常会在distributions/target目录下或者根据你构建的模块不同也会在application/target下出现一个可执行的 jar 包。我们需要的是带完整启动脚本的发行包所以在distributions目录下执行编译最后得到的 tar.gz 包才是完整形态。我习惯的最终产物路径是distributions/target/thingsboard-3.4.4.tar.gz把这个包解压到目标目录就是一套完整的可运行服务。4. 安装部署与初始化数据库、配置与服务启动4.1 PostgreSQL 数据库初始化第一次启动 ThingsBoard 之前必须先初始化数据库。如果数据库都没建好服务启动会一直报连接错误页面根本起不来。首先安装 PostgreSQL 并启动服务sudo apt install postgresql postgresql-contrib sudo systemctl start postgresql sudo systemctl enable postgresql然后切换到 postgres 用户创建数据库和用户密码按需修改sudo -i -u postgres psql -c CREATE USER thingsboard WITH PASSWORD thingsboard; psql -c CREATE DATABASE thingsboard OWNER thingsboard;这一步需要说明ThingsBoard 初始化脚本会用 conf 里的账号密码去连 PostgreSQL所以这里建的用户名密码要和后面配置文件里的一致。4.2 ThingsBoard 安装与配置修改把前面编译出的安装包解压到目标目录sudo mkdir -p /opt/thingsboard sudo tar -zxvf distributions/target/thingsboard-3.4.4.tar.gz -C /opt/thingsboard --strip-components1找到配置文件conf/thingsboard.conf这个文件默认存在但内容基本是注释状态需要按需开启配置。核心要改的是数据库连接信息export DATABASE_TYPEpostgres export SPRING_DATASOURCE_URLjdbc:postgresql://localhost:5432/thingsboard export SPRING_DATASOURCE_USERNAMEthingsboard export SPRING_DATASOURCE_PASSWORDthingsboard如果你只是单机测试其实配置文件里还有一堆可以保持默认的项比如TB_QUEUE_TYPEin-memory消息队列用内存实现不需要额外装 Kafka。默认配置下规则引擎的队列就是 in-memory够测试用。4.3 启动服务与页面验证配置完数据库执行初始化脚本cd /opt/thingsboard sudo ./bin/install/install.sh这个脚本会创建数据库 schema、写入系统默认数据比如管理员账号、默认租户、默认设备配置。日志如果看到Installation finished successfully!就说明数据库这关过了。接下来启动服务sudo ./bin/thingsboard.sh start服务启动需要几十秒可以持续看日志确认状态tail -f logs/thingsboard.log看到类似Started ThingsboardApplication的日志后浏览器访问http://服务器IP:8080默认账号是sysadminthingsboard.org密码sysadmin。能打开登录页并成功登录说明整个编译、部署链路基本通畅了。需要注意的是8080 端口不要被占用如果同时装了其他 Web 服务先处理掉。如果端口被占用可以在conf/thingsboard.conf里通过SERVER_PORT调整。5. 用 MqttFX 上报遥测验证平台可用性5.1 创建设备与获取 Access Token编译部署完成不等于万事大吉真正要验证的是设备接入链路是否通。ThingsBoard 的设备接入方式比较统一设备通过 MQTT 或 HTTP 上报数据时认证方式是使用设备凭证里的 Access Token。先登录平台在左侧菜单打开实体 - 设备点击右上角新建设备名称填test-device-01设备配置档案保持默认。创建完成后点击设备进入详情页切到管理凭证标签页就能看到这行 Access Token。这是一个很长的十六进制字符串先复制下来后面 MqttFX 连接时会用到。这里有一个细节ThingsBoard 的 MQTT 认证规则中Access Token 既当作用户名也当作密码。你可以在 MqttFX 的配置里把用户名和密码都填成这个 Token或者用户名填 Token、密码留空实测两种方式都能通过认证。5.2 MqttFX 连接与数据上报MqttFX 是一款跨平台的 MQTT 客户端调试工具非常轻量适合快速验证设备接入。打开 MqttFX新建一个连接Broker Address填 ThingsBoard 服务器 IPPort1883ThingsBoard 默认 MQTT 端口UsernameAccess TokenPasswordAccess Token点击连接如果右侧状态变为绿色并且显示Connected说明设备鉴权和 MQTT 通道都正常。上报遥测数据在 Publish 页签下topic 填写v1/devices/me/telemetrypayload 填写普通 JSON{temperature: 26.5, humidity: 60}点击发送。回到 ThingsBoard 页面刷新设备详情页切到最新遥测标签页你会看到刚刚上报的 temperature 和 humidity 两条数据已经躺在里面了。能走到这一步整个链路就是通的。除了遥测数据还可以用 MqttFX 向v1/devices/me/attributes上报属性数据以及向v1/devices/me/rpc/request/订阅 RPC 命令这些是后面做设备联动和远程控制的基础。6. 编译安装常见问题与排查实操6.1 编译期典型报错与定位思路编译期的问题十有八九出在依赖和插件上。分支不对导致的版本混乱。有同事没切 tag直接在 develop 分支上编译 3.4.4 的文档去配置数据库结果 schema 不匹配服务起了又挂。遇到问题先确认代码版本。Maven 依赖下载失败。表现是编译卡在某个模块反复报Could not resolve dependencies。这时候优先检查 Maven 镜像配置另外清理本地仓库重新拉rm -rf ~/.m2/repository/org/thingsboard mvn clean install -U -DskipTests -Dlicense.skiptrue -Dblackbox.skiptrue前端构建报错。如果在ui-ngx模块看到npm ERR!或者Error: getaddrinfo ENOTFOUND之类的输出基本就是 npm 源没配好或者 Node 版本不对。建议彻底删除ui-ngx/node_modules和ui-ngx/package-lock.json后重试。编译到一半内存不够。Angular 的ng build很吃内存4GB 机器上经常出现JavaScript heap out of memory。解决办法是给 Node 增大内存上限export NODE_OPTIONS--max_old_space_size4096然后再执行编译命令。6.2 运行期异常排查清单服务能启动但页面打不开、设备上报不成功这类运行期问题我整理成了一张速查表遇到直接对照排查现象可能原因排查/解决页面 503/404前端静态资源没打包进 jar确认编译时没有加-Dnpm.skiptrue重新完整编译启动日志报数据库连接失败conf 中数据库信息错误检查 SPRING_DATASOURCE_* 四组配置psql 手动连一次设备上报没数据MQTT 端口没监听netstat -tlnp登录报错Invalid credentials初始化脚本没执行重新执行./bin/install/install.sh上报时设备离线Access Token 填错重新复制 Token确认没有首尾空格规则引擎不触发队列配置有问题单机测试保持TB_QUEUE_TYPEin-memory不要配置 Kafka8080 被占用其他服务冲突sudo lsof -i:8080找到占用进程或改 SERVER_PORT6.3 几条实测心得最后分享几个从实操中沉淀下来的建议第一编译前把MAVEN_OPTS和NODE_OPTIONS都配好宁可多给一点内存也不要省。我见过太多人卡在前端编译 OOM 上其实一行 export 就能解决。第二整个过程最容易出问题的时间点就是首次编译但一旦编译成功后面重新编译都会很快因为 Maven 有增量构建和本地仓库缓存。所以碰到失败不用慌修改配置后重跑同一条命令即可。第三如果你打算长期做 ThingsBoard 二次开发我强烈建议保留编译环境不要编译完就清掉。每次改完代码在本地重新打包部署迭代效率会高很多。第四内网部署时在联网机器上编译成功后把整个~/.m2/repository和distributions/target下的安装包一起拷过去这样内网机器即使没有 Maven 依赖仓库也能正常安装运行。我个人在实际部署中的体会是ThingsBoard 源码编译确实比普通 Java 项目繁琐但整个链路走通之后你对平台的理解深度完全不一样。以后再遇到需要修改传输层逻辑、定制前端页面的场景心里就有一张清晰的构建地图了不会面对源码无从下手。最后再分享一个操作习惯每次修改配置或代码后先在测试环境完整跑一遍 compile 和部署确认没问题再上生产。这套流程虽然保守但在 ThingsBoard 这种体量的项目上是值得的。本文还有配套的精品资源点击获取