ThingsBoard专业版Docker Compose集群设置指南

前置条件
步骤 1. 拉取 ThingsBoard PE 镜像
步骤 2. 克隆 ThingsBoard PE Docker Compose 脚本
步骤 3. 获取许可证密钥
步骤 4. 配置许可证密钥
步骤 5. 配置部署类型
步骤 6. 配置 ThingsBoard 数据库
步骤 7. 选择 ThingsBoard 队列服务
步骤 8. 启用监控（可选）
步骤 9. 启用 Trendz Analytics（可选）
步骤 10. 运行
- 创建并检查所需主机卷
- 安装并运行 ThingsBoard
安装后步骤
后续步骤

本指南将帮助您使用 Docker Compose 以集群模式设置 ThingsBoard。为此，我们将使用 Docker Hub 上提供的 Docker 容器镜像。

前置条件

ThingsBoard 微服务在 Docker 化环境中运行。开始前请确保系统中已安装 Docker Engine 和 Docker Compose。

安装 Docker：

步骤 1. 拉取 ThingsBoard PE 镜像

运行以下命令验证您能否从 Docker Hub 拉取镜像。

docker pull thingsboard/tb-pe-node:4.3.0.1PE
docker pull thingsboard/tb-pe-web-report:4.3.0.1PE
docker pull thingsboard/tb-pe-web-ui:4.3.0.1PE
docker pull thingsboard/tb-pe-js-executor:4.3.0.1PE
docker pull thingsboard/tb-pe-http-transport:4.3.0.1PE
docker pull thingsboard/tb-pe-mqtt-transport:4.3.0.1PE
docker pull thingsboard/tb-pe-coap-transport:4.3.0.1PE
docker pull thingsboard/tb-pe-lwm2m-transport:4.3.0.1PE
docker pull thingsboard/tb-pe-snmp-transport:4.3.0.1PE

步骤 2. 克隆 ThingsBoard PE Docker Compose 脚本

git clone -b release-4.3.0.1 https://github.com/thingsboard/thingsboard-pe-docker-compose.git tb-pe-docker-compose --depth 1
cd tb-pe-docker-compose

步骤 3. 获取许可证密钥

我们假定您已选择订阅计划或决定购买永久许可证。否则，请前往 pricing 页面选择适合的许可证选项并获取许可证。详见如何获取按需付费订阅或如何获取永久许可证。

重要提示：若使用高级部署类型，请确保已购买至少四个 ThingsBoard PE 实例的许可证密钥。否则，需修改 docker-compose.yml) 的本地副本，以使用您已购买的 ThingsBoard 实例数量。本指南稍后将使用 PUT_YOUR_LICENSE_SECRET_HERE 引用您在本步骤获取的许可证密钥。

步骤 4. 配置许可证密钥

nano tb-node.env

并将 “PUT_YOUR_LICENSE_SECRET_HERE” 替换为许可证密钥参数：

# ThingsBoard server configuration
...
TB_LICENSE_SECRET=PUT_YOUR_LICENSE_SECRET_HERE

步骤 5. 配置部署类型

自 ThingsBoard v2.2 起，可使用新的微服务架构和 Docker 容器安装 ThingsBoard 集群。详见 微服务 架构页面。

Docker Compose 脚本支持三种部署模式。要设置部署模式，请将 .env 文件中 TB_SETUP 变量的值改为以下之一：

basic （推荐，默认） - ThingsBoard 核心与规则引擎在同一 JVM 中启动（仅需一个许可证）。 MQTT、CoAP 和 HTTP 传输在独立容器中启动。
monolith - ThingsBoard 核心与规则引擎在同一 JVM 中启动（仅需一个许可证）。 MQTT、CoAP 和 HTTP 传输也在同一 JVM 中启动，以最小化内存占用和服务器要求。
advanced - ThingsBoard 核心与规则引擎在独立容器中启动并复制（需要 4 个许可证）。

所有部署模式均支持独立 JS 执行器、Redis 及不同队列。

