在 CentOS/RHEL Server 上安装 ThingsBoard Edge

前置条件
- Edge 硬件要求
- 部署新 Edge 实例
使用 ThingsBoard Server 预配置指令进行引导安装
手动安装与配置
故障排除
下一步

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

安装 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 团队无法保证所有功能可用或正常工作。

本指南介绍在 RHEL/CentOS 8/9 上安装 ThingsBoard Edge 的步骤。

前置条件

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

您可以安装ThingsBoard CE本地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 CE 实例，进入 Edge Management > Instances 区域。点击右上角 ”+” 图标并选择 “Add new edge”。
输入要创建的 Edge 名称，如 “My New Edge”。点击 “Add” 按钮以确认添加 Edge instance。
新 Edge 已创建，将出现在列表顶部（默认按创建时间排序）。

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

输入要创建的 Edge 名称，如 "My New Edge"。点击 "Add" 按钮以确认添加 Edge instance。 — 输入要创建的 Edge 名称，如 “My New Edge”。点击 **“Add”** 按钮以确认添加 **Edge instance**。

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

使用 ThingsBoard Server 预配置指令进行引导安装

Edge 实例创建后，即可使用安装说明。
每个 Edge 都有包含重要凭证（如 Edge Secret、Edge Key 等）的预设配置。要访问这些配置：

点击 Edge 实体打开其详情。
点击 「Install & Connection Instructions」 按钮。
按说明安装 Edge 并连接到服务器。

点击「Install & Connection Instructions」按钮。 — 点击 **「Install & Connection Instructions」** 按钮。

按说明安装 Edge 并连接到服务器。 — 按说明安装 **Edge** 并连接到服务器。

手动安装与配置

如因故无法使用上述 ThingsBoard Server 预配置指令，请按以下步骤操作。以下步骤将指导您自行安装并配置 Edge。

安装前步骤

在继续安装前，请执行以下命令安装必要工具：

sudo yum install -y nano wget && sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

步骤 1：安装 Java 17（OpenJDK）

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

sudo dnf install java-17-openjdk-headless

请勿忘记将您的操作系统配置为默认使用 OpenJDK 17。您可以使用以下命令配置默认版本：

sudo update-alternatives --config java

您可以使用以下命令检查安装：

java -version

预期命令输出为：

openjdk version "17.x.xx"
OpenJDK Runtime Environment (...)
OpenJDK 64-Bit Server VM (build ...)

步骤 2：配置 ThingsBoard 数据库

ThingsBoard Edge 支持 SQL 与 hybrid 数据库架构。详见架构说明。

PostgreSQL (recommended for < 5K msg/sec)

Hybrid
PostgreSQL+Cassandra
(recommended for > 5K msg/sec)

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

要安装 PostgreSQL，请按以下说明操作。

更新系统：

sudo dnf update

安装仓库 RPM：

CentOS/RHEL 8：

sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

CentOS/RHEL 9：

sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm

安装软件包并初始化 PostgreSQL。PostgreSQL 服务将在系统启动时自动运行。

sudo dnf -qy module disable postgresql && \
sudo dnf -y install postgresql16 postgresql16-server postgresql16-contrib && \
sudo /usr/pgsql-16/bin/postgresql-16-setup initdb && \
sudo systemctl enable --now postgresql-16

安装 PostgreSQL 后，建议为 PostgreSQL 主用户 设置密码。

以下命令将切换当前用户为 PostgreSQL 用户并在 PostgreSQL 中直接设置密码。

sudo -u postgres psql -c "\password"

然后输入并确认密码。

修改 PostgreSQL 的认证方式（可选）

由于 ThingsBoard Edge 使用 PostgreSQL 数据库进行本地存储，配置 MD5 认证 可确保仅经认证的用户或应用能访问数据库，从而保护数据。配置密码后，编辑 pg_hba.conf 文件，将本地 IPv4 连接 的认证方式从默认的 ident 改为 MD5 哈希。

