# 大量认证失败告警处理指南

大量认证失败告警表示在部署中，客户端在短时间内出现了大量认证失败的情况。该告警在以下条件下触发：

- **Warning**：过去 30 分钟内认证总次数 ≥ 1800，且认证失败比例 > 0.5。  
- **Error**：过去 30 分钟内认证总次数 ≥ 1800，且认证失败比例 > 0.75。  

该情况通常意味着客户端认证行为存在异常，可能影响正常的业务接入。常见问题包括客户端认证配置错误、客户端使用了过期或错误的凭证、大量非法连接尝试，或认证服务本身出现异常。

## 客户端认证配置错误

### 问题描述

在部署中，如果大量客户端在短时间内出现认证失败，且失败行为与特定客户端 ID、用户名或来源 IP 地址高度相关，则可能是客户端认证配置错误导致。

### 常见原因

- 客户端配置了错误的用户名、密码或 Token。  
- 在大规模设备升级、批量配置下发过程中，下发了错误的认证信息。  

### 处理方法

- 检查客户端的认证配置，确保用户名、密码或 Token 与服务端配置保持一致。  
- 在批量设备升级或配置下发前，先在测试环境中进行验证，避免错误配置集中上线。  

## 非法客户端连接尝试

### 问题描述

如果在短时间内出现大量认证失败请求，但这些请求并不来自正常业务客户端，则可能存在非法客户端连接尝试或恶意攻击行为。

在认证失败日志中，若发现认证失败请求集中来自少量异常 IP 地址，且不属于正常业务访问范围，或新增连接数明显增加但认证成功率极低，则通常符合此类情况。

### 常见原因

- 外部恶意扫描或暴力破解行为。  
- 使用无效凭证频繁尝试建立连接。  

### 处理方法

- 通过黑名单机制屏蔽异常 IP 段，阻止非法访问。  
- 使用 EMQX 提供的连接与认证防护能力，限制异常连接行为。  
- EMQX 默认已开启针对同一 Client ID 的重连频率限制，用于防止暴力攻击，相关机制可参考[到期时间说明](../blacklist.md#到期时间)。  

## 认证服务异常

### 问题描述

当外部认证服务（如 HTTP 认证接口或数据库查询）出现延迟、超时或故障时，部分原本合法的客户端认证请求也可能失败，从而触发大量认证失败告警。

在监控中，如果认证失败比例的上升与外部认证服务错误率增加或响应延迟上升同步发生，则通常可以判断为认证服务异常。

### 常见原因

- 外部认证服务不可用或响应异常。  
- 认证服务负载过高，导致请求超时或失败。  

### 处理方法

- 检查外部认证服务的运行状态和性能指标，确认是否存在超时或错误。  
- 为认证接口增加合理的重试机制或缓存策略，降低短暂波动对认证结果的影响。  
- 适当增加认证服务实例数量，提高整体可用性和处理能力。  

## 排查步骤

1. 登录 EMQX Cloud 控制台，进入部署。

2. 进入**日志**页面，将日志类型过滤为**认证**，查看是否存在大量认证失败相关的错误日志，并结合日志内容分析失败原因。

3. 进入**告警**页面，查看是否存在与认证相关的告警记录，确认告警触发时间与认证失败行为是否一致。

4. 结合客户端来源、认证配置和外部认证服务状态，进一步确认属于客户端配置问题、非法连接尝试还是认证服务异常。

## 告警影响说明

- 大量认证失败告警通常不会直接导致部署停止。  
- 如果认证失败情况持续超出阈值，说明客户端连接认证或认证逻辑存在问题，可能影响业务正常接入。  
- 建议在告警触发后尽快检查涉及的客户端认证配置、连接行为以及认证服务状态，避免问题持续扩大。