在 Windows 上安装 ThingsBoard Edge

前置条件
- Edge 硬件要求
- 部署新 Edge 实例
安装和配置
故障排查
Windows防火墙设置
下一步

版本兼容规则 - 操作前请阅读

安装 ThingsBoard Edge 前，请确保 ThingsBoard Server 已安装并更新至最新版本。

此外，请确认 ThingsBoard Edge 与 ThingsBoard Server 版本兼容。

兼容规则：

ThingsBoard Edge 版本 X.Y.Z 可与 ThingsBoard Server 版本 X.Y.Z 及后续两个版本配合使用。

示例：ThingsBoard Edge 3.8.0 可与 ThingsBoard Server 3.8.0 及两个后续版本（3.9.0、3.9.1）配合。查看 ThingsBoard Server 发行说明。

ThingsBoard Edge 版本 X.Y.Z 无法与较旧版本的 ThingsBoard Server 配合使用。

示例：ThingsBoard Edge 3.9.1 不支持 ThingsBoard Server 3.8.0 或更早版本，需先将 ThingsBoard Server 升级至最新版本。

注意： 若使用较旧版本的 ThingsBoard Edge（如 3.6.0），ThingsBoard 团队无法保证所有功能可用或正常工作。

本指南提供在Windows上安装ThingsBoard Edge的说明。

以下步骤适用于：

32位或64位系统
Windows 11/10版本

前置条件

要运行 ThingsBoard Professional Edition Edge，需具备支持 Edge 功能的活跃 ThingsBoard Professional Edition 账号。

ThingsBoard Cloud（云端）

Local Server（本地服务器）

请使用ThingsBoard Cloud 租户凭据登录。

您可以安装ThingsBoard Professional Edition本地Server。请参阅 ThingsBoard安装指南。

可通过 http://localhost:8080 访问本地Server。在本教程中，我们将该URL称为 SERVER_URL。请使用以下凭据登录：

用户名： tenant@thingsboard.org
密码： tenant

Edge 硬件要求

ThingsBoard Edge 的硬件要求取决于连接设备数量及与平台界面的交互强度。为获得最佳性能，建议如下：

至少 1GB RAM（轻负载）： 适用于与平台界面交互较少（如 dashboards 和设备管理）及少于 100 台连接设备的场景。
至少 4GB RAM（重负载）： 适用于与平台频繁交互及单台机器连接 100 台以上设备的场景。

部署新 Edge 实例

要创建新的 Edge：

登录 ThingsBoard PE 实例，进入 Edge Management > Instances 区域。点击右上角 ”+” 图标并选择 “Add new edge”。
输入要创建的 Edge 名称，如 “My New Edge”。如需要，更新 cloud endpoint。
- 若 Edge 运行在 Docker 容器中，不要使用 “localhost” 作为endpoint，应使用 ThingsBoard PE 所在且 Edge 容器可访问的机器 IP 地址，如 http://10.7.2.143:8080。
- 若使用 ThingsBoard Cloud，则无需修改此设置。
- 点击 “Add” 按钮以确认添加 Edge instance。
新 Edge 已创建，将出现在列表顶部（默认按创建时间排序）。

登录 ThingsBoard PE 实例，进入 Edge Management > Instances 区域。点击右上角 "+" 图标并选择 "Add new edge"。 — 登录 **ThingsBoard PE** 实例，进入 **Edge Management > Instances** 区域。点击右上角 **”+”** 图标并选择 **“Add new edge”**。

