2、环境准备：安装Docker、Java、Maven、Node.js等开发环境，配置虚拟机或云服务器，准备数据库（PostgreSQL/Cassandra）

ThingsBoard 作为一款开源的物联网平台，其核心架构由 Java 后端服务、前端 UI（基于 Angular/TypeScript）、消息队列（Kafka/RabbitMQ）以及数据库（PostgreSQL 或 Cassandra）构成。在开始二次开发之前，搭建一套稳定、可复现的开发环境是后续所有工作的基础。本章将围绕开发环境的搭建展开，涵盖虚拟机/云服务器选型、基础工具链安装、数据库配置以及 ThingsBoard 源码编译前的环境校验。我们将以 Ubuntu 22.04 LTS 作为标准操作系统，兼顾稳定性与社区支持度。

2.1 虚拟机与云服务器选型：开发环境的“地基”

核心原理

ThingsBoard 的微服务架构（Transport、Rule Engine、Web UI 等模块）在开发调试时需要占用较多内存和 CPU。若直接使用个人电脑作为宿主机，操作系统差异、环境变量冲突、端口占用等问题会显著降低开发效率。虚拟机或云服务器提供了隔离的、可快照回滚的独立环境，确保开发环境与日常办公环境互不干扰。云服务器还具备弹性伸缩和公网访问能力，便于后续部署 IoT 设备模拟器进行联调。

判断方法与操作流程

操作流程（以 VirtualBox 为例）：

1. 下载 Ubuntu 22.04 LTS 桌面版 ISO 镜像（约 4.5GB）。
2. 新建虚拟机，分配 4 核 CPU、6GB 内存、50GB 动态磁盘。
3. 网络模式选择“桥接网卡”，确保虚拟机与宿主机在同一网段，便于 SSH 连接。
4. 安装系统时选择“最小安装”，避免安装不必要的图形软件包。
5. 安装完成后执行 sudo apt update && sudo apt upgrade -y 更新系统。

2.2 核心工具链安装：Java、Maven、Node.js 与 Docker

核心原理

ThingsBoard 后端基于 Spring Boot 框架，依赖 Java 11 编译运行；前端使用 Angular 框架，需要 Node.js 环境进行依赖安装和构建。Maven 负责管理 Java 项目的依赖和构建生命周期。Docker 则用于快速启动 PostgreSQL、Cassandra 等中间件，避免在宿主机上直接安装数据库导致的环境污染。版本选择上，ThingsBoard 3.x 分支要求 Java 11，Node.js 16.x 是 Angular 12 的兼容版本。

安装命令与验证

# 1. 安装 OpenJDK 11
sudo apt install -y openjdk-11-jdk
java -version  # 验证输出包含 "11.0.x"

# 2. 安装 Maven 3.8.x
sudo apt install -y maven
mvn -version   # 验证输出包含 "Apache Maven 3.8.x"

# 3. 安装 Node.js 16.x (使用 NodeSource 源)
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install -y nodejs
node -v        # 验证输出 v16.20.x
npm -v         # 验证输出 8.x

# 4. 安装 Docker 与 Docker Compose
sudo apt install -y docker.io docker-compose-v2
sudo systemctl enable --now docker
docker --version  # 验证输出 "Docker version 24.x"
docker compose version  # 验证输出 "Docker Compose version v2.x"

案例拆解：Maven 依赖下载缓慢的解决方案

背景与约束： 在编译 ThingsBoard 源码时，Maven 需要从 Maven Central 下载数百个依赖包。国内网络环境下，默认中央仓库下载速度常低于 50KB/s，导致编译超时失败。

分析判断： 通过 mvn -X 调试日志发现，大量请求阻塞在 repo.maven.apache.org。解决方案是配置阿里云镜像仓库。

操作步骤： 编辑 ~/.m2/settings.xml，添加以下镜像配置：

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

