使用 Docker Compose 部署 TBMQ PE 集群

• 前置要求-Install Docker
• 拉取TBMQ PE 镜像
• 克隆TBMQ PE Docker Compose仓库
• Get the license key
• Configure the license key
• 安装
• 运行
• 日志、停止和启动命令
• Upgrading
  • Backup and restore (Optional)
  • Upgrade from TBMQ CE to TBMQ PE (v2.2.0)
• 为HTTPS生成证书
• 启用MQTTS（MQTT over SSL/TLS）
  • 双向MQTTS此配置下，TBMQ自身完成TLS终结及（可选）客户端证书认证。
  • 单向MQTTS此配置下，TLS在负载均衡器（HAProxy）处终结。
• 下一步

本指南将帮助你在Docker Compose集群模式下部署TBMQ PE。

前置要求-Install Docker

不要忘记将 Linux 用户加入 docker 用户组。参见 以非 root 用户管理 Docker。

拉取TBMQ PE 镜像

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

1
2
docker pull thingsboard/tbmq-pe-node:2.2.0PE
docker pull thingsboard/tbmq-pe-integration-executor:2.2.0PE

克隆TBMQ PE Docker Compose仓库

1
2
git clone -b release-2.2.0 https://github.com/thingsboard/tbmq-pe-docker-compose.git
cd tbmq-pe-docker-compose/cluster

Get the license key

Before proceeding, make sure you’ve selected your subscription plan or chosen to purchase a perpetual license. If you haven’t done this yet, please visit the Pricing page to compare available options and obtain your license key.

Note: Throughout this guide, we’ll refer to your license key as YOUR_LICENSE_KEY_HERE.

Configure the license key

1
nano tbmq.env

并将license secret参数填入，替换 “YOUR_LICENSE_KEY_HERE”：

1
2
# License info
TBMQ_LICENSE_SECRET=YOUR_LICENSE_KEY_HERE

安装

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

1
./scripts/docker-create-volumes.sh

执行以下命令进行安装：

1
./scripts/docker-install-tbmq.sh

运行

执行以下命令启动服务：

1
./scripts/docker-start-services.sh

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

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

用户名：

1
sysadmin@thingsboard.org

密码：

1
sysadmin

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

日志、停止和启动命令

遇到问题时，可查看服务日志排查错误。 例如，查看TBMQ日志可执行：

1
docker compose logs -f tbmq1

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

1
docker compose ps

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

1
docker compose logs -f

详见 docker compose logs 命令参考。

执行以下命令停止服务：

1
./scripts/docker-stop-services.sh

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

1
./scripts/docker-remove-services.sh

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

1
./scripts/docker-remove-volumes.sh

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

1
./scripts/docker-refresh-config.sh

To reload HAProxy’s configuration without restarting the Docker container, you can send the HUP signal to this process (PID 1):

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

Upgrading

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

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

Backup and restore (Optional)

While backing up your PostgreSQL database is highly recommended, it is optional before proceeding with the upgrade. For further guidance, follow the next instructions.

Upgrade from TBMQ CE to TBMQ PE (v2.2.0)

To upgrade your existing TBMQ Community Edition (CE) to TBMQ Professional Edition (PE), ensure you are running the latest TBMQ CE 2.2.0 version before starting the process. Merge your current configuration with the latest TBMQ PE Docker Compose scripts. Do not forget to configure the license key.

Run the following commands, including the upgrade script to migrate PostgreSQL database data from CE to PE:

1
2
3
./scripts/docker-stop-services.sh
./scripts/docker-upgrade-tbmq.sh --fromVersion=ce
./scripts/docker-start-services.sh

为HTTPS生成证书

使用HAproxy将流量代理到容器及Web UI。默认使用80和443端口。 使用有效证书启用HTTPS时，执行以下命令：

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

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

启用MQTTS（MQTT over SSL/TLS）

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行：

1
volumes:-PATH_TO_CERTS:/config/certificates

将 PATH_TO_CERTS 替换为存放证书的目录路径，确保TBMQ可访问。

配置环境变量

编辑 tbmq.env，取消注释并配置以下行以启用SSL：

1
2
3
4
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服务以应用更改：

1
./scripts/docker-start-services.sh

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

单向MQTTS此配置下，TLS在负载均衡器（HAProxy）处终结。

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

将HAProxy指向证书包（PEM完整链 + 私钥）。若复用HTTPS证书，引用同一证书包。 定位并更新 haproxy.cfg 文件：

1
2
3
4
5
6
7
8
9
10
 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 集成。