在 Ubuntu Server 上安装 ThingsBoard Edge

前置条件
手动安装与配置
故障排查
下一步

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

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

本指南提供在Ubuntu 22.04 LTS / 24.04 LTS上安装ThingsBoard Edge的分步说明。

前置条件

要运行 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** 已创建，将出现在列表顶部（默认按创建时间排序）。

使用服务器UI中的预配置指引安装

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

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

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

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

手动安装与配置

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

步骤1. 安装Java 17（OpenJDK）

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

sudo apt update && sudo apt install openjdk-17-jdk-headless

将您的操作系统配置为默认使用 OpenJDK 17。您可以通过运行以下命令来配置默认版本：

sudo update-alternatives --config java

要检查系统上已安装的 Java 版本，请使用以下命令：

java -version

预期输出为：

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

步骤2. 配置ThingsBoard Edge数据库

ThingsBoard Edge支持SQL和混合数据库方案。详情请参阅架构说明页面。

PostgreSQL (推荐用于 < 5K条消息/秒)

Hybrid
PostgreSQL+Cassandra
(推荐用于 > 5K条消息/秒)

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

要安装 PostgreSQL 数据库，请运行以下命令：

# Automated repository configuration:
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

# install and launch the postgresql service:
sudo apt update
sudo apt -y install postgresql-16
sudo service postgresql start

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

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

sudo -u postgres psql -c "\password"

然后输入并确认密码。

最后，执行以下命令创建名为 tb_edge 的 PostgreSQL 数据库：

echo "CREATE DATABASE tb_edge;" | psql -U postgres -d postgres -h 127.0.0.1 -W

PostgreSQL 安装

要安装 PostgreSQL 数据库，请运行以下命令：

# Automated repository configuration:
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh

# install and launch the postgresql service:
sudo apt update
sudo apt -y install postgresql-16
sudo service postgresql start

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

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

sudo -u postgres psql -c "\password"

然后输入并确认密码。

要创建名为 tb_edge 的新 PostgreSQL 数据库，请使用以下命令：

echo "CREATE DATABASE tb_edge;" | psql -U postgres -d postgres -h 127.0.0.1 -W

按两次 “Ctrl+D” 退出 PostgreSQL。

Cassandra 安装

以下说明将帮助您安装 Cassandra。

# 添加 cassandra 仓库
echo "deb https://debian.cassandra.apache.org 41x main" | sudo tee /etc/apt/sources.list.d/cassandra.sources.list
curl https://downloads.apache.org/cassandra/KEYS | sudo apt-key add -
sudo apt-get update
## 安装 Cassandra
sudo apt-get install cassandra
## 安装工具
sudo apt-get install cassandra-tools

要运行 Cassandra，请安装 Java 11。

sudo apt install openjdk-11-jdk-headless

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

sudo update-alternatives --config java

编辑 Cassandra 配置文件：

sudo sed -i 's|#JAVA_HOME=/usr/local/jdk6|JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64|' /usr/share/cassandra/cassandra.in.sh

然后重启 Cassandra：

sudo service cassandra stop && 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

您可以选择性添加以下参数，以将 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. 选择队列服务

ThingsBoard Edge可以使用不同的消息系统和消息代理来存储消息并实现其服务之间的通信。请根据您的具体业务需求选择合适的队列实现：

In Memory：内置的默认队列实现。适用于开发或概念验证（PoC）环境，但由于可扩展性有限，不建议用于生产或任何类型的集群部署。
Kafka：推荐用于生产部署。这是目前大多数ThingsBoard生产环境使用的队列。

In Memory (built-in and default)

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

Docker 安装

为 Ubuntu 安装 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 "export TB_QUEUE_TYPE=kafka\nexport TB_KAFKA_SERVERS=localhost:9092" | sudo tee -a /etc/tb-edge/conf/tb-edge.conf > /dev/null

如有需要，请务必将 “localhost:9092” 替换为您的 Kafka bootstrap 服务器地址

步骤4. 安装ThingsBoard Edge服务

下载安装包。

wget https://dist.thingsboard.io/tb-edge-4.3.0.1pe.deb

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

sudo dpkg -i tb-edge-4.3.0.1pe.deb

步骤5. 配置ThingsBoard Edge

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

编辑 ThingsBoard Edge 配置文件。

Cloud
(北美地区)
Cloud
(Europe)
On-Premise
(Local host)

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=thingsboard.cloud
export CLOUD_RPC_PORT=7070
export CLOUD_RPC_SSL_ENABLED=true
export INTEGRATIONS_RPC_PORT=19090
EOL'

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=eu.thingsboard.cloud
export CLOUD_RPC_PORT=7070
export CLOUD_RPC_SSL_ENABLED=true
export INTEGRATIONS_RPC_PORT=19090
EOL'

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
export INTEGRATIONS_RPC_PORT=19090
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 start

步骤8. 打开ThingsBoard Edge UI

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

请使用 ThingsBoard Server 的租户凭证 or ThingsBoard Cloud{: target=登录 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 路线图。