外置认证 / 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 进行验证：
bashjwt decode <token>检查 JWT 的 header、payload 和 signature 是否符合预期。
确认 EMQX 配置文件中的
algorithm、public_key与客户端生成 JWT 的配置保持一致。为 JWT 设置合理的过期时间，并确保客户端能够定期刷新 Token。
排查步骤
- 确认网络连通性，配合 EMQX 技术支持人员，使用
curl、ping、nc或telnet等工具，验证 EMQX 节点是否能够访问外部认证或授权服务。 - 检查外部服务状态，确认数据库或 HTTP 服务是否正常运行，是否达到连接数上限，以及 HTTP 接口是否能够返回正确的 JSON 格式和状态码。
- 查看部署日志，将错误类型过滤为认证 / 授权，结合日志中的具体错误信息定位问题原因。
- 针对使用 JWT 的场景，验证
algorithm、public_key等配置是否与客户端保持一致，并对测试 Token 进行解码，确认是否存在过期或 claim 缺失的问题。