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

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

文档信息图标
ThingsBoard Cloud

我们推荐使用 ThingsBoard Cloud —— 为您的 IoT 应用提供全托管、可扩展且具备容错能力的平台。
ThingsBoard Cloud 面向希望使用 ThingsBoard 但不想自行托管平台实例的用户。

本指南将帮助您在Linux或MacOS上使用Docker安装和启动ThingsBoard。

前置条件

安装 Docker：

文档警告图标

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

运行

运行此镜像需要至少4GB内存（建议8GB）且负载较低的服务器（每秒仅少量消息）。

选择ThingsBoard队列服务

ThingsBoard 平台目前支持两种消息 broker 用于存储消息及 ThingsBoard 服务间通信：In-memory 和基于 Kafka 的 broker。

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

  • Kafka 推荐用于生产部署。该 queue 现已在多数 ThingsBoard 生产环境中使用。 适用于本地部署和私有云部署。若希望独立于云提供商，同样适用。 部分云提供商也提供 Kafka 托管服务，如 AWS MSK。

  • Confluent Cloud 是基于 Kafka 的全托管流平台。适用于云无关部署。

详见对应架构 页面 和规则引擎 页面。

In Memory (built-in and default)
Kafka (recommended for on-prem, production installations)
Confluent Cloud (Event Streaming Platform based on Kafka)

ThingsBoard 内置 In Memory 队列服务，默认使用且无需额外配置。

创建 ThingsBoard 队列服务的 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

services:
  postgres:
    restart: always
    image: "postgres:16"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
  thingsboard-ce:
    restart: always
    image: "thingsboard/tb-node:4.3.0.1"
    ports:
      - "8080:8080"
      - "7070:7070"
      - "1883:1883"
      - "8883:8883"
      - "5683-5688:5683-5688/udp"
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "10"
    environment:
      TB_SERVICE_ID: tb-ce-node
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
    depends_on:
      - postgres

volumes:
  postgres-data:
    name: tb-postgres-data
    driver: local

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

创建 ThingsBoard 队列服务的 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

services:
  postgres:
    restart: always
    image: "postgres:16"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
  kafka:
    restart: always
    image: bitnamilegacy/kafka:4.0
    ports:
      - 9092:9092 #to localhost:9092 from host machine
      - 9093 #for Kraft
    environment:
      ALLOW_PLAINTEXT_LISTENER: "yes"
      KAFKA_CFG_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
      KAFKA_CFG_ADVERTISED_LISTENERS: "PLAINTEXT://:9092"
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "PLAINTEXT"
      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
      KAFKA_CFG_LOG_RETENTION_MS: "300000"
      KAFKA_CFG_SEGMENT_BYTES: "26214400"
    volumes:
      - kafka-data:/bitnami
  thingsboard-ce:
    restart: always
    image: "thingsboard/tb-node:4.3.0.1"
    ports:
      - "8080:8080"
      - "7070:7070"
      - "1883:1883"
      - "8883:8883"
      - "5683-5688:5683-5688/udp"
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "10"
    environment:
      TB_SERVICE_ID: tb-ce-node
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      TB_QUEUE_TYPE: kafka
      TB_KAFKA_SERVERS: kafka:9092
    depends_on:
      - postgres
      - kafka

volumes:
  postgres-data:
    name: tb-postgres-data
    driver: local
  kafka-data:
    name: tb-ce-kafka-data
    driver: local

Confluent Cloud 配置

要访问 Confluent Cloud，您需要先创建账户，然后创建 Kafka 集群并获取您的 API Key。

创建 ThingsBoard 队列服务的 docker compose 文件：

1

nano docker-compose.yml

将以下内容添加到 yml 文件中。请勿忘记将 “CLUSTER_API_KEY”, “CLUSTER_API_SECRET” 和 “localhost:9092” 替换为实际的 Confluent Cloud 引导服务器：

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

