0b28c9fa4c
- 重构API文档侧边栏，将公开API拆分为子分类（评论、点赞、配置、身份验证、访问统计） - 新增详细的公开API接口文档，包括评论管理、点赞功能、配置获取、身份验证和访问统计 - 完善数据统计功能文档，增加概览数据、访问明细和数据分析说明 - 更新功能设置文档，补充图片预览和个性化设置说明 - 修正管理员登录文档中的错误描述和格式问题
114 lines
2.5 KiB
Markdown
114 lines
2.5 KiB
Markdown
# 身份认证相关
|
||
|
||
管理员登录接口用于获取后续调用其他管理员接口所需的临时 Token。
|
||
|
||
除登录接口外，所有管理员接口都需要在请求头中携带 Bearer Token。
|
||
|
||
```http
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
Token 通过登录接口获取，有效期为 48 小时。
|
||
|
||
## 1.1 管理员登录
|
||
|
||
```
|
||
POST /admin/login
|
||
```
|
||
|
||
管理员登录，获取后续调用其他管理员接口所需的临时 Token。
|
||
|
||
- 方法：`POST`
|
||
- 路径：`/admin/login`
|
||
- 鉴权：不需要
|
||
|
||
**请求头**
|
||
|
||
| 名称 | 必填 | 示例 |
|
||
| -------------- | ---- | ------------------ |
|
||
| `Content-Type` | 是 | `application/json` |
|
||
|
||
**请求体**
|
||
|
||
```json
|
||
{
|
||
"name": "admin@example.com",
|
||
"password": "your_password"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
| ---------- | ------ | ---- | -------------- |
|
||
| `name` | string | 是 | 管理员登录名 |
|
||
| `password` | string | 是 | 管理员登录密码 |
|
||
|
||
管理员登录名和密码由后端环境变量控制，字段为：
|
||
|
||
- `ADMIN_NAME`
|
||
- `ADMIN_PASSWORD`
|
||
|
||
**成功响应**
|
||
|
||
- 状态码：`200`
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"key": "f6e1e0e3-3c9b-4a24-9e88-3b1f709f1e4a"
|
||
}
|
||
}
|
||
```
|
||
|
||
前端需要将 `data.key` 作为 Token 存储（例如 LocalStorage），并在后续请求中通过 `Authorization: Bearer <key>` 携带。
|
||
|
||
**错误与风控**
|
||
|
||
系统对登录失败进行了风控限制，防止暴力破解：
|
||
|
||
| 参数 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| 最大失败次数 | 5.次 | 超过次数后封禁 IP |
|
||
| 封禁时间 | 30 分钟 | IP 被封禁后需等待此时间 |
|
||
| 计数有效期 | 10 分钟 | 失败计数在此时间后自动重置 |
|
||
|
||
**风控逻辑**：
|
||
1. 每次登录失败，系统会记录该 IP 的失败次数
|
||
2. 失败次数在 10 分钟内连续累计
|
||
3. 达到 5 次失败后，该 IP 被封禁 30 分钟
|
||
4. 登录成功后会清除失败计数
|
||
5. 所有状态存储在 Cloudflare KV 中，基于 IP 地址区分
|
||
|
||
- 登录失败（用户名或密码无效）：
|
||
- 状态码：`401`
|
||
|
||
```json
|
||
{
|
||
"message": "用户名或密码无效",
|
||
"failedAttempts": 3
|
||
}
|
||
```
|
||
|
||
`failedAttempts` 字段表示当前失败次数（1-4），前端可用于提示用户剩余尝试次数。
|
||
|
||
- IP 已被封禁：
|
||
- 状态码：`403`
|
||
|
||
```json
|
||
{
|
||
"message": "IP 已被封禁，30 分钟后重试"
|
||
}
|
||
```
|
||
|
||
IP 被封禁后，需等待 30 分钟后自动解除，或通过管理后台手动清除 KV（删除 `block:<IP>` 键）。
|
||
|
||
- 内部错误：
|
||
- 状态码：`500`
|
||
|
||
```json
|
||
{
|
||
"message": "错误信息"
|
||
}
|
||
```
|