# 大量客户端取消订阅告警处理指南

大量客户端取消订阅告警表示在部署中，短时间内出现了大量客户端取消订阅主题的情况。该告警仅在 **30 分钟前订阅数不少于 100**，且**取消订阅比例超过设定阈值**时触发。

该情况通常意味着客户端发生了批量取消订阅行为，可能导致消息无法正常推送至订阅端。常见问题包括客户端异常断开连接、客户端重新连接后未重新订阅，或客户端取消订阅相关逻辑存在缺陷。

## 客户端异常断连导致取消订阅

### 问题描述

由于网络抖动、区域性运营商故障或网络维护，可能导致客户端与 EMQX Cloud 的连接在短时间内大量中断。如果客户端未正确实现会话保留和自动重连机制，其已有订阅关系可能会被取消，从而触发大量客户端取消订阅告警。

在部署**监控**页面中，若观察到客户端连接数和主题订阅数在短时间内同时大幅下降，则通常符合此类情况。

### 常见原因

- 网络抖动或区域性网络故障导致客户端大量断连。  
- 客户端未实现会话保留机制，断线后订阅关系无法保留。  
- 客户端未实现或未正确实现自动重连逻辑。  

### 处理方法

- 确认客户端已正确实现会话保留和自动重连机制，确保断线后能够及时恢复连接，并保持订阅关系。  
- 在启用会话保留的场景下，确保 `clientid` 固定，避免因重连导致 `clientid` 变化而丢失订阅。  

## 客户端 SDK 或 API 调用问题

### 问题描述

当订阅数量在短时间内显著下降，但客户端连接数保持相对稳定时，通常表明客户端仍然在线，但订阅被主动取消。该情况可能由客户端 SDK 的默认行为缺陷，或应用层错误调用 API（例如批量调用 `unsubscribe` 接口）导致。

在部署**监控**页面中，若观察到取消订阅数量大幅上升，但连接数维持稳定，并且客户端日志中在相同时间段出现批量 `unsubscribe` 或异常重连行为，则可能与客户端逻辑或 SDK 问题有关。

### 常见原因

- 客户端代码逻辑存在缺陷，出现重复订阅后又取消订阅，但未执行重新订阅。  
- 第三方 SDK 在处理 Clean Session 或持久会话参数时存在兼容性问题。  
- 应用层误用批量 `unsubscribe` 接口，导致订阅被集中清空。  

### 处理方法

- 检查客户端代码逻辑，确认不存在“重复订阅后取消订阅但未重新订阅”的问题。  
- 如使用第三方 SDK，建议升级至最新版本，并重点排查其在 Clean Session 和持久会话参数处理上的行为。  
- 在业务代码中避免不必要的批量 `unsubscribe` 或清空全部订阅的调用；如确有需要，需确保后续 `resubscribe` 能够正确执行。  

## 排查步骤

1. 登录 EMQX Cloud 控制台。

2. 进入部署**告警** -> **告警列表**，确认是否存在大量客户端取消订阅告警，并查看告警触发的时间范围及其影响规模。

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

3. 结合**监控** -> **指标** -> **时间轴** -> **订阅数**，确认过去 30 分钟内订阅数量是否从 100 个以上骤降，且下降幅度超过设定阈值。

4. 对照告警触发时间，结合客户端日志和应用行为，判断是异常断连导致的被动取消，还是客户端主动调用取消订阅接口导致。

## 监控与统计

在**指标** -> **时间轴** -> **订阅数**中，可以查看基于时间轴的整体订阅数量变化趋势，用于持续观察取消订阅情况是否得到缓解。

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

## 客户端取消订阅事件追踪说明

- EMQX Cloud 不存储历史客户端订阅变更信息。若需要长期追踪客户端取消订阅行为，可订阅事件主题 `$events/session_unsubscribed`，并结合规则引擎将事件转发或存储。  示例 SQL 如下：

  ```sql
  SELECT
      *
  FROM
      "$events/session_unsubscribed"
  ```

- 可进一步添加条件过滤，例如 `clientid`、`topic` 等。参考：[SQL 数据源和字段](../../rule_engine/rule_engine_events.md#客户端取消订阅成功事件-events-session-unsubscribed)。

- 该规则仅在**客户端主动取消订阅**时触发；若因客户端断连导致订阅被动取消，则不会生成该事件。