Skip to content

第二章、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 服务,建议先清理,避免冲突。

  1. Win + R,输入 regedit,回车。

运行对话框

输入 regedit

确认

注册表界面

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

查找 thingsboard 服务

更细的截图说明也可对照 CE 文 §1.1 检查旧服务。

2.1.1、环境要求 ​

组件本课示例
JDK25(4.4 线路官方强调 Java 25)
PostgreSQL18
Maven3.9.x(源码编译需要;仅用 Windows 安装包可暂不装)
IDEA2024/2025+(源码调试推荐)

JDK 25 ​

请从可信发行版下载 Windows x64 安装包,例如 Eclipse Temurin 或其它官方构建,按向导下一步安装。

JDK 安装示意

安装后在 cmd 中验证:

bat
java --version

应能看到 Java 25 相关输出。验证方式与 CE 文 §1.3 相同,只是版本号不同。

Maven 3.9.x(源码路径需要) ​

  1. 从 Maven 下载页 下载 Binary zip。

Maven 下载

下载包

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

解压与本地仓库

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

settings.xml

配置 localRepository

  1. 将 Maven 的 bin 加入系统 PATH。

复制 bin 路径

环境变量入口

  1. 验证:
bat
mvn -v

验证 Maven

PostgreSQL 18 ​

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

PostgreSQL 下载示意

EnterpriseDB 下载页

用 pgAdmin 创建数据库:

text
thingsboard

记住超级用户密码与端口(默认 5432;若改端口,后面 thingsboard.yml 必须一致)。学习环境可暂用简单密码,生产请用强密码。

IDEA(源码路径) ​

从 JetBrains IDEA 下载页 安装即可。

IDEA 下载

2.1.2、下载 thingsboard-windows 包 ​

打开 Release:

text
https://github.com/thingsboard/thingsboard/releases/tag/v4.4

下载 Windows 安装包并解压到固定目录(如 D:\thingsboard 或 Downloads\thingsboard-windows-4.4\thingsboard)。

Release 页

选择资源

解压

进入目录

进入 conf,用文本编辑器打开 thingsboard.yml,确认数据源类似:

yaml
url: "${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/thingsboard}"
username: "${SPRING_DATASOURCE_USERNAME:postgres}"
password: "${SPRING_DATASOURCE_PASSWORD:postgres}"

端口、库名、账号密码与本机 PostgreSQL / pgAdmin 中创建的库保持一致。

编辑 thingsboard.yml

配置含义对照 CE 文 §2.2 即可。

2.1.3、初始化 ​

  1. 以管理员身份打开命令提示符。

管理员命令行

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

定位目录

进入目录

  1. 执行(带演示数据):
bat
.\install.bat --loadDemo

执行 install.bat

若提示服务已存在 / 安装失败,多半是旧 thingsboard 服务未清干净:回到 §2.1.0 删注册表项并重启后再装。

服务冲突提示

清理后重试

8080 被占用时的排查方式与 CE 文 常见问题:8080 相同:结束占用进程后重新 install.bat。

2.1.4、启动服务 ​

管理员命令行:

bat
net start thingsboard

启动服务

安装为 Windows 服务后,开机/重启通常会自动启动。

服务状态

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

启动失败示例

排查示意

继续排查

停止服务:

bat
net stop thingsboard

停止服务

2.1.5、访问 Web 并进入激活 ​

浏览器打开(4.4 统一版首次常先进入激活页):

text
http://localhost:8080/activation

也可先试:

text
http://localhost:8080/

激活页

打不开时检查:服务是否已启动、防火墙、8080 占用——与 CE 文 §2.5 相同。

2.1.6、License 授权(4.4 关键) ​

4.4 起合并后需按协议完成授权。在激活页点击 Open the License Portal,按向导登录许可门户。

开始授权

打开许可门户

账号登录示例

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

选择许可类型

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

勾选并激活

获得密钥

许可模型细节见官方 One ThingsBoard;条款以官方法务页为准。

2.1.7、继续实例设置 ​

激活完成后,按向导继续在本实例上完成系统管理员账号等设置。

继续实例设置

为与旧版习惯对齐,系统层账号示例可用(仅学习环境):

text
sysadmin@thingsboard.org / sysadmin

创建后若询问是否进入租户页,可先选 not now,进入系统层查看:

not now

系统层

系统层续

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

租户入口

租户层

至此,Windows 安装包路径完成。生产环境请立即修改默认密码并使用强口令。


2.2、Windows 本地源码安装 ​

适合要看源码、改代码、做定制化开发的同学。JDK 25 / PostgreSQL 18 可与上一节共用。

2.2.1、环境 ​

  • JDK 25、Maven 3.9.x、IDEA
  • 拉取 GitHub 若较慢,可自备合规网络代理

2.2.2、拉取源码 ​

bash
git clone -b release-4.4 https://github.com/thingsboard/thingsboard.git

2.2.3、编译 ​

先阅读仓库根目录 CONTRIBUTING.md(环境与注意点很重要),再执行:

bash
mvn clean install -DskipTests -Dpkg.skip=true

2.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、访问与授权 ​

浏览器打开:

text
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 环境 ​

bash
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 思路一致,部署前请再核对官方文档是否有更新):

yaml
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、清理旧卷(可选) ​

若以前创建过同名卷、担心脏数据:

bash
docker volume ls
docker volume rm <卷名>

查看 volume

2.3.5、初始化 ​

在 docker-compose.yml 所在目录:

bash
docker compose run --rm -e INSTALL_TB=true thingsboard

2.3.6、启动 / 停止 / 日志 ​

bash
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 主类 → 授权
DockerCompose 编排 → INSTALL_TB=true → up -d → 授权

与 CE 4.3 Windows 包的对照:Windows上安装ThingsBoard。
概念回顾:第一章、概述 · 专栏导读。