使用 Docker Compose 部署 TBMQ 集群

前置条件-安装Docker
步骤1. 拉取TBMQ镜像
步骤2. 克隆TBMQ仓库
步骤3. 安装
步骤4. 运行
步骤5. 日志、停止与启动命令
升级
为HTTPS生成证书
启用MQTTS（基于SSL/TLS的MQTT）
- 双向MQTTS在此配置下，由TBMQ自身处理TLS终止及（可选）客户端证书认证。
- 单向MQTTS在此方式下，TLS在负载均衡器（HAProxy）处终止。
后续步骤

本指南将帮助您使用Docker Compose以集群模式部署TBMQ。

前置条件-安装Docker

步骤1. 拉取TBMQ镜像

请确保已通过命令行登录 Docker Hub。

docker pull thingsboard/tbmq-node:2.2.0

步骤2. 克隆TBMQ仓库

git clone -b release-2.2.0 https://github.com/thingsboard/tbmq.git
cd tbmq/docker

步骤3. 安装

执行以下命令为所有服务创建所需卷并更新所创建卷中的haproxy配置：

./scripts/docker-create-volumes.sh

执行以下命令运行安装：

./scripts/docker-install-tbmq.sh

步骤4. 运行

执行以下命令启动服务：

./scripts/docker-start-services.sh

当所有服务成功启动后，您可以在浏览器中访问 http://{your-host-ip}（例如 http://localhost），并在 1883端口使用MQTT协议连接客户端。

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

用户名：

sysadmin@thingsboard.org

密码：

sysadmin

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

步骤5. 日志、停止与启动命令

若遇问题可查看服务日志。例如查看TBMQ日志可执行：

docker compose logs -f tbmq1

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

docker compose ps

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

docker compose logs -f

更多说明请参阅 docker compose logs 命令参考。

执行以下命令停止服务：

./scripts/docker-stop-services.sh

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

./scripts/docker-remove-services.sh

若要移除所有容器的Docker卷，请执行以下命令。 注意： 将删除所有数据，执行前请谨慎。

./scripts/docker-remove-volumes.sh

若需在运行时更新日志（启用DEBUG/TRACE日志）或修改TBMQ、Haproxy配置，请编辑 haproxy.cfg 或 logback.xml 等文件，然后执行以下命令使容器应用更改：

./scripts/docker-refresh-config.sh

若要在不重启Docker容器的情况下重载HAProxy配置，可向该进程（PID 1）发送HUP信号：

docker exec -it haproxy-certbot sh -c "kill -HUP 1"

升级

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

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

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

备份与恢复（可选）

强烈建议在升级前备份PostgreSQL数据库，但此为可选步骤。更多说明请参阅后续说明。

升级至2.2.0

在此版本中，MQTT认证机制已从YAML/环境变量配置迁移到数据库。升级时，TBMQ需要知道当前部署启用了哪些认证提供方。该信息通过传入 升级容器 的环境变量提供。

升级脚本要求存在名为 tb-mqtt-broker.env 的文件并在此文件中显式定义这些变量。升级过程中不会使用 docker-compose.yml 中的环境变量，仅使用 tb-mqtt-broker.env 中的值。

提示若仅使用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 微服务支持外部集成。

完整更新的 docker-compose.yml 请参阅官方示例。

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

成功拉取更新后，运行以下命令创建用于存储 Integration Executor 日志的 Docker volumes：

./scripts/docker-create-volumes.sh

执行命令后，输出应类似以下内容：

user@user:~/tbmq/docker$ ./scripts/docker-create-volumes.sh

tbmq-ie1-logs
tbmq-ie2-logs
tbmq-ie-config

更新第三方服务

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

服务	更新前版本	更新后版本
Redis	7.0	7.2.5
PostgreSQL	15.x	16.x
Kafka	3.5.1	3.7.0

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

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

执行升级

若要升级，请从最新发布分支拉取最近更改：

git pull origin release-2.2.0

注意： 请确保在合并过程中不丢失您的自定义修改。确保 .env文件中的 TBMQ_VERSION 已设置为目标版本（例如升级到最新版时设为 2.2.0）。

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

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

git merge --abort

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

git pull origin release-2.2.0 -X theirs

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

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

然后执行以下命令：

Since v2.1.0
Before v2.1.0

./scripts/docker-stop-services.sh
./scripts/docker-upgrade-tbmq.sh
./scripts/docker-start-services.sh

