1. 先把Thingsboard在Windows上的运行逻辑说清楚1.1 Thingsboard到底是个什么东西为什么大家都想跑起来Thingsboard是一套开源的物联网平台这几年在设备接入、数据可视化、规则链编排、多租户权限管理这些场景里几乎成了标配。做硬件开发的人拿它来快速看设备上报数据做系统集成的人拿它在POC阶段跟客户演示“你的设备数据长这样”做平台研发的人则拿它当底座在上面做二次开发。一句话概括它把“设备连接、数据存储、界面展示、业务规则”这四件事打包好了你能在浏览器里看到实时数据也能写规则链让平台自动处理告警。但很多人一提到Thingsboard第一反应就是Linux服务器、Docker容器、一堆命令行。实际上在Windows上完全能把它跑起来而且流程固定下来之后并不复杂。尤其是个人电脑做原型验证、传感器调试、前端样式修改Windows环境反而是最顺手的地方。1.2 在Windows上启动的三条路线怎么选目前想在Windows上把一个Thingsboard服务拉起来主流有三条路我分别列一下选型思路后面细说。路线操作方式适合人群踩坑指数官方Windows安装包下载MSI安装包按向导安装自动注册系统服务只关心功能不想碰源码的人中低源码构建拉GitHub源码用Maven构建再运行启动脚本需要二次开发、改代码、学习内部结构的人中高Docker Desktop跑容器用docker-compose拉取官方镜像熟悉Docker、需要快速部署的人中我个人的建议是如果你只是想先把Thingsboard跑起来看一看界面、接一两个设备测试下功能直接走官方Windows安装包或者Docker如果你打算二次开发或者想搞清楚它的数据库结构、服务启动细节那就老老实实走源码构建。本文后面主要按源码构建和安装包两条主线来讲因为这两条线最能让你理解Thingsboard的启动原理排查问题的时候也知道去哪里看。1.3 启动的本质你其实在运行一个Java Web服务别被“物联网平台”这四个字吓到剥开来看Thingsboard就是一个典型的Java后端服务加上一套Angular前端页面。它的核心进程就是嵌入式Tomcat或者说Spring Boot应用监听8080端口提供Web服务同时监听1883端口接收MQTT设备消息、监听5683端口用于CoAP接入。所以你启动Thingsboard本质上就是完成三件事把Java运行环境准备好、把数据库准备好、把编译好的程序跑起来。理解了这一点后面所有报错你都能找到大方向——不是环境问题就是数据库问题再就是程序本身启动顺序问题。在Windows上之所以容易卡住是因为大家习惯了Linux下“写脚本、跑服务”的模式到了Windows就忘了环境变量、路径格式、防火墙这些小事恰恰是这些小事最容易翻车。2. 动手前的版本和数据库选型决定了你能不能一次跑通2.1 Thingsboard版本与JDK版本的对应关系这里必须先说一个最常见的坑Thingsboard不同版本对Java版本的要求差别很大。2.x时代用JDK 8完全没问题但从3.2版本开始切换到了Java 113.5版本以后又逐步要求JDK 17。如果你拿JDK 8去跑新版Thingsboard启动的时候会看到类似UnsupportedClassVersionError或者直接提示class文件版本52.0不支持。这种错误最迷惑人因为它不是“环境变量没配好”那种一眼能看出来的问题。以目前主流的3.5.x、3.6.x版本为例要求如下JavaJDK 17必须配置好JAVA_HOMEPostgreSQL12及以上如果用PostgreSQL作为数据库Maven3.6.3及以上Node.js16及以上仅源码构建前端时需要Git无硬性版本要求所以动手之前先确认你要装哪个版本的Thingsboard再回头准备对应的JDK。不要先装了最新JDK又回头用老版本也不要拿JDK 8硬跑新版本。版本对应关系我建议以官方Release分支为准比如拉release-3.5分支就在该分支的README或文档里确认要求的Java版本。2.2 数据库选型H2快速体验还是PostgreSQL一步到位Thingsboard支持两种主流的数据库方案一种是内置的H2嵌入式数据库另一种是PostgreSQL独立数据库服务。这个选型决定后面一大半的安装步骤必须先定下来。H2模式数据库跟着Thingsboard跑数据文件直接写在本地目录。好处是零安装不用单独装数据库软件对新手来说最友好坏处是性能上限低部分高级功能受限官方也不建议生产环境使用。如果你的诉求只是“把平台跑起来看看长什么样、接两个模拟设备验证流程”H2完全够用。PostgreSQL模式独立安装PostgreSQL启动前手动建库、配置账号。好处是贴近生产环境Thingsboard很多查询优化、分区表能力需要它才能发挥后续接正式业务也方便迁移。坏处是安装步骤多一点端口、密码、权限任何一环出错都会导致启动失败。我的建议是第一次跑先用H2把流程走通感受一下整个系统启动后的状态然后再决定要不要切到PostgreSQL。文章后面的操作步骤两种模式都会覆盖到你可以按自己的选择走。2.3 用到的辅助工具清单除了JDK和数据库源码构建模式还需要准备几个辅助工具这里列个全乎的免得装到一半发现少了东西MavenJava项目的构建工具用来拉依赖、编译代码、打包。必备。Git从GitHub拉取源码。必备。Node.js编译Angular前端时用。如果只跑后端可以暂不装但是完整构建建议装好。curlWindows 10/11自带用来验证Web服务是否正常响应比单纯看日志更直观。这些工具都没有什么特殊配置难题唯一比较需要花时间的是Maven的镜像设置国内网络下载Maven中央仓库的依赖容易卡这个我在后面“环境准备”章节单独说。3. 环境准备阶段把这些软件装好省得后面哭3.1 JDK 17安装与环境变量配置JDK安装本身没什么好讲的直接去下载JDK 17的安装包一路Next。装完之后最关键的是配置环境变量这步做不好后面所有java命令都会报“不是内部或外部命令”。配置步骤右键“此电脑” - “属性” - “高级系统设置” - “环境变量”。在“系统变量”区域点击“新建”变量名填JAVA_HOME变量值填JDK的实际安装目录例如C:\Program Files\Java\jdk-17。找到Path变量双击它点击“新建”填入%JAVA_HOME%\bin然后一路“确定”保存。重新打开一个命令行窗口输入java -version能看到类似openjdk version 17.x的输出就是成功了。这里我要多提醒一句Windows下修改环境变量后已经在运行的命令行窗口不会自动刷新必须新开窗口验证。踩过坑的人都懂那种“明明配好了但命令还是找不到”的焦虑其实就是没开新窗口。3.2 PostgreSQL安装与数据库初始化如果你选择H2模式这节可以直接跳过。选PostgreSQL的话安装包从官网下载即可安装过程中会要求设置一个超级用户密码默认用户是postgres这个密码后面配置要用到建议就设置成postgres省得后面填配置老错。安装完成后需要创建一个Thingsboard专用的数据库。打开开始菜单里的“SQL Shellpsql”或者用任意PostgreSQL客户端工具执行下面几条SQLCREATE DATABASE thingsboard; ALTER USER postgres WITH PASSWORD postgres;这里有个容易混淆的点ALTER USER这一步是确保你想用的密码和后面配置里填的一致。有些人安装PostgreSQL时顺手设了一个复杂密码结果启动Thingsboard时报密码错误最后排查到怀疑人生。所以干脆统一密码测试阶段没必要折腾复杂密码。PostgreSQL安装完之后默认会注册成Windows系统服务服务名类似postgresql-x64-15。可以通过服务管理器确认它在运行或者命令行执行net start postgresql-x64-15如果提示“服务已经启动”说明数据库服务没问题。3.3 Maven安装和国内镜像配置Maven装起来简单解压压缩包到一个固定目录然后配置环境变量MAVEN_HOME指向解压目录并在Path中加入%MAVEN_HOME%\bin。验证方式是新开命令行窗口执行mvn -v能输出Maven版本、Java版本就算成功。但真正卡人的是依赖下载速度。Maven默认从中央仓库下载依赖库国内网络容易超时或龟速。解决方式是在Maven安装目录的conf/settings.xml里配置镜像。找到mirrors节点在里面加一段mirror idaliyun/id mirrorOfcentral/mirrorOf nameAliyun Maven Central Mirror/name urlhttps://maven.aliyun.com/repository/central/url /mirror这样后续Maven拉包的时候会优先走国内镜像速度会有明显改善。这步属于本地构建环境的常见优化跟项目本身无关但省下的时间够你喝几杯茶了。3.4 环境变量自检清单正式进入源码构建之前建议先开一个命令行窗口把这些命令挨个敲一遍确认环境都到位。我习惯把这一步叫“启动前体检”因为后面所有报错大部分都能在这里提前暴露java -version mvn -version git --version node -v psql --version每一条都应该返回对应版本号。如果某一条报错先停下来解决不要急着继续。说句实在话很多人卡在Thingsboard启动环节不是Thingsboard的问题而是环境没准备好一个java -version就暴露了所有问题。4. 源码构建到首次启动手把手走一遍4.1 拉取源码与切换release分支源码方式第一步是拉代码。用Git命令行执行git clone https://github.com/thingsboard/thingsboard.git cd thingsboard git checkout release-3.5这里我特别提一下“分支选择”。GitHub上默认的master分支可能处于开发状态版本迭代快依赖变化也大并不适合新手直接拿来启动。建议切换到官方维护的release分支比如release-3.5或release-3.6这些分支经过了发版测试稳定性更有保障。切换分支后可以用git status确认当前所在分支再继续下一步。如果你不想从源码构建而是走官方Windows安装包路线逻辑类似去Release页面下载Windows安装包安装到C:\Program Files\Thingsboard然后跳过4.2和4.3直接看4.3之后的配置说明官方安装包会把启动脚本一起装好。4.2 Maven全量构建的完整命令进入源码根目录后执行构建命令。整个Thingsboard工程是一个多模块Maven项目前后端、各个子服务都在同一个仓库里所以构建命令也比较重。推荐先跑mvn clean install -DskipTests参数-DskipTests表示跳过单元测试只做编译和打包能省不少时间。第一次构建会比较慢因为要下载大量依赖几十分钟到一个小时都正常。构建过程中如果卡在某个依赖上长时间没动静就是镜像配置的问题回到3.3节处理。构建完成后在application模块的target目录下可以看到生成的可执行jar包文件名类似thingsboard-3.5.1-boot.jar同时也会生成install.bat、start.bat这些Windows启动脚本。整个源码构建到这里就算完成了。4.3 首次初始化install.bat --loadDemo构建完成或者安装包解压好之后在对应的application目录安装包模式下是安装目录下会找到install.bat和start.bat两个脚本。先运行的是install.bat这个脚本负责初始化数据库结构、导入系统默认数据。如果使用H2模式在运行之前需要先设置一个环境变量让Thingsboard知道你要用H2而不是默认的PostgreSQL。命令行里执行set DATABASE_TYPEh2如果使用PostgreSQL模式则不要设置这个变量保持默认即可但要确认PostgreSQL服务已启动且库和账号密码都对得上。接下来执行初始化install.bat --loadDemo带--loadDemo参数会把示例设备、示例仪表板、示例规则链一起装进去这样启动之后打开界面不会一片空白能看到现成的演示数据。这一步是一次性操作执行成功后数据库的schema就建好了。如果以后想重置重新初始化需要把数据库清理干净再重新执行脚本。有个细节值得注意install.bat运行时有可能会打印一堆SQL执行日志这是正常的只要最后没有出现红色ERROR字样就说明初始化成功了。不要看到一堆日志就以为出错耐心等它跑完。4.4 正式启动start.bat与Web界面验证初始化完成后运行启动脚本start.bat此时命令行窗口会持续输出日志包括Spring Boot的启动过程、各个监听端口绑定的信息等。启动过程通常需要一两分钟看到类似“Started Thingsboard”或者“Netty started on port”之类的日志说明核心服务已经起来了。这时候不要急着关窗口因为窗口关掉等于进程退出。建议新开一个命令行窗口用下面两条命令验证服务状态netstat -ano | findstr :8080 curl http://localhost:8080第一条命令查看8080端口有没有进程在监听第二条命令拿到HTTP响应说明Web服务正常。然后浏览器打开http://localhost:8080会进入Thingsboard登录页面到这一步启动流程已经完成了九成。4.5 默认账号和登录后的第一件事Thingsboard内置了三类默认账号社区版通用第一次登录一定要用对角色登录邮箱密码系统管理员sysadminthingsboard.orgsysadmin租户管理员tenantthingsboard.orgtenant普通客户用户customerthingsboard.orgcustomer我的建议是先用sysadminthingsboard.org登录进去后你会看到“系统管理”菜单包括租户管理、邮件设置等适合先整体看一眼平台架构。再看一眼预置的Dashboard用tenantthingsboard.org登录能看到Demo仪表板里面有几个模拟设备在动态走向上的数据曲线说明整个链路是通的。登录之后第一件事我建议先改掉默认密码尤其是要暴露到外网用的场景。Thingsboard在账户设置里提供了改密码入口改完再继续折腾别的。5. 把Thingsboard注册成Windows服务进阶操作5.1 官方安装包的自动服务注册如果你直接下载官方Windows安装包来装好消息是它已经把“Windows服务注册”这一步做了系统服务列表里会出现Thingsboard相关的服务。这种方式最大的好处是开机可以自动启动不用每次手动跑脚本服务挂了可以自动重启比裸跑控制台稳定日志统一写到安装目录的logs文件夹方便排查服务一旦注册成功你就可以通过Windows服务管理器或者下面的命令来控制它net start thingsboard net stop thingsboard不过需要提醒的是服务方式启动时install.bat --loadDemo依然要在服务第一次启动前手动执行一次因为服务只负责“运行程序”不负责“初始化数据库”。顺序一定不能搞反。5.2 用NSSM手动注册源码版为系统服务源码构建方式没有官方安装包那么方便默认只能通过start.bat前台运行一旦关掉命令行窗口服务就停了。如果想让源码版也变成Windows服务我常用NSSMNon-Sucking Service Manager这个工具来做。NSSM的使用逻辑很直白把“命令行窗口里手动跑的那条命令”包装成一个Windows服务。具体操作步骤下载NSSM解压到本地目录。管理员身份打开命令行执行nssm install Thingsboard在弹出的配置窗口里“Program”填Java可执行文件路径例如C:\Program Files\Java\jdk-17\bin\java.exe“Arguments”填启动参数例如-jar D:\thingsboard\application\target\thingsboard-3.5.1-boot.jar“Startup directory”填jar包所在目录。保存配置然后执行nssm start Thingsboard这样Thingsboard就以Windows服务的方式跑起来了。后来我实际用下来的体会是NSSM这种方式比官方安装包更灵活因为它完全由你自己控制服务名、启动参数、日志输出路径适合那些需要自定义启动参数的二次开发场景。但说实话如果只是单纯使用平台官方安装包更省心服务注册这步我建议能不自己折腾就别折腾。6. 保姆级收尾常见启动问题排查实录6.1 Java版本不对报错千奇百怪根因只有一个Thingsboard启动报错里Java版本问题是最迷惑人的。常见现象包括启动脚本一闪而过什么日志都没留下日志里出现UnsupportedClassVersionError报ClassNotFoundException: org.springframework...或者干脆提示Unable to open nested jar entry BOOT-INF/lib/...这些报错表面看各不相同但根因往往是JDK版本低于要求。我排查这类问题的顺序是第一步看java -version输出第二步看echo %JAVA_HOME%是否正确第三步确认命令行里跑的是不是同一个Java。有几次我遇到诡异问题仔细观察才发现命令行默认的Java被某个软件的安装包改了而JAVA_HOME指向的还是对的前后端不一致那必然出问题。6.2 端口被占用8080/9090/5432被抢Thingsboard启动过程中如果出现端口绑定错误日志里会明确告诉你哪个端口被占用了比如Web server failed to start. Port 8080 was already in use.。这时候别急着改配置文件先看看是什么程序占了端口。netstat -ano | findstr :8080这条命令会输出占用8080端口的进程PID然后用taskkill /PID 12345 /F杀掉对应进程再重新启动Thingsboard。需要注意的是一台机器上占8080端口的程序太多了比如其他Java服务、Tomcat、一些开发工具自带的代理。如果那个进程不能杀那就去改Thingsboard的监听端口配置文件里把server.port改掉再启动。6.3 数据库初始化失败与连接报错数据库相关的报错我遇到的典型有几种报错关键词可能原因处理办法Connection refusedPostgreSQL服务未启动启动PostgreSQL服务Password authentication failed密码与配置不一致重置密码或修改配置Database thingsboard does not exist没有创建对应数据库执行CREATE DATABASEPeer authentication failed用户权限问题确认账号有无访问库权限PostgreSQL模式下最常见的组合错误是数据库没创建、密码不匹配、服务没启动三件事一起来。所以我强烈建议你按照3.2节的步骤先手动建库、确认密码、确认服务状态再执行install.bat。如果在初始化过程中发现已经跑了一半最后报错下次初始化前要把半成品数据清理掉否则数据残留会导致后续步骤冲突。6.4 启动到一半退出日志却只有一行有些新手运行start.bat后控制台闪了一下就没了日志文件里也只有一两行记录这种情况多半是因为install.bat没有执行成功数据库结构还不完整。程序的逻辑是启动时先检查数据库库里面该有的表没有直接就退出根本没有机会打印完整的错误堆栈。排查方式很直接先确认数据库目录或者PostgreSQL里有没有Thingsboard的表如果没有重新执行install.bat --loadDemo要耐心等它完全跑完再回去执行start.bat。如果之前已经运行过一次初始化但中间报错了H2模式下需要去删除本地数据目录再重新初始化PostgreSQL模式下则把thingsboard库删掉重建。6.5 Maven构建卡住或拉包失败构建期间最容易遇到的问题就是依赖下载慢、超时、卡在某个插件上。如果你已经参考3.3节配置了国内镜像一般会好很多。但如果项目刚更新有些依赖在镜像仓库还没同步还是会从中央仓库慢慢拉。这种情况下我一般不做过多干预等就好或者用命令mvn clean install -DskipTests -Dmaven.wagon.http.retryHandler.count3减少重试等待。还有一个提升构建速度的小技巧如果你不需要改前端代码可以只构建后端模块。不过这个操作有几处依赖缩略新手容易漏模块导致启动缺类所以我的建议是第一次老老实实全量构建以后再考虑局部构建。6.6 控制台中文乱码与页面加载慢Windows命令行窗口跑Java程序经常出现中文乱码看着糟心但不影响程序运行。想控制台不乱码可以在运行start.bat前执行chcp 65001把命令行编码切换到UTF-8。另外首次启动时浏览器打开页面会比较慢因为前端静态资源被服务端加载、浏览器端也在解析大量脚本这属于正常现象。如果页面长时间打不开优先看8080端口能否访问再检查控制台日志里有没有明显的异常不要一上来就怀疑程序卡死。对于Windows防火墙拦截Java进程的问题也比较容易遇到。启动之后如果有外设设备要通过MQTT接入Windows会弹窗询问是否允许Java访问网络这时候必须勾选“专用网络”并允许访问否则设备消息就进不来。这个弹窗错过一次之后不好找遇到设备连接不上时记得检查这里。最后再分享一个我个人实际跑下来最深刻的体会Windows上启动Thingsboard这件事三分靠技术七分靠耐心。环境变量、数据库版本、端口占用、初始化顺序每一个小点都可能让你卡几个小时但只要你按顺序把环境准备好、把数据库方案定下来、把安装脚本跑完剩下的其实就是“看日志、查端口、对账号”这三板斧。这个平台本身非常皮实真正出问题的往往是环境而不是Thingsboard本身。先把H2版本跑通一次建立起“启动成功”的信心再考虑迁移到PostgreSQL或部署到服务器你会发现后面的路越走越顺。
Thingsboard在Windows上的安装启动全攻略：从环境配置到常见问题
1. 先把Thingsboard在Windows上的运行逻辑说清楚1.1 Thingsboard到底是个什么东西为什么大家都想跑起来Thingsboard是一套开源的物联网平台这几年在设备接入、数据可视化、规则链编排、多租户权限管理这些场景里几乎成了标配。做硬件开发的人拿它来快速看设备上报数据做系统集成的人拿它在POC阶段跟客户演示“你的设备数据长这样”做平台研发的人则拿它当底座在上面做二次开发。一句话概括它把“设备连接、数据存储、界面展示、业务规则”这四件事打包好了你能在浏览器里看到实时数据也能写规则链让平台自动处理告警。但很多人一提到Thingsboard第一反应就是Linux服务器、Docker容器、一堆命令行。实际上在Windows上完全能把它跑起来而且流程固定下来之后并不复杂。尤其是个人电脑做原型验证、传感器调试、前端样式修改Windows环境反而是最顺手的地方。1.2 在Windows上启动的三条路线怎么选目前想在Windows上把一个Thingsboard服务拉起来主流有三条路我分别列一下选型思路后面细说。路线操作方式适合人群踩坑指数官方Windows安装包下载MSI安装包按向导安装自动注册系统服务只关心功能不想碰源码的人中低源码构建拉GitHub源码用Maven构建再运行启动脚本需要二次开发、改代码、学习内部结构的人中高Docker Desktop跑容器用docker-compose拉取官方镜像熟悉Docker、需要快速部署的人中我个人的建议是如果你只是想先把Thingsboard跑起来看一看界面、接一两个设备测试下功能直接走官方Windows安装包或者Docker如果你打算二次开发或者想搞清楚它的数据库结构、服务启动细节那就老老实实走源码构建。本文后面主要按源码构建和安装包两条主线来讲因为这两条线最能让你理解Thingsboard的启动原理排查问题的时候也知道去哪里看。1.3 启动的本质你其实在运行一个Java Web服务别被“物联网平台”这四个字吓到剥开来看Thingsboard就是一个典型的Java后端服务加上一套Angular前端页面。它的核心进程就是嵌入式Tomcat或者说Spring Boot应用监听8080端口提供Web服务同时监听1883端口接收MQTT设备消息、监听5683端口用于CoAP接入。所以你启动Thingsboard本质上就是完成三件事把Java运行环境准备好、把数据库准备好、把编译好的程序跑起来。理解了这一点后面所有报错你都能找到大方向——不是环境问题就是数据库问题再就是程序本身启动顺序问题。在Windows上之所以容易卡住是因为大家习惯了Linux下“写脚本、跑服务”的模式到了Windows就忘了环境变量、路径格式、防火墙这些小事恰恰是这些小事最容易翻车。2. 动手前的版本和数据库选型决定了你能不能一次跑通2.1 Thingsboard版本与JDK版本的对应关系这里必须先说一个最常见的坑Thingsboard不同版本对Java版本的要求差别很大。2.x时代用JDK 8完全没问题但从3.2版本开始切换到了Java 113.5版本以后又逐步要求JDK 17。如果你拿JDK 8去跑新版Thingsboard启动的时候会看到类似UnsupportedClassVersionError或者直接提示class文件版本52.0不支持。这种错误最迷惑人因为它不是“环境变量没配好”那种一眼能看出来的问题。以目前主流的3.5.x、3.6.x版本为例要求如下JavaJDK 17必须配置好JAVA_HOMEPostgreSQL12及以上如果用PostgreSQL作为数据库Maven3.6.3及以上Node.js16及以上仅源码构建前端时需要Git无硬性版本要求所以动手之前先确认你要装哪个版本的Thingsboard再回头准备对应的JDK。不要先装了最新JDK又回头用老版本也不要拿JDK 8硬跑新版本。版本对应关系我建议以官方Release分支为准比如拉release-3.5分支就在该分支的README或文档里确认要求的Java版本。2.2 数据库选型H2快速体验还是PostgreSQL一步到位Thingsboard支持两种主流的数据库方案一种是内置的H2嵌入式数据库另一种是PostgreSQL独立数据库服务。这个选型决定后面一大半的安装步骤必须先定下来。H2模式数据库跟着Thingsboard跑数据文件直接写在本地目录。好处是零安装不用单独装数据库软件对新手来说最友好坏处是性能上限低部分高级功能受限官方也不建议生产环境使用。如果你的诉求只是“把平台跑起来看看长什么样、接两个模拟设备验证流程”H2完全够用。PostgreSQL模式独立安装PostgreSQL启动前手动建库、配置账号。好处是贴近生产环境Thingsboard很多查询优化、分区表能力需要它才能发挥后续接正式业务也方便迁移。坏处是安装步骤多一点端口、密码、权限任何一环出错都会导致启动失败。我的建议是第一次跑先用H2把流程走通感受一下整个系统启动后的状态然后再决定要不要切到PostgreSQL。文章后面的操作步骤两种模式都会覆盖到你可以按自己的选择走。2.3 用到的辅助工具清单除了JDK和数据库源码构建模式还需要准备几个辅助工具这里列个全乎的免得装到一半发现少了东西MavenJava项目的构建工具用来拉依赖、编译代码、打包。必备。Git从GitHub拉取源码。必备。Node.js编译Angular前端时用。如果只跑后端可以暂不装但是完整构建建议装好。curlWindows 10/11自带用来验证Web服务是否正常响应比单纯看日志更直观。这些工具都没有什么特殊配置难题唯一比较需要花时间的是Maven的镜像设置国内网络下载Maven中央仓库的依赖容易卡这个我在后面“环境准备”章节单独说。3. 环境准备阶段把这些软件装好省得后面哭3.1 JDK 17安装与环境变量配置JDK安装本身没什么好讲的直接去下载JDK 17的安装包一路Next。装完之后最关键的是配置环境变量这步做不好后面所有java命令都会报“不是内部或外部命令”。配置步骤右键“此电脑” - “属性” - “高级系统设置” - “环境变量”。在“系统变量”区域点击“新建”变量名填JAVA_HOME变量值填JDK的实际安装目录例如C:\Program Files\Java\jdk-17。找到Path变量双击它点击“新建”填入%JAVA_HOME%\bin然后一路“确定”保存。重新打开一个命令行窗口输入java -version能看到类似openjdk version 17.x的输出就是成功了。这里我要多提醒一句Windows下修改环境变量后已经在运行的命令行窗口不会自动刷新必须新开窗口验证。踩过坑的人都懂那种“明明配好了但命令还是找不到”的焦虑其实就是没开新窗口。3.2 PostgreSQL安装与数据库初始化如果你选择H2模式这节可以直接跳过。选PostgreSQL的话安装包从官网下载即可安装过程中会要求设置一个超级用户密码默认用户是postgres这个密码后面配置要用到建议就设置成postgres省得后面填配置老错。安装完成后需要创建一个Thingsboard专用的数据库。打开开始菜单里的“SQL Shellpsql”或者用任意PostgreSQL客户端工具执行下面几条SQLCREATE DATABASE thingsboard; ALTER USER postgres WITH PASSWORD postgres;这里有个容易混淆的点ALTER USER这一步是确保你想用的密码和后面配置里填的一致。有些人安装PostgreSQL时顺手设了一个复杂密码结果启动Thingsboard时报密码错误最后排查到怀疑人生。所以干脆统一密码测试阶段没必要折腾复杂密码。PostgreSQL安装完之后默认会注册成Windows系统服务服务名类似postgresql-x64-15。可以通过服务管理器确认它在运行或者命令行执行net start postgresql-x64-15如果提示“服务已经启动”说明数据库服务没问题。3.3 Maven安装和国内镜像配置Maven装起来简单解压压缩包到一个固定目录然后配置环境变量MAVEN_HOME指向解压目录并在Path中加入%MAVEN_HOME%\bin。验证方式是新开命令行窗口执行mvn -v能输出Maven版本、Java版本就算成功。但真正卡人的是依赖下载速度。Maven默认从中央仓库下载依赖库国内网络容易超时或龟速。解决方式是在Maven安装目录的conf/settings.xml里配置镜像。找到mirrors节点在里面加一段mirror idaliyun/id mirrorOfcentral/mirrorOf nameAliyun Maven Central Mirror/name urlhttps://maven.aliyun.com/repository/central/url /mirror这样后续Maven拉包的时候会优先走国内镜像速度会有明显改善。这步属于本地构建环境的常见优化跟项目本身无关但省下的时间够你喝几杯茶了。3.4 环境变量自检清单正式进入源码构建之前建议先开一个命令行窗口把这些命令挨个敲一遍确认环境都到位。我习惯把这一步叫“启动前体检”因为后面所有报错大部分都能在这里提前暴露java -version mvn -version git --version node -v psql --version每一条都应该返回对应版本号。如果某一条报错先停下来解决不要急着继续。说句实在话很多人卡在Thingsboard启动环节不是Thingsboard的问题而是环境没准备好一个java -version就暴露了所有问题。4. 源码构建到首次启动手把手走一遍4.1 拉取源码与切换release分支源码方式第一步是拉代码。用Git命令行执行git clone https://github.com/thingsboard/thingsboard.git cd thingsboard git checkout release-3.5这里我特别提一下“分支选择”。GitHub上默认的master分支可能处于开发状态版本迭代快依赖变化也大并不适合新手直接拿来启动。建议切换到官方维护的release分支比如release-3.5或release-3.6这些分支经过了发版测试稳定性更有保障。切换分支后可以用git status确认当前所在分支再继续下一步。如果你不想从源码构建而是走官方Windows安装包路线逻辑类似去Release页面下载Windows安装包安装到C:\Program Files\Thingsboard然后跳过4.2和4.3直接看4.3之后的配置说明官方安装包会把启动脚本一起装好。4.2 Maven全量构建的完整命令进入源码根目录后执行构建命令。整个Thingsboard工程是一个多模块Maven项目前后端、各个子服务都在同一个仓库里所以构建命令也比较重。推荐先跑mvn clean install -DskipTests参数-DskipTests表示跳过单元测试只做编译和打包能省不少时间。第一次构建会比较慢因为要下载大量依赖几十分钟到一个小时都正常。构建过程中如果卡在某个依赖上长时间没动静就是镜像配置的问题回到3.3节处理。构建完成后在application模块的target目录下可以看到生成的可执行jar包文件名类似thingsboard-3.5.1-boot.jar同时也会生成install.bat、start.bat这些Windows启动脚本。整个源码构建到这里就算完成了。4.3 首次初始化install.bat --loadDemo构建完成或者安装包解压好之后在对应的application目录安装包模式下是安装目录下会找到install.bat和start.bat两个脚本。先运行的是install.bat这个脚本负责初始化数据库结构、导入系统默认数据。如果使用H2模式在运行之前需要先设置一个环境变量让Thingsboard知道你要用H2而不是默认的PostgreSQL。命令行里执行set DATABASE_TYPEh2如果使用PostgreSQL模式则不要设置这个变量保持默认即可但要确认PostgreSQL服务已启动且库和账号密码都对得上。接下来执行初始化install.bat --loadDemo带--loadDemo参数会把示例设备、示例仪表板、示例规则链一起装进去这样启动之后打开界面不会一片空白能看到现成的演示数据。这一步是一次性操作执行成功后数据库的schema就建好了。如果以后想重置重新初始化需要把数据库清理干净再重新执行脚本。有个细节值得注意install.bat运行时有可能会打印一堆SQL执行日志这是正常的只要最后没有出现红色ERROR字样就说明初始化成功了。不要看到一堆日志就以为出错耐心等它跑完。4.4 正式启动start.bat与Web界面验证初始化完成后运行启动脚本start.bat此时命令行窗口会持续输出日志包括Spring Boot的启动过程、各个监听端口绑定的信息等。启动过程通常需要一两分钟看到类似“Started Thingsboard”或者“Netty started on port”之类的日志说明核心服务已经起来了。这时候不要急着关窗口因为窗口关掉等于进程退出。建议新开一个命令行窗口用下面两条命令验证服务状态netstat -ano | findstr :8080 curl http://localhost:8080第一条命令查看8080端口有没有进程在监听第二条命令拿到HTTP响应说明Web服务正常。然后浏览器打开http://localhost:8080会进入Thingsboard登录页面到这一步启动流程已经完成了九成。4.5 默认账号和登录后的第一件事Thingsboard内置了三类默认账号社区版通用第一次登录一定要用对角色登录邮箱密码系统管理员sysadminthingsboard.orgsysadmin租户管理员tenantthingsboard.orgtenant普通客户用户customerthingsboard.orgcustomer我的建议是先用sysadminthingsboard.org登录进去后你会看到“系统管理”菜单包括租户管理、邮件设置等适合先整体看一眼平台架构。再看一眼预置的Dashboard用tenantthingsboard.org登录能看到Demo仪表板里面有几个模拟设备在动态走向上的数据曲线说明整个链路是通的。登录之后第一件事我建议先改掉默认密码尤其是要暴露到外网用的场景。Thingsboard在账户设置里提供了改密码入口改完再继续折腾别的。5. 把Thingsboard注册成Windows服务进阶操作5.1 官方安装包的自动服务注册如果你直接下载官方Windows安装包来装好消息是它已经把“Windows服务注册”这一步做了系统服务列表里会出现Thingsboard相关的服务。这种方式最大的好处是开机可以自动启动不用每次手动跑脚本服务挂了可以自动重启比裸跑控制台稳定日志统一写到安装目录的logs文件夹方便排查服务一旦注册成功你就可以通过Windows服务管理器或者下面的命令来控制它net start thingsboard net stop thingsboard不过需要提醒的是服务方式启动时install.bat --loadDemo依然要在服务第一次启动前手动执行一次因为服务只负责“运行程序”不负责“初始化数据库”。顺序一定不能搞反。5.2 用NSSM手动注册源码版为系统服务源码构建方式没有官方安装包那么方便默认只能通过start.bat前台运行一旦关掉命令行窗口服务就停了。如果想让源码版也变成Windows服务我常用NSSMNon-Sucking Service Manager这个工具来做。NSSM的使用逻辑很直白把“命令行窗口里手动跑的那条命令”包装成一个Windows服务。具体操作步骤下载NSSM解压到本地目录。管理员身份打开命令行执行nssm install Thingsboard在弹出的配置窗口里“Program”填Java可执行文件路径例如C:\Program Files\Java\jdk-17\bin\java.exe“Arguments”填启动参数例如-jar D:\thingsboard\application\target\thingsboard-3.5.1-boot.jar“Startup directory”填jar包所在目录。保存配置然后执行nssm start Thingsboard这样Thingsboard就以Windows服务的方式跑起来了。后来我实际用下来的体会是NSSM这种方式比官方安装包更灵活因为它完全由你自己控制服务名、启动参数、日志输出路径适合那些需要自定义启动参数的二次开发场景。但说实话如果只是单纯使用平台官方安装包更省心服务注册这步我建议能不自己折腾就别折腾。6. 保姆级收尾常见启动问题排查实录6.1 Java版本不对报错千奇百怪根因只有一个Thingsboard启动报错里Java版本问题是最迷惑人的。常见现象包括启动脚本一闪而过什么日志都没留下日志里出现UnsupportedClassVersionError报ClassNotFoundException: org.springframework...或者干脆提示Unable to open nested jar entry BOOT-INF/lib/...这些报错表面看各不相同但根因往往是JDK版本低于要求。我排查这类问题的顺序是第一步看java -version输出第二步看echo %JAVA_HOME%是否正确第三步确认命令行里跑的是不是同一个Java。有几次我遇到诡异问题仔细观察才发现命令行默认的Java被某个软件的安装包改了而JAVA_HOME指向的还是对的前后端不一致那必然出问题。6.2 端口被占用8080/9090/5432被抢Thingsboard启动过程中如果出现端口绑定错误日志里会明确告诉你哪个端口被占用了比如Web server failed to start. Port 8080 was already in use.。这时候别急着改配置文件先看看是什么程序占了端口。netstat -ano | findstr :8080这条命令会输出占用8080端口的进程PID然后用taskkill /PID 12345 /F杀掉对应进程再重新启动Thingsboard。需要注意的是一台机器上占8080端口的程序太多了比如其他Java服务、Tomcat、一些开发工具自带的代理。如果那个进程不能杀那就去改Thingsboard的监听端口配置文件里把server.port改掉再启动。6.3 数据库初始化失败与连接报错数据库相关的报错我遇到的典型有几种报错关键词可能原因处理办法Connection refusedPostgreSQL服务未启动启动PostgreSQL服务Password authentication failed密码与配置不一致重置密码或修改配置Database thingsboard does not exist没有创建对应数据库执行CREATE DATABASEPeer authentication failed用户权限问题确认账号有无访问库权限PostgreSQL模式下最常见的组合错误是数据库没创建、密码不匹配、服务没启动三件事一起来。所以我强烈建议你按照3.2节的步骤先手动建库、确认密码、确认服务状态再执行install.bat。如果在初始化过程中发现已经跑了一半最后报错下次初始化前要把半成品数据清理掉否则数据残留会导致后续步骤冲突。6.4 启动到一半退出日志却只有一行有些新手运行start.bat后控制台闪了一下就没了日志文件里也只有一两行记录这种情况多半是因为install.bat没有执行成功数据库结构还不完整。程序的逻辑是启动时先检查数据库库里面该有的表没有直接就退出根本没有机会打印完整的错误堆栈。排查方式很直接先确认数据库目录或者PostgreSQL里有没有Thingsboard的表如果没有重新执行install.bat --loadDemo要耐心等它完全跑完再回去执行start.bat。如果之前已经运行过一次初始化但中间报错了H2模式下需要去删除本地数据目录再重新初始化PostgreSQL模式下则把thingsboard库删掉重建。6.5 Maven构建卡住或拉包失败构建期间最容易遇到的问题就是依赖下载慢、超时、卡在某个插件上。如果你已经参考3.3节配置了国内镜像一般会好很多。但如果项目刚更新有些依赖在镜像仓库还没同步还是会从中央仓库慢慢拉。这种情况下我一般不做过多干预等就好或者用命令mvn clean install -DskipTests -Dmaven.wagon.http.retryHandler.count3减少重试等待。还有一个提升构建速度的小技巧如果你不需要改前端代码可以只构建后端模块。不过这个操作有几处依赖缩略新手容易漏模块导致启动缺类所以我的建议是第一次老老实实全量构建以后再考虑局部构建。6.6 控制台中文乱码与页面加载慢Windows命令行窗口跑Java程序经常出现中文乱码看着糟心但不影响程序运行。想控制台不乱码可以在运行start.bat前执行chcp 65001把命令行编码切换到UTF-8。另外首次启动时浏览器打开页面会比较慢因为前端静态资源被服务端加载、浏览器端也在解析大量脚本这属于正常现象。如果页面长时间打不开优先看8080端口能否访问再检查控制台日志里有没有明显的异常不要一上来就怀疑程序卡死。对于Windows防火墙拦截Java进程的问题也比较容易遇到。启动之后如果有外设设备要通过MQTT接入Windows会弹窗询问是否允许Java访问网络这时候必须勾选“专用网络”并允许访问否则设备消息就进不来。这个弹窗错过一次之后不好找遇到设备连接不上时记得检查这里。最后再分享一个我个人实际跑下来最深刻的体会Windows上启动Thingsboard这件事三分靠技术七分靠耐心。环境变量、数据库版本、端口占用、初始化顺序每一个小点都可能让你卡几个小时但只要你按顺序把环境准备好、把数据库方案定下来、把安装脚本跑完剩下的其实就是“看日志、查端口、对账号”这三板斧。这个平台本身非常皮实真正出问题的往往是环境而不是Thingsboard本身。先把H2版本跑通一次建立起“启动成功”的信心再考虑迁移到PostgreSQL或部署到服务器你会发现后面的路越走越顺。