动态与公告

新功能发布记录

产品简介

TDMQ 产品系列介绍与选型

什么是消息队列 MQTT 版

应用场景

技术架构

产品系列

MQTT 协议兼容说明

开源对比

高可用

产品约束与使用配额

基本概念

开服地域

购买指南

计费概述

续费说明

查看消费明细

欠费说明

退费说明

快速入门

入门流程指引

准备工作

公网接入

VPC 网络接入

用户指南

使用流程指引

配置账号权限

新建集群

管理 Topic

连接集群

查询消息

管理客户端

管理集群

查看监控和配置告警

数据集成

集成数据到云函数 SCF

集成数据到 CKafka

集成数据到 RocketMQ

开发指南

MQTT 5 高级特性

数据面 HTTP 接口说明

配置自定义域名

配置 SQL 过滤

配置点对点订阅

MQTT over QUIC

管理客户端订阅

消息增强规则

实践教程

MQTT 客户端开发注意事项

可观测能力

Topic 与通配符订阅

API 参考

History

Introduction

API Category

Making API Requests

Cluster APIs

Topic APIs

Authorization Policy APIs

User APIs

Client APIs

Message Enhancement Rule APIs

Message APIs

Data Types

Error Codes

SDK 参考

接入点格式

Java SDK

C SDK

Javascript/Node.JS/小程序

Go SDK

iOS SDK

JavaScript SDK

Dart SDK

Python SDK

.NET

安全与合规

权限管理

常见问题

产品约束与使用配额

PDF

聚焦模式

字号

最后更新时间： 2026-01-30 15:04:59

