本指南将帮助您在Windows上使用Docker安装并启动独立版TBMQ PE。 如需集群安装说明，请访问集群设置页面。
前置条件
在单机上运行TBMQ PE 至少需要2GB内存。
获取许可证密钥
在继续之前，请确保已选择订阅计划或购买永久许可证。 若尚未完成，请访问 定价页面 比较可选方案 并获取许可证密钥。
注意：本指南中，我们将许可证密钥称为 YOUR_LICENSE_KEY_HERE.
安装
执行以下命令下载安装并启动TBMQ PE 的脚本：
注意： 请确保下载的 PowerShell 脚本可在您的系统上运行。
- 打开 PowerShell（以管理员身份运行）。
- （可选）查看当前执行策略。
它决定了系统上运行脚本的安全级别。例如，若返回
Restricted，表示 PowerShell 不执行任何脚本。
1
Get-ExecutionPolicy
- （可选）如需，更改当前执行策略。
设置为允许运行 PowerShell 脚本且符合您安全要求的策略。
例如，
Unrestricted为限制最少，允许执行所有脚本。
1
Set-ExecutionPolicy Unrestricted
- 安装 TBMQ
1
2
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/thingsboard/tbmq-pe-docker-compose/release-2.2.0/basic/windows/tbmq-install-and-run.ps1" `
-OutFile ".\tbmq-install-and-run.ps1"; .\tbmq-install-and-run.ps1
脚本会下载 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，故障时自动重启。
Update your docker-compose.yml file with the license secret you obtained earlier. Open the file, find the TBMQ_LICENSE_SECRET environment variable, and replace YOUR_LICENSE_KEY_HERE with your actual license secret. After updating the file, restart TBMQ by running the following command.
1
.\tbmq-install-and-run.ps1
注意：若TBMQ安装在ThingsBoard已运行的同一主机上，可能出现以下错误：
1
Error response from daemon: ... Bind for 0.0.0.0:1883 failed: port is already allocated
修复方法：为TBMQ容器暴露另一个主机端口，例如将已下载的docker-compose.yml中的 1883:1883 改为 1889:1883，然后重新运行脚本。
1
.\tbmq-install-and-run.ps1
安装完成后，可在浏览器中访问 http://{your-host-ip}:8083（例如 http://localhost:8083）打开TBMQ UI。
您将看到TBMQ登录页面。请使用以下 System Administrator（系统管理员）默认凭据：
用户名：
1
sysadmin@thingsboard.org
密码：
1
sysadmin
首次登录时，系统将要求您将默认密码修改为自定义密码，然后使用新凭据重新登录。
日志、停止和启动命令
若遇问题，可查看服务日志排查错误。 例如，查看TBMQ日志请执行以下命令：
1
docker compose logs -f tbmq
停止容器：
1
docker compose stop
启动容器：
1
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 (Windows PowerShell)
From the directory containing docker-compose.yml, run:
1
2
3
@'
JAVA_TOOL_OPTIONS=-Dinstall.upgrade.from_version=ce
'@ | Set-Content -Path .tbmq-upgrade.env -Encoding UTF8
Important Notes
- Required: The upgrade script will fail if
.tbmq-upgrade.envis missing. - After creating the file, proceed with the upgrade process.
执行升级
要更新到最新版本，请执行以下命令：
1
2
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/thingsboard/tbmq-pe-docker-compose/release-2.2.0/basic/windows/tbmq-upgrade.ps1" `
-OutFile ".\tbmq-upgrade.ps1"; .\tbmq-upgrade.ps1
注意：将脚本中的 valkey_url、db_url、db_username 和 db_password 变量替换为DB初始化时使用的对应值。
如需升级到特定版本（如 TBMQ v2.0.0），将上述命令中的 release 分支替换为目标分支名，例如 release-2.0.0。
启用 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 中挂载包含证书的目录：
1
2
volumes:
- PATH_TO_CERTS:/config/certificates
将 PATH_TO_CERTS 替换为证书文件路径。确保TBMQ对这些文件具有读权限。
配置环境变量
在 docker-compose.yml 中添加以下变量以启用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留空。
暴露 MQTTS 端口
在 docker-compose.yml 中：
1
2
ports:
- "8883:8883"
重启 TBMQ
通过重启TBMQ使更改生效：
1
./tbmq-install-and-run.sh
重启后，MQTT客户端可通过 8883 端口使用 TLS/SSL 安全连接。
下一步
-
快速入门指南 - 本指南提供 TBMQ 的快速概览。
-
安全指南 - 学习如何为 MQTT 客户端启用认证与授权。
-
配置指南 - 了解 TBMQ 配置文件和参数。
-
MQTT 客户端类型指南 - 了解 TBMQ 客户端类型。
-
与 ThingsBoard 集成 - 了解如何将 TBMQ 与 ThingsBoard 集成。