产品定价 立即试用
MQTT Broker
社区版 专业版 云平台 边缘 PE边缘 IoT网关 许可证服务器 Trendz Analytics 移动应用 PE移动应用 MQTT Broker PE MQTT Broker
在 Minikube 上使用 Helm 部署 TBMQ 集群
入门 文档 安装 架构 API 常见问题
目录

在 Minikube 上使用 Helm 部署 TBMQ 集群

本指南将帮助你在自托管Kubernetes环境下使用官方Helm chart 部署TBMQ集群，以Minikube作为参考环境。 若在无云负载均衡器集成的自管集群中部署TBMQ，Minikube便于端到端测试。

前置要求

要在 Minikube 中使用 Helm 部署 TBMQ 集群，需在本地机器上安装以下工具：

配置Kubernetes环境

启动 Minikube

1

minikube start

安装 NGINX Ingress Controller

在 Minikube 等通用 Kubernetes 环境中暴露 HTTP(S) 服务，需安装 NGINX Ingress Controller。 本示例使用 Helm 安装并配置为 LoadBalancer 服务类型：

1
2
3
4
5
6

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

helm install nginx-ingress ingress-nginx/ingress-nginx \
  --set controller.admissionWebhooks.enabled=false \
  --set controller.service.type=LoadBalancer

这将在 default 命名空间部署 NGINX ingress controller，并配置为通过 LoadBalancer 服务对外暴露流量。 继续前，请确保 ingress controller pod 已运行且就绪：

1

kubectl get pods -n default

输出应类似：

1
2

NAME                                                     READY   STATUS    RESTARTS   AGE
nginx-ingress-ingress-nginx-controller-xxxxx             1/1     Running   0          1m

启动 Minikube Tunnel

由于 Minikube 本身不支持外部 LoadBalancer 服务，需创建 tunnel 以在集群外暴露这些服务。 这是访问 NGINX Ingress Controller 和 TBMQ 的 MQTT LoadBalancer 等服务的必要条件。

在单独终端中运行以下命令：

1

minikube tunnel

此命令需要管理员权限，可能会提示输入密码。 它将在您的机器上创建网络路由并为 NGINX LoadBalancer 服务分配外部 IP。

启动 tunnel 后，验证 NGINX Ingress Controller 是否已获得 EXTERNAL-IP：

1

kubectl get svc -n default

示例输出：

1
2

NAME                                     TYPE           CLUSTER-IP       EXTERNAL-IP      PORT(S)                      AGE
nginx-ingress-ingress-nginx-controller   LoadBalancer   10.101.102.99    192.168.49.2     80:32023/TCP,443:32144/TCP   2m

添加TBMQ集群Helm仓库

安装 chart 前，请将 TBMQ Helm 仓库添加到本地 Helm 客户端：

1
2

helm repo add tbmq-helm-chart https://helm.thingsboard.io/tbmq
helm repo update

修改默认chart值

要自定义 TBMQ 部署，请先从 chart 下载默认 values.yaml 文件：

1

helm show values tbmq-helm-chart/tbmq-cluster > values.yaml
文档信息图标

请勿直接在 values.yaml 中修改 installation.installDbSchema。 此参数仅在首次安装时用于初始化 TBMQ 数据库 schema。 我们将在 helm install 命令中通过 --set 选项显式传入该参数。

External PostgreSQL

默认情况下，chart 会安装 Bitnami PostgreSQL 作为子 chart：

1
2
3
4
5

# 此部分将引入 bitnami/postgresql (https://artifacthub.io/packages/helm/bitnami/postgresql)。
# 若要添加额外配置参数，可将其放在 `postgresql` 键下，将传递给 bitnami/postgresql chart
postgresql:
  # @param enabled 若 enabled 为 true，将忽略 externalPostgresql 配置
  enabled: true

该 chart 将配置单节点实例，支持可配置的存储、备份和监控选项。 若已有 PostgreSQL 实例，可将 TBMQ 配置为外部连接。 为此，请将 postgresql.enabled 设为 false 以禁用内置 PostgreSQL，并在 externalPostgresql 部分指定连接详情。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# 若在外部部署 PostgreSQL，请在此部分配置
externalPostgresql:
  # @param host - 外部 PostgreSQL 服务器 host
  host: ""
  # @param port - 外部 PostgreSQL 服务器端口
  ##
  port: 5432
  # @param username - PostgreSQL 用户
  ##
  username: "postgres"
  # @param password - PostgreSQL 用户密码
  ##
  password: "postgres"
  # @param database - TBMQ 使用的 PostgreSQL 数据库名
  ##
  database: "thingsboard_mqtt_broker"

负载均衡器配置