为了保证集群的性能稳定，腾讯云消息队列 MQTT 版根据不同的售卖规格差异进行一些使用限制，不同售卖规格间的主要功能差异请参考 产品系列。以下介绍您在使用 MQTT 时可能遇到的不同维度的限制。
售卖规格相关限制
限制项
具体限制说明
超限制后的行为
建议
集群 TPS 限制
按照购买页选择的规格进行严格限制。
注意：QoS 和 cleanSession 参数的设置会影响 TPS 的计算，1 TPS并不完全对等1条消息的生产/发送，详见 计费概述。
超出 TPS 限制后，消息的生产/消费请求会被拒绝，并产生报错，详见配额和流控机制说明。
在控制台可以查看相关的限流指标，详见 监控说明。
在购买时请根据实际情况评估流量，当限流发生时，您可以选择升级集群规格 来应对突发流量。
集群客户端连接数量
按照购买页选择的规格进行严格限制。
客户端连接被拒绝，连接请求 (CONNECT) 报错。
在购买时请根据实际情况评估客户端数量，当客户端数量达到上限时，您可以选择 升级集群规格 。
集群订阅数量
30 × 最大客户端连接数量，集群订阅数量包含共享订阅和自动订阅
新的客户端订阅被拒绝，订阅请求 (SUBSCRIBE) 报错。
当多个订阅场景出现限额冲突时，将按照“非 Clean Session 订阅 > 自动订阅规则 > 客户端手动订阅 ”的优先级进行限流，详见自动订阅说明。
﻿
单个客户端（client ID）订阅 Topic Filter 数
30，集群订阅数量包含共享订阅和自动订阅的数量
新的客户端订阅被拒绝，订阅请求 (SUBSCRIBE) 报错。
当多个订阅场景出现限额冲突时，将按照“非 Clean Session 订阅 > 自动订阅规则 > 客户端手动订阅 ”的优先级进行限流，详见自动订阅说明。
﻿
集群订阅速率
集群每秒可接受的最大订阅请求数（一个MQTT SUBSCRIBE 请求），取固定值 100 与集群规格中的客户端连接数的 1/100 两者间的最大值，即max(100, ClientNum / 100)。
新的客户端订阅被拒绝，订阅请求 (SUBSCRIBE) 报错。
﻿
集群取消订阅速率
集群每秒可接受的最大取消订阅请求数（一个MQTT UNSUBSCRIBE 请求），取固定值 100 与集群规格中的客户端连接数的 1/100 两者间的最大值，即max(100, ClientNum / 100)
新的客户端取消订阅被拒绝，取消订阅请求 (UNSUBSCRIBE) 报错。
﻿
集群新建连接速率
max(100, ClientNum / 100)。如集群的连接数上限为 10000，则每秒允许的新建客户端连接数为 100。最多每秒可以新建 100 个连接。
客户端连接被拒绝，连接请求 (CONNECT) 报错。
﻿
携带 Will 消息连接速率
100，每秒允许新建的携带 Will 消息连接的客户端数量。
客户端连接被拒绝，连接请求 (CONNECT) 报错。
﻿
数据面服务使用限制
为了保证服务端的稳定性和性能，同时考虑开源协议的标准和规范，腾讯云消息队列 MQTT 版进行了以下限制。如果某些限制项目和当前的使用场景冲突，可以根据表格中的建议进行相应的操作。对于铂金版的集群，部分限制项可以通过工单服务和专家支持进行调整。
限制项分类
限制细项
具体限制说明
超限制后的行为
建议
资源命名
客户端 ID 和 客户端别名
单集群内唯一，如果不同客户端或设备使用同一个客户端 ID，则会出现互相抢占（take-over）导致下线的情况。
字符要求：仅支持数字 0~9、字母 a~z 或 A~Z 以及 -_@ 三种特殊字符
长度：128 字节
客户端连接被拒绝，连接请求 (CONNECT) 将被拒绝。
如果实际需求超过当前规格限制可以通过工单 联系我们。
﻿
Topic Name
MQTT 协议中定义消息传输的通道和路径。
字符要求：任意 UTF-8 编码字符
长度：256 字节
达到限额后，客户端发送消息请求 (PUBLISH) 将被拒绝。
﻿
﻿
Topic 层级数
10，Topic 名称最多支持使用 9 个 / 符号
达到限额后，客户端发送消息请求 (PUBLISH) 或者订阅请求 (SUBSCRIBE) 将被拒绝。
﻿
﻿
Topic 前缀数量
默认20个
达到限额后无法创建新的Topic前缀
﻿
消息属性和消息体
消息大小
4MiB，指一个完整的消息
发送消息时会出现消息大小超限额的报错。
如果实际需求超过当前规格限制可以通过工单 联系我们。
﻿
Content Type 属性长度
256 字节，仅 MQTT 5.0 涉及
客户端连接（CONNECT）被拒绝或者发送消息请求 (PUBLISH) 报错。
﻿
﻿
User Property 属性长度
8 KB，仅 MQTT 5.0 涉及
发送消息时会出现消息大小超限额的报错。
﻿
﻿
Correlation Data 属性长度
8 KB，仅 MQTT 5.0 涉及
发送消息时会出现消息大小超限额的报错。
﻿
﻿
消息除消息体外的其他属性长度
16 KB
发送消息时会出现消息大小超限额的报错。
﻿
﻿
Topic Alias 最大数量
默认不开启，单个客户端最大 10 个
超出数量的客户端连接会被断开
﻿
消息保存规则
暂未消费的消息保存时间（含保留消息）
3 天
超出时间的消息会被删除。
铂金版的集群可以通过工单服务和专家支持进行调整。
﻿
单集群保留消息最大数量
10000
达到这个上限后，新到达服务端的保留消息发送请求 (PUBLISH) 将被拒绝。
﻿
消息收发
单会话服务端接收的最大 Unack 消息数（QoS >0）
对于 QoS 为 1 和 2 的消息，单个客户端未确认的消息数最多为 32
服务端收到超过限额的消息会断开与客户端的连接。
铂金版的集群可以通过工单服务和专家支持进行调整。
﻿
单会话服务端发送的最大 Unack 消息数（QoS >0）
对于 QoS 为 1 和 2 的消息，单个客户端未确认的消息数最多为 16。
使用 MQTT 5 协议的客户端可以通过 Receive Maximum 调整限制，上限为 1024
达到限额后，服务端将停止发送消息到客户端。
﻿
﻿
HTTP 接口
单个 HTTP 连接占用一个连接数规格。单次调用按照 QoS 1 消息计算 TPS，查看接口使用详情。
达到限额后，调用会报错。
﻿
﻿
单集群排队消息数
无数量限制，但受消息保留时间限制
-
﻿
﻿
单集群保留消息发送和消费速率
100 条/秒
达到限额后，消息发送请求会报错。服务端会暂停发送消息到客户端
﻿
客户端连接
客户端心跳的检查周期
（Keep Alive Interval）
30-1200 秒，根据协议规定，若服务端在设置的 Keep Alive 1.5 倍时间内未收到任何消息，将判定当前连接失效。
如果客户端设置的时间超出这个时间默认也为 1200 秒，则认为是 1200 秒；如果客户端设置的时间低于 30 秒，则认为是 30 秒。
-
﻿
每个客户端 ID 新建连接数
每秒 1 次，每分钟 10 次
客户端连接被拒绝，连接请求 (CONNECT) 报错。
-
﻿
HTTP 查询在线客户端的在线状态
单个 HTTP 连接占用一个连接数规格。单次消息调用按照 QoS 1 消息计算 TPS，查看接口使用详情。
超出限制后，接口调用失败
在购买时请根据实际情况评估客户端数量，当客户端数量达到上限时，您可以选择 升级集群规格 。
﻿
WebSocket 连接时间
24小时
超出连接时间后自动断开连接
-
﻿
离线客户端状态保留时间
默认保留 3 天，可以使用 MQTT 5 协议客户端设置 Session Expiry Interval 来调整保留时间，上限为 3 天
超出保留时间的客户端状态会被删除。
铂金版的集群可以通过工单服务和专家支持进行调整。
﻿
离线客户端状态数量限制
离线客户端与在线客户端共同占用集群客户端连接数量限制
当在线客户端 + 离线客户端数量大于集群客户端连接数量限制时，超出限制的客户端连接会被拒绝。
﻿
证书
单集群服务端证书数量
3，上限为10
-
铂金版的集群可以通过工单服务和专家支持进行调整。
﻿
单集群 CA 证书数量
32
超出后自动注册或手动注册失败
﻿
自动订阅
自动订阅规则数
默认为10，上限为20
无法创建新的自动订阅规则
如果实际需求超过当前规格限制可以通过工单 联系我们。
﻿
单个自动订阅规则内订阅数量
默认为20，上限为30
规则内无法新增订阅规则，添加后无效
﻿
共享订阅
单集群共享订阅组数量上限
20
达到限额后，客户端订阅消息请求 (SUBSCRIBE) 报错
铂金版的集群可以通过工单服务和专家支持进行调整。
﻿
单个共享订阅组中订阅表达式数量上限
10，即 $share/{ShareName}/{filter} 中 filter 的数量
达到限额后，客户端订阅消息请求 (SUBSCRIBE) 报错
﻿
﻿
单个共享订阅组下的客户端数量
1024
达到限额后，客户端订阅消息请求 (SUBSCRIBE) 报错
﻿
消息增强规则
单集群消息增强规则数量
10，每个规则最多添加10个key-value对的用户属性，每个属性值总大小不超过 8KB。
超出后新增消息增强规则的请求会失败。
﻿
其他功能
单个客户端的传播属性数量
10 对 Key: Value 的组合，详见传播属性﻿
超出后新增属性的请求会报失败错误，需要调用接口删除对应的属性后再次添加
﻿
﻿
单个集群的设备身份数量
与集群客户端连接数量相同，如2000 TPS, 2000 连接数的集群，最多可以注册2000个设备身份。
超出后调用注册设备身份接口会报错
﻿
MQTT 协议使用限制
当前 TDMQ MQTT 支持 V3.1.1 的全部特性，支持 5.0 协议的除以下特性外的所有特性：
1. 暂不支持 AUTH 请求；
2. 暂不支持指定 Will Delay Interval；
3. 暂不支持 Server Redirection；
4. Topic Alias 特性灰度开放，如有需要请联系我们；
5. 当消息的 QoS = 2 时，在部分极端情况下，如网络抖动等，会出现消息重复的情况，必要时请做好消息的幂等处理 。

