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

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

文档警告图标

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

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

Docker 安装

文档信息图标

ThingsBoard从3.4.2版本开始支持Docker Compose V2（Docker Desktop或Compose插件）。

我们强烈建议升级并使用Docker Compose V2，因为Docker已不再支持独立安装的docker-compose。

文档警告图标

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

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

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：运行 ThingsBoard Edge

ThingsBoard Edge Docker 镜像位置：

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

步骤 2：选择 Queue 和/或 Database 服务

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

  • In Memory 为内置默认 queue 实现，适用于开发（PoC）环境，不适合生产部署或集群部署。

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

  • Hybrid 实现将 PostgreSQL 和 Cassandra 与 Kafka queue 服务相结合，若计划在生产中管理 100 万以上设备或需要高数据摄入速率（超过 5000 msg/sec），建议采用。

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

In Memory (built-in and default)
Kafka (recommended for on-prem, production installations)
Hybrid (PostgreSQL+Cassandra with Kafka queue service)

创建 docker compose 文件：

1

nano docker-compose.yml

在 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
30
31
32
33
34
35

version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge:4.3.0.1EDGE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      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
    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:4.3.0.1EDGE： ThingsBoard Edge Docker 镜像。

  • CLOUD_ROUTING_KEY： 填入实际的 Edge key。
  • CLOUD_ROUTING_SECRET： 填入实际的 Edge secret。
  • CLOUD_RPC_HOST： 运行 ThingsBoard 平台的机器 IP 地址或主机名。
文档信息图标

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

  • 切勿使用 ‘localhost’——在 Docker 容器内 ‘localhost’ 指 Edge 服务自身地址。

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

文档信息图标

若 ThingsBoard Edge 与 ThingsBoard 服务器运行在 同一台机器 上，需修改端口配置以避免端口冲突。

请确保端口 18080、11883、15683-15688 未被其他应用占用。

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

1

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：

1

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

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

创建 docker compose 文件：

1

nano docker-compose.yml

在 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge:4.3.0.1EDGE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      CLOUD_ROUTING_KEY: PUT_YOUR_EDGE_KEY_HERE # 例如 19ea7ee8-5e6d-e642-4f32-05440a529015
      CLOUD_ROUTING_SECRET: PUT_YOUR_EDGE_SECRET_HERE # 例如 bztvkvfqsye7omv9uxlp
      CLOUD_RPC_HOST: PUT_YOUR_CLOUD_IP # 例如 192.168.1.1
      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:4.3.0.1EDGE： ThingsBoard Edge Docker 镜像。

  • CLOUD_ROUTING_KEY： 填入实际的 Edge key。
  • CLOUD_ROUTING_SECRET： 填入实际的 Edge secret。
  • CLOUD_RPC_HOST： 运行 ThingsBoard 平台的机器 IP 地址或主机名。
文档信息图标

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

  • 切勿使用 ‘localhost’——在 Docker 容器内 ‘localhost’ 指 Edge 服务自身地址。

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

文档信息图标

若 ThingsBoard Edge 与 ThingsBoard 服务器运行在 同一台机器 上，需修改端口配置以避免端口冲突。

请确保端口 18080、11883、15683-15688 未被其他应用占用。

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

1

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：

1

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

Apache Cassandra 是用于管理海量数据的开源 NoSQL 数据库。

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

创建 docker compose 文件：

1

nano docker-compose.yml

在 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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76

version: '3.8'
services:
  mytbedge:
    restart: always
    image: "thingsboard/tb-edge:4.3.0.1EDGE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "5683-5688:5683-5688/udp"
    environment:
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tb-edge
      CLOUD_ROUTING_KEY: PUT_YOUR_EDGE_KEY_HERE # 例如 19ea7ee8-5e6d-e642-4f32-05440a529015
      CLOUD_ROUTING_SECRET: PUT_YOUR_EDGE_SECRET_HERE # 例如 bztvkvfqsye7omv9uxlp
      CLOUD_RPC_HOST: PUT_YOUR_CLOUD_IP # 例如 192.168.1.1
      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:4.3.0.1EDGE： ThingsBoard Edge Docker 镜像。

  • CLOUD_ROUTING_KEY： 填入实际的 Edge key。
  • CLOUD_ROUTING_SECRET： 填入实际的 Edge secret。
  • CLOUD_RPC_HOST： 运行 ThingsBoard 平台的机器 IP 地址或主机名。
文档信息图标

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

  • 切勿使用 ‘localhost’——在 Docker 容器内 ‘localhost’ 指 Edge 服务自身地址。

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

文档信息图标

若 ThingsBoard Edge 与 ThingsBoard 服务器运行在 同一台机器 上，需修改端口配置以避免端口冲突。

请确保端口 18080、11883、15683-15688 未被其他应用占用。

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

1

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：

1

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

步骤 3：打开 ThingsBoard Edge UI

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

文档信息图标

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

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

步骤 4：分离、停止与启动命令

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

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

1

docker compose logs -f mytbedge

要 停止 容器，请执行：

1

docker compose stop mytbedge

要 启动 容器，请执行：

1

docker compose start mytbedge

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

1

docker compose down -v

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

1

docker compose up -d

故障排除

DNS 问题

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

1

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 规则引擎：

  • 安全：
    • 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 路线图。