在 Windows 上安装 ThingsBoard

ThingsBoard Cloud

我们推荐使用 ThingsBoard Cloud —— 为您的 IoT 应用提供全托管、可扩展且具备容错能力的平台。
ThingsBoard Cloud 面向希望使用 ThingsBoard 但不想自行托管平台实例的用户。

• 前置条件
• 步骤 1. 安装 Java 17 (OpenJDK)
• 步骤 2. ThingsBoard 服务安装
• 步骤 3. 配置 ThingsBoard 数据库
• 步骤 4. 选择 ThingsBoard queue 服务
• 步骤 5. [可选] 低配机器内存更新（4GB 内存）
• 步骤 6. 运行安装脚本
• 步骤 7. 启动 ThingsBoard 服务
• 安装后步骤
  • 升级到新版本 ThingsBoard
• 故障排查
• Windows 防火墙设置
• 下一步

建议考虑使用 Linux 安装方式，因为 Linux 是运行 ThingsBoard 最稳定的平台。Windows 安装将在未来弃用。可在 安装指南 页面查找 Linux 安装指南。

前置条件

本指南介绍如何在 Windows 机器上安装 ThingsBoard。 以下说明适用于 Windows 11/10。 硬件要求取决于所选数据库及连接系统的设备数量。 在同一台机器上运行 ThingsBoard 和 PostgreSQL 至少需要 4GB 内存。 在同一台机器上运行 ThingsBoard 和 Cassandra 至少需要 8GB 内存。

步骤 1. 安装 Java 17 (OpenJDK)

ThingsBoard 服务运行于 Java 17。请按以下说明安装 OpenJDK 17。

• 访问 Open JDK 下载页。进入 “Other platforms and versions”，选择 “Operating System” 为 “Windows”、”Architecture” 为 “x64”、”Version” 为 “17 - LTS”，下载 JDK .msi 安装包。
• 运行下载的 MSI 安装包并按照提示操作。 确保将 “Add to PATH” 和 “Set JAVA_HOME variable” 选项设为 “Will be installed on local hard drive”。
• 访问 PostgreSQL JDBC 下载页 下载 PostgreSQL JDBC Driver。选择最新可用版本。
• 创建文件夹 C:\Program Files\JDBC 并将下载的文件复制到其中。然后添加新的全局变量——以管理员身份运行 PowerShell 并执行以下命令。请勿忘记将命令中的 “postgresql-42.2.18.jar” 替换为下载的版本名称。

  1
  [System.Environment]::SetEnvironmentVariable("CLASSPATH", '.;"C:\Program Files\JDBC\postgresql-42.2.18.jar"', [System.EnvironmentVariableTarget]::Machine)
  

可使用以下命令（在命令提示符中）检查安装：

1
java -version

预期命令输出为：

1
2
3
4
C:\Users\User>java -version
openjdk version "17.x.xx" 
OpenJDK Runtime Environment Temurin-17.x.xx (...)
OpenJDK 64-Bit Server VM Temurin-17.x.xx (...)

步骤 2. ThingsBoard 服务安装

下载并解压安装包。

1
https://github.com/thingsboard/thingsboard/releases/download/v4.3.0.1/thingsboard-windows-4.3.0.1.zip

注意： 我们假定您已将 ThingsBoard 安装包解压到默认位置：C:\Program Files (x86)\thingsboard

步骤 3. 配置 ThingsBoard 数据库

ThingsBoard 可使用 SQL 或混合数据库方案。详见对应架构 页面。

PostgreSQL (recommended for < 5K msg/sec)

ThingsBoard 团队建议在负载合理（< 5000 条消息/秒）的开发和生产环境中使用 PostgreSQL。 许多云服务商提供托管 PostgreSQL 服务，对大多数 ThingsBoard 实例而言是成本效益较高的解决方案。 PostgreSQL 安装 从此处下载安装文件（PostgreSQL 15 或更新版本）并按照安装说明操作。 在 PostgreSQL 安装过程中，系统会提示您输入超级用户 (postgres) 密码。 请勿忘记此密码，后续将使用。为简便起见，我们将用 “postgres” 代替。 创建 ThingsBoard 数据库 安装完成后，启动 “pgAdmin” 软件并以超级用户 (postgres) 登录。 打开服务器并创建数据库 “thingsboard”，所有者设置为 “postgres”。 ThingsBoard 配置 若您已将 PostgreSQL 超级用户密码设为 “postgres”，可跳过此步骤。 以管理员身份打开记事本或其他编辑器（右键点击应用图标并选择“以管理员身份运行”）。 打开以下文件进行编辑（在文件选择对话框中选择“所有文件”而非“文本文档”，编码为 UTF-8）： 1 C:\Program Files (x86)\thingsboard\conf\thingsboard.yml 并找到 “# SQL DAO Configuration” 配置块。请勿忘记将 “postgres” 替换为您的实际 postgres 用户密码： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 # SQL DAO Configuration spring: data: jpa: repositories: enabled: "true" jpa: open-in-view: "false" hibernate: ddl-auto: "none" datasource: driverClassName: "${SPRING_DRIVER_CLASS_NAME:org.postgresql.Driver}" url: "${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/thingsboard}" username: "${SPRING_DATASOURCE_USERNAME:postgres}" password: "${SPRING_DATASOURCE_PASSWORD:YOUR_POSTGRES_PASSWORD_HERE}" hikari: maximumPoolSize: "${SPRING_DATASOURCE_MAXIMUM_POOL_SIZE:16}" 找到 “SQL_POSTGRES_TS_KV_PARTITIONING” 参数以覆盖时间戳键值存储分区大小的默认值： 1 2 3 4 sql: postgres: # Specify partitioning size for timestamp key-value storage. Example: DAYS, MONTHS, YEARS, INDEFINITE. ts_key_value_partitioning: "${SQL_POSTGRES_TS_KV_PARTITIONING:MONTHS}"

