使用 Docker 安装 ThingsBoard Edge（Linux 或 Mac OS）

前置条件
使用ThingsBoard服务器预配置指引安装
手动安装与配置
故障排查
- DNS 问题
下一步

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

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

本指南提供在Linux或Mac OS上使用Docker运行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** 已创建，将出现在列表顶部（默认按创建时间排序）。

Docker安装

使用ThingsBoard服务器预配置指引安装

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

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

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

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

手动安装与配置

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

步骤1. 运行ThingsBoard Edge

ThingsBoard Edge Docker 镜像位置：

thingsboard/tb-edge-pe

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

步骤2. 选择队列和/或数据库服务

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

In Memory队列实现是内置的默认方案。适用于开发（PoC）环境，不适合生产部署或任何类型的集群部署。
Kafka推荐用于生产部署。这是目前大多数ThingsBoard生产环境使用的队列。
Hybrid混合实现结合了PostgreSQL和Cassandra数据库以及Kafka队列服务。如果您计划在生产环境中管理100万+设备或处理高数据接入率（超过5000条消息/秒），建议使用此方案。

为ThingsBoard Edge服务创建Docker Compose文件：

In Memory (built-in and default)

Hybrid PostgreSQL+Cassandra with Kafka queue service

为 ThingsBoard Edge 服务创建 docker compose 文件：

nano docker-compose.yml

在 yml 文件 中添加以下配置内容：

version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge-pe:4.3.0.1EDGEPE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      EDGE_LICENSE_INSTANCE_DATA_FILE: /data/instance-edge-license.data
      CLOUD_ROUTING_KEY: PUT_YOUR_EDGE_KEY_HERE # e.g. 19ea7ee8-5e6d-e642-4f32-05440a529015
      CLOUD_ROUTING_SECRET: PUT_YOUR_EDGE_SECRET_HERE # e.g. bztvkvfqsye7omv9uxlp
      CLOUD_RPC_HOST: PUT_YOUR_CLOUD_IP # e.g. 192.168.1.1 or thingsboard.cloud
      CLOUD_RPC_SSL_ENABLED: 'false' # set it to 'true' if you are connecting edge to thingsboard.cloud 
    volumes:
      - tb-edge-data:/data
      - tb-edge-logs:/var/log/tb-edge
  postgres:
    restart: always
    image: "postgres:15"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: tb-edge
      POSTGRES_PASSWORD: postgres
    volumes:
      - tb-edge-postgres-data:/var/lib/postgresql/data
      
volumes:
  tb-edge-data:
    name: tb-edge-data
  tb-edge-logs:
    name: tb-edge-logs
  tb-edge-postgres-data:
    name: tb-edge-postgres-data

说明：

restart: always： 系统重启或故障后 ThingsBoard Edge 将自动启动。
8080:8080： 将本地端口 8080 映射到容器内部 HTTP 端口 8080。
1883:1883： 将本地端口 1883 映射到容器内部 MQTT 端口 1883。
5683-5688:5683-5688/udp： 将本地 UDP 端口 5683–5688 映射到容器内部 CoAP 与 LwM2M 端口。
thingsboard/tb-edge-pe:4.3.0.1EDGEPE： ThingsBoard Edge PE Docker 镜像。
CLOUD_ROUTING_KEY： 填入实际的 Edge key。
CLOUD_ROUTING_SECRET： 填入实际的 Edge secret。
CLOUD_RPC_HOST： 运行 ThingsBoard 平台的机器 IP 地址或主机名。
CLOUD_RPC_SSL_ENABLED： 定义 Edge 与 ThingsBoard 服务器间连接是否使用 SSL。true 启用，false 禁用。

请将 CLOUD_RPC_HOST 设为运行 ThingsBoard PE 的机器 IP 地址：

切勿使用 ‘localhost’——在 Docker 容器内 ‘localhost’ 指 Edge 服务自身地址。
若将 Edge 连接到 ThingsBoard Cloud，请使用 thingsboard.cloud。

注意： thingsboard.cloud 在 Edge 通信中使用 SSL。请将 CLOUD_RPC_SSL_ENABLED 改为 true。

Edge 连接同一网络或 Docker 环境中的 Cloud 实例时，使用 X.X.X.X IP 地址。

要更新 docker-compose.yml 中的端口配置，请执行：

sed -i 's/8080:8080/18080:8080/; s/1883:1883/11883:1883/; s/5683-5688:5683-5688\/udp/15683-15688:5683-5688\/udp/' docker-compose.yml

将终端切换到包含 docker-compose.yml 文件的目录，执行以下命令直接启动该 docker compose：

docker compose up -d && docker compose logs -f mytbedge

Apache Kafka 是开源流处理软件平台。

创建 docker compose 文件

nano docker-compose.yml

将以下配置行添加到文件：

