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

使用 Docker 安装 ThingsBoard PE（Linux 或 MacOS）

本指南将帮助您使用Docker和Docker Compose在Linux或MacOS上安装并启动ThingsBoard专业版（PE）。 本指南介绍的是ThingsBoard PE单机安装方式。 如需集群安装说明，请访问集群部署页面。

前置条件

安装 Docker：

文档警告图标

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

步骤1. 获取许可证密钥

我们假设您已经选择了订阅计划或决定购买永久许可证。 如果尚未选择，请前往定价页面选择最适合您的许可证方案。 详情请参考如何获取按需订阅或如何获取永久许可证。

注意：在本指南后续步骤中，此步获取的许可证密钥将统一用PUT_YOUR_LICENSE_SECRET_HERE表示。

步骤2. 选择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 文件中。请勿忘记将 “PUT_YOUR_LICENSE_SECRET_HERE” 替换为第一步获取的许可证密钥:

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

services:
  postgres:
    restart: always
    image: "postgres:16"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
  thingsboard-pe:
    restart: always
    image: "thingsboard/tb-pe-node:4.3.0.1PE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "8883:8883"
      - "9090:9090"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "10"
    environment:
      TB_SERVICE_ID: tb-pe-node
      TB_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
      TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data
      REPORTS_SERVER_ENDPOINT_URL: http://tb-web-report:8383
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      DEFAULT_TRENDZ_URL: http://trendz:8888
      DEFAULT_TB_URL: http://thingsboard-pe:8080
    volumes:
      - license-data:/data
    depends_on:
      - postgres
  tb-web-report:
    restart: always
    image: "thingsboard/tb-pe-web-report:4.3.0.1PE"
    ports:
      - "8383"
    depends_on:
      - thingsboard-pe
    environment:
      HTTP_BIND_ADDRESS: 0.0.0.0
      HTTP_BIND_PORT: 8383
      LOGGER_LEVEL: info
      LOG_FOLDER: logs
      LOGGER_FILENAME: tb-web-report-%DATE%.log
      DOCKER_MODE: true
      DEFAULT_PAGE_NAVIGATION_TIMEOUT: 120000
      DASHBOARD_IDLE_WAIT_TIME: 3000
      USE_NEW_PAGE_FOR_REPORT: true
volumes:
  postgres-data:
    name: tb-postgres-data
    driver: local
  license-data:
    name: tb-pe-license-data
    driver: local

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

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

1

nano docker-compose.yml

将以下内容添加到 yml 文件中。请勿忘记将 “PUT_YOUR_LICENSE_SECRET_HERE” 替换为第一步获取的许可证密钥:

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
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

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-pe:
    restart: always
    image: "thingsboard/tb-pe-node:4.3.0.1PE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "8883:8883"
      - "9090:9090"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "10"
    environment:
      TB_SERVICE_ID: tb-pe-node
      TB_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
      TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data
      REPORTS_SERVER_ENDPOINT_URL: http://tb-web-report:8383
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      DEFAULT_TRENDZ_URL: http://trendz:8888
      DEFAULT_TB_URL: http://thingsboard-pe:8080
      TB_QUEUE_TYPE: kafka
      TB_KAFKA_SERVERS: kafka:9092
    volumes:
      - license-data:/data
    depends_on:
      - postgres
  tb-web-report:
    restart: always
    image: "thingsboard/tb-pe-web-report:4.3.0.1PE"
    ports:
      - "8383"
    depends_on:
      - thingsboard-pe
    environment:
     HTTP_BIND_ADDRESS: 0.0.0.0
     HTTP_BIND_PORT: 8383
     LOGGER_LEVEL: info
     LOG_FOLDER: logs
     LOGGER_FILENAME: tb-web-report-%DATE%.log
     DOCKER_MODE: true
     DEFAULT_PAGE_NAVIGATION_TIMEOUT: 120000
     DASHBOARD_IDLE_WAIT_TIME: 3000
     USE_NEW_PAGE_FOR_REPORT: true
volumes:
  postgres-data:
    name: tb-postgres-data
    driver: local
  license-data:
    name: tb-pe-license-data
    driver: local
  kafka-data:
    name: tb-pe-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” and “localhost:9092” with your real Confluent Cloud bootstrap servers:

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
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

services:
  postgres:
    restart: always
    image: "postgres:16"
    ports:
      - "5432"
    environment:
      POSTGRES_DB: thingsboard
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
  thingsboard-pe:
    restart: always
    image: "thingsboard/tb-pe-node:4.3.0.1PE"
    ports:
      - "8080:8080"
      - "1883:1883"
      - "8883:8883"
      - "9090:9090"
      - "7070:7070"
      - "5683-5688:5683-5688/udp"
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "10"
    environment:
      TB_SERVICE_ID: tb-pe-node
      TB_LICENSE_SECRET: PUT_YOUR_LICENSE_SECRET_HERE
      TB_LICENSE_INSTANCE_DATA_FILE: /data/license.data
      REPORTS_SERVER_ENDPOINT_URL: http://tb-web-report:8383
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
      DEFAULT_TRENDZ_URL: http://trendz:8888
      DEFAULT_TB_URL: http://thingsboard-pe:8080
      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:
      - license-data:/data
  tb-web-report:
    restart: always
    image: "thingsboard/tb-pe-web-report:4.3.0.1PE"
    ports:
      - "8383"
    depends_on:
      - thingsboard-pe
    environment:
      HTTP_BIND_ADDRESS: 0.0.0.0
      HTTP_BIND_PORT: 8383
      LOGGER_LEVEL: info
      LOG_FOLDER: logs
      LOGGER_FILENAME: tb-web-report-%DATE%.log
      DOCKER_MODE: true
      DEFAULT_PAGE_NAVIGATION_TIMEOUT: 120000
      DASHBOARD_IDLE_WAIT_TIME: 3000
      USE_NEW_PAGE_FOR_REPORT: true