步骤 4. 选择 ThingsBoard queue 服务

ThingsBoard 平台目前支持两种消息 broker 用于存储消息及 ThingsBoard 服务间通信：In-memory 和基于 Kafka 的 broker。

• In Memory queue 实现为内置且默认。 适用于开发（PoC）环境，不适合生产部署或任何集群部署。

• Kafka 推荐用于生产部署。该 queue 现已在多数 ThingsBoard 生产环境中使用。 适用于本地部署和私有云部署。若希望独立于云提供商，同样适用。 部分云提供商也提供 Kafka 托管服务，如 AWS MSK。

• Confluent Cloud 是基于 Kafka 的全托管流平台。适用于云无关部署。

详见对应架构 页面 和规则引擎 页面。

1
nano docker-compose-kafka.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
services:
  kafka:
    restart: always
    image: bitnamilegacy/kafka:4.0
    ports:
      - 9092:9092 #to localhost:9092 from host machine
      - 9093 #for Kraft
      - 9094 #to kafka:9094 from within Docker network
    environment:
      ALLOW_PLAINTEXT_LISTENER: "yes"
      KAFKA_CFG_LISTENERS: "OUTSIDE://:9092,CONTROLLER://:9093,INSIDE://:9094"
      KAFKA_CFG_ADVERTISED_LISTENERS: "OUTSIDE://localhost:9092,INSIDE://kafka:9094"
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "INSIDE:PLAINTEXT,OUTSIDE:PLAINTEXT,CONTROLLER:PLAINTEXT"
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "INSIDE"
      KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE: "false"
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
      KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
      KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
      KAFKA_CFG_PROCESS_ROLES: "controller,broker" #KRaft
      KAFKA_CFG_NODE_ID: "0" #KRaft
      KAFKA_CFG_CONTROLLER_LISTENER_NAMES: "CONTROLLER" #KRaft
      KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: "0@kafka:9093" #KRaft
    volumes:
      - kafka-data:/bitnami
volumes:
  kafka-data:
    driver: local

1
docker compose -f docker-compose-kafka.yml up -d

1
C:\Program Files (x86)\thingsboard\conf\thingsboard.yml

1
2
3
4
5
6
7
8
9
10
11
queue:
  type: "${TB_QUEUE_TYPE:kafka}"
...
  kafka:
    bootstrap.servers: "${TB_KAFKA_SERVERS:localhost:9092}"
    acks: "${TB_KAFKA_ACKS:all}"
    retries: "${TB_KAFKA_RETRIES:1}"
    batch.size: "${TB_KAFKA_BATCH_SIZE:16384}"
    linger.ms: "${TB_KAFKA_LINGER_MS:1}"
    buffer.memory: "${TB_BUFFER_MEMORY:33554432}"
    replication_factor: "${TB_QUEUE_KAFKA_REPLICATION_FACTOR:1}"

1
C:\Program Files (x86)\thingsboard\conf\thingsboard.yml

1
2
3
4
5
6
7
8
9
10
11
queue:
  type: "${TB_QUEUE_TYPE:kafka}"
...
  kafka:
    bootstrap.servers: "${TB_KAFKA_SERVERS:localhost:9092}"
...
    replication_factor: "${TB_QUEUE_KAFKA_REPLICATION_FACTOR:3}"
...
    use_confluent_cloud: "${TB_QUEUE_KAFKA_USE_CONFLUENT_CLOUD:true}"
...
      sasl.config: "${TB_QUEUE_KAFKA_CONFLUENT_SASL_JAAS_CONFIG:org.apache.kafka.common.security.plain.PlainLoginModule required username=\"CLUSTER_API_KEY\" password=\"CLUSTER_API_SECRET\";}"

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
queue:
...
  transport_api:
    request_poll_interval: "${TB_QUEUE_TRANSPORT_REQUEST_POLL_INTERVAL_MS:1000}"
    response_poll_interval: "${TB_QUEUE_TRANSPORT_RESPONSE_POLL_INTERVAL_MS:1000}"
...
  core:
    poll-interval: "${TB_QUEUE_CORE_POLL_INTERVAL_MS:1000}"
    partitions: "${TB_QUEUE_CORE_PARTITIONS:2}"
...
  vc:
    partitions: "${TB_QUEUE_VC_PARTITIONS:1}"
    poll-interval: "${TB_QUEUE_VC_INTERVAL_MS:1000}"