默认情况下，在 Kubernetes 上安装 TBMQ 时，Helm chart 会为标准 NGINX Ingress Controller 部署 HTTP 和 MQTT 流量配置。

1
2

loadbalancer:
  type: "nginx"

此配置适用于 Minikube 及其他通用 Kubernetes 环境。

HTTPS 访问

目前 NGINX Ingress Controller 在负载均衡器层面的 HTTPS 终止尚未实现。此功能可能在后续版本中添加。

MQTTS 访问

NGINX Ingress Controller 不支持基于 TCP 的协议（如 MQTT）的 TLS 终止。 若要保护 MQTT 通信，必须在应用层（TBMQ 侧）直接配置双向 TLS（Mutual TLS 或 mTLS）。 有关配置双向 TLS 的详情，请参阅 TBMQ Helm chart 文档 此处。

创建命名空间

建议为 TBMQ 集群部署创建专用命名空间：

1

kubectl create namespace tbmq

1

kubectl config set-context --current --namespace=tbmq

这将把 tbmq 设为当前上下文的默认命名空间，因此您无需在每个命令中传递 –namespace 参数。

安装TBMQ Helm chart

现在可以使用 Helm chart 安装 TBMQ。 请确保当前目录与自定义的 values.yaml 文件所在目录一致。

1
2
3

helm install my-tbmq-cluster tbmq-helm-chart/tbmq-cluster \
  -f values.yaml \
  --set installation.installDbSchema=true
文档信息图标

my-tbmq-cluster 为 Helm release 名称。可改为任意名称，后续 Helm 命令中将使用此名称引用该部署。

部署完成后，输出应类似以下内容：

1
2
3
4
5
6
7
8
9
10

NAME: my-tbmq-cluster
LAST DEPLOYED: Wed Mar 26 17:42:49 2025
NAMESPACE: tbmq
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
TBMQ 集群 my-tbmq-cluster 将在数分钟内部署完成。
信息：
命名空间：tbmq

验证HTTP访问

1

kubectl get ingress my-tbmq-cluster-http-lb

输出应类似：

1
2

NAME                      CLASS   HOSTS   ADDRESS         PORTS   AGE
my-tbmq-cluster-http-lb   nginx   *       10.111.137.85   80      47m

使用 my-tbmq-cluster-http-lb 的 ADDRESS 字段连接集群。

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

用户名：

1

sysadmin@thingsboard.org

密码：

1

sysadmin

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

验证MQTT访问

若 minikube tunnel 已运行，您会看到列表中多出一个新服务，用于对外暴露 MQTT 流量：

1
2
3
4
5
6

Status:	
	machine: minikube
	pid: 35528
	route: 10.96.0.0/12 -> 192.168.49.2
	minikube: Running
	services: [nginx-ingress-ingress-nginx-controller, my-tbmq-cluster-mqtt-lb]

服务 my-tbmq-cluster-mqtt-lb 为用于 MQTT 通信的 LoadBalancer。可使用以下命令获取其 EXTERNAL-IP：

1

kubectl get svc my-tbmq-cluster-mqtt-lb

输出应类似：

1
2

NAME                      TYPE           CLUSTER-IP     EXTERNAL-IP    PORT(S)                                                       AGE
my-tbmq-cluster-mqtt-lb   LoadBalancer   10.101.27.40   *******        1883:31041/TCP,8084:30151/TCP,8883:30188/TCP,8085:32706/TCP   41m

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

故障排除

如遇问题，可查看服务日志中的错误。例如，要查看 TBMQ 日志，请执行以下命令：

1

kubectl logs -f my-tbmq-cluster-tbmq-node-0

使用以下命令查看所有 statefulsets 的状态：

1

kubectl get statefulsets

更多详情请参阅 kubectl Cheat Sheet 命令参考。

升级

Helm 支持自 TBMQ 2.1.0 版本起引入。自 TBMQ 2.2.0 起， Helm chart 已更新至 1.1.0 版本，并引入了升级选项。 有关如何升级 TBMQ Helm 部署的详细说明，请参阅 Artifact Hub 上 TBMQ Helm Chart 文档的 Upgrading 部分。

卸载TBMQ Helm chart

要卸载 TBMQ Helm chart，请运行以下命令：

1

helm delete my-tbmq-cluster

此命令将从当前 Kubernetes 上下文中设置的命名空间内移除与该 release 关联的所有 TBMQ 组件。

helm delete 命令仅移除 TBMQ 集群的逻辑资源。 要完全清理所有持久化数据，卸载后可能还需手动删除关联的 Persistent Volume Claims (PVCs)：

1

kubectl delete pvc -l app.kubernetes.io/instance=my-tbmq-cluster

删除Kubernetes集群

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

1

minikube delete

下一步