services:
  postgres:
    restart: always
    image: "postgres:16"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
  thingsboard-ce:
    restart: always
    image: "thingsboard/tb-node:4.3.0.1"
    ports:
      - "8080:8080"
      - "7070:7070"
      - "1883:1883"
      - "8883:8883"
      - "5683-5688:5683-5688/udp"
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "10"
    environment:
      TB_SERVICE_ID: tb-ce-node
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      TB_QUEUE_TYPE: kafka
      TB_KAFKA_SERVERS: localhost:9092
      TB_QUEUE_KAFKA_REPLICATION_FACTOR: 3
      TB_QUEUE_KAFKA_USE_CONFLUENT_CLOUD: true
      TB_QUEUE_KAFKA_CONFLUENT_SASL_JAAS_CONFIG: 'org.apache.kafka.common.security.plain.PlainLoginModule required username="CLUSTER_API_KEY" password="CLUSTER_API_SECRET";'
      # These params affect the number of requests per second from each partitions per each queue.
      # Number of requests to particular Message Queue is calculated based on the formula:
      # ((Number of Rule Engine and Core Queues) * (Number of partitions per Queue) + (Number of transport queues)
      #  + (Number of microservices) + (Number of JS executors)) * 1000 / POLL_INTERVAL_MS
      # For example, number of requests based on default parameters is:
      # Rule Engine queues:
      # Main 10 partitions + HighPriority 10 partitions + SequentialByOriginator 10 partitions = 30
      # Core queue 10 partitions
      # Transport request Queue + response Queue = 2
      # Rule Engine Transport notifications Queue + Core Transport notifications Queue = 2
      # Total = 44
      # Number of requests per second = 44 * 1000 / 25 = 1760 requests
      # 
      # Based on the use case, you can compromise latency and decrease number of partitions/requests to the queue, if the message load is low.
      # By UI set the parameters - interval (1000) and partitions (1) for Rule Engine queues.
      # Sample parameters to fit into 10 requests per second on a "monolith" deployment: 
      TB_QUEUE_CORE_POLL_INTERVAL_MS: 1000
      TB_QUEUE_CORE_PARTITIONS: 2
      TB_QUEUE_RULE_ENGINE_POLL_INTERVAL_MS: 1000
      TB_QUEUE_TRANSPORT_REQUEST_POLL_INTERVAL_MS: 1000
      TB_QUEUE_TRANSPORT_RESPONSE_POLL_INTERVAL_MS: 1000
      TB_QUEUE_TRANSPORT_NOTIFICATIONS_POLL_INTERVAL_MS: 1000
      TB_QUEUE_VC_INTERVAL_MS: 1000
      TB_QUEUE_VC_PARTITIONS: 1      
    depends_on:
      - postgres

volumes:
  postgres-data:
    name: tb-postgres-data
    driver: local

您可以通过 UI 更新默认规则引擎队列配置。有关 ThingsBoard 规则引擎队列的更多信息，请参阅文档。

参数说明：

  • 8080:8080 - 将本地端口8080映射到容器内部HTTP端口8080
  • 1883:1883 - 将本地端口1883映射到容器内部MQTT端口1883
  • 8883:8883 - 将本地端口8883映射到容器内部MQTT over SSL端口8883
  • 7070:7070 - 将本地端口7070映射到容器内部Edge RPC端口7070
  • 5683-5688:5683-5688/udp - 将本地UDP端口5683-5688映射到容器内部CoAP和LwM2M端口
  • tb-postgres-data - 存储PostgreSQL数据的Docker卷名称
  • thingsboard-ce - ThingsBoard容器的本地别名
  • restart: always - 系统重启时自动启动ThingsBoard，故障时自动重启
  • image: "thingsboard/tb-node:4.3.0.1" - ThingsBoard的Docker镜像及版本

初始化数据库结构和系统资源

启动ThingsBoard之前，请运行以下命令初始化数据库结构并加载内置资源：

1

docker compose run --rm -e INSTALL_TB=true -e LOAD_DEMO=true thingsboard-ce

环境变量说明：

  • INSTALL_TB=true - 安装核心数据库结构和系统资源（部件、图片、规则链等）。
  • LOAD_DEMO=true - 加载示例租户账户、仪表板和设备，用于评估和测试。

启动平台并查看日志

以后台模式启动所有容器，然后查看ThingsBoard日志：

1

docker compose up -d && docker compose logs -f thingsboard-ce

执行此命令后，在浏览器中打开http://{your-host-ip}:8080（例如http://localhost:8080），即可看到ThingsBoard登录页面。 使用以下默认凭据登录：

  • 系统管理员：sysadmin@thingsboard.org / sysadmin
  • 租户管理员：tenant@thingsboard.org / tenant
  • 客户用户：customer@thingsboard.org / customer

您可以随时在账户个人资料页面修改各账户的密码。

可以安全地从日志流中分离（例如按Ctrl+C），容器将继续运行。

查看日志和管理容器生命周期

如果出现问题，可以实时查看ThingsBoard容器日志：

1

docker compose logs -f thingsboard-ce

停止并移除Compose文件中定义的所有容器：

1

docker compose down

以后台模式启动所有服务：

1

docker compose up -d

安装后步骤

升级到新版本ThingsBoard

保持平台安全与更新

当有新 ThingsBoard 版本发布时，我们提供简化的更新流程，确保系统获得最新功能和安全补丁，且不危及您的数据。

文档信息图标

为保持数据库完整性和系统稳定性，请按顺序进行升级（例如 v4.0.2 → v4.1.0 → v4.2.0）。

请参阅官方 升级说明，获取针对您当前部署环境的详细步骤。

故障排查

DNS问题

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

1

127.0.1.1:53: cannot unmarshal DNS message

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

下一步