...
  js:
    response_poll_interval: "${REMOTE_JS_RESPONSE_POLL_INTERVAL_MS:1000}"
...
  rule-engine:
    poll-interval: "${TB_QUEUE_RULE_ENGINE_POLL_INTERVAL_MS:1000}"
...
  transport:
    poll_interval: "${TB_QUEUE_TRANSPORT_NOTIFICATIONS_POLL_INTERVAL_MS:1000}"

步骤 5. [可选] 低配机器内存更新（4GB 内存）

以管理员身份打开记事本或其他编辑器（右键点击应用图标并选择“以管理员身份运行”）。
打开以下文件进行编辑（在文件选择对话框中选择“所有文件”而非“文本文档”，编码为 UTF-8）：

1
C:\Program Files (x86)\thingsboard\thingsboard.xml

在配置文件中找到以下行。

1
2
<startargument>-Xms512m</startargument>
<startargument>-Xmx1024m</startargument>

并将其修改为

1
2
<startargument>-Xms2048m</startargument>
<startargument>-Xmx2048m</startargument>

将 “2048m” 改为约为总内存的 1/3（单位为 MB）

步骤 6. 运行安装脚本

以管理员身份启动 Windows shell（命令提示符）。切换至 ThingsBoard 安装目录。

执行 install.bat 脚本，将 ThingsBoard 安装为 Windows 服务（或运行 ”.\install.bat –loadDemo” 安装并添加演示数据）。 安装后将在系统启动时自动运行。 类似地，uninstall.bat 可从 Windows 服务中移除 ThingsBoard。 输出应类似如下：

1
2
3
4
5
6
7
C:\Program Files (x86)\thingsboard>.\install.bat --loadDemo
Detecting Java version installed.
CurrentVersion 170
Java 17 found!
Installing thingsboard ...
...
ThingsBoard installed successfully!

步骤 7. 启动 ThingsBoard 服务

现在启动 ThingsBoard 服务！ 以管理员身份打开命令提示符并执行以下命令：

1
net start thingsboard

预期输出：

1
2
The ThingsBoard Server Application service is starting.
The ThingsBoard Server Application service was started successfully.

要重启 ThingsBoard 服务，可执行以下命令：

1
2
net stop thingsboard
net start thingsboard

启动后，可通过以下链接打开 Web UI：

1
http://localhost:8080/

若在运行安装脚本时指定了 –loadDemo，可使用以下默认凭证：

• System Administrator：sysadmin@thingsboard.org / sysadmin
• Tenant Administrator：tenant@thingsboard.org / tenant
• Customer User：customer@thingsboard.org / customer

可随时在账户资料页面修改各账户密码。

Web UI 启动最多可能需要 90 秒。

安装后步骤

升级到新版本 ThingsBoard

保持平台安全与更新

当有新 ThingsBoard 版本发布时，我们提供简化的更新流程，确保系统获得最新功能和安全补丁，且不危及您的数据。

为保持数据库完整性和系统稳定性，请按顺序进行升级（例如 v4.0.2 → v4.1.0 → v4.2.0）。

请参阅官方 升级说明，获取针对您当前部署环境的详细步骤。

故障排查

日志文件位于 logs 文件夹（本文示例为 “C:\Program Files (x86)\thingsboard\logs”）。

thingsboard.log 文件应包含如下行：

1
YYYY-MM-DD HH:mm:ss,sss [main] INFO  o.t.s.ThingsboardServerApplication - Started ThingsboardServerApplication in x.xxx seconds (JVM running for x.xxx)

如遇不明错误，请参考通用 故障排查指南 或 联系我们。

Windows 防火墙设置

为允许外部访问 ThingsBoard Web UI 及设备连接（HTTP、MQTT、CoAP）， 需在 Windows 高级安全防火墙中新建入站规则。

• 从「控制面板」打开 “Windows Firewall”：

• 在左侧面板点击 “Advanced settings”：

• 在左侧面板选择 “Inbound Rules”，在右侧 “Actions” 面板点击 “New Rule…“：

• 将打开 “New Inbound Rule Wizard” 窗口。在第一步 “Rule Type” 选择 “Port” 选项：

• 在 “Protocol and Ports” 步骤选择 “TCP” 协议，在 “Specific local ports” 字段输入端口列表 8080, 1883, 5683：

• 在 “Action” 步骤保持 “Allow the connection” 选项为选中状态：

• 在 “Profile” 步骤选择应用此规则的 Windows 网络配置文件：

• 最后，为此规则命名（例如 “ThingsBoard Service Networking”）并点击 “Finish”。

下一步

• 快速入门指南 - 快速了解ThingsBoard主要功能，约15-30分钟完成。

• 连接设备 - 根据连接技术或方案学习如何连接设备。

• 数据可视化 - 配置ThingsBoard复杂仪表盘的说明。

• 数据处理与操作 - 学习使用ThingsBoard规则引擎。

• IoT数据分析 - 学习使用规则引擎执行基本分析任务。

• 高级功能 - 了解ThingsBoard高级功能。

• 贡献与开发 - 了解ThingsBoard贡献与开发。