cwd/docs/api/admin/auth.md

身份认证相关

管理员登录接口用于获取后续调用其他管理员接口所需的临时 Token。

除登录接口外，所有管理员接口都需要在请求头中携带 Bearer Token。

Authorization: Bearer <token>

Token 通过登录接口获取，有效期为 48 小时。

1.1 管理员登录

POST /admin/login

管理员登录，获取后续调用其他管理员接口所需的临时 Token。

• 方法：POST
• 路径：/admin/login
• 鉴权：不需要

请求头

名称	必填	示例
Content-Type	是	application/json

请求体

{
	"name": "admin@example.com",
	"password": "your_password"
}

字段说明：

字段名	类型	必填	说明
name	string	是	管理员登录名
password	string	是	管理员登录密码

管理员登录名和密码由后端环境变量控制，字段为：

• ADMIN_NAME
• ADMIN_PASSWORD

成功响应

• 状态码：200

{
	"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

  {
  	"message": "用户名或密码无效",
  	"failedAttempts": 3
  }
  

  failedAttempts 字段表示当前失败次数（1-4），前端可用于提示用户剩余尝试次数。

• 登录失败次数过多导致 IP 被封禁：

  • 状态码：403

  {
  	"message": "IP 已被封禁，30 分钟后重试"
  }
  

  IP 被封禁后，需等待 30 分钟后自动解除，或通过管理后台手动清除 KV（删除 block:<IP> 键）。

• 内部错误：

  • 状态码：500

  {
  	"message": "错误信息"
  }