feat(docs): 更新&丰富项目文档

docs/security/admin-auth-protection.md

@@ -0,0 +1,81 @@
+# 管理员认证与防护
+
+本文档聚焦管理后台的认证方式、当前已启用的应用层保护，以及生产环境建议补齐的边缘层防护。
+
+## 认证模式
+
+当前版本支持两种后台认证模式：
+
+- 基础模式：仅校验 `ADMIN_TOKEN`
+- 增强模式：在系统设置中配置并验证 Telegram `Bot Token` / `Chat ID` 后，启用 Telegram 验证码登录
+
+当前实现的认证与安全要点：
+
+- 管理后台使用 session cookie，而不是每次请求直接传管理员令牌
+- 登录、验证码验证和 Telegram 通知都带应用层限速
+- API 文档可在系统设置中关闭；关闭后 `/api/docs`、`/api/redocs`、`/api/openapi.json` 会直接返回 `404`
+
+生产环境不要只依赖应用层逻辑，仍应额外配置 Cloudflare WAF / Rate Limiting。
+
+## 应用层
+
+当前版本已在应用层启用以下保护：
+
+- `/api/admin/auth/login` 按 IP 统计请求频率，超限后返回 `429`
+- 管理员令牌连续失败达到阈值后进入冻结窗口
+- `/api/admin/auth/verify` 按 IP 统计请求频率，超限后返回 `429`
+- 验证码连续失败达到阈值后进入冻结窗口
+- 验证码 challenge 绑定首次请求 IP，来源变化后要求重新获取验证码
+- Telegram 验证码通知按 IP 和全局双层节流
+- Telegram 登录结果通知按 IP 和全局双层节流，超限后静默跳过
+
+## 相关配置
+
+认证与防护相关设置主要位于管理后台的 `System Settings` 页面：
+
+- Telegram 管理员验证开关
+- Telegram `Bot Token` / `Chat ID`
+- API 文档开关
+
+建议流程：
+
+1. 先配置 `ADMIN_TOKEN`
+2. 在系统设置中填写 Telegram 配置
+3. 发送测试消息并完成验证
+4. 再启用 Telegram 二次验证
+5. 根据暴露面决定是否关闭 API 文档
+
+## 边缘层
+
+应用层限速不能替代 Cloudflare 边缘层拦截。生产环境至少再加一层 WAF / Rate Limiting：
+
+- 保护路径：
+  - `POST /api/admin/auth/login`
+  - `POST /api/admin/auth/verify`
+- 推荐匹配表达式：
+
+```txt
+http.request.method eq "POST" and (
+  http.request.uri.path eq "/api/admin/auth/login" or
+  http.request.uri.path eq "/api/admin/auth/verify"
+)
+```
+
+- 推荐计数维度：
+  - `ip.src`
+  - `cf.colo.id`
+- 推荐动作：
+  - 首选 `Managed Challenge`
+  - 高频攻击场景可改为 `Block`
+- 推荐起始阈值：
+  - `login`: 1 分钟内 5 次
+  - `verify`: 1 分钟内 8 次
+  - 缓解时长：15 分钟
+
+## 落地顺序
+
+1. 先在 Cloudflare 控制台或 API 建立登录限速规则
+2. 再观察应用层 `429` 是否仍大量出现
+3. 完成 Telegram 验证配置并确认 session 登录链路正常
+4. 根据实际暴露情况决定是否关闭 API 文档
+5. 若仍有 Telegram 刷屏或管理口扫号，再继续收紧边缘层阈值