TBMQ集群部署完全指南：从Docker Compose到K8s云原生方案

【免费下载链接】tbmqThe ultimate distributed MQTT broker. Handles 100M+ connections and 10M msg/sec with ease. Built on Kafka to provide industrial-grade persistence and eliminate data loss.项目地址: https://gitcode.com/gh_mirrors/tb/tbmq

TBMQ作为终极分布式MQTT broker，能够轻松处理1亿+连接和1000万条/秒消息，基于Kafka构建的工业级持久化能力确保数据零丢失。本文将带您从Docker Compose快速部署到K8s云原生方案，掌握TBMQ集群的完整部署流程。

📋 准备工作：环境与资源需求

在开始部署前，请确保您的环境满足以下要求：

• Docker Engine 20.10+ 或 Kubernetes 1.24+ 集群
• 每节点至少4核CPU、8GB内存
• 持久化存储支持（Docker使用卷挂载，K8s使用PVC）
• 网络支持TCP 1883(MQTT)、8883(MQTTs)、8080(HTTP)端口

项目提供的部署资源文件位于：

• Docker部署：docker/
• K8s部署：k8s/

🔍 核心配置文件位置

• Docker环境变量：docker/tbmq.env
• K8s配置模板：k8s/minikube/tbmq.yml
• 系统配置文件：application/src/main/conf/thingsboard-mqtt-broker.conf

🐳 方案一：Docker Compose快速部署

1️⃣ 一键安装脚本

项目提供了简化部署的Shell脚本，执行以下命令即可启动基础集群：

git clone https://gitcode.com/gh_mirrors/tb/tbmq cd tbmq/docker/scripts chmod +x docker-install-tbmq.sh ./docker-install-tbmq.sh

2️⃣ 手动配置与启动

如果需要自定义配置，可修改以下文件后手动启动：

1. 配置环境变量（关键设置示例）：

   # [docker/tbmq.env](https://link.gitcode.com/i/e8eb5efa287606ef7e7603a0c8060f0a) TBMQ_BROKER_CLUSTER_ENABLED=true TBMQ_KAFKA_SERVERS=kafka:9092 TBMQ_CACHE_TYPE=redis

2. 启动Docker Compose集群：

   cd tbmq/docker docker-compose up -d

3. 验证集群状态：

   docker-compose ps # 查看日志确认启动成功 docker-compose logs -f tbmq

TBMQ管理控制台首页展示集群状态、消息流量和Kafka主题信息

☸️ 方案二：Kubernetes云原生部署

1️⃣ 基础集群部署（Minikube示例）

适用于开发测试环境的快速部署：

cd tbmq/k8s/minikube chmod +x k8s-install-tbmq.sh ./k8s-install-tbmq.sh

2️⃣ 生产级部署（多环境支持）

项目提供AWS、Azure、GCP三大云平台的部署方案：

• AWS部署：k8s/aws/k8s-deploy-tbmq.sh
• Azure部署：k8s/azure/k8s-deploy-tbmq.sh
• GCP部署：k8s/gcp/k8s-deploy-tbmq.sh

3️⃣ 核心部署清单说明

K8s部署的核心资源定义文件：

1. 命名空间与配置：

   # [k8s/minikube/tbmq-namespace.yml](https://link.gitcode.com/i/5ac5a8668384b3baea25e4aeb4f7f283) apiVersion: v1 kind: Namespace metadata: name: tbmq

2. StatefulSet部署：

   # [k8s/minikube/tbmq.yml](https://link.gitcode.com/i/c585276022efb1fd074185154a1cc388) apiVersion: apps/v1 kind: StatefulSet metadata: name: tbmq namespace: tbmq spec: serviceName: tbmq replicas: 3 # 建议生产环境至少3节点

3. 负载均衡配置：

   • MQTT负载均衡：k8s/aws/receipts/mqtt-load-balancer.yml
   • HTTPS负载均衡：k8s/azure/receipts/https-load-balancer.yml

TBMQ会话管理界面展示多节点连接状态与客户端分布

🔧 集群配置最佳实践

1️⃣ 性能优化参数

在application/src/main/conf/thingsboard-mqtt-broker.conf中调整：

# 网络优化 netty.maxThreads=32 netty.soBacklog=1024 # Kafka持久化配置 queue.kafka.partitions=12 queue.kafka.replicationFactor=3

2️⃣ 高可用设置

• Kafka集群：建议至少3节点，配置在k8s/minikube/kafka.yml
• 缓存集群：使用Valkey集群docker/cache-valkey-cluster.env
• 健康检查：配置存活探针和就绪探针确保自动恢复

3️⃣ 监控与维护

• 集成Prometheus监控：integration/executor/src/main/conf/tbmq-integration-executor.conf
• 日志配置：docker/tbmq/conf/logback.xml
• 备份脚本：docker/backup-restore/

🚀 集群升级与扩展

1️⃣ 平滑升级流程

Docker环境：

cd tbmq/docker/scripts ./docker-upgrade-tbmq.sh

K8s环境：

cd tbmq/k8s/aws ./k8s-upgrade-tbmq.sh

2️⃣ 横向扩展方法

• Docker Compose：修改docker-compose.yml的replicas数量
• K8s：执行kubectl scale statefulset tbmq -n tbmq --replicas=5

❓ 常见问题排查

1. Kafka连接失败：检查docker/kafka.env中的KAFKA_ADVERTISED_LISTENERS配置
2. 节点同步问题：查看日志确认TBMQ_BROKER_CLUSTER_NODES配置正确
3. 性能瓶颈：通过管理界面监控"Outgoing messages"和" Sessions"指标调整资源

📚 相关资源

• 配置文件模板：msa/tbmq/configs/
• 集成示例：ui-ngx/src/assets/getting-started/
• 测试脚本：application/src/test/

通过本文指南，您已掌握TBMQ从Docker Compose到K8s的完整部署流程。无论是快速启动测试环境还是构建生产级高可用集群，TBMQ的弹性架构都能满足您的需求。根据实际业务规模调整节点数量和资源配置，即可轻松应对百万级设备连接与消息处理挑战。

【免费下载链接】tbmqThe ultimate distributed MQTT broker. Handles 100M+ connections and 10M msg/sec with ease. Built on Kafka to provide industrial-grade persistence and eliminate data loss.项目地址: https://gitcode.com/gh_mirrors/tb/tbmq