帮助和支持

本页内容是否解决了您的问题？

您也可以联系销售或提交工单以寻求帮助。

填写满意度调查问卷，共创更好文档体验。

文档反馈

限制项	具体限制说明	超限制后的行为	建议
集群 TPS 限制	按照购买页选择的规格进行严格限制。注意：QoS 和 cleanSession 参数的设置会影响 TPS 的计算，1 TPS并不完全对等1条消息的生产/发送，详见计费概述。	超出 TPS 限制后，消息的生产/消费请求会被拒绝，并产生报错，详见配额和流控机制说明。在控制台可以查看相关的限流指标，详见监控说明。	在购买时请根据实际情况评估流量，当限流发生时，您可以选择升级集群规格来应对突发流量。
集群客户端连接数量	按照购买页选择的规格进行严格限制。	客户端连接被拒绝，连接请求 (CONNECT) 报错。	在购买时请根据实际情况评估客户端数量，当客户端数量达到上限时，您可以选择升级集群规格。
集群订阅数量	30 × 最大客户端连接数量，集群订阅数量包含共享订阅和自动订阅	新的客户端订阅被拒绝，订阅请求 (SUBSCRIBE) 报错。当多个订阅场景出现限额冲突时，将按照“非 Clean Session 订阅 > 自动订阅规则 > 客户端手动订阅 ”的优先级进行限流，详见自动订阅说明。
单个客户端（client ID）订阅 Topic Filter 数	30，集群订阅数量包含共享订阅和自动订阅的数量	新的客户端订阅被拒绝，订阅请求 (SUBSCRIBE) 报错。当多个订阅场景出现限额冲突时，将按照“非 Clean Session 订阅 > 自动订阅规则 > 客户端手动订阅 ”的优先级进行限流，详见自动订阅说明。
集群订阅速率	集群每秒可接受的最大订阅请求数（一个MQTT SUBSCRIBE 请求），取固定值 100 与集群规格中的客户端连接数的 1/100 两者间的最大值，即`max(100, ClientNum / 100)`。	新的客户端订阅被拒绝，订阅请求 (SUBSCRIBE) 报错。
集群取消订阅速率	集群每秒可接受的最大取消订阅请求数（一个MQTT UNSUBSCRIBE 请求），取固定值 100 与集群规格中的客户端连接数的 1/100 两者间的最大值，即`max(100, ClientNum / 100)`	新的客户端取消订阅被拒绝，取消订阅请求 (UNSUBSCRIBE) 报错。
集群新建连接速率	`max(100, ClientNum / 100)`。如集群的连接数上限为 10000，则每秒允许的新建客户端连接数为 100。最多每秒可以新建 100 个连接。	客户端连接被拒绝，连接请求 (CONNECT) 报错。
携带 Will 消息连接速率	100，每秒允许新建的携带 Will 消息连接的客户端数量。	客户端连接被拒绝，连接请求 (CONNECT) 报错。

