# 连接数达到限制告警处理指南

连接数达到限制告警表示 EMQX 当前的客户端连接数量超过该部署规格的阈值。

该情况通常意味着系统的连接规模已达到预期上限，可能对后续的连接接入或整体性能带来影响。常见问题包括客户端连接数增长过快、连接释放不及时，或同一设备出现多个客户端会话。

## 客户端连接数增长过快

### 问题描述

EMQX 在短时间内承载大量新增连接，在部署监控页面中，如果客户端连接数在短时间内大幅上升，且增长曲线与业务高峰时段吻合，则可能符合此类情况。

### 常见原因

常见于客户端批量上线、系统重启或设备集中上电，也可能因业务高峰期导致连接超过预期。

### 处理方法

在**监控** -> **指标** -> **时间轴** -> **连接数**中，可查看基于时间轴的整体连接数趋势。提前根据业务规模评估连接峰值，在高峰前对部署进行扩容。

![session_limit_monitor](./_assets/session_limit_monitor.png)

## 连接释放不及时

### 问题描述

在部署监控页面中，如果连接数持续高于预期，且断开连接数量异常，则可能符合此类情况。

### 常见原因

部分客户端异常断开后未能正常关闭连接，或心跳保活配置过长，导致不活跃连接滞留在系统中，占用连接资源，造成实时连接数居高不下。

### 处理方法

- 调整 keepalive 配置，缩短心跳检测时间，加快异常连接清理。
- 使用连接踢除机制，定期剔除长时间无流量的空闲连接。

## 同一设备出现多个客户端会话

### 问题描述

在部署监控页面中，如果连接数异常增加，同时客户端会话数量远高于实际在线设备数量，则可能符合此类情况。

### 常见原因

当客户端将 Clean Session 设置为 False，且 SDK 随机生成 Client ID 时，频繁重连断开可能导致同一设备产生成百上千个离线会话，从而占用连接资源并间接导致实时连接数异常升高。

### 处理方法

禁止使用随机 Client ID 搭配 Clean Session = False，否则重连会带来会话堆积。

### 排查步骤

1. 登录 EMQX Cloud 控制台，进入部署的**监控** -> **指标**页面：
    - 若过去 30 分钟内的最大连接数超过部署规格允许的最大连接数，则会触发此告警。
    - 若过去 30 分钟内的最大连接数超过部署规格允许的最大连接数的 110%，则会拒绝新的客户端连接。打开日志后，将“错误类型”过滤为**客户端**，可找到类似记录：

    ```text
    peername: xx.xxx.xxx.xx:64599, pid: <xxxxx>, tag: LICENSE, msg: connection_rejected_due_to_license_limit_reached`。
    ```

2. 在**监控** ->**客户端**中，筛选连接状态为未连接的客户端，若有多个 IP 地址相同但客户端 ID 不同，且 Clean Session = False 的客户端，则可以判断原因为同一设备出现多个客户端会话。

![session_limit_clients](./_assets/session_limit_clients.png)

## 关于提升最大连接数的说明

> 以下内容用于说明通过提升部署最大连接数来缓解“连接数达到限制”告警时的行为和影响，不属于该告警的直接排查或解决步骤。

当需要增加部署的最大连接数时，可通过 EMQX Cloud 提交工单进行自动扩容。在运维团队完成环境准备后，扩容过程通常持续 15 ~ 25 分钟。

扩容期间服务将保持可用，但可能出现 2 到 3 次设备级的秒级断线重连现象。若客户端已配置自动重连机制，通常不会对业务产生可感知影响。