步骤 6. 配置 ThingsBoard 数据库

在执行初始安装之前，可配置 ThingsBoard 使用的数据库类型。要设置数据库类型，请在 .env 文件中更改 DATABASE 变量的值：

nano .env

设置为以下之一：

postgres - 使用 PostgreSQL 数据库；
hybrid - 实体数据库使用 PostgreSQL，时序数据库使用 Cassandra；

注意：根据数据库类型将部署相应的 docker 服务（详见 docker-compose.postgres.yml、docker-compose.hybrid.yml）。

步骤 7. 选择 ThingsBoard 队列服务

ThingsBoard 目前支持两种用于存储消息的消息系统/代理：内存队列和基于 Kafka 的系统。

In Memory 队列实现不适用于任何类型的集群部署。

Kafka 推荐用于生产部署，且为默认选项。该队列已在大多数 ThingsBoard 生产环境中使用。适用于本地和私有云部署。若希望与云厂商解耦，也可选用。部分云厂商也提供 Kafka 托管服务，例如 AWS MSK。
Confluent Cloud 是基于 Kafka 的全托管流平台，适用于云无关部署。

更多详情请参阅相应架构页面和规则引擎页面。

Kafka （默认，推荐用于本地生产部署）

Confluent Cloud （基于 Kafka 的事件流平台）

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

配置 ThingsBoard 环境文件：

nano .env

检查以下行：

TB_QUEUE_TYPE=kafka

Confluent Cloud 配置

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

配置 ThingsBoard 环境文件：

nano .env

检查以下行：

TB_QUEUE_TYPE=confluent

为 ThingsBoard 队列服务配置 Confluent Cloud 环境文件：

nano queue-confluent-cloud.env

请勿忘记将 “CLUSTER_API_KEY”、”CLUSTER_API_SECRET” 和 “confluent.cloud:9092” 替换为您的实际 Confluent Cloud 引导服务器：

TB_QUEUE_TYPE=kafka

TB_KAFKA_SERVERS=confluent.cloud:9092
TB_QUEUE_KAFKA_REPLICATION_FACTOR=3

TB_QUEUE_KAFKA_USE_CONFLUENT_CLOUD=true
TB_QUEUE_KAFKA_CONFLUENT_SSL_ALGORITHM=https
TB_QUEUE_KAFKA_CONFLUENT_SASL_MECHANISM=PLAIN
TB_QUEUE_KAFKA_CONFLUENT_SASL_JAAS_CONFIG='org.apache.kafka.common.security.plain.PlainLoginModule required username="CLUSTER_API_KEY" password="CLUSTER_API_SECRET";'
TB_QUEUE_KAFKA_CONFLUENT_SECURITY_PROTOCOL=SASL_SSL
TB_QUEUE_KAFKA_CONFLUENT_USERNAME=CLUSTER_API_KEY
TB_QUEUE_KAFKA_CONFLUENT_PASSWORD=CLUSTER_API_SECRET

TB_QUEUE_KAFKA_RE_TOPIC_PROPERTIES=retention.ms:604800000;segment.bytes:52428800;retention.bytes:1048576000
TB_QUEUE_KAFKA_CORE_TOPIC_PROPERTIES=retention.ms:604800000;segment.bytes:52428800;retention.bytes:1048576000
TB_QUEUE_KAFKA_TA_TOPIC_PROPERTIES=retention.ms:604800000;segment.bytes:52428800;retention.bytes:1048576000
TB_QUEUE_KAFKA_NOTIFICATIONS_TOPIC_PROPERTIES=retention.ms:604800000;segment.bytes:52428800;retention.bytes:1048576000
TB_QUEUE_KAFKA_JE_TOPIC_PROPERTIES=retention.ms:604800000;segment.bytes:52428800;retention.bytes:104857600

# 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

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

步骤 8. 启用监控（可选）

要启动集群监控（Grafana 和 Prometheus 服务），请编辑配置文件：

nano .env

需确保 MONITORING_ENABLED 变量设置为 true：

MONITORING_ENABLED=true

