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

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

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

前置条件

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

Install Docker

安装

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

wget https://raw.githubusercontent.com/thingsboard/tbmq/release-2.2.0/msa/tbmq/configs/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的关键配置点：

-8083:8083-将本地端口8083映射到内部HTTP端口8083；-1883:1883-将本地端口1883映射到内部MQTT端口1883；-8084:8084-将本地端口8084映射到内部MQTT over WebSockets端口8084； -tbmq-redis-data:/bitnami/redis/data-将 tbmq-redis-data 卷映射到TBMQ Redis数据库数据目录； -tbmq-postgres-data:/var/lib/postgresql/data-将 tbmq-postgres-data 卷映射到TBMQ Postgres数据库数据目录； -tbmq-kafka-data:/bitnami/kafka-将 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安装在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 和升级说明了解最新变更详情。

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

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

备份与恢复（可选）

强烈建议备份PostgreSQL数据库，但在升级前为可选操作。 For further guidance, follow the next instructions.

Upgrade to 2.2.0

In this release, the MQTT authentication mechanism was migrated from YAML/env configuration into the database. During upgrade, TBMQ needs to know which authentication providers are enabled in your deployment. This is done using environment variables passed to the upgrade container.

The upgrade script therefore requires a file named .tbmq-upgrade.env in the same directory as docker-compose.yml. This file is used only during upgrade to create the default auth providers. Make sure the values match what you already run in your tbmq service (docker-compose.yml → environment:).

Create the env file

From the directory containing docker-compose.yml:

cat > .tbmq-upgrade.env <<'EOF'
SECURITY_MQTT_BASIC_ENABLED=true
SECURITY_MQTT_SSL_ENABLED=true
SECURITY_MQTT_SSL_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT=false
EOF

Tips If you use only Basic authentication, set SECURITY_MQTT_SSL_ENABLED=false. If you use only X.509 authentication, set SECURITY_MQTT_BASIC_ENABLED=false and SECURITY_MQTT_SSL_ENABLED=true.

Notes

Required: If .tbmq-upgrade.env is missing, the upgrade script will fail.
Supported variables:
- SECURITY_MQTT_BASIC_ENABLED (true|false)
- SECURITY_MQTT_SSL_ENABLED (true|false)
- SECURITY_MQTT_SSL_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT (true|false) — usually false.

Once the file is created, continue with the upgrade process.

Upgrade to 2.1.0

TBMQ v2.1.0 引入多项改进，包括新的 Integration Executor 微服务及第三方服务版本升级。

添加 Integration Executor 微服务

本版本通过新的 Integration Executor 微服务支持外部集成。

在现有的 docker-compose.yml 中添加服务定义和 volume

  tbmq-integration-executor:
    restart: always
    image: "thingsboard/tbmq-integration-executor:2.1.0"
    depends_on:
      - kafka
      - tbmq
    logging:
      driver: "json-file"
      options:
        max-size: "200m"
        max-file: "5"
    environment:
      TB_SERVICE_ID: tbmq-ie
      TB_KAFKA_SERVERS: kafka:9092
      #JAVA_OPTS: "-Xmx2048M -Xms2048M -Xss384k -XX:+AlwaysPreTouch"
    volumes:
      - tbmq-ie-logs:/var/log/tbmq-integration-executor

volumes:
  tbmq-ie-logs:
    external: true

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

运行以下命令创建 Integration Executor 日志的 Docker volume：

docker volume create tbmq-ie-logs

更新配置后，使用以下命令启动服务：

docker compose up -d tbmq-integration-executor --no-deps

更新第三方服务

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

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

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

Upgrade to 2.0.0

For the TBMQ 2.0.0 release, the installation scripts have been updated to include Redis configuration.

Please update your docker-compose.yml file to incorporate the Redis settings. You can review the necessary changes by visiting the following link.

Here is the complete docker compose file with the Redis configuration prior to the upgrade

#
# Copyright © 2016-2024 The Thingsboard Authors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

services:
  postgres:
    restart: always
    image: "postgres:15"
    ports:-"5432"
    environment:
      POSTGRES_DB: thingsboard_mqtt_broker
      POSTGRES_PASSWORD: postgres
    volumes:-tbmq-postgres-data:/var/lib/postgresql/data
  kafka:
    restart: always
    image: "bitnamilegacy/kafka:3.5.1"
    ports:-"9092"
    environment:
      KAFKA_CFG_NODE_ID: 0
      KAFKA_CFG_PROCESS_ROLES: controller,broker
      KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: 0@kafka:9093
      KAFKA_CFG_LISTENERS: PLAINTEXT://:9092,CONTROLLER://:9093
      KAFKA_CFG_ADVERTISED_LISTENERS: PLAINTEXT://:9092
      KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT
      KAFKA_CFG_CONTROLLER_LISTENER_NAMES: CONTROLLER
      KAFKA_CFG_INTER_BROKER_LISTENER_NAME: PLAINTEXT
    volumes:-tbmq-kafka-data:/bitnami/kafka
  redis:
    restart: always
    image: "bitnamilegacy/redis:7.0"
    environment:
      # ALLOW_EMPTY_PASSWORD is recommended only for development.
      ALLOW_EMPTY_PASSWORD: "yes"
    ports:-"6379"
    volumes:-tbmq-redis-data:/bitnami/redis/data
  tbmq:
    restart: always
    image: "thingsboard/tbmq:1.4.0"
    depends_on:-postgres-kafka-redis
    ports:-"8083:8083"-"1883:1883"-"8084:8084"
    environment:
      TB_SERVICE_ID: tbmq
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard_mqtt_broker
      SPRING_DATASOURCE_USERNAME: postgres
      SPRING_DATASOURCE_PASSWORD: postgres
      TB_KAFKA_SERVERS: kafka:9092
      REDIS_HOST: redis
      SECURITY_MQTT_BASIC_ENABLED: "true"
      #JAVA_OPTS: "-Xmx2048M -Xms2048M -Xss384k -XX:+AlwaysPreTouch"
    volumes:-tbmq-logs:/var/log/thingsboard-mqtt-broker-tbmq-data:/data

volumes:
  tbmq-postgres-data:
    external: true
  tbmq-kafka-data:
    external: true
  tbmq-redis-data:
    external: true
  tbmq-logs:
    external: true
  tbmq-data:
    external: true

Additionally, add the following line to your tbmq-install-and-run.sh script (locate create_volume_if_not_exists lines) to create a volume for Redis data:

create_volume_if_not_exists tbmq-redis-data

Or simply create it with the following command:

docker volume create tbmq-redis-data

Once this is done, run the script to apply the changes:

./tbmq-install-and-run.sh

This will restart TBMQ with Redis enabled. Afterward, you can proceed with the upgrade process. Please contact us, so we can answer any questions and provide our help if needed.

执行升级

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

wget -O tbmq-upgrade.sh https://raw.githubusercontent.com/thingsboard/tbmq/release-2.2.0/msa/tbmq/configs/tbmq-upgrade.sh &&
sudo chmod +x tbmq-upgrade.sh && ./tbmq-upgrade.sh

注意：将脚本中的 redis_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 集成。