1. 这是什么机制

为防止外部 Token 接口被暴力尝试，VVCMS 提供按来源 IP 的认证失败锁定，同时作用于外部 API、MCP 和后台管理接口。连续失败达阈值后，该 IP 被锁定一段时间，锁定期间所有需要认证的接口返回 HTTP 429 并带 Retry-After 头。

配置项在后台「安全配置」：

{
  "auth_guard_enabled": true,
  "auth_guard_max_failures": 10,
  "auth_guard_block_seconds": 600,
  "auth_guard_trust_proxy": false
}

2. 什么情况会计数，什么不会

「未带凭证不计数」是刻意设计，避免未登录状态的正常访问被误锁。

注意：/api/public/ 不参与计数，也就意味着 /api/public/login 的密码尝试不受本机制保护，目前只依赖验证码等业务手段。

3. 被锁了怎么自救

1. 等。锁定按 auth_guard_block_seconds 自动解除，默认是 600 秒。响应头里的 Retry-After 会告诉你还要多久。
2. 重启服务可以立即清空。失败计数保存在进程内存里，重启即清零——这是应急手段，不是常规解法。
3. 改配置需要有效凭证。调整阈值本身要走管理接口，而管理接口在锁定期内同样返回 429，所以锁住之后没法靠改配置自救。

4. 反向代理后面必踩的坑

如果你的站点前面有 Nginx 等反向代理，必须把 auth_guard_trust_proxy 设为 true。否则所有请求的来源 IP 都会被识别成代理机那一个地址，结果是：

• 任何人一次输错密码，全站所有人一起被锁。
• 反过来，直连部署时如果开了这个选项，攻击者可以伪造 X-Forwarded-For 绕过锁定。

判断标准很简单：有没有反向代理就开不开。

5. 为什么有人一直攒不满阈值

一次认证成功且请求最终未被拒绝才会清零该 IP 的连续失败数。这里的判定不只看中间件是否中断请求，还要看最终响应状态码——因为部分端点（如 MCP）的权限判断在业务处理内部完成，会直接返回 403 而不中断中间件链。如果只按"有没有中断"来判成功，刚记录的失败会被立刻清零，越权请求就永远攒不满阈值、拉黑形同虚设。

对你来说这个细节的实际意义是：成功的请求才能真正把计数冲掉，反复拿错 Token 重试只会加速被锁。