docs: 更新文档链接、添加favicon并完善API文档
- 更新widget/README.md中的文档链接 - 在cwd-comments-admin/index.html中添加favicon - 更新docs/.vitepress/config.mjs中的标题和favicon配置 - 在cwd-comments-admin/src/views/LayoutView.vue中添加文档链接 - 全面重写并完善API文档结构，包括overview.md、public.md和admin.md - 更新前端配置文档frontend-config.md和后端配置文档backend-config.md
This commit is contained in:
anghunk
@@ -1,150 +1,433 @@
|
||||
# 管理员 API
|
||||
|
||||
所有管理员 API 都需要在请求头中携带 Bearer Token：
|
||||
管理员接口用于登录后台、查看和管理评论、配置邮件通知和评论显示设置。
|
||||
|
||||
除登录接口外，所有管理员接口都需要在请求头中携带 Bearer Token。
|
||||
|
||||
```http
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
## 管理员登录
|
||||
Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
获取管理员 Token。
|
||||
本节按 OpenAPI 风格描述每个接口的请求 / 响应结构，并补充鉴权和错误码说明。
|
||||
|
||||
### 请求
|
||||
## POST /admin/login
|
||||
|
||||
```http
|
||||
POST /admin/login
|
||||
Content-Type: application/json
|
||||
```
|
||||
管理员登录，获取后续调用其他管理员接口所需的临时 Token。
|
||||
|
||||
- 方法：`POST`
|
||||
- 路径：`/admin/login`
|
||||
- 鉴权：不需要
|
||||
|
||||
### 请求头
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------- |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "admin",
|
||||
"name": "admin@example.com",
|
||||
"password": "your_password"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应示例
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| --------- | ------ | ---- | ------------------ |
|
||||
| `name` | string | 是 | 管理员登录名 |
|
||||
| `password`| string | 是 | 管理员登录密码 |
|
||||
|
||||
管理员登录名和密码由后端环境变量控制，字段为：
|
||||
|
||||
- `ADMIN_NAME`
|
||||
- `ADMIN_PASSWORD`
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||
"expiresIn": 604800
|
||||
"key": "f6e1e0e3-3c9b-4a24-9e88-3b1f709f1e4a"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 获取评论管理列表
|
||||
前端需要将 `data.key` 作为 Token 存储（例如 LocalStorage），并在后续请求中通过 `Authorization: Bearer <key>` 携带。
|
||||
|
||||
获取所有评论列表（包括待审核的评论）。
|
||||
### 错误与风控
|
||||
|
||||
### 请求
|
||||
- 登录失败（用户名或密码错误）：
|
||||
|
||||
```http
|
||||
GET /admin/comments/list?page={page}&pageSize={pageSize}&status={status}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
- 状态码：`401`
|
||||
|
||||
### 参数
|
||||
```json
|
||||
{
|
||||
"message": "Invalid username or password",
|
||||
"failedAttempts": 3
|
||||
}
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| -------- | ------ | ---- | ----------------------------------- |
|
||||
| page | number | 否 | 页码，默认 1 |
|
||||
| pageSize | number | 否 | 每页数量，默认 20 |
|
||||
| status | string | 否 | 状态筛选：pending/approved/rejected |
|
||||
- 登录失败次数过多导致 IP 被封禁：
|
||||
|
||||
### 响应示例
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "IP is blocked due to multiple failed login attempts"
|
||||
}
|
||||
```
|
||||
|
||||
- 内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
## GET /admin/comments/list
|
||||
|
||||
获取评论列表，用于后台管理页面展示。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/admin/comments/list`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ------- | ----- | ------- | ---- | ----------------------- |
|
||||
| `page` | query | integer | 否 | 页码，默认 `1` |
|
||||
|
||||
说明：
|
||||
|
||||
- 当前实现中每页固定大小为 `10`，暂不支持 `pageSize` 或状态过滤。
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"comments": [
|
||||
{
|
||||
"id": 1,
|
||||
"path": "/blog/hello-world",
|
||||
"author": "张三",
|
||||
"email": "zhangsan@example.com",
|
||||
"content": "很棒的文章！",
|
||||
"parent_id": null,
|
||||
"status": "pending",
|
||||
"created_at": "2026-01-13T10:00:00Z"
|
||||
}
|
||||
],
|
||||
"total": 1,
|
||||
"data": [
|
||||
{
|
||||
"id": 1,
|
||||
"pubDate": "2026-01-13T10:00:00Z",
|
||||
"author": "张三",
|
||||
"email": "zhangsan@example.com",
|
||||
"postSlug": "/blog/hello-world",
|
||||
"url": "https://zhangsan.me",
|
||||
"ipAddress": "127.0.0.1",
|
||||
"contentText": "很棒的文章！",
|
||||
"contentHtml": "很棒的文章！",
|
||||
"status": "approved",
|
||||
"avatar": "https://gravatar.com/avatar/..."
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"pageSize": 20
|
||||
"limit": 10,
|
||||
"total": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 更新评论状态
|
||||
### 鉴权错误
|
||||
|
||||
审核评论，更新评论状态。
|
||||
- 未携带 Token 或 Token 失效：
|
||||
|
||||
### 请求
|
||||
- 状态码：`401`
|
||||
|
||||
```http
|
||||
PUT /admin/comments/status
|
||||
Authorization: Bearer <token>
|
||||
Content-Type: application/json
|
||||
```json
|
||||
{
|
||||
"message": "Unauthorized"
|
||||
}
|
||||
```
|
||||
|
||||
## PUT /admin/comments/status
|
||||
|
||||
更新评论状态（例如通过 / 拒绝）。
|
||||
|
||||
- 方法：`PUT`
|
||||
- 路径：`/admin/comments/status`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| -------- | ----- | ------ | ---- | -------------------------------- |
|
||||
| `id` | query | number | 是 | 评论 ID |
|
||||
| `status` | query | string | 是 | 评论状态，例如 `approved`、`rejected` |
|
||||
|
||||
当前实现中未对 `status` 值进行枚举校验，但推荐仅使用：
|
||||
|
||||
- `approved`：已通过
|
||||
- `rejected`：已拒绝
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Comment status updated, id: 1, status: approved."
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 缺少参数：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Missing id or status"
|
||||
}
|
||||
```
|
||||
|
||||
- 更新失败：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Update failed"
|
||||
}
|
||||
```
|
||||
|
||||
## DELETE /admin/comments/delete
|
||||
|
||||
删除指定评论。
|
||||
|
||||
- 方法：`DELETE`
|
||||
- 路径：`/admin/comments/delete`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ---- | ----- | ------ | ---- | ------ |
|
||||
| `id` | query | number | 是 | 评论 ID |
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Comment deleted, id: 1."
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 缺少 ID：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Missing id"
|
||||
}
|
||||
```
|
||||
|
||||
- 删除失败：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Delete operation failed"
|
||||
}
|
||||
```
|
||||
|
||||
## GET /admin/settings/email
|
||||
|
||||
获取当前通知邮箱配置。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/admin/settings/email`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "admin@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
## PUT /admin/settings/email
|
||||
|
||||
设置通知邮箱，用于接收新评论提醒。
|
||||
|
||||
- 方法：`PUT`
|
||||
- 路径：`/admin/settings/email`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 请求头
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------- |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 1,
|
||||
"status": "approved"
|
||||
"email": "admin@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
### 参数说明
|
||||
### 成功响应
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ------ | ------ | ---- | ---------------------------------------- |
|
||||
| id | number | 是 | 评论 ID |
|
||||
| status | string | 是 | 状态：approved（通过）/ rejected（拒绝） |
|
||||
|
||||
### 响应示例
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"message": "评论状态已更新"
|
||||
}
|
||||
"message": "保存成功"
|
||||
}
|
||||
```
|
||||
|
||||
## 删除评论
|
||||
### 错误响应
|
||||
|
||||
删除指定评论。
|
||||
- 邮箱格式不正确：
|
||||
|
||||
### 请求
|
||||
- 状态码：`400`
|
||||
|
||||
```http
|
||||
DELETE /admin/comments/delete?id={id}
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
```json
|
||||
{
|
||||
"message": "邮箱格式不正确"
|
||||
}
|
||||
```
|
||||
|
||||
### 参数
|
||||
- 服务器错误：
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
|------|------|------|------|
|
||||
| id | number | 是 | 评论 ID |
|
||||
- 状态码：`500`
|
||||
|
||||
### 响应示例
|
||||
```json
|
||||
{
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
## GET /admin/settings/comments
|
||||
|
||||
获取评论配置，例如博主邮箱、徽标和头像前缀等。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/admin/settings/comments`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"message": "评论已删除"
|
||||
}
|
||||
"adminEmail": "admin@example.com",
|
||||
"adminBadge": "博主",
|
||||
"avatarPrefix": "https://gravatar.com/avatar",
|
||||
"adminEnabled": true
|
||||
}
|
||||
```
|
||||
|
||||
字段说明与公开接口 `/api/config/comments` 一致。
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "加载评论配置失败"
|
||||
}
|
||||
```
|
||||
|
||||
## PUT /admin/settings/comments
|
||||
|
||||
更新评论配置。
|
||||
|
||||
- 方法：`PUT`
|
||||
- 路径：`/admin/settings/comments`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
### 请求头
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------- |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"adminEmail": "admin@example.com",
|
||||
"adminBadge": "站长",
|
||||
"avatarPrefix": "https://cravatar.cn/avatar",
|
||||
"adminEnabled": true
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| -------------- | ------- | ---- | ------------------------------------------------ |
|
||||
| `adminEmail` | string | 否 | 博主邮箱地址，需为合法邮箱 |
|
||||
| `adminBadge` | string | 否 | 博主标识文字，例如 `"博主"` |
|
||||
| `avatarPrefix` | string | 否 | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 |
|
||||
| `adminEnabled` | boolean | 否 | 是否启用博主标识相关功能 |
|
||||
|
||||
### 成功响应
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "保存成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 邮箱格式错误：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "邮箱格式不正确"
|
||||
}
|
||||
```
|
||||
|
||||
- 内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "保存失败"
|
||||
}
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user