使用 Docker 安装 TBMQ PE（Linux 或 Mac OS）

前置条件
Get the license key
安装
日志、停止和启动命令
升级
启用 MQTTS（基于 SSL/TLS 的 MQTT）
下一步

本指南将帮助您在Linux或macOS上使用Docker安装并启动独立版TBMQ PE。如需集群安装说明，请访问集群设置页面。

前置条件

在单机上运行TBMQ PE 至少需要2GB内存。

Install Docker

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.

安装

执行以下命令下载安装并启动TBMQ PE 的脚本：

wget https://raw.githubusercontent.com/thingsboard/tbmq-pe-docker-compose/release-2.2.0/basic/tbmq-install-and-run.sh &&
sudo chmod +x tbmq-install-and-run.sh && ./tbmq-install-and-run.sh

脚本会下载 docker-compose.yml 文件、创建必要的docker卷、安装TBMQ的数据库并启动TBMQ。 docker-compose文件中TBMQ的关键配置点：

-TBMQ_LICENSE_SECRET: YOUR_LICENSE_KEY_HERE-此前获取的许可证密钥占位符； -8083:8083-将本地端口8083映射到内部HTTP端口8083；-1883:1883-将本地端口1883映射到内部MQTT端口1883；-8084:8084-将本地端口8084映射到内部MQTT over WebSockets端口8084； -tbmq-valkey-data:/data-将 tbmq-valkey-data 卷映射到TBMQ Valkey数据库数据目录； -tbmq-postgres-data:/var/lib/postgresql/data-将 tbmq-postgres-data 卷映射到TBMQ Postgres数据库数据目录； -tbmq-kafka-data:/var/lib/kafka/data-将 tbmq-kafka-data 卷映射到Kafka数据目录； -tbmq-logs:/var/log/thingsboard-mqtt-broker-将 tbmq-logs 卷映射到TBMQ日志目录；-tbmq-data:/data-将 tbmq-data 卷映射到TBMQ数据目录（安装DB后包含 .firstlaunch 文件）；-tbmq-本机友好名称；-restart: always-系统重启时自动启动TBMQ，故障时自动重启。

./tbmq-install-and-run.sh

注意：若TBMQ安装在ThingsBoard已运行的同一主机上，可能出现以下错误：

Error response from daemon: ... Bind for 0.0.0.0:1883 failed: port is already allocated

修复方法：为TBMQ容器暴露另一个主机端口，例如将已下载的docker-compose.yml中的 1883:1883 改为 1889:1883，然后重新运行脚本。

./tbmq-install-and-run.sh

安装完成后，可在浏览器中访问 http://{your-host-ip}:8083（例如 http://localhost:8083）打开TBMQ UI。

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

用户名：

sysadmin@thingsboard.org

密码：

sysadmin

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

日志、停止和启动命令

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

docker compose logs -f tbmq

停止容器：

docker compose stop

启动容器：

docker compose start

升级

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

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

备份与恢复（可选）

强烈建议备份PostgreSQL数据库，但在升级前为可选操作。 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. Do not forget to configure the license key.

The upgrade procedure requires a file named .tbmq-upgrade.env located in the same directory as your docker-compose.yml. This file is only used during the upgrade.

Create the .tbmq-upgrade.env file

From the directory containing docker-compose.yml, run:

cat > .tbmq-upgrade.env <<'EOF'
JAVA_TOOL_OPTIONS=-Dinstall.upgrade.from_version=ce
EOF

Important Notes

Required: The upgrade script will fail if .tbmq-upgrade.env is missing.
After creating the file, proceed with the upgrade process.

执行升级

要更新到最新版本，请执行以下命令：

wget -O tbmq-upgrade.sh https://raw.githubusercontent.com/thingsboard/tbmq-pe-docker-compose/release-2.2.0/basic/tbmq-upgrade.sh &&
sudo chmod +x tbmq-upgrade.sh && ./tbmq-upgrade.sh

注意：将脚本中的 valkey_url、db_url、db_username 和 db_password 变量替换为DB初始化时使用的对应值。

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

要在TBMQ中启用 MQTT over SSL/TLS (MQTTS)，需提供有效的SSL证书并配置TBMQ使用这些证书。

支持的格式及配置选项详见 MQTT over SSL 指南。

准备 SSL 证书

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

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

测试时可使用自签名证书，但生产环境建议使用受信任证书颁发机构颁发的证书。

将证书挂载到容器

在 docker-compose.yml 中挂载包含证书的目录：

volumes:
  - PATH_TO_CERTS:/config/certificates

将 PATH_TO_CERTS 替换为证书文件路径。确保TBMQ对这些文件具有读权限。

配置环境变量

在 docker-compose.yml 中添加以下变量以启用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 留空。

暴露 MQTTS 端口

在 docker-compose.yml 中：

ports:
  - "8883:8883"

重启 TBMQ

通过重启TBMQ使更改生效：

./tbmq-install-and-run.sh

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

下一步

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