---
title: "身份认证相关"
image: "https://cwd.js.org/icon.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://cwd.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 身份认证相关

管理员登录接口用于获取后续调用其他管理员接口所需的临时 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": "错误信息"
  }
  ```

Source: https://cwd.js.org/api/admin/auth/index.mdx