version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge-pe:4.3.0.1EDGEPE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      EDGE_LICENSE_INSTANCE_DATA_FILE: /data/instance-edge-license.data
      CLOUD_ROUTING_KEY: PUT_YOUR_EDGE_KEY_HERE # e.g. 19ea7ee8-5e6d-e642-4f32-05440a529015
      CLOUD_ROUTING_SECRET: PUT_YOUR_EDGE_SECRET_HERE # e.g. bztvkvfqsye7omv9uxlp
      CLOUD_RPC_HOST: PUT_YOUR_CLOUD_IP # e.g. host.docker.internal, 192.168.1.1 or thingsboard.cloud, etc.
      CLOUD_RPC_SSL_ENABLED: 'false' # set it to 'true' if you are connecting edge to thingsboard.cloud
      TB_QUEUE_TYPE: "kafka"
      TB_KAFKA_SERVERS: "kafka:9092"
    volumes:
      - tb-edge-data:/data
      - tb-edge-logs:/var/log/tb-edge
    extra_hosts:
      - "host.docker.internal:host-gateway" 
  postgres:
    restart: always
    image: "postgres:15"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: tb-edge
      POSTGRES_PASSWORD: postgres
    volumes:
      - tb-edge-postgres-data:/var/lib/postgresql/data
  kafka:
    restart: always
    image: bitnamilegacy/kafka:4.0
    ports:
      - 9092
      - 9093 #for Kraft
    environment:
      ALLOW_PLAINTEXT_LISTENER: "yes"
      KAFKA_CFG_LISTENERS: "INTERNAL://:9092,CONTROLLER://:9093"
      KAFKA_CFG_ADVERTISED_LISTENERS: "INTERNAL://kafka:9092"
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "INTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT"
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "INTERNAL"
      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:
  tb-edge-data:
    name: tb-edge-data
  tb-edge-logs:
    name: tb-edge-logs
  tb-edge-postgres-data:
    name: tb-edge-postgres-data
  kafka-data:
    driver: local

说明：

restart: always： 系统重启或故障后 ThingsBoard Edge 将自动启动。
8080:8080： 将本地端口 8080 映射到容器内部 HTTP 端口 8080。
1883:1883： 将本地端口 1883 映射到容器内部 MQTT 端口 1883。
5683-5688:5683-5688/udp： 将本地 UDP 端口 5683–5688 映射到容器内部 CoAP 与 LwM2M 端口。
thingsboard/tb-edge-pe:4.3.0.1EDGEPE： ThingsBoard Edge PE Docker 镜像。
CLOUD_ROUTING_KEY： 填入实际的 Edge key。
CLOUD_ROUTING_SECRET： 填入实际的 Edge secret。
CLOUD_RPC_HOST： 运行 ThingsBoard 平台的机器 IP 地址或主机名。
CLOUD_RPC_SSL_ENABLED： 定义 Edge 与 ThingsBoard 服务器间连接是否使用 SSL。true 启用，false 禁用。

请将 CLOUD_RPC_HOST 设为运行 ThingsBoard PE 的机器 IP 地址：

切勿使用 ‘localhost’——在 Docker 容器内 ‘localhost’ 指 Edge 服务自身地址。
若将 Edge 连接到 ThingsBoard Cloud，请使用 thingsboard.cloud。

注意： thingsboard.cloud 在 Edge 通信中使用 SSL。请将 CLOUD_RPC_SSL_ENABLED 改为 true。

Edge 连接同一网络或 Docker 环境中的 Cloud 实例时，使用 X.X.X.X IP 地址。

要更新 docker-compose.yml 中的端口配置，请执行：

sed -i 's/8080:8080/18080:8080/; s/1883:1883/11883:1883/; s/5683-5688:5683-5688\/udp/15683-15688:5683-5688\/udp/' docker-compose.yml

将终端切换到包含 docker-compose.yml 文件的目录，执行以下命令直接启动该 docker compose：

docker compose up -d && docker compose logs -f mytbedge

Apache Cassandra 是一款开源 NoSQL 数据库，专为管理海量数据而设计。

Apache Kafka 是开源流处理软件平台。

创建 docker compose 文件：

nano docker-compose.yml

将以下配置行添加到 yml 文件：