限制项分类	限制细项	具体限制说明	超限制后的行为	建议
资源命名	客户端 ID 和客户端别名	单集群内唯一，如果不同客户端或设备使用同一个客户端 ID，则会出现互相抢占（take-over）导致下线的情况。字符要求：仅支持数字 0~9、字母 a~z 或 A~Z 以及 `-_@` 三种特殊字符长度：128 字节	客户端连接被拒绝，连接请求 (CONNECT) 将被拒绝。	如果实际需求超过当前规格限制可以通过工单联系我们。
		Topic Name	MQTT 协议中定义消息传输的通道和路径。字符要求：任意 UTF-8 编码字符长度：256 字节		达到限额后，客户端发送消息请求 (PUBLISH) 将被拒绝。
		Topic 层级数	10，Topic 名称最多支持使用 9 个 / 符号		达到限额后，客户端发送消息请求 (PUBLISH) 或者订阅请求 (SUBSCRIBE) 将被拒绝。
		Topic 前缀数量	默认20个		达到限额后无法创建新的Topic前缀
消息属性和消息体	消息大小	4MiB，指一个完整的消息	发送消息时会出现消息大小超限额的报错。	如果实际需求超过当前规格限制可以通过工单联系我们。
		Content Type 属性长度	256 字节，仅 MQTT 5.0 涉及		客户端连接（CONNECT）被拒绝或者发送消息请求 (PUBLISH) 报错。
		User Property 属性长度	8 KB，仅 MQTT 5.0 涉及		发送消息时会出现消息大小超限额的报错。
		Correlation Data 属性长度	8 KB，仅 MQTT 5.0 涉及		发送消息时会出现消息大小超限额的报错。
		消息除消息体外的其他属性长度	16 KB		发送消息时会出现消息大小超限额的报错。
		Topic Alias 最大数量	默认不开启，单个客户端最大 10 个		超出数量的客户端连接会被断开