要将 ident 替换为 md5，执行以下命令：

sudo sed -i 's/^host\s\+all\s\+all\s\+127\.0\.0\.1\/32\s\+ident/host    all             all             127.0.0.1\/32            md5/' /var/lib/pgsql/16/data/pg_hba.conf

然后执行将重启 PostgreSQL 服务以应用配置更改、以 postgres 用户连接数据库并创建 ThingsBoard Edge 数据库 (tb_edge) 的命令。连接 PostgreSQL 数据库时，请输入 PostgreSQL 密码。

sudo systemctl restart postgresql-16.service && psql -U postgres -d postgres -h 127.0.0.1 -W -c "CREATE DATABASE tb_edge;"

PostgreSQL 安装

要安装 PostgreSQL，请按以下说明操作。

更新系统：

sudo dnf update

安装仓库 RPM：

CentOS/RHEL 8：

sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

CentOS/RHEL 9：

sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm

安装软件包并初始化 PostgreSQL。PostgreSQL 服务将在系统启动时自动运行。

sudo dnf -qy module disable postgresql && \
sudo dnf -y install postgresql16 postgresql16-server postgresql16-contrib && \
sudo /usr/pgsql-16/bin/postgresql-16-setup initdb && \
sudo systemctl enable --now postgresql-16

安装 PostgreSQL 后，建议为 PostgreSQL 主用户 设置密码。

以下命令将切换当前用户为 PostgreSQL 用户并在 PostgreSQL 中直接设置密码。

sudo -u postgres psql -c "\password"

然后输入并确认密码。

修改 PostgreSQL 的认证方式（可选）

要将 ident 替换为 md5，执行以下命令：

sudo sed -i 's/^host\s\+all\s\+all\s\+127\.0\.0\.1\/32\s\+ident/host    all             all             127.0.0.1\/32            md5/' /var/lib/pgsql/16/data/pg_hba.conf

sudo systemctl restart postgresql-16.service && psql -U postgres -d postgres -h 127.0.0.1 -W -c "CREATE DATABASE tb_edge;"

Cassandra 安装

运行 Cassandra 前需安装 Java 11：

sudo apt install openjdk-11-jdk-headless

将 Java 17 设为默认版本（ThingsBoard Edge 所需）：

sudo update-alternatives --config java

添加 Cassandra 软件源：

sudo nano /etc/yum.repos.d/cassandra.repo

加入以下内容：

[cassandra]
name=Apache Cassandra
baseurl=https://redhat.cassandra.apache.org/50x/
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://downloads.apache.org/cassandra/KEYS

50x 对应 Cassandra 5.0 系列。

如需要，更新软件包索引：

sudo yum update

安装 Cassandra：

sudo yum install cassandra

启动 Cassandra 服务：

sudo service cassandra start

ThingsBoard Edge 配置

编辑 ThingsBoard Edge 配置文件：

sudo nano /etc/tb-edge/conf/tb-edge.conf

将以下行添加到配置文件。别忘了将 “PUT_YOUR_POSTGRESQL_PASSWORD_HERE” 替换为您的 postgres 用户实际密码：

# DB Configuration 
export DATABASE_TS_TYPE=cassandra
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/tb_edge
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE

您可以选择性添加以下参数，以将 ThingsBoard Edge 实例重新配置为连接外部 Cassandra 节点：

export CASSANDRA_CLUSTER_NAME=Edge Cluster
export CASSANDRA_KEYSPACE_NAME=thingsboard
export CASSANDRA_URL=127.0.0.1:9042
export CASSANDRA_USE_CREDENTIALS=false
export CASSANDRA_USERNAME=
export CASSANDRA_PASSWORD=

步骤 3：选择 Queue 服务

ThingsBoard Edge 可使用不同消息系统/代理来存储消息并实现 ThingsBoard 服务间通信。如何选择合适的 queue 实现？