version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge-pe:4.3.0.1EDGEPE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      EDGE_LICENSE_INSTANCE_DATA_FILE: /data/instance-edge-license.data
      CLOUD_ROUTING_KEY: PUT_YOUR_EDGE_KEY_HERE # e.g. 19ea7ee8-5e6d-e642-4f32-05440a529015
      CLOUD_ROUTING_SECRET: PUT_YOUR_EDGE_SECRET_HERE # e.g. bztvkvfqsye7omv9uxlp
      CLOUD_RPC_HOST: PUT_YOUR_CLOUD_IP # e.g. 192.168.1.1 or thingsboard.cloud
      CLOUD_RPC_SSL_ENABLED: 'false' # set it to 'true' if you are connecting edge to thingsboard.cloud
      TB_QUEUE_TYPE: "kafka"
      TB_KAFKA_SERVERS: "kafka:9092"
      DATABASE_TS_TYPE: "cassandra"
      CASSANDRA_URL: "cassandra:9042"
    volumes:
      - tb-edge-data:/data
      - tb-edge-logs:/var/log/tb-edge
    extra_hosts:
      - "host.docker.internal:host-gateway"
  postgres:
    restart: always
    image: "postgres:15"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: tb-edge
      POSTGRES_PASSWORD: postgres
    volumes:
      - tb-edge-postgres-data:/var/lib/postgresql/data
  kafka:
    restart: always
    image: bitnamilegacy/kafka:4.0
    ports:
      - 9092
      - 9093 #for Kraft
    environment:
      ALLOW_PLAINTEXT_LISTENER: "yes"
      KAFKA_CFG_LISTENERS: "INTERNAL://:9092,CONTROLLER://:9093"
      KAFKA_CFG_ADVERTISED_LISTENERS: "INTERNAL://kafka:9092"
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "INTERNAL:PLAINTEXT,CONTROLLER:PLAINTEXT"
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "INTERNAL"
      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
  cassandra:
    restart: always
    image: cassandra:4.0
    container_name: cassandra
    environment:
      CASSANDRA_CLUSTER_NAME: "Thingsboard Edge Cluster"
      CASSANDRA_KEYSPACE_NAME: "tb_edge"
      CASSANDRA_LOCAL_DATACENTER: "datacenter1"
    ports:
      - 9042:9042
    volumes:
      - ./data/cassandra:/var/lib/cassandra
volumes:
  tb-edge-data:
    name: tb-edge-data
  tb-edge-logs:
    name: tb-edge-logs
  tb-edge-postgres-data:
    name: tb-edge-postgres-data
  kafka-data:
    driver: local

说明：

restart: always： 系统重启或故障后 ThingsBoard Edge 将自动启动。
8080:8080： 将本地端口 8080 映射到容器内部 HTTP 端口 8080。
1883:1883： 将本地端口 1883 映射到容器内部 MQTT 端口 1883。
5683-5688:5683-5688/udp： 将本地 UDP 端口 5683–5688 映射到容器内部 CoAP 与 LwM2M 端口。
thingsboard/tb-edge-pe:4.3.0.1EDGEPE： ThingsBoard Edge PE Docker 镜像。
CLOUD_ROUTING_KEY： 填入实际的 Edge key。
CLOUD_ROUTING_SECRET： 填入实际的 Edge secret。
CLOUD_RPC_HOST： 运行 ThingsBoard 平台的机器 IP 地址或主机名。
CLOUD_RPC_SSL_ENABLED： 定义 Edge 与 ThingsBoard 服务器间连接是否使用 SSL。true 启用，false 禁用。

请将 CLOUD_RPC_HOST 设为运行 ThingsBoard PE 的机器 IP 地址：

切勿使用 ‘localhost’——在 Docker 容器内 ‘localhost’ 指 Edge 服务自身地址。
若将 Edge 连接到 ThingsBoard Cloud，请使用 thingsboard.cloud。

注意： thingsboard.cloud 在 Edge 通信中使用 SSL。请将 CLOUD_RPC_SSL_ENABLED 改为 true。

Edge 连接同一网络或 Docker 环境中的 Cloud 实例时，使用 X.X.X.X IP 地址。

要更新 docker-compose.yml 中的端口配置，请执行：

sed -i 's/8080:8080/18080:8080/; s/1883:1883/11883:1883/; s/5683-5688:5683-5688\/udp/15683-15688:5683-5688\/udp/' docker-compose.yml

将终端切换到包含 docker-compose.yml 文件的目录，执行以下命令直接启动该 docker compose：

docker compose up -d && docker compose logs -f mytbedge

步骤3. 打开ThingsBoard Edge UI

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

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

步骤4. 分离、停止和启动命令

可使用 Ctrl+p 后跟 Ctrl+q 从会话终端分离。容器将在后台继续运行。

若遇问题，可查看服务日志排查错误。例如，要查看 ThingsBoard Edge 容器日志，执行以下命令：

docker compose logs -f mytbedge

要停止容器，请执行：

docker compose stop mytbedge

要启动容器，请执行：

docker compose start mytbedge

要 停止并清理 docker compose 环境并删除所有相关数据，请执行：

docker compose down -v

要重建容器、卷和网络，请执行：

docker compose up -d

故障排查

DNS 问题

注意若出现与 DNS 相关的错误，例如：

127.0.1.1:53: cannot unmarshal DNS message

可将系统配置为使用 Google 公共 DNS 服务器。请参阅对应的 Linux 和 Mac OS 说明。

下一步

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