./scripts/docker-stop-services.sh
./scripts/docker-upgrade-tbmq.sh --fromVersion=FROM_VERSION
./scripts/docker-start-services.sh

其中 FROM_VERSION 表示升级的起始版本。参见升级说明了解有效的 fromVersion 取值。

为HTTPS生成证书

我们使用HAproxy将流量代理到容器，Web界面默认使用80和443端口。要使用有效证书启用HTTPS，请执行：

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

注意： 仅当通过URL中的域名访问Web界面时才会使用有效证书。

启用MQTTS（基于SSL/TLS的MQTT）

MQTTS 允许客户端通过加密的TLS/SSL通道连接TBMQ，确保MQTT消息在传输过程中的机密性与完整性。常见有两种部署方式：

双向MQTTS（双向TLS） – TBMQ自行终止TLS，客户端须提供有效证书进行认证。
单向MQTTS（在负载均衡器终止TLS） – 由HAProxy或其他负载均衡器终止TLS，并通过可信内网将明文MQTT流量转发给TBMQ。

两种方式均能加密保护外部连接，双向MQTTS 额外通过客户端证书校验提高安全性， 单向MQTTS 则简化Broker配置，并可在负载均衡器上复用现有HTTPS证书。

双向MQTTS在此配置下，由TBMQ自身处理TLS终止及（可选）客户端证书认证。

适用于希望由Broker完全控制SSL/TLS与双向认证、而不依赖负载均衡器提供安全性的场景。

要启用 MQTT over SSL（MQTTS），需提供有效SSL证书并配置TBMQ使用它们。

有关支持的证书格式与选项，请参阅 MQTT over SSL 文档。

提供SSL证书

获取有效SSL证书与私钥。例如：

mqttserver.pem – 公钥证书（可包含完整链）；
mqttserver_key.pem – 私钥。

测试环境支持自签名证书，生产环境建议使用受信任CA签发的证书。

将证书挂载到容器

打开 docker-compose.yml，取消注释挂载证书文件的volume行：

volumes:-PATH_TO_CERTS:/config/certificates

将 PATH_TO_CERTS 替换为包含证书文件的目录路径，并确保TBMQ能访问这些文件。

配置环境变量

编辑 tb-mqtt-broker.env，取消注释/配置以下行以启用SSL：

LISTENER_SSL_ENABLED=true
LISTENER_SSL_PEM_CERT=/config/certificates/mqttserver.pem
LISTENER_SSL_PEM_KEY=/config/certificates/mqttserver_key.pem
LISTENER_SSL_PEM_KEY_PASSWORD=server_key_password

请按需调整文件路径和密码。若私钥未设密码，可将 LISTENER_SSL_PEM_KEY_PASSWORD 留空。

重启服务

通过重启TBMQ服务使更改生效：

./scripts/docker-start-services.sh

启动后，MQTT客户端即可通过TLS/SSL安全连接 8883 端口。

单向MQTTS在此方式下，TLS在负载均衡器（HAProxy）处终止。

客户端通过MQTTS（8883端口）安全连接HAProxy，HAProxy通过内网将明文MQTT转发给TBMQ（1883端口）。可复用已用于HTTPS的证书。

在HAProxy中指定证书包路径（含完整链的PEM + 私钥）。若复用HTTPS证书，可引用同一证书包。找到并更新 haproxy.cfg 文件：

 listen mqtts-in
  bind *:${MQTTS_PORT} ssl crt /usr/local/etc/haproxy/certs.d/fullchain-and-key.pem
  mode tcp
  option clitcpka # For TCP keep-alive
  timeout client 3h
  timeout server 3h
  option tcplog
  balance leastconn
  server tbMqtt1 tbmq1:1883 check inter 5s resolvers docker_resolver resolve-prefer ipv4
  server tbMqtt2 tbmq2:1883 check inter 5s resolvers docker_resolver resolve-prefer ipv4

注意： 请将 fullchain-and-key.pem 替换为您的证书包实际文件名。

后续步骤

快速入门指南 - 本指南提供 TBMQ 的快速概览。
安全指南 - 学习如何为 MQTT 客户端启用认证与授权。
配置指南 - 了解 TBMQ 配置文件和参数。
MQTT 客户端类型指南 - 了解 TBMQ 客户端类型。
与 ThingsBoard 集成 - 了解如何将 TBMQ 与 ThingsBoard 集成。