在 GCP 上使用 Kubernetes 部署 TBMQ 集群

• 前置条件
  • 安装并配置工具
  • 启用 GCP 服务
• 步骤1. 克隆TBMQ K8S脚本仓库
• 步骤2. 定义环境变量
• 步骤3. 配置并创建GKE集群
• 步骤4. 更新kubectl上下文
• 步骤5. 配置Google Cloud SQL (PostgreSQL) 实例
  • 5.1 前提条件
  • 5.2 创建数据库服务器实例
  • 5.3 设置数据库密码
  • 5.4 创建数据库
  • 5.5编辑数据库设置
• 步骤6. 创建Namespace为TBMQ集群部署创建专用命名空间，以确保更好的资源隔离和管理。
• 步骤7. 配置Redis集群
• 步骤8. 安装
• 步骤9. 配置Kafka
• 步骤10. 启动
• 步骤11. 配置负载均衡器
  • 11.1配置HTTP(S) 负载均衡器
    • HTTP负载均衡器
    • HTTPS负载均衡器
  • 11.2配置MQTT负载均衡器
    • MQTT over SSL按照本指南创建带 SSL证书的 .pem文件。将文件保存为工作目录中的 server.pem。
• 步骤 12. 验证配置
  • 验证 MQTT访问
  • 故障排查
• 升级
  • 备份和恢复（可选）
  • 升级到 2.2.0
  • 升级到 2.1.0
    • 添加 Integration Executor 微服务
    • 更新第三方服务
  • 升级到 2.0.0
  • 执行升级
• 删除集群
• 后续步骤

本指南将帮助您在GKE中以微服务模式部署TBMQ。

前置条件

安装并配置工具

要在 GKE 集群上部署 ThingsBoard，需安装 kubectl 和 gcloud 工具。 更多信息参见 开始前准备 指南。

创建新的 Google Cloud Platform 项目（推荐）或选择现有项目。

执行以下命令确保已选择正确项目：

1
gcloud init

启用 GCP 服务

执行以下命令为您的项目启用 GKE 和 SQL 服务：

1
gcloud services enable container.googleapis.com sql-component.googleapis.com sqladmin.googleapis.com

步骤1. 克隆TBMQ K8S脚本仓库

1
2
git clone -b release-2.2.0 https://github.com/thingsboard/tbmq.git
cd tbmq/k8s/gcp

步骤2. 定义环境变量

定义您将在此指南后续各种命令中使用的环境变量。

假设您使用 Linux。执行以下命令：

1
2
3
4
5
6
7
8
9
10
export GCP_PROJECT=$(gcloud config get-value project)
export GCP_REGION=us-central1
export GCP_ZONE=us-central1
export GCP_ZONE1=us-central1-a
export GCP_ZONE2=us-central1-b
export GCP_ZONE3=us-central1-c
export GCP_NETWORK=default
export TB_CLUSTER_NAME=tbmq-cluster
export TB_DATABASE_NAME=tbmq-db
echo "You have selected project: $GCP_PROJECT, region: $GCP_REGION, gcp zones: $GCP_ZONE1,$GCP_ZONE2,$GCP_ZONE3, network: $GCP_NETWORK, cluster: $TB_CLUSTER_NAME, database: $TB_DATABASE_NAME"

其中：

• 第一行使用 gcloud 命令获取您当前的 GCP 项目 ID。我们将在本指南后续内容中使用 $GCP_PROJECT 引用；
• us-central1 是可用的计算区域之一。我们将在本指南后续内容中使用 $GCP_REGION 引用；
• default 是默认 GCP 网络名称；我们将在本指南后续内容中使用 $GCP_NETWORK 引用；
• tbmq-cluster 是您的集群名称。您可以输入不同的名称。我们将在本指南后续内容中使用 $TB_CLUSTER_NAME 引用；
• tbmq-db 是您的数据库服务器名称。您可以输入不同的名称。我们将在本指南后续内容中使用 $TB_DATABASE_NAME 引用。

步骤3. 配置并创建GKE集群

在 3 个可用区内创建分布式的区域集群，使用您偏好的机器类型。 以下示例在每个可用区预置 1 个 e2-standard-4 节点（共三个节点），但您可以根据工作负载需求修改 --machine-type 和 --num-nodes。 有关可用机器类型及其规格的完整列表，请参阅 GCP 机器类型文档。

执行以下命令（推荐）：

