83 lines
2.8 KiB
Markdown
83 lines
2.8 KiB
Markdown
# 管理员认证与防护
|
||
|
||
本文档聚焦管理后台的认证方式、当前已启用的应用层保护，以及生产环境建议补齐的边缘层防护。
|
||
|
||
## 认证模式
|
||
|
||
当前版本支持两种后台认证模式：
|
||
|
||
- 基础模式：仅校验 `ADMIN_TOKEN`
|
||
- 增强模式：在系统设置中配置并验证 Telegram `Bot Token` / `Chat ID` 后，启用 Telegram 验证码登录
|
||
|
||
当前实现的认证与安全要点：
|
||
|
||
- 管理后台使用 session cookie，而不是每次请求直接传管理员令牌
|
||
- session 有效期按登录安全级别区分：未启用 Telegram 验证时为 7 天，启用后为 30 天
|
||
- 登录、验证码验证和 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 刷屏或管理口扫号，再继续收紧边缘层阈值
|