连接数达到限制告警处理指南
连接数达到限制告警表示 EMQX 当前的客户端连接数量超过该部署规格的阈值。
该情况通常意味着系统的连接规模已达到预期上限，可能对后续的连接接入或整体性能带来影响。常见问题包括客户端连接数增长过快、连接释放不及时，或同一设备出现多个客户端会话。
客户端连接数增长过快
问题描述
EMQX 在短时间内承载大量新增连接，在部署监控页面中，如果客户端连接数在短时间内大幅上升，且增长曲线与业务高峰时段吻合，则可能符合此类情况。
常见原因
常见于客户端批量上线、系统重启或设备集中上电，也可能因业务高峰期导致连接超过预期。
处理方法
在监控 -> 指标 -> 时间轴 -> 连接数中，可查看基于时间轴的整体连接数趋势。提前根据业务规模评估连接峰值，在高峰前对部署进行扩容。
连接释放不及时
问题描述
在部署监控页面中，如果连接数持续高于预期，且断开连接数量异常，则可能符合此类情况。
常见原因
部分客户端异常断开后未能正常关闭连接，或心跳保活配置过长，导致不活跃连接滞留在系统中，占用连接资源，造成实时连接数居高不下。
处理方法
- 调整 keepalive 配置，缩短心跳检测时间，加快异常连接清理。
- 使用连接踢除机制，定期剔除长时间无流量的空闲连接。
同一设备出现多个客户端会话
问题描述
在部署监控页面中，如果连接数异常增加，同时客户端会话数量远高于实际在线设备数量，则可能符合此类情况。
常见原因
当客户端将 Clean Session 设置为 False，且 SDK 随机生成 Client ID 时，频繁重连断开可能导致同一设备产生成百上千个离线会话，从而占用连接资源并间接导致实时连接数异常升高。
处理方法
禁止使用随机 Client ID 搭配 Clean Session = False，否则重连会带来会话堆积。
排查步骤
登录 EMQX Cloud 控制台，进入部署的监控 -> 指标页面：
- 若过去 30 分钟内的最大连接数超过部署规格允许的最大连接数，则会触发此告警。
- 若过去 30 分钟内的最大连接数超过部署规格允许的最大连接数的 110%，则会拒绝新的客户端连接。打开日志后，将“错误类型”过滤为客户端，可找到类似记录：
textpeername: xx.xxx.xxx.xx:64599, pid: <xxxxx>, tag: LICENSE, msg: connection_rejected_due_to_license_limit_reached`。在监控 ->客户端中，筛选连接状态为未连接的客户端，若有多个 IP 地址相同但客户端 ID 不同，且 Clean Session = False 的客户端，则可以判断原因为同一设备出现多个客户端会话。
关于提升最大连接数的说明
以下内容用于说明通过提升部署最大连接数来缓解“连接数达到限制”告警时的行为和影响，不属于该告警的直接排查或解决步骤。
当需要增加部署的最大连接数时，可通过 EMQX Cloud 提交工单进行自动扩容。在运维团队完成环境准备后，扩容过程通常持续 15 ~ 25 分钟。
扩容期间服务将保持可用，但可能出现 2 到 3 次设备级的秒级断线重连现象。若客户端已配置自动重连机制，通常不会对业务产生可感知影响。