1
2
3
4
5
6
7
8
9
gcloud container clusters create $TB_CLUSTER_NAME \
--release-channel stable \
--region $GCP_REGION \
--network=$GCP_NETWORK \
--node-locations $GCP_ZONE1,$GCP_ZONE2,$GCP_ZONE3 \
--enable-ip-alias \
--num-nodes=1 \
--node-labels=role=main \
--machine-type=e2-standard-4

或者，您可以使用此指南进行自定义集群设置。

步骤4. 更新kubectl上下文

使用以下命令更新 kubectl 的上下文：

1
gcloud container clusters get-credentials $TB_CLUSTER_NAME --region $GCP_REGION

步骤5. 配置Google Cloud SQL (PostgreSQL) 实例

5.1 前提条件

启用服务网络以使 K8S 集群连接至 DB 实例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
gcloud services enable servicenetworking.googleapis.com --project=$GCP_PROJECT

gcloud compute addresses create google-managed-services-$GCP_NETWORK \
--global \
--purpose=VPC_PEERING \
--prefix-length=16 \
--network=projects/$GCP_PROJECT/global/networks/$GCP_NETWORK

gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=google-managed-services-$GCP_NETWORK \
--network=$GCP_NETWORK \
--project=$GCP_PROJECT
    

5.2 创建数据库服务器实例

创建数据库版本为 “PostgreSQL 16” 的 PostgreSQL 实例，建议如下：

• 使用与 K8S 集群 GCP_REGION 相同区域；
• 使用与 K8S 集群 GCP_REGION 相同的 VPC 网络；
• 使用私有 IP 连接实例并禁用公网 IP；
• 生产环境使用高可用 DB 实例，开发集群使用单可用区实例；
• 至少使用 2 vCPU 和 7.5 GB 内存，可满足大多数负载，可按需扩展；

执行以下命令：

1
2
3
4
5
6
gcloud beta sql instances create $TB_DATABASE_NAME \
--database-version=POSTGRES_16 \
--region=$GCP_REGION --availability-type=regional \
--no-assign-ip --network=projects/$GCP_PROJECT/global/networks/$GCP_NETWORK \
--cpu=2 --memory=7680MB

也可参考 此 指南配置数据库。

从命令输出中记录 IP 地址（YOUR_DB_IP_ADDRESS）。成功执行后的输出类似：