消息保存规则	暂未消费的消息保存时间（含保留消息）	3 天	超出时间的消息会被删除。	铂金版的集群可以通过工单服务和专家支持进行调整。
消息保存规则		单集群保留消息最大数量	10000	铂金版的集群可以通过工单服务和专家支持进行调整。	达到这个上限后，新到达服务端的保留消息发送请求 (PUBLISH) 将被拒绝。
消息收发	单会话服务端接收的最大 Unack 消息数（QoS >0）	对于 QoS 为 1 和 2 的消息，单个客户端未确认的消息数最多为 32	服务端收到超过限额的消息会断开与客户端的连接。	铂金版的集群可以通过工单服务和专家支持进行调整。
		单会话服务端发送的最大 Unack 消息数（QoS >0）	对于 QoS 为 1 和 2 的消息，单个客户端未确认的消息数最多为 16。使用 MQTT 5 协议的客户端可以通过 Receive Maximum 调整限制，上限为 1024		达到限额后，服务端将停止发送消息到客户端。
		HTTP 接口	单个 HTTP 连接占用一个连接数规格。单次调用按照 QoS 1 消息计算 TPS，查看接口使用详情。		达到限额后，调用会报错。
		单集群排队消息数	无数量限制，但受消息保留时间限制		-
		单集群保留消息发送和消费速率	100 条/秒		达到限额后，消息发送请求会报错。服务端会暂停发送消息到客户端
客户端连接	客户端心跳的检查周期（Keep Alive Interval）	30-1200 秒，根据协议规定，若服务端在设置的 Keep Alive 1.5 倍时间内未收到任何消息，将判定当前连接失效。	如果客户端设置的时间超出这个时间默认也为 1200 秒，则认为是 1200 秒；如果客户端设置的时间低于 30 秒，则认为是 30 秒。	-
		每个客户端 ID 新建连接数	每秒 1 次，每分钟 10 次	客户端连接被拒绝，连接请求 (CONNECT) 报错。	-
		HTTP 查询在线客户端的在线状态	单个 HTTP 连接占用一个连接数规格。单次消息调用按照 QoS 1 消息计算 TPS，查看接口使用详情。	超出限制后，接口调用失败	在购买时请根据实际情况评估客户端数量，当客户端数量达到上限时，您可以选择升级集群规格。
		WebSocket 连接时间	24小时	超出连接时间后自动断开连接	-
		离线客户端状态保留时间	默认保留 3 天，可以使用 MQTT 5 协议客户端设置 Session Expiry Interval 来调整保留时间，上限为 3 天	超出保留时间的客户端状态会被删除。	铂金版的集群可以通过工单服务和专家支持进行调整。
		离线客户端状态数量限制	离线客户端与在线客户端共同占用集群客户端连接数量限制	当在线客户端 + 离线客户端数量大于集群客户端连接数量限制时，超出限制的客户端连接会被拒绝。	铂金版的集群可以通过工单服务和专家支持进行调整。
证书	单集群服务端证书数量	3，上限为10	-	铂金版的集群可以通过工单服务和专家支持进行调整。
证书		单集群 CA 证书数量	32	铂金版的集群可以通过工单服务和专家支持进行调整。	超出后自动注册或手动注册失败
自动订阅	自动订阅规则数	默认为10，上限为20	无法创建新的自动订阅规则	如果实际需求超过当前规格限制可以通过工单联系我们。
自动订阅		单个自动订阅规则内订阅数量	默认为20，上限为30	如果实际需求超过当前规格限制可以通过工单联系我们。	规则内无法新增订阅规则，添加后无效
共享订阅	单集群共享订阅组数量上限	20	达到限额后，客户端订阅消息请求 (SUBSCRIBE) 报错	铂金版的集群可以通过工单服务和专家支持进行调整。
		单个共享订阅组中订阅表达式数量上限	10，即 `$share/{ShareName}/{filter}` 中 filter 的数量		达到限额后，客户端订阅消息请求 (SUBSCRIBE) 报错
		单个共享订阅组下的客户端数量	1024		达到限额后，客户端订阅消息请求 (SUBSCRIBE) 报错
消息增强规则	单集群消息增强规则数量	10，每个规则最多添加10个key-value对的用户属性，每个属性值总大小不超过 8KB。	超出后新增消息增强规则的请求会失败。
其他功能	单个客户端的传播属性数量	10 对 Key: Value 的组合，详见传播属性	超出后新增属性的请求会报失败错误，需要调用接口删除对应的属性后再次添加
其他功能		单个集群的设备身份数量	与集群客户端连接数量相同，如2000 TPS, 2000 连接数的集群，最多可以注册2000个设备身份。		超出后调用注册设备身份接口会报错

tencent cloud

消息队列 MQTT 版

产品约束与使用配额

售卖规格相关限制

数据面服务使用限制

MQTT 协议使用限制

帮助和支持