In Memory 为内置默认 queue 实现，适用于开发（PoC）环境，不适合生产部署或集群部署。
Kafka 适用于生产部署，当前大多数 ThingsBoard 生产环境均使用该 queue。

In Memory (built-in and default)

In Memory 队列已内置且默认启用，无需额外配置。

Docker 安装

为 CentOS/RHEL 安装 Docker

Kafka 安装

Apache Kafka 是一个开源流处理平台。

要在 Docker 容器中安装 Kafka，请运行以下命令。该命令会创建 docker-compose-kafka.yml，填入配置内容，并启动容器。

cat > docker-compose-kafka.yml <<EOF && docker compose -f docker-compose-kafka.yml up -d
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
EOF

ThingsBoard Edge 配置

编辑 ThingsBoard Edge 配置文件 (tb-edge.conf)：

echo -e "\nexport TB_QUEUE_TYPE=kafka\nexport TB_KAFKA_SERVERS=localhost:9092" | sudo tee -a /etc/tb-edge/conf/tb-edge.conf > /dev/null

步骤 4：安装 ThingsBoard Edge 服务

下载安装包。

wget https://github.com/thingsboard/thingsboard-edge/releases/download/v4.3.0.1/tb-edge-4.3.0.1.rpm

进入下载目录并安装 ThingsBoard Edge 服务

sudo rpm -Uvh tb-edge-4.3.0.1.rpm

步骤 5：配置 ThingsBoard Edge

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

编辑 ThingsBoard Edge 配置文件。

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export CLOUD_ROUTING_KEY=<PUT_YOUR_EDGE_KEY_HERE>
export CLOUD_ROUTING_SECRET=<PUT_YOUR_EDGE_SECRET_HERE>
export CLOUD_RPC_HOST=<PUT_YOUR_RPC_HOST>
export CLOUD_RPC_PORT=7070
export CLOUD_RPC_SSL_ENABLED=false
export HTTP_BIND_PORT=18080
export MQTT_BIND_PORT=11883
export COAP_BIND_PORT=15683
export LWM2M_ENABLED=false
export SNMP_ENABLED=false
EOL'

PUT_YOUR_EDGE_KEY_HERE： 替换为 实际的 Edge Key。
PUT_YOUR_EDGE_SECRET_HERE： 替换为 实际的 Edge Secret。
PUT_YOUR_RPC_HOST：
- Edge 与 Server 实例在同一台机器上时使用 localhost。
- Edge 连接同一网络或 Docker 内的 Server 实例时使用 X.X.X.X IP 地址。

配置 PostgreSQL（可选）

若修改了 PostgreSQL 默认数据源设置，请使用以下命令：

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/tb_edge
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=<PUT_YOUR_POSTGRESQL_PASSWORD_HERE>
EOL'

PUT_YOUR_POSTGRESQL_PASSWORD_HERE： 替换为实际的 PostgreSQL 用户密码。

步骤 6：运行安装脚本

ThingsBoard Edge 安装并配置完成后，请执行以下安装脚本：

sudo /usr/share/tb-edge/bin/install/install.sh

步骤 7：重启 ThingsBoard Edge 服务

sudo service tb-edge restart

步骤 8：打开 ThingsBoard Edge UI

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

请使用 ThingsBoard Server 的租户凭证登录 ThingsBoard Edge。

故障排除

ThingsBoard Edge 日志位于以下目录：

/var/log/tb-edge

检查服务端错误可运行以下命令：

cat /var/log/tb-edge/tb-edge.log | grep ERROR

启动 ThingsBoard Edge 服务：

sudo service tb-edge start

停止 ThingsBoard Edge 服务：

sudo service tb-edge stop

重启 ThingsBoard Edge 服务：

sudo service tb-edge restart

查看 ThingsBoard Edge 服务状态：

sudo service tb-edge status

下一步

恭喜！您已成功配置、安装 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 路线图。