结果对比： 配置后，依赖下载速度提升至 2-5MB/s，编译时间从 40 分钟缩短至 8 分钟。此配置同样适用于后续的 CI/CD 流水线。

2.3 数据库准备：PostgreSQL 与 Cassandra 的部署策略

核心原理

ThingsBoard 支持两种数据库模式：混合模式（默认）使用 PostgreSQL 存储实体数据（设备、资产、用户）和最近一段时间的事件数据，使用 Cassandra 存储历史遥测数据；单数据库模式则仅使用 PostgreSQL 存储所有数据，适用于数据量较小的开发环境。开发阶段建议使用混合模式，以贴近生产环境架构。

数据库部署流程

使用 Docker Compose 一键启动数据库服务，避免手动安装配置的繁琐步骤。创建 docker-compose.yml 文件：

version: '3.0'
services:
  postgres:
    image: postgres:12
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_USER: tb_user
      POSTGRES_PASSWORD: tb_password
    ports:
      - "5432:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
  cassandra:
    image: cassandra:3.11
    ports:
      - "9042:9042"
    volumes:
      - cassandra-data:/var/lib/cassandra
volumes:
  postgres-data:
  cassandra-data:

执行 docker compose up -d 启动服务。验证连接：

# 验证 PostgreSQL
psql -h localhost -U tb_user -d thingsboard -c "SELECT version();"
# 验证 Cassandra
cqlsh localhost 9042 -e "SELECT release_version FROM system.local;"

常见误区与复盘

• 误区一： 使用 PostgreSQL 14 或 15 版本。ThingsBoard 3.3 之前版本对 PostgreSQL 12 支持最佳，高版本可能因数据类型变更导致迁移脚本失败。
• 误区二： 忽略 Cassandra 的 JVM 堆内存设置。Cassandra 默认占用 4GB 内存，若开发机内存不足，需在 docker-compose.yml 中设置 MAX_HEAP_SIZE=1G 和 HEAP_NEWSIZE=256M 环境变量。
• 复盘： 数据库容器应设置 restart: unless-stopped 策略，避免宿主机重启后数据库未启动导致 ThingsBoard 服务启动失败。

2.4 环境校验与 ThingsBoard 源码编译

核心原理

环境准备是否成功，最终需要通过编译 ThingsBoard 源码来验证。源码编译不仅校验了 Java、Maven、Node.js 的版本兼容性，还会触发前端构建流程，验证 npm 依赖安装是否完整。编译产物将直接用于后续的二次开发调试。

编译操作流程

# 1. 克隆 ThingsBoard 源码（指定稳定分支）
git clone -b release-3.3 https://github.com/thingsboard/thingsboard.git
cd thingsboard

# 2. 编译后端 Java 代码（跳过测试）
mvn clean install -DskipTests -Dlicense.skip=true

# 3. 编译前端 UI（进入 UI 目录）
cd ui-ngx
npm install --registry=https://registry.npmmirror.com
npm run build:dev

# 4. 启动 ThingsBoard（开发模式）
cd ..
mvn spring-boot:run -pl application

案例拆解：前端编译内存溢出（JavaScript heap out of memory）

背景与约束： 执行 npm run build:dev 时，Node.js 默认堆内存上限约 1.5GB，而 ThingsBoard 前端项目包含大量 Angular 组件和第三方库，编译过程中内存占用峰值可达 3GB。

初始现象： 编译进行到约 70% 时抛出 FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory。

分析判断： 通过 node --max-old-space-size=4096 参数可以临时提升内存上限，但更优雅的方式是在 package.json 的构建脚本中配置 NODE_OPTIONS 环境变量。

实际操作： 修改 ui-ngx/package.json 中的构建脚本：

"scripts": {
  "build:dev": "NODE_OPTIONS=--max-old-space-size=4096 ng build --configuration development"
}

结果对比： 重新执行构建，编译顺利通过，耗时约 3 分钟。此问题在 16GB 内存的机器上仍可能出现，建议开发机内存不低于 16GB。