输入要创建的 Edge 名称，如 "My New Edge"。如需要，更新 cloud endpoint。
若 Edge 运行在 [Docker 容器](https://docs.docker.com/get-started/docker-overview/){:target="_blank"}中，不要使用 "localhost" 作为endpoint，应使用 ThingsBoard PE 所在且 Edge 容器可访问的机器 IP 地址，如 http://10.7.2.143:8080。
若使用 ThingsBoard Cloud，则无需修改此设置。
点击 "Add" 按钮以确认添加 Edge instance。 — 输入要创建的 Edge 名称，如 “My New Edge”。**如需要**，更新 **cloud endpoint**。

若 **Edge** 运行在 Docker 容器中，不要使用 “localhost” 作为endpoint，应使用 **ThingsBoard PE** 所在且 Edge 容器可访问的机器 **IP 地址**，如 http://10.7.2.143:8080。

若使用 **ThingsBoard Cloud**，则无需修改此设置。

点击 **“Add”** 按钮以确认添加 **Edge instance**。

新 Edge 已创建，将出现在列表顶部（默认按创建时间排序）。 — 新 **Edge** 已创建，将出现在列表顶部（默认按创建时间排序）。

安装和配置

步骤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” 替换为下载的版本名称。

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

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

java -version

预期命令输出为：

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. 配置PostgreSQL

ThingsBoard Edge 使用 PostgreSQL 作为本地存储。

PostgreSQL 安装

在此下载安装文件（PostgreSQL 12.17 或更新版本）并按说明完成安装。

安装 PostgreSQL 时会提示设置超级用户（postgres）密码。请牢记该密码，后续步骤会使用。为简化示例，此处假设密码为 “postgres”。

创建 ThingsBoard Edge 数据库

安装完成后，启动 “pgAdmin”，以超级用户（postgres）登录。打开服务器并创建数据库 tb_edge，所有者设为 “postgres”。

步骤3. 安装ThingsBoard Edge服务

下载并解压安装包。

https://dist.thingsboard.io/tb-edge-windows-4.3.0.1pe.zip

注意： 我们假设您已将包解压到默认位置：C:\Program Files (x86)\tb-edge

步骤4. 配置ThingsBoard Edge

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

C:\Program Files (x86)\tb-edge\conf\tb-edge.yml

数据库配置

在上一步的 “tb-edge.yml” 文件中找到 “# SQL DAO Configuration” 段落。

请将 YOUR_POSTGRES_PASSWORD_HERE 替换为实际的 postgres 用户密码：

# SQL DAO Configuration
spring:
  data:
    jpa:
      repositories:
        enabled: "true"
  jpa:
    hibernate:
      ddl-auto: "none"
  datasource:
    driverClassName: "${SPRING_DRIVER_CLASS_NAME:org.postgresql.Driver}"
    url: "${SPRING_DATASOURCE_URL:jdbc:postgresql://localhost:5432/tb_edge}"
    username: "${SPRING_DATASOURCE_USERNAME:postgres}"
    password: "${SPRING_DATASOURCE_PASSWORD:YOUR_POSTGRES_PASSWORD_HERE}"

配置云端连接

在 edge 详情区域点击 Copy Edge Key 和 Copy Edge Secret。这将把 edge 凭证复制到剪贴板。请妥善保存，后续步骤将用到这些值。

找到 “# Cloud configuration” 段落，将 PUT_YOUR_EDGE_KEY_HERE 和 PUT_YOUR_EDGE_SECRET_HERE 分别替换为 Edge 的 key 和 secret。

将 PUT_YOUR_CLOUD_IP 替换为运行 ThingsBoard PE 的机器 IP 地址：

若 Edge 连接到 ThingsBoard Cloud，请使用 thingsboard.cloud。

注意： thingsboard.cloud 在 Edge 通信中使用 SSL 协议。请同时将 CLOUD_RPC_SSL_ENABLED 设为 true。

Edge 与 cloud 实例在同一台机器上运行时使用 localhost。
Edge 连接同一网络或 Docker 内的 cloud 实例时使用 X.X.X.X IP 地址。

# Cloud configuration
cloud:
    routingKey: "${CLOUD_ROUTING_KEY:PUT_YOUR_EDGE_KEY_HERE}"
    secret: "${CLOUD_ROUTING_SECRET:PUT_YOUR_EDGE_SECRET_HERE}"
    rpc:
      host: "${CLOUD_RPC_HOST:PUT_YOUR_CLOUD_IP}"
      ssl:
        # 若使用 thingsboard.cloud 或已在 Server 上配置 TLS 连接，则设为 'true'；否则设为 'false'。
        enabled: "${CLOUD_RPC_SSL_ENABLED:true/false}" 

若 ThingsBoard Edge 与 ThingsBoard PE 服务器运行在同一台机器上，需调整以下配置参数以避免端口冲突。

请在ThingsBoard Edge 配置文件（C:\Program Files (x86)\tb-edge\conf\tb-edge.yml）中定位并修改以下参数：

…
port: “${HTTP_BIND_PORT:18080}”
…
bind_port: “${MQTT_BIND_PORT:11883}”
…
bind_port: “${COAP_BIND_PORT:15683}”
…
LWM2M_ENABLED: false
…

bind_port: “${INTEGRATIONS_RPC_PORT:19090}”
…

确保以上端口（18080、11883、15683）未被其他应用占用。

步骤5. 运行安装脚本

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

执行 install.bat 脚本，将 ThingsBoard Edge 安装为 Windows 服务。安装后系统启动时会自动运行。同理，uninstall.bat 可将 ThingsBoard Edge 从 Windows 服务中移除。输出应类似如下：

C:\Program Files (x86)\tb-edge\install.bat
Detecting Java version installed.
CurrentVersion 110
Java 11 found!
Installing Thingsboard Edge...
...
ThingsBoard Edge installed successfully!

步骤6. 启动ThingsBoard Edge服务

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

net start tb-edge

预期输出：

The ThingsBoard Edge Server Application service is starting.
The ThingsBoard Edge Server Application service was started successfully.

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

net stop tb-edge
net start tb-edge

步骤7. 打开ThingsBoard Edge UI

Edge 服务启动后，在 http://localhost:8080 打开 Edge UI。

请使用 ThingsBoard Server 的租户凭证 or ThingsBoard Cloud{: target=登录 ThingsBoard Edge。

故障排查

日志文件位于logs文件夹（本例中为”C:\Program Files (x86)\tb-edge\logs”）。

tb-edge.log文件应包含以下内容：

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

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

Windows防火墙设置

要从外部访问ThingsBoard Web UI和设备连接（HTTP、MQTT、CoAP），您需要在高级安全Windows防火墙中创建新的入站规则。

从”控制面板”打开”Windows防火墙”：

点击左侧面板的”高级设置”：

在左侧面板选择”入站规则”，然后点击右侧”操作”面板中的”新建规则…“：

此时会打开”新建入站规则向导”窗口。在第一步”规则类型”中选择”端口”选项：

在”协议和端口”步骤中选择”TCP”协议，并在”特定本地端口”字段中输入端口列表8080, 1883, 5683：

在”操作”步骤中保持选择”允许连接”选项：

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

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

下一步

恭喜！您已成功配置、安装 ThingsBoard Edge 并连接到 ThingsBoard 服务器。

可继续阅读 入门指南 了解 ThingsBoard Edge 基础知识，或直接进入更进阶主题：

Getting started guide（入门指南）- 快速概览 ThingsBoard Edge 主要功能。预计 15–30 分钟完成：
Edge 规则引擎：
- Rule Chain Templates（规则链模板）- 了解如何使用 ThingsBoard Edge 规则链模板。
- Provision Rule Chains from cloud to edge（从云端向 Edge 下发规则链）- 了解如何从云端向 Edge 下发边缘规则链。
安全：
- gRPC over SSL/TLS - 了解如何为 Edge 与云端之间的通信配置 gRPC over SSL/TLS。
功能：
- Edge Status（Edge 状态）- 了解 ThingsBoard Edge 上的 Edge Status 页面。
- Cloud Events（云端事件）- 了解 ThingsBoard Edge 上的 Cloud Events 页面。
使用场景：
- Manage alarms and RPC requests on edge devices（在边缘设备上管理告警和 RPC 请求）- 本指南展示如何在 Edge 上生成本地告警并向连接到 Edge 的设备发送 RPC 请求：
- Data filtering and traffic reduce（数据过滤与流量削减）- 本指南展示如何从 Edge 向云端仅发送过滤后的设备数据：
Roadmap（路线图）- ThingsBoard Edge 路线图。