产品定价 立即试用
边缘
社区版 专业版 云平台 边缘 PE边缘 IoT网关 许可证服务器 Trendz Analytics 移动应用 PE移动应用 MQTT Broker PE MQTT Broker
安装 > 本地部署 > Ubuntu Server
入门 文档
架构 API 常见问题
目录

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

使用 Server UI 中的预配置指令进行引导安装

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

  • 点击 Edge 实体打开其详情。

  • 点击 「Install & Connection Instructions」 按钮。

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

点击 Edge 实体打开其详情。

点击 Edge 实体打开其详情。

点击 「Install & Connection Instructions」 按钮。

点击 「Install & Connection Instructions」 按钮。

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

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

手动安装与配置

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

步骤 1：安装 Java 17（OpenJDK）

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

1

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

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

1

sudo update-alternatives --config java

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

1

java -version

预期输出为：

1
2
3

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

步骤 2：配置 ThingsBoard Edge 数据库

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

PostgreSQL (recommended for < 5K msg/sec)
Hybrid
PostgreSQL+Cassandra
(recommended for > 5K msg/sec)
文档信息图标

ThingsBoard 团队建议在 中等负载（低于 5000 msg/sec） 的开发和生产环境中使用 PostgreSQL。 多数云服务商提供托管 PostgreSQL 服务，对大多数 ThingsBoard 部署来说性价比较高。

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

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

1
2
3
4
5
6
7
8

# 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 中直接设置密码。

1

sudo -u postgres psql -c "\password"

然后输入并确认密码。

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

1

echo "CREATE DATABASE tb_edge;" | psql -U postgres -d postgres -h 127.0.0.1 -W
文档信息图标

如果您计划在生产环境中管理 100 万以上设备或处理高数据采集率（超过 5000 msg/sec），ThingsBoard 团队建议使用混合数据库方案。 在此方案下，ThingsBoard Edge 将时序数据存储在 Cassandra 中，同时继续使用 PostgreSQL 存储设备、资产、仪表板和客户等主要实体。

PostgreSQL 安装

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

1
2
3
4
5
6
7
8

# 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 中直接设置密码。

1

sudo -u postgres psql -c "\password"

然后输入并确认密码。

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

1

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

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

Cassandra 安装

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

1
2
3
4
5
6
7
8

# 添加 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。

1

sudo apt install openjdk-11-jdk-headless

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

1

sudo update-alternatives --config java

编辑 Cassandra 配置文件：

1

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：

1

sudo service cassandra stop && sudo service cassandra start
ThingsBoard Edge 配置

编辑 ThingsBoard Edge 配置文件：

1

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

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

1
2
3
4
5

# 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 节点：

1
2
3
4
5
6

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 可使用不同消息系统和代理来存储消息并实现服务间通信。请根据业务需求选择合适的 queue 实现：

  • In Memory：内置默认 queue 实现，适用于开发或概念验证（PoC）环境，因可扩展性有限，不建议用于生产或集群部署。

  • Kafka：建议用于生产部署，当前大多数 ThingsBoard 生产环境均使用该 queue。

In Memory (built-in and default)
Kafka (recommended for on-prem, production installations)

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

Docker 安装

为 Ubuntu 安装 Docker

文档警告图标

不要忘记将 Linux 用户加入 docker 用户组。参见 以非 root 用户管理 Docker。

Kafka 安装

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

要在 Docker 容器 中安装 Kafka，请运行以下命令。 该命令会创建 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
28
29

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)：

1

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 服务

下载安装包：

1

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

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

1

sudo dpkg -i tb-edge-4.3.0.1.deb

步骤 5：配置 ThingsBoard Edge

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

编辑 ThingsBoard Edge 配置文件。

1
2
3
4
5
6
7
8
9
10
11
12

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 默认数据源设置，请使用以下命令：

1
2
3
4
5

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 安装并配置完成后，请执行以下安装脚本：

1

sudo /usr/share/tb-edge/bin/install/install.sh
文档信息图标

请确保在根目录下运行此脚本。要切换到根目录，可执行命令 cd /。

步骤 7：启动 ThingsBoard Edge 服务

1

sudo service tb-edge start

步骤 8：打开 ThingsBoard Edge UI

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

文档信息图标

若Edge安装时将HTTP bind port修改为18080，请通过 http://localhost:18080 访问 ThingsBoard Edge 实例。

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

故障排除

ThingsBoard Edge 日志位于以下目录：

1

/var/log/tb-edge

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

1

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

启动 ThingsBoard Edge 服务：

1

sudo service tb-edge start

停止 ThingsBoard Edge 服务：

1

sudo service tb-edge stop

重启 ThingsBoard Edge 服务：

1

sudo service tb-edge restart

查看 ThingsBoard Edge 服务状态：

1

sudo service tb-edge status

下一步

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

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

  • Getting started guide（入门指南）- 快速概览 ThingsBoard Edge 主要功能。预计 15–30 分钟完成：

  • Edge 规则引擎：

  • 安全：
    • gRPC over SSL/TLS - 了解如何为 Edge 与云端之间的通信配置 gRPC over SSL/TLS。

  • 功能：

    • Edge Status（Edge 状态）- 了解 ThingsBoard Edge 上的 Edge Status 页面。

    • Cloud Events（云端事件）- 了解 ThingsBoard Edge 上的 Cloud Events 页面。

  • 使用场景：

  • Roadmap（路线图）- ThingsBoard Edge 路线图。