# 外置认证 / ACL 模块状态告警处理指南

外置认证 / ACL 模块状态告警表示 EMQX 在与配置的外部认证或授权服务（如 HTTP、MySQL、Redis、Postgres、JWT 等）交互过程中出现异常。

该告警可能导致客户端连接无法正常完成认证或授权，从而出现连接失败或权限校验异常的情况。

## 网络连通性异常

### 问题描述

当 EMQX 无法与外部认证或授权服务建立网络连接时，会触发外置认证 / ACL 模块状态告警。

在**部署日志**中，如果出现 `timeout`、`connection refused` 等报错信息，则通常表明 EMQX 与外部服务之间存在网络连通性问题。

### 常见原因

- 未正确配置 VPC 对等连接、Private Link 或 NAT 网关，导致 EMQX 无法访问外部服务。  
- 外部服务的 IP 地址或端口配置错误。  
- 防火墙或安全组未放行相关访问端口。  

### 处理方法

- 确认 VPC 对等连接、Private Link 或 NAT 网关配置正确，并已生效。  
- 核对外部服务的 IP 地址和端口配置是否正确。  
- 检查防火墙或安全组规则，确保已放行 EMQX 到外部服务的访问。  
- 对外部认证服务启用高可用和负载均衡，避免单点故障。  

## 外部服务不可用或运行异常

### 问题描述

当外部认证或授权服务本身不可用或运行异常时，EMQX 在认证或授权阶段无法获取有效响应，从而触发告警。

在**部署日志**中，如果出现 `unrecoverable_error` 或 `disconnected` 等报错信息，通常可以确认该问题与外部服务状态异常有关。

### 常见原因

- 外部服务宕机或进程异常退出。  
- 外部服务负载过高，无法及时响应请求。  
- 数据库连接池耗尽，导致新连接被拒绝。  

### 处理方法

- 检查外部服务（MySQL / Postgres / Redis / HTTP 服务等）的运行状态和服务日志。  
- 监控外部服务的资源使用情况，避免因 CPU、内存或连接数耗尽导致服务异常。  
- 对数据库类服务适当扩容连接池，防止连接资源耗尽。  

## 外部认证或授权配置错误

### 问题描述

当外部认证或授权服务返回的数据格式或内容不符合 EMQX 的要求时，EMQX 无法正确解析响应，从而触发告警。

在**部署日志**中，如果出现 `invalid_response`、`decode error` 等报错信息，则通常表明存在配置或返回格式问题。

### 常见原因

- HTTP API 返回结果中缺少 EMQX 要求的 `result` 字段。  
- 数据库查询语句错误，或查询未返回任何结果。  
- JWT 公钥或私钥配置与客户端不一致。  

### 处理方法

- 检查外部 HTTP API 的返回格式，确保符合 EMQX 认证或授权接口的要求。  
- 验证数据库查询语句是否正确，并能正常返回预期结果。  
- 在测试环境中启用调试模式，确认外部服务返回内容符合 EMQX 的解析要求。  

## JWT 配置相关问题

### 问题描述

在使用 JWT 进行认证或授权时，如果 JWT 配置与客户端生成方式不一致，或 Token 本身无效，也会触发外置认证 / ACL 模块状态告警。

### 常见原因

- **密钥不一致**：客户端生成 JWT 的签名密钥与 EMQX 配置的验证密钥不同。在日志中通常表现为 `JWT verification failed`。  
  
- **算法不匹配**：客户端使用 `HS256`，而 EMQX 配置了 `RS256` 等不同算法。在日志中通常表现为 `unsupported algorithm`。  
  
- **Token 过期或无效**：客户端使用了已过期或无效的 JWT。在日志中通常表现为 `exp claim is expired`。  

### 处理方法

- 使用 JWT 在线解码工具或命令行工具对 Token 进行验证：

  ```bash
  jwt decode <token>

- 检查 JWT 的 header、payload 和 signature 是否符合预期。
- 确认 EMQX 配置文件中的 `algorithm`、`public_key` 与客户端生成 JWT 的配置保持一致。
- 为 JWT 设置合理的过期时间，并确保客户端能够定期刷新 Token。

## 排查步骤

1. 确认网络连通性，配合 EMQX 技术支持人员，使用 `curl`、`ping`、`nc` 或 `telnet` 等工具，验证 EMQX 节点是否能够访问外部认证或授权服务。
2. 检查外部服务状态，确认数据库或 HTTP 服务是否正常运行，是否达到连接数上限，以及 HTTP 接口是否能够返回正确的 JSON 格式和状态码。
3. 查看**部署日志**，将错误类型过滤为**认证 / 授权**，结合日志中的具体错误信息定位问题原因。
4. 针对使用 JWT 的场景，验证 `algorithm`、`public_key` 等配置是否与客户端保持一致，并对测试 Token 进行解码，确认是否存在过期或 claim 缺失的问题。