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`