1
2
3
Created [https://sqladmin.googleapis.com/sql/v1beta4/projects/YOUR_PROJECT_ID/instances/$TB_DATABASE_NAME].
NAME                        DATABASE_VERSION  LOCATION       TIER              PRIMARY_ADDRESS  PRIVATE_ADDRESS  STATUS
$TB_DATABASE_NAME           POSTGRES_16       us-central1-f  db-custom-2-7680  35.192.189.68    -                RUNNABLE

5.3 设置数据库密码

为新建数据库服务器实例设置密码：

1
2
3
gcloud sql users set-password postgres \
--instance=$TB_DATABASE_NAME \
--password=secret

其中：

• instance 为数据库服务器实例名称；
• secret 为密码。应使用不同密码。本指南后续以 YOUR_DB_PASSWORD 引用；

5.4 创建数据库

在 postgres 数据库服务器实例中创建 “thingsboard_mqtt_broker” 数据库：

1
gcloud sql databases create thingsboard_mqtt_broker --instance=$TB_DATABASE_NAME

其中 thingsboard_mqtt_broker 为数据库名称。可使用其他名称。本指南后续以 YOUR_DB_NAME 引用；

5.5编辑数据库设置

将 YOUR_DB_IP_ADDRESS、YOUR_DB_PASSWORD 和 YOUR_DB_NAME 替换为正确的值：

1
nano tb-broker-db-configmap.yml

步骤6. 创建Namespace为TBMQ集群部署创建专用命名空间，以确保更好的资源隔离和管理。

1
2
kubectl apply -f tb-broker-namespace.yml
kubectl config set-context $(kubectl config current-context) --namespace=thingsboard-mqtt-broker

步骤7. 配置Redis集群

我们建议使用Helm部署Bitnami Redis Cluster。请查看 redis 文件夹。

1
ls redis/

您可以找到 default-values-redis.yml 文件（从 Bitnami artifactHub 下载的默认值）和带有修改值的 values-redis.yml 文件。 我们建议保持第一个文件不变，仅修改第二个文件。这样，升级到下一版本的过程会更顺利，因为可以查看diff。

添加Bitnami Helm仓库：

1
2
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

安装Bitnami Redis集群，执行以下命令：

1
helm install redis -f redis/values-redis.yml bitnami/redis-cluster --version 10.2.5

部署完成后，您将看到部署状态信息，随后是获取REDIS_PASSWORD的命令：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
NAME: redis
LAST DEPLOYED: Tue Apr  8 11:22:44 2025
NAMESPACE: thingsboard-mqtt-broker
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
CHART NAME: redis-cluster
CHART VERSION: 10.2.5
APP VERSION: 7.2.5** 请在图表部署期间耐心等待 **


获取密码请运行：
    export REDIS_PASSWORD=$(kubectl get secret --namespace "thingsboard-mqtt-broker" redis-redis-cluster -o jsonpath="{.data.redis-password}" | base64 -d)

修改此命令以在终端打印密码：

1
echo $(kubectl get secret --namespace "thingsboard-mqtt-broker" redis-redis-cluster -o jsonpath="{.data.redis-password}" | base64 -d)

您需要复制输出并将其粘贴到 tb-broker-cache-configmap.yml 文件中，替换 YOUR_REDIS_PASSWORD。

1
nano tb-broker-cache-configmap.yml

tb-broker-cache-configmap.yml 中 REDIS_NODES 的值默认为 "redis-redis-cluster-headless:6379"。 主机名基于release名称 (redis) 和Bitnami图表的默认命名约定。 如果您在Redis values文件中修改了 nameOverride 或 fullnameOverride 字段，或在安装期间更改了release名称， 则必须相应地更新此值以匹配图表创建的实际headless服务名称。

步骤8. 安装

执行以下命令运行安装：

1
./k8s-install-tbmq.sh

此命令完成后，您应在控制台看到下一行：

1
安装已成功完成！

否则，请检查您是否在 tb-broker-db-configmap.yml 中正确设置了PostgreSQL URL和PostgreSQL密码。

步骤9. 配置Kafka

建议使用 Helm 部署 Bitnami Kafka。请先查看 kafka 目录。

1
ls kafka/

其中可找到 default-values-kafka.yml 文件——从 Bitnami artifactHub 下载的默认值。以及修改后的 values-kafka.yml 文件。 建议保持第一个文件不变，仅修改第二个文件。这样升级到下一版本时更容易通过 diff 看出变更。

添加 Bitnami helm 仓库：

1
2
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

安装 Bitnami Kafka 时执行以下命令：

1
helm install kafka -f kafka/values-kafka.yml bitnami/kafka --version 29.3.4

等待几分钟直至 Kafka Pod 启动并运行。

步骤10. 启动

执行以下命令部署broker：

1
./k8s-deploy-tbmq.sh

几分钟后，您可以执行下一个命令检查所有pod的状态。

1
kubectl get pods

如果一切正常，您应该能看到 tb-broker-0 和 tb-broker-1 pod。每个pod应处于 READY 状态。

步骤11. 配置负载均衡器

11.1配置HTTP(S) 负载均衡器

配置HTTP(S) 负载均衡器以访问TBMQ实例的Web界面。基本上，您有两种配置选项：

• http-不支持HTTPS的负载均衡器。推荐用于开发。唯一优点是配置简单、成本最低。可能适合开发服务器，但绝对不适合生产环境。
• https-支持HTTPS的负载均衡器。推荐用于生产。作为SSL终止点。您可以轻松配置它来颁发和维护有效的SSL证书。自动将所有非安全 (HTTP) 流量重定向到安全 (HTTPS) 端口。

请参阅以下链接/说明了解如何配置每种建议选项。

HTTP负载均衡器

执行以下命令部署纯http负载均衡器：

1
kubectl apply -f receipts/http-load-balancer.yml

负载均衡器配置过程可能需要一些时间。您可以使用以下命令定期检查负载均衡器状态：

1
kubectl get ingress

配置完成后，您应该看到类似输出：

1
2
NAME                          CLASS    HOSTS   ADDRESS         PORTS   AGE
tb-broker-http-loadbalancer   <none>   *       34.111.24.134   80      7m25s

HTTPS负载均衡器

使用Google托管SSL证书配置负载均衡器的过程在官方文档页面中有描述。 以下说明摘自官方文档。在继续之前，请务必仔细阅读前置条件。

1
gcloud compute addresses create tbmq-http-lb-address --global

在 https-load-balancer.yml 文件中将 PUT_YOUR_DOMAIN_HERE 替换为有效域名：

1
nano receipts/https-load-balancer.yml

执行以下命令部署安全http负载均衡器：

1
 kubectl apply -f receipts/https-load-balancer.yml

负载均衡器配置过程可能需要一些时间。您可以使用以下命令定期检查负载均衡器状态：

1
kubectl get ingress

配置完成后，您应该看到类似输出：

1
2
NAME                           CLASS    HOSTS   ADDRESS         PORTS   AGE
tb-broker-https-loadbalancer   gce      *       34.111.24.134   80      7m25s

现在，将您使用的域名分配给负载均衡器IP地址（命令输出中34.111.24.134的替代地址）。

使用dig检查域名配置是否正确：

1
dig YOUR_DOMAIN_NAME

示例输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
; <<>> DiG 9.11.3-1ubuntu1.16-Ubuntu <<>> YOUR_DOMAIN_NAME
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 12513
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 65494
;; QUESTION SECTION:
;YOUR_DOMAIN_NAME.	IN	A

;; ANSWER SECTION:
YOUR_DOMAIN_NAME. 36 IN	A	34.111.24.134

;; Query time: 0 msec
;; SERVER: 127.0.0.53#53(127.0.0.53)
;; WHEN: Fri Nov 19 13:00:00 EET 2021
;; MSG SIZE  rcvd: 74

分配后，等待Google托管证书完成配置。这可能需要长达60分钟。您可以使用以下命令检查证书状态：

1
kubectl describe managedcertificate managed-cert

如果您正确配置了域名记录，证书最终会被配置完成。 配置完成后，您可以使用域名通过https访问Web UI。

11.2配置MQTT负载均衡器

配置MQTT负载均衡器以便使用MQTT协议连接设备。

使用以下命令创建TCP负载均衡器：

1
kubectl apply -f receipts/mqtt-load-balancer.yml

负载均衡器将转发端口1883和8883的所有TCP流量。

MQTT over SSL按照本指南创建带 SSL证书的 .pem文件。将文件保存为工作目录中的 server.pem。

您需要创建带有PEM文件的config-map，可以通过调用以下命令完成：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
kubectl create configmap tbmq-mqtts-config \
 --from-file=server.pem=YOUR_PEM_FILENAME \
 --from-file=mqttserver_key.pem=YOUR_PEM_KEY_FILENAME \
 -o yaml --dry-run=client | kubectl apply -f-```
{: .copy-code}

* 其中 **YOUR_PEM_FILENAME** 是您的**服务器证书文件**名称。
* 其中 **YOUR_PEM_KEY_FILENAME** 是您的**服务器证书私钥文件**名称。

然后，取消注释 'tb-broker.yml' 文件中标记为"Uncomment the following lines to enable two-way MQTTS"的所有部分。

执行命令应用更改：

```bash
kubectl apply -f tb-broker.yml

步骤 12. 验证配置

现在您可以在浏览器中使用负载均衡器的 DNS名称打开TBMQ Web界面。

您可以使用以下命令获取负载均衡器的 DNS名称：

1
kubectl get ingress

您应该看到类似画面：

1
2
NAME                          CLASS    HOSTS   ADDRESS         PORTS   AGE
tb-broker-http-loadbalancer   <none>   *       34.111.24.134   80      3d1h

使用 tb-broker-http-loadbalancer 的 ADDRESS 字段连接到集群。

您将看到TBMQ登录页面。请使用以下 System Administrator（系统管理员）默认凭据：

用户名：

1
sysadmin@thingsboard.org

密码：

1
sysadmin

首次登录时，系统将要求您将默认密码修改为自定义密码，然后使用新凭据重新登录。

验证 MQTT访问

要通过 MQTT连接到集群，您需要获取相应的服务IP。您可以使用以下命令执行此操作：

1
kubectl get services

您应该看到类似画面：

1
2
NAME                          TYPE           CLUSTER-IP       EXTERNAL-IP              PORT(S)                         AGE
tb-broker-mqtt-loadbalancer   LoadBalancer   10.100.119.170   *******                  1883:30308/TCP,8883:31609/TCP6m58s

使用负载均衡器的 EXTERNAL-IP 字段通过 MQTT协议连接到集群。

故障排查

如有任何问题，您可以检查服务日志以查找错误。例如，要查看 TBMQ日志，执行以下命令：

1
kubectl logs -f tb-broker-0

使用以下命令查看所有 statefulset 的状态。

1
kubectl get statefulsets

有关更多详细信息，请参阅 kubectl 速查表命令参考。

升级

查看 release notes 和 升级说明 了解最新变更详情。

若您当前版本无 Upgrade to x.x.x 说明，可直接按升级说明执行。

若文档未涵盖您的升级场景，请联系我们以获取进一步指导。

备份和恢复（可选）

强烈建议备份 PostgreSQL数据库，但在进行升级之前这是可选的。 有关进一步指导，请遵循以下说明。

升级到 2.2.0

在此版本中，MQTT认证机制已从YAML/env 配置迁移到数据库。 升级期间，TBMQ需要了解部署中启用了哪些认证提供程序。 此信息通过传递给 upgrade pod 的环境变量提供。

升级脚本需要一个名为 database-setup.yml 的文件，该文件明确定义这些变量。 您的 tb-broker.yml 文件中的环境变量在升级期间不会应用——仅使用 database-setup.yml 中的值。

提示 如果仅使用 Basic认证，请设置 SECURITY_MQTT_SSL_ENABLED=false。 如果仅使用X.509 认证，请设置 SECURITY_MQTT_BASIC_ENABLED=false 和 SECURITY_MQTT_SSL_ENABLED=true。

支持的变量

• SECURITY_MQTT_BASIC_ENABLED (true|false)
• SECURITY_MQTT_SSL_ENABLED (true|false)
• SECURITY_MQTT_SSL_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT (true|false) — 通常为 false。

准备好文件并验证值后，继续升级过程。

升级到 2.1.0

TBMQ v2.1.0 引入多项改进，包括新的 Integration Executor 微服务及第三方服务版本升级。

添加 Integration Executor 微服务

本版本通过新的 Integration Executor 微服务支持外部集成。

要获取包括 Integration Executor 在内的最新配置文件，请从release分支拉取更新。 按照 运行升级说明 中的步骤操作，直至执行升级脚本前（暂不执行 .sh 命令）。

更新第三方服务

v2.1.0 中，TBMQ 更新了关键第三方依赖版本，包括 Redis、PostgreSQL 和 Kafka。 可通过以下 链接 查看变更详情。

建议 将环境中的第三方版本与上述更新版本对齐，以确保与本版本完全兼容。 也可选择不升级，但兼容性仅在推荐版本下得到保证。

我们不为第三方服务提供逐步升级说明。 此类操作请参阅各平台的官方文档，或在使用托管服务时查阅服务提供商的资源。 注意： 仅更改镜像标签不足以完成升级，且可能并非正确或安全的升级方式。

若选择跳过第三方服务版本更新，请仔细检查前一步合并过程是否修改了其版本。 如有必要，请撤销这些更改。

按需处理第三方服务版本后，可继续 升级流程 的剩余步骤。

升级到 2.0.0

对于TBMQ v2.0.0 升级，如果您尚未安装 Redis，请按照步骤 7 完成安装。 然后才能继续升级。

执行升级

如果您想升级，请从最新 release 分支拉取最新更改：

1
git pull origin release-2.2.0

如需升级到特定版本（如 TBMQ v2.0.0），将上述命令中的 release 分支替换为目标分支名，例如 release-2.0.0。

注意：确保您的自定义更改（如有）在合并过程中不会丢失。

若合并过程中出现与您修改无关的冲突， 建议接受远程分支的所有新变更。

可通过执行以下命令撤销合并操作：

1
git merge --abort

然后通过接受 theirs 变更重新执行合并：

1
git pull origin release-2.2.0 -X theirs

默认合并策略的常用选项：

• -X ours - 此选项强制以我方版本自动解决冲突块。
• -X theirs - 与 ours 相反。更多详情请参阅 此处。

之后，执行以下命令：

1
./k8s-upgrade-tbmq.sh

1
./k8s-upgrade-tbmq.sh --fromVersion=FROM_VERSION

说明： 升级数据库时，可选择使用以下命令停止 TBMQ pods：

1
./k8s-delete-tbmq.sh

这将导致服务中断，但可确保更新后 DB 状态一致。 多数更新不需要停止 TBMQ。

完成后，再次执行资源部署。这将触发 TBMQ 使用最新版本进行 rollout restart。

1
./k8s-deploy-tbmq.sh

删除集群

执行以下命令删除 TBMQ节点：

1
./k8s-delete-tbmq.sh

执行以下命令删除所有 TBMQ节点和 configmap、负载均衡器等：

1
./k8s-delete-all.sh

执行以下命令删除 GKE集群：

1
gcloud container clusters delete $TB_CLUSTER_NAME --region=$GCP_REGION

后续步骤

• 快速入门指南 - 本指南提供 TBMQ 的快速概览。

• 安全指南 - 学习如何为 MQTT 客户端启用认证与授权。

• 配置指南 - 了解 TBMQ 配置文件和参数。

• MQTT 客户端类型指南 - 了解 TBMQ 客户端类型。

• 与 ThingsBoard 集成 - 了解如何将 TBMQ 与 ThingsBoard 集成。