volumes:
  postgres-data:
    name: tb-postgres-data
    driver: local
  license-data:
    name: tb-pe-license-data
    driver: local

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

参数说明：

  • PUT_YOUR_LICENSE_SECRET_HERE - 第三步获取的许可证密钥占位符
  • 8080:8080 - 将本地端口8080映射到内部HTTP端口8080
  • 1883:1883 - 将本地端口1883映射到内部MQTT端口1883
  • 8883:8883 - 将本地端口8883映射到内部MQTT over SSL端口8883
  • 7070:7070 - 将本地端口7070映射到内部Edge RPC端口7070
  • 9090:9090 - 将本地端口9090映射到内部远程集成端口9090
  • 5683-5688:5683-5688/udp - 将本地UDP端口5683-5688映射到内部CoAP和LwM2M端口
  • tb-pe-license-data - 存储ThingsBoard许可证实例数据文件的Docker卷名称
  • tb-postgres-data - 存储PostgreSQL数据的Docker卷名称
  • thingsboard-pe - 本机的本地别名
  • restart: always - 系统重启时自动启动ThingsBoard，失败时自动重启
  • thingsboard/tb-pe-node:4.3.0.1PE - Docker镜像

步骤3. 初始化数据库架构和系统资源

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

1

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

环境变量说明：

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

步骤4. 启动平台并查看日志

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

1

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

After executing this command you can open http://{your-host-ip}:8080 in your browser (for ex. http://localhost:8080). You should see ThingsBoard login page.

文档信息图标

注意：仅当通过外部IP地址或域名访问ThingsBoard时，Web报表才能正常生成。

通过 http://localhost:8080 访问ThingsBoard时，Web报表将无法生成。

默认登录凭据：

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

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

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

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

如遇问题，可实时查看 ThingsBoard 容器日志：

1

docker compose logs -f thingsboard-pe

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

1

docker compose down

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

1

docker compose up -d

安装后步骤

安装Trendz Analytics

您可以随时通过以下步骤可选安装Trendz Analytics：

在 Postgres 中创建 Trendz 数据库：

1

docker compose -f docker-compose.yml exec -it postgres psql -U postgres -c "CREATE DATABASE trendz;"

为 Trendz Analytics 创建独立的 docker compose 文件：

1

nano docker-compose-trendz.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

services:
  trendz:
    restart: always
    image: "thingsboard/trendz:1.15.0.4"
    ports:
      - "8888:8888"
    environment:
      TB_API_URL: http://thingsboard-pe:8080
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/trendz
      SPRING_DATASOURCE_USERNAME: postgres
      SPRING_DATASOURCE_PASSWORD: postgres
      SCRIPT_ENGINE_DOCKER_PROVIDER_URL: trendz-python-executor:8181
      SCRIPT_ENGINE_TIMEOUT: 30000
    volumes:
      - trendz-conf:/trendz-config-files
      - trendz-data:/data
    depends_on:
      - postgres
  trendz-python-executor:
    restart: always
    image: "thingsboard/trendz-python-executor:1.15.0.4"
    ports:
      - "8181:8181"
    environment:
      EXECUTOR_MANAGER: 1
      EXECUTOR_SCRIPT_ENGINE: 6
      THROTTLING_QUEUE_CAPACITY: 10
      THROTTLING_THREAD_POOL_SIZE: 6
      NETWORK_BUFFER_SIZE: 5242880
    volumes:
      - trendz-python-executor-conf:/python-executor-config-files
      - trendz-python-executor-data:/data
volumes:
  trendz-conf:
    name: trendz-conf
    driver: local
  trendz-data:
    name: trendz-data
    driver: local
  trendz-python-executor-conf:
    name: trendz-python-executor-conf
    driver: local
  trendz-python-executor-data:
    name: trendz-python-executor-data
    driver: local

参数说明：

  • 8888:8888 - 将本地端口8888映射到内部HTTP端口8888
  • trendz-conf - 存储Trendz配置文件的Docker卷名称
  • trendz-data - 存储Trendz数据的Docker卷名称
  • trendz-python-executor-conf - 存储Trendz Python执行器配置文件的Docker卷名称
  • trendz-python-executor-data - 存储Trendz Python执行器数据的Docker卷名称
  • trendz-postgres-data - 存储Trendz PostgreSQL数据的Docker卷名称

了解更多Trendz Analytics信息，请参考此处。

启动平台（包含Trendz）并查看日志

以后台模式将全部容器（含 Trendz 容器）作为单一 Compose 项目启动，然后查看 ThingsBoard 日志：

1
2

docker compose -f docker-compose.yml -f docker-compose-trendz.yml up -d
docker compose -f docker-compose.yml -f docker-compose-trendz.yml logs -f thingsboard-pe

检查日志和管理容器生命周期（包含Trendz）

如遇问题，可实时查看 ThingsBoard 容器日志：

1

docker compose -f docker-compose.yml -f docker-compose-trendz.yml logs -f thingsboard-pe

实时查看 Trendz 容器日志：

1

docker compose -f docker-compose.yml -f docker-compose-trendz.yml logs -f trendz

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

1

docker compose -f docker-compose.yml -f docker-compose-trendz.yml down

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

1

docker compose -f docker-compose.yml -f docker-compose-trendz.yml up -d

升级到新版本Trendz

Trendz Analytics有独立的版本体系，需要与ThingsBoard平台主服务分开升级。

Trendz Analytics升级方法请参考此处。

升级到新版本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 说明。

下一步