From 49cb63751ffa528dfcf1a2c0aec3e86b438cadfb Mon Sep 17 00:00:00 2001
From: anghunk <anghunk@gmail.com>
Date: Fri, 23 Jan 2026 21:03:07 +0800
Subject: [PATCH] =?UTF-8?q?docs(auth):=20=E6=B7=BB=E5=8A=A0=E7=99=BB?=
 =?UTF-8?q?=E5=BD=95=E6=8E=A5=E5=8F=A3=E7=9A=84=E9=A3=8E=E6=8E=A7=E9=80=BB?=
 =?UTF-8?q?=E8=BE=91=E8=AF=B4=E6=98=8E=E3=80=82?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 新增登录失败的风控限制规则，包括最大失败次数、封禁时间和计数有效期。
- 详细说明风控逻辑的实现步骤和状态存储方式。
- 补充登录失败时返回的 `failedAttempts` 字段说明。
- 添加 IP 被封禁后的处理方式说明。
---
 docs/api/admin/auth.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/api/admin/auth.md b/docs/api/admin/auth.md
index 3f6b6b8..a70b0f8 100644
--- a/docs/api/admin/auth.md
+++ b/docs/api/admin/auth.md
@@ -65,6 +65,21 @@ POST /admin/login
 
 **错误与风控**
 
+系统对登录失败进行了风控限制，防止暴力破解：
+
+| 参数 | 值 | 说明 |
+|------|-----|------|
+| 最大失败次数 | 5 次 | 超过次数后封禁 IP |
+| 封禁时间 | 30 分钟 | IP 被封禁后需等待此时间 |
+| 计数有效期 | 10 分钟 | 失败计数在此时间后自动重置 |
+
+**风控逻辑**：
+1. 每次登录失败，系统会记录该 IP 的失败次数
+2. 失败次数在 10 分钟内连续累计
+3. 达到 5 次失败后，该 IP 被封禁 30 分钟
+4. 登录成功后会清除失败计数
+5. 所有状态存储在 Cloudflare KV 中，基于 IP 地址区分
+
 - 登录失败（用户名或密码错误）：
   - 状态码：`401`
 
@@ -75,6 +90,8 @@ POST /admin/login
   }
   ```
 
+  `failedAttempts` 字段表示当前失败次数（1-4），前端可用于提示用户剩余尝试次数。
+
 - 登录失败次数过多导致 IP 被封禁：
   - 状态码：`403`
 
@@ -84,6 +101,8 @@ POST /admin/login
   }
   ```
 
+  IP 被封禁后，需等待 30 分钟后自动解除，或通过管理后台手动清除 KV（删除 `block:<IP>` 键）。
+
 - 内部错误：
   - 状态码：`500`