部署完成后，可通过 http://localhost:9090 访问 Prometheus，通过 http://localhost:3000 访问 Grafana（默认登录名为 admin，密码为 foobar）。

步骤 9. 启用 Trendz Analytics（可选）

您可随时按以下步骤安装 Trendz Analytics：

编辑配置文件：

nano .env

需确保 TRENDZ_ENABLED 变量设置为 true：

TRENDZ_ENABLED=true

可在此处了解 Trendz Analytics 详情。

步骤 10. 运行

创建并检查所需主机卷

执行以下命令为服务创建日志文件夹，并将这些文件夹的 chown 权限授予 docker 容器用户。要更改用户，需使用 chown 命令，该命令需要 sudo 权限（脚本将提示输入 sudo 密码）：

./docker-create-log-folders.sh

检查所有必需的卷文件夹是否可用且具有正确的所有权：

./docker-check-log-folders.sh

安装并运行 ThingsBoard

执行以下命令进行安装：

./docker-install-tb.sh --loadDemo

其中：

--loadDemo - 可选参数。是否加载额外演示数据。

执行以下命令启动服务：

./docker-start-services.sh

当所有服务成功启动后，可在浏览器中打开 http://{your-host-ip}（例如 http://localhost）。您将看到 ThingsBoard 登录页面。

使用以下默认凭证：

系统管理员：sysadmin@thingsboard.org / sysadmin

若使用了 --loadDemo 参数安装包含演示数据的数据库，还可使用以下凭证：

租户管理员：tenant@thingsboard.org / tenant
客户用户：customer@thingsboard.org / customer

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

docker compose -f $TB_SETUP/docker-compose.yml logs -f tb-core1 tb-rule-engine1

或使用以下命令查看所有容器状态：

docker compose -f $TB_SETUP/docker-compose.yml ps

使用以下命令查看所有运行中服务的日志：

docker compose -f $TB_SETUP/docker-compose.yml logs -f

详见 docker-compose logs 命令参考。

执行以下命令停止服务：

./docker-stop-services.sh

执行以下命令停止并完全移除已部署的 Docker 容器：

./docker-remove-services.sh

执行以下命令更新指定或所有服务（拉取新镜像并重建容器）：

./docker-update-service.sh [SERVICE...]

其中：

[SERVICE...] - 要更新的服务列表（在 docker-compose 配置中定义）。若未指定则更新所有服务。

安装后步骤

生成 HTTPS 证书

我们使用 HAproxy 将流量代理至容器，Web UI 默认使用 80 和 443 端口。要为 HTTPS 使用有效证书，请执行以下命令：

docker exec haproxy-certbot certbot-certonly --domain your_domain --email your_email
docker exec haproxy-certbot haproxy-refresh

注意：仅当通过 URL 中的域名访问 Web UI 时才使用有效证书。若通过 IP 地址访问 UI，将使用自签名证书。

升级到新版 ThingsBoard

保持平台安全与更新

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

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

升级到新版 Trendz（可选）

Trendz Analytics 采用独立的版本体系，应与 ThingsBoard 平台主服务分开更新。

要更新 Trendz，需编辑 .env 文件，将 “TRENDZ_VERSION” 设为目标版本（如升级到最新版可设为 1.15.0.4）。然后执行以下命令：

./docker-stop-services.sh
./docker-upgrade-trendz.sh
./docker-start-services.sh

注意，可从任意版本升级 Trendz 至最新版（例如 1.12.0 -> 1.15.0.4 等）。

后续步骤

快速入门指南 - 快速了解ThingsBoard主要功能，约15-30分钟完成。
连接设备 - 根据连接技术或方案学习如何连接设备。
数据可视化 - 配置ThingsBoard复杂仪表盘的说明。
数据处理与操作 - 学习使用ThingsBoard规则引擎。
IoT数据分析 - 学习使用规则引擎执行基本分析任务。
高级功能 - 了解ThingsBoard高级功能。
贡献与开发 - 了解ThingsBoard贡献与开发。