第二章、ThingsBoard 安装
整理自《第二章、ThingsBoard 安装》原稿。本课以 ThingsBoard 4.4.0 为例。
Windows 安装包流程与本站 Windows上安装ThingsBoard(4.3.1 / JDK 17 / PG 16)高度相似;本章按 4.4 统一版更新版本号,并补充 License 激活、源码与 Docker 路径。
2.0、概述
4.4 之前,ThingsBoard 区分 CE 与 PE。从 4.4.0 起,官方将两套合并为统一平台(能力侧更接近原 PE 能力集:白标、更细权限与分组、Integrations、调度器、部分规则/报表能力等——以当前版本界面与许可为准)。
同时,开源/源码可得协议与计费模型发生变化(BUSL 等)。合并原因与许可说明见官方博文:

概念入门可先看本专栏 第一章、概述。下面开始安装。
| 安装方式 | 适合谁 | 本章环境要点 |
|---|---|---|
| Windows 官方 zip + 服务 | 快速体验、本机演示 | JDK 25、PostgreSQL 18、包 v4.4 |
| Windows 源码 + IDEA | 阅读源码、定制开发 | 另需 Maven、IDEA;可复用同一套 JDK/PG |
| Ubuntu Docker Compose | 服务器 / 接近生产演练 | 官方 tb-node:4.4.0 等镜像 |
2.1、Windows 快速安装启动
整体步骤与 Windows上安装ThingsBoard 一致:清旧服务 → 装 JDK → 装 PostgreSQL 并建库 → 改 yml → install.bat → net start → 浏览器登录。差别主要在 JDK/PG/ThingsBoard 版本,以及首次进入后的 License 激活页。
2.1.0、检查是否安装过旧服务
若本机装过 ThingsBoard Windows 服务,建议先清理,避免冲突。
Win + R,输入regedit,回车。




- 定位到:
计算机\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\thingsboard- 没有该键:可跳过。
- 有该键:删除后重启电脑再继续。

更细的截图说明也可对照 CE 文 §1.1 检查旧服务。
2.1.1、环境要求
| 组件 | 本课示例 |
|---|---|
| JDK | 25(4.4 线路官方强调 Java 25) |
| PostgreSQL | 18 |
| Maven | 3.9.x(源码编译需要;仅用 Windows 安装包可暂不装) |
| IDEA | 2024/2025+(源码调试推荐) |
JDK 25
请从可信发行版下载 Windows x64 安装包,例如 Eclipse Temurin 或其它官方构建,按向导下一步安装。

安装后在 cmd 中验证:
java --version应能看到 Java 25 相关输出。验证方式与 CE 文 §1.3 相同,只是版本号不同。
Maven 3.9.x(源码路径需要)
- 从 Maven 下载页 下载 Binary zip。


- 解压到固定目录,并新建本地仓库目录(如
repository)。

- 编辑
conf/settings.xml,把localRepository指到该目录。


- 将 Maven 的
bin加入系统 PATH。


- 验证:
mvn -v
PostgreSQL 18
安装思路与 CE 文 §1.4~1.5 相同,请改用 PostgreSQL 18 安装包:


用 pgAdmin 创建数据库:
thingsboard记住超级用户密码与端口(默认 5432;若改端口,后面 thingsboard.yml 必须一致)。学习环境可暂用简单密码,生产请用强密码。
IDEA(源码路径)
从 JetBrains IDEA 下载页 安装即可。

2.1.2、下载 thingsboard-windows 包
打开 Release:
https://github.com/thingsboard/thingsboard/releases/tag/v4.4下载 Windows 安装包并解压到固定目录(如 D:\thingsboard 或 Downloads\thingsboard-windows-4.4\thingsboard)。




进入 conf,用文本编辑器打开 thingsboard.yml,确认数据源类似:
url: "${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/thingsboard}"
username: "${SPRING_DATASOURCE_USERNAME:postgres}"
password: "${SPRING_DATASOURCE_PASSWORD:postgres}"端口、库名、账号密码与本机 PostgreSQL / pgAdmin 中创建的库保持一致。

配置含义对照 CE 文 §2.2 即可。
2.1.3、初始化
- 以管理员身份打开命令提示符。

- 进入包含
install.bat的目录,例如:
cd C:\Users\Administrator\Downloads\thingsboard-windows-4.4\thingsboard

- 执行(带演示数据):
.\install.bat --loadDemo
若提示服务已存在 / 安装失败,多半是旧 thingsboard 服务未清干净:回到 §2.1.0 删注册表项并重启后再装。


8080 被占用时的排查方式与 CE 文 常见问题:8080 相同:结束占用进程后重新 install.bat。
2.1.4、启动服务
管理员命令行:
net start thingsboard
安装为 Windows 服务后,开机/重启通常会自动启动。

若启动失败,按日志提示处理(权限、端口、JDK、数据库连通性等):



停止服务:
net stop thingsboard
2.1.5、访问 Web 并进入激活
浏览器打开(4.4 统一版首次常先进入激活页):
http://localhost:8080/activation也可先试:
http://localhost:8080/
打不开时检查:服务是否已启动、防火墙、8080 占用——与 CE 文 §2.5 相同。
2.1.6、License 授权(4.4 关键)
4.4 起合并后需按协议完成授权。在激活页点击 Open the License Portal,按向导登录许可门户。



按组织用途选择许可证类型(不同类型设备额度不同)。学习演示可选择符合自身场景的非商业/免费档(以门户当前选项与条款为准)。

勾选协议并激活,等待签发密钥:


许可模型细节见官方 One ThingsBoard;条款以官方法务页为准。
2.1.7、继续实例设置
激活完成后,按向导继续在本实例上完成系统管理员账号等设置。

为与旧版习惯对齐,系统层账号示例可用(仅学习环境):
sysadmin@thingsboard.org / sysadmin创建后若询问是否进入租户页,可先选 not now,进入系统层查看:



再从租户用户入口跳到默认租户层:


至此,Windows 安装包路径完成。生产环境请立即修改默认密码并使用强口令。
2.2、Windows 本地源码安装
适合要看源码、改代码、做定制化开发的同学。JDK 25 / PostgreSQL 18 可与上一节共用。
2.2.1、环境
- JDK 25、Maven 3.9.x、IDEA
- 拉取 GitHub 若较慢,可自备合规网络代理
2.2.2、拉取源码
git clone -b release-4.4 https://github.com/thingsboard/thingsboard.git2.2.3、编译
先阅读仓库根目录 CONTRIBUTING.md(环境与注意点很重要),再执行:
mvn clean install -DskipTests -Dpkg.skip=true2.2.4、IDEA 配置要点
- 指定本机 Maven / JDK 25
- 配置数据源指向 PostgreSQL 中的
thingsboard库 - 按项目约定放置 SQL /
data目录 - 设置
install.data_dir、install.load_demo等安装相关参数(以当前分支文档与运行配置为准)
2.2.5、初始化与启动
- 运行 ThingsboardInstallApplication(或当前分支等价的 Install 入口)初始化库表
- 运行 ThingsboardServerApplication 启动服务
2.2.6、访问与授权
浏览器打开:
http://localhost:8080未授权时先进入 License 页;授权完成后进入登录页。流程同 §2.1.6。
更细的源码编译排错,可对照 CE 语境下的 Windows上源码编译安装ThingsBoard,注意把 JDK / 分支换成 25 / release-4.4。
2.3、Ubuntu 上 Docker Compose 安装
官方参考:PE / 统一版 Docker 安装。
2.3.1~2.3.2、Docker 环境
sudo apt update
sudo apt install docker.io docker-compose
docker --version
docker-compose --version国内拉取 Docker Hub 不稳定时,需自行配置可用的镜像加速或代理(镜像源列表变化快,请按当时可用源维护 /etc/docker/daemon.json,然后 systemctl restart docker)。
2.3.3、编排 docker-compose.yml
示例(与原稿 / 官方 4.4.0 思路一致,部署前请再核对官方文档是否有更新):
services:
postgres:
restart: always
image: "postgres:18"
ports:
- "5432"
environment:
POSTGRES_DB: thingsboard
POSTGRES_PASSWORD: postgres
volumes:
- postgres-data:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres -d thingsboard"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
thingsboard:
restart: always
image: "thingsboard/tb-node:4.4.0"
ports:
- "8080:8080"
- "1883:1883"
- "8883:8883"
- "9090:9090"
- "7070:7070"
- "5683-5688:5683-5688/udp"
logging:
driver: "json-file"
options:
max-size: "100m"
max-file: "10"
environment:
TB_SERVICE_ID: tb-node
# TB_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data
REPORTS_SERVER_ENDPOINT_URL: http://tb-web-report:8383
SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
SPRING_DATASOURCE_PASSWORD: postgres
DEFAULT_TRENDZ_URL: http://trendz:8888
DEFAULT_TB_URL: http://thingsboard:8080
volumes:
- license-data:/data
depends_on:
postgres:
condition: service_healthy
tb-web-report:
restart: always
image: "thingsboard/tb-web-report:4.4.0"
ports:
- "8383"
depends_on:
- thingsboard
environment:
HTTP_BIND_ADDRESS: 0.0.0.0
HTTP_BIND_PORT: 8383
LOGGER_LEVEL: info
LOG_FOLDER: logs
LOGGER_FILENAME: tb-web-report-%DATE%.log
DOCKER_MODE: true
DEFAULT_PAGE_NAVIGATION_TIMEOUT: 120000
DASHBOARD_IDLE_WAIT_TIME: 3000
USE_NEW_PAGE_FOR_REPORT: true
volumes:
postgres-data:
name: tb-postgres-data
driver: local
license-data:
name: tb-license-data
driver: local说明:
- 取消注释并填写
TB_LICENSE_SECRET,或按官方方式在首次访问时完成激活。 tb-web-report服务于报表相关能力,与统一版能力集相关。
2.3.4、清理旧卷(可选)
若以前创建过同名卷、担心脏数据:
docker volume ls
docker volume rm <卷名>
2.3.5、初始化
在 docker-compose.yml 所在目录:
docker compose run --rm -e INSTALL_TB=true thingsboard2.3.6、启动 / 停止 / 日志
docker compose up -d
docker compose down
docker logs -f --tail 500 <容器名>2.3.7、访问并授权
浏览器访问主机 http://<IP>:8080,按 §2.1.6 完成 License,再登录使用。
2.4、小结
| 路径 | 关键命令 / 入口 |
|---|---|
| Windows 包 | 清旧服务 → JDK25 + PG18 → 改 yml → install.bat --loadDemo → net start thingsboard → /activation |
| 源码 | release-4.4 → mvn clean install ... → Install / Server 主类 → 授权 |
| Docker | Compose 编排 → INSTALL_TB=true → up -d → 授权 |
与 CE 4.3 Windows 包的对照:Windows上安装ThingsBoard。
概念回顾:第一章、概述 · 专栏导读。
