2、开发环境搭建：JDK安装、PostgreSQL安装、ThingsBoard源码编译、本地启动

好，咱们正式开始动手了。

这一章，说白了就是「把家伙事儿备齐」。很多新手在 ThingsBoard 上栽跟头，不是代码写不对，而是环境没搭好。我见过太多人卡在 PostgreSQL 连不上、Maven 编译到一半报错，然后就开始怀疑人生。

别急，跟着我的节奏来。我把自己踩过的坑、绕过的路，都揉进这一章里。你照着做，基本一次过。

2.1 JDK 安装：版本选对，事半功倍

ThingsBoard 3.x 系列，官方推荐 JDK 11。我个人习惯用 OpenJDK 11，稳定、没版权问题。

⚠️ 注意： 别用 JDK 8，也别用 JDK 17 以上的版本。JDK 8 缺模块，JDK 17 有些 API 被删了，编译时会报错。我当初图新鲜试过 JDK 17，结果编译到一半卡在 java.xml.bind 包上，折腾了两小时才换回来。

安装步骤（Linux / macOS）

# 下载 OpenJDK 11
wget https://github.com/AdoptOpenJDK/openjdk11-binaries/releases/download/jdk-11.0.11%2B9/OpenJDK11U-jdk_x64_linux_hotspot_11.0.11_9.tar.gz

# 解压到 /usr/local
sudo tar -zxvf OpenJDK11U-jdk_x64_linux_hotspot_11.0.11_9.tar.gz -C /usr/local/

# 配置环境变量
export JAVA_HOME=/usr/local/jdk-11.0.11+9
export PATH=$JAVA_HOME/bin:$PATH

安装步骤（Windows）

直接去 Adoptium 官网 下载 msi 安装包，一路下一步就行。安装完后记得配一下环境变量：

JAVA_HOME = C:\Program Files\Eclipse Adoptium\jdk-11.0.11.9-hotspot
PATH 里加上 %JAVA_HOME%\bin

验证一下：

java -version
# 输出类似：openjdk version "11.0.11" 2021-04-20
💡 我的小技巧： 我习惯在 ~/.bashrc 或 ~/.zshrc 里写死 JAVA_HOME，这样每次打开终端不用重新 export。你想想看，要是每次编译前都要敲一遍，多烦人。

2.2 PostgreSQL 安装：数据库是 ThingsBoard 的「胃」

ThingsBoard 用 PostgreSQL 存设备数据、用户信息、规则链配置。没有它，ThingsBoard 就是个空壳。

版本选择

官方推荐 PostgreSQL 12+。我用的是 14，目前跑了一年多，没出过问题。

安装（以 Ubuntu 为例）

# 添加官方源
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get install postgresql-14

# 启动服务
sudo systemctl start postgresql
sudo systemctl enable postgresql

创建数据库和用户

# 切换到 postgres 用户
sudo -i -u postgres

# 创建用户（密码自己记好）
createuser thingsboard -P

# 创建数据库
createdb thingsboard -O thingsboard
⚠️ 我曾经踩过的坑： 创建用户时忘了设密码，结果 ThingsBoard 启动时连不上数据库，报错信息又很模糊。后来查了半天才发现是认证方式不对。建议你创建用户时一定要加 -P 参数，手动输入密码。

验证一下：

psql -U thingsboard -d thingsboard -h localhost
# 输入密码后能进入 psql 命令行，就说明成功了

2.3 ThingsBoard 源码编译：Maven 是核心

源码编译，说白了就是用 Maven 把 Java 代码打包成可运行的 jar 包。这一步最考验耐心，因为 Maven 会下载一大堆依赖，网络不好就容易超时。

克隆源码

git clone https://github.com/thingsboard/thingsboard.git
cd thingsboard

我个人习惯切到最新的稳定版分支，比如 3.6.2：

git checkout release-3.6.2

编译命令

mvn clean install -DskipTests -Dnpm.skip=true

这里解释一下参数：

  • -DskipTests：跳过单元测试，节省时间。我第一次编译时没加这个参数，结果跑了半小时测试，还挂了几个，心态直接崩了。
  • -Dnpm.skip=true：跳过前端 npm 构建。我们后面单独搞前端，这里先不管。
💡 避坑指南： 如果你在编译过程中遇到「下载依赖超时」或「SSL 证书错误」，八成是 Maven 镜像源的问题。我建议你修改 ~/.m2/settings.xml，加上阿里云镜像： 
<mirror>
  <id>aliyunmaven</id>
  <mirrorOf>*</mirrorOf>
  <name>阿里云公共仓库</name>
  <url>https://maven.aliyun.com/repository/public</url>
</mirror>

编译成功后的产物

编译完成后，在 application/target 目录下会生成一个 thingsboard-3.6.2-boot.jar。这个就是我们要的东西。

2.4 本地启动：终于跑起来了

编译成功只是第一步，能启动才算真正搭好环境。

配置数据库连接

在 application/src/main/resources 目录下，找到 thingsboard.yml，修改数据库配置：

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/thingsboard
    username: thingsboard
    password: 你刚才设的密码
    driver-class-name: org.postgresql.Driver

启动命令

cd application/target
java -jar thingsboard-3.6.2-boot.jar

启动日志会刷刷刷地往上滚。看到类似这样的输出，就说明成功了：

2024-01-15 10:23:45.123  INFO 12345 --- [main] o.t.s.ThingsboardServerApplication : Started ThingsboardServerApplication in 45.789 seconds
🎉 启动成功后： 打开浏览器，访问 http://localhost:8080，就能看到 ThingsBoard 的登录页面了。默认账号是 sysadmin@thingsboard.org，密码是 sysadmin。

常见启动失败原因

错误现象 原因 解决办法
数据库连接失败 PostgreSQL 没启动，或用户名密码不对 检查 PostgreSQL 服务状态，确认配置
端口被占用 8080 端口已被其他程序占用 用 lsof -i:8080 查看，杀掉占用进程
内存不足 ThingsBoard 默认需要 2G 内存 启动时加 -Xmx1g 参数限制内存
⚠️ 最后提醒一句： 本地启动时，建议用 Ctrl+C 正常关闭，别直接关终端。否则数据库连接池可能没释放干净，下次启动会报错。我当初偷懒直接关窗口，结果数据库里残留了一堆死连接，重启了三次才恢复正常。

好了，环境搭好了，下一章我们开始真正写代码。你想想看，从零到能跑起一个 ThingsBoard 实例，是不是也没那么难？

← 上一章 📖 返回目录 下一章 →