docs: 更新文档内容及结构调整
- 修复文档中的格式问题和错误 - 新增功能文档：数据迁移和管理后台 - 调整文档目录结构，将管理后台移至功能分类 - 更新API文档中的字段说明和响应示例 - 优化后端配置文档，移除冗余内容
This commit is contained in:
anghunk
@@ -20,25 +20,25 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
### 请求头
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------- |
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------ |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "admin@example.com",
|
||||
"password": "your_password"
|
||||
"name": "admin@example.com",
|
||||
"password": "your_password"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| --------- | ------ | ---- | ------------------ |
|
||||
| `name` | string | 是 | 管理员登录名 |
|
||||
| `password`| string | 是 | 管理员登录密码 |
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ---------- | ------ | ---- | -------------- |
|
||||
| `name` | string | 是 | 管理员登录名 |
|
||||
| `password` | string | 是 | 管理员登录密码 |
|
||||
|
||||
管理员登录名和密码由后端环境变量控制，字段为：
|
||||
|
||||
@@ -51,9 +51,9 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"key": "f6e1e0e3-3c9b-4a24-9e88-3b1f709f1e4a"
|
||||
}
|
||||
"data": {
|
||||
"key": "f6e1e0e3-3c9b-4a24-9e88-3b1f709f1e4a"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -62,33 +62,30 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
### 错误与风控
|
||||
|
||||
- 登录失败（用户名或密码错误）：
|
||||
|
||||
- 状态码：`401`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Invalid username or password",
|
||||
"failedAttempts": 3
|
||||
"message": "Invalid username or password",
|
||||
"failedAttempts": 3
|
||||
}
|
||||
```
|
||||
|
||||
- 登录失败次数过多导致 IP 被封禁：
|
||||
|
||||
- 状态码：`403`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "IP is blocked due to multiple failed login attempts"
|
||||
"message": "IP is blocked due to multiple failed login attempts"
|
||||
}
|
||||
```
|
||||
|
||||
- 内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "错误信息"
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -102,9 +99,9 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ------- | ----- | ------- | ---- | ----------------------- |
|
||||
| `page` | query | integer | 否 | 页码，默认 `1` |
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ------ | ----- | ------- | ---- | -------------- |
|
||||
| `page` | query | integer | 否 | 页码，默认 `1` |
|
||||
|
||||
说明：
|
||||
|
||||
@@ -116,38 +113,37 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
{
|
||||
"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,
|
||||
"limit": 10,
|
||||
"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,
|
||||
"limit": 10,
|
||||
"total": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 鉴权错误
|
||||
|
||||
- 未携带 Token 或 Token 失效：
|
||||
|
||||
- 状态码：`401`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Unauthorized"
|
||||
"message": "Unauthorized"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -161,9 +157,9 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| -------- | ----- | ------ | ---- | -------------------------------- |
|
||||
| `id` | query | number | 是 | 评论 ID |
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| -------- | ----- | ------ | ---- | ------------------------------------- |
|
||||
| `id` | query | number | 是 | 评论 ID |
|
||||
| `status` | query | string | 是 | 评论状态，例如 `approved`、`rejected` |
|
||||
|
||||
当前实现中未对 `status` 值进行枚举校验，但推荐仅使用：
|
||||
@@ -177,29 +173,27 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Comment status updated, id: 1, status: approved."
|
||||
"message": "Comment status updated, id: 1, status: approved."
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 缺少参数：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Missing id or status"
|
||||
"message": "Missing id or status"
|
||||
}
|
||||
```
|
||||
|
||||
- 更新失败：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Update failed"
|
||||
"message": "Update failed"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -213,8 +207,8 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
### 查询参数
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ---- | ----- | ------ | ---- | ------ |
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ---- | ----- | ------ | ---- | ------- |
|
||||
| `id` | query | number | 是 | 评论 ID |
|
||||
|
||||
### 成功响应
|
||||
@@ -223,29 +217,27 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Comment deleted, id: 1."
|
||||
"message": "Comment deleted, id: 1."
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 缺少 ID：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Missing id"
|
||||
"message": "Missing id"
|
||||
}
|
||||
```
|
||||
|
||||
- 删除失败：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "Delete operation failed"
|
||||
"message": "Delete operation failed"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -263,35 +255,34 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"pub_date": "2026-01-13 10:00:00",
|
||||
"post_slug": "/blog/hello-world",
|
||||
"author": "张三",
|
||||
"email": "zhangsan@example.com",
|
||||
"url": "https://zhangsan.me",
|
||||
"ip_address": "127.0.0.1",
|
||||
"device": "Desktop",
|
||||
"os": "Windows 10",
|
||||
"browser": "Chrome 90",
|
||||
"user_agent": "Mozilla/5.0 ...",
|
||||
"content_text": "很棒的文章！",
|
||||
"content_html": "很棒的文章！",
|
||||
"parent_id": null,
|
||||
"status": "approved"
|
||||
}
|
||||
{
|
||||
"id": 1,
|
||||
"pub_date": "2026-01-13 10:00:00",
|
||||
"post_slug": "/blog/hello-world",
|
||||
"author": "张三",
|
||||
"email": "zhangsan@example.com",
|
||||
"url": "https://zhangsan.me",
|
||||
"ip_address": "127.0.0.1",
|
||||
"device": "Desktop",
|
||||
"os": "Windows 10",
|
||||
"browser": "Chrome 90",
|
||||
"user_agent": "Mozilla/5.0 ...",
|
||||
"content_text": "很棒的文章！",
|
||||
"content_html": "很棒的文章！",
|
||||
"parent_id": null,
|
||||
"status": "approved"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 导出失败：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "导出失败"
|
||||
"message": "导出失败"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -307,23 +298,23 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 5,
|
||||
"pub_date": "2026-01-20T04:36:57.636Z",
|
||||
"post_slug": "",
|
||||
"author": "1024605422",
|
||||
"email": "1024605422@qq.com",
|
||||
"url": null,
|
||||
"ip_address": "15.235.156.27",
|
||||
"device": "Desktop",
|
||||
"os": "Windows 10",
|
||||
"browser": "Chrome 143.0.0.0",
|
||||
"user_agent": "Mozilla/5.0 ...",
|
||||
"content_text": "试一下",
|
||||
"content_html": "试一下",
|
||||
"parent_id": null,
|
||||
"status": "approved"
|
||||
}
|
||||
{
|
||||
"id": 5,
|
||||
"pub_date": "2026-01-20T04:36:57.636Z",
|
||||
"post_slug": "",
|
||||
"author": "1024605422",
|
||||
"email": "1024605422@qq.com",
|
||||
"url": null,
|
||||
"ip_address": "15.235.156.27",
|
||||
"device": "Desktop",
|
||||
"os": "Windows 10",
|
||||
"browser": "Chrome 143.0.0.0",
|
||||
"user_agent": "Mozilla/5.0 ...",
|
||||
"content_text": "试一下",
|
||||
"content_html": "试一下",
|
||||
"parent_id": null,
|
||||
"status": "approved"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
@@ -335,29 +326,27 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "成功导入 1 条评论"
|
||||
"message": "成功导入 1 条评论"
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 导入数据为空：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "导入数据为空"
|
||||
"message": "导入数据为空"
|
||||
}
|
||||
```
|
||||
|
||||
- 导入失败：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "导入失败"
|
||||
"message": "导入失败"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -375,7 +364,7 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "admin@example.com"
|
||||
"email": "admin@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -385,7 +374,7 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "错误信息"
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -399,15 +388,15 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
### 请求头
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------- |
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------ |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"email": "admin@example.com"
|
||||
"email": "admin@example.com"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -417,29 +406,27 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "保存成功"
|
||||
"message": "保存成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 邮箱格式不正确：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "邮箱格式不正确"
|
||||
"message": "邮箱格式不正确"
|
||||
}
|
||||
```
|
||||
|
||||
- 服务器错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "错误信息"
|
||||
"message": "错误信息"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -457,10 +444,11 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
{
|
||||
"adminEmail": "admin@example.com",
|
||||
"adminBadge": "博主",
|
||||
"avatarPrefix": "https://gravatar.com/avatar",
|
||||
"adminEnabled": true
|
||||
"adminEmail": "admin@example.com",
|
||||
"adminBadge": "博主",
|
||||
"avatarPrefix": "https://gravatar.com/avatar",
|
||||
"adminEnabled": true,
|
||||
"allowedDomains": []
|
||||
}
|
||||
```
|
||||
|
||||
@@ -472,7 +460,7 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "加载评论配置失败"
|
||||
"message": "加载评论配置失败"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -486,29 +474,31 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
### 请求头
|
||||
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------- |
|
||||
| 名称 | 必填 | 示例 |
|
||||
| -------------- | ---- | ------------------ |
|
||||
| `Content-Type` | 是 | `application/json` |
|
||||
|
||||
### 请求体
|
||||
|
||||
```json
|
||||
{
|
||||
"adminEmail": "admin@example.com",
|
||||
"adminBadge": "站长",
|
||||
"avatarPrefix": "https://cravatar.cn/avatar",
|
||||
"adminEnabled": true
|
||||
"adminEmail": "admin@example.com",
|
||||
"adminBadge": "站长",
|
||||
"avatarPrefix": "https://cravatar.cn/avatar",
|
||||
"adminEnabled": true,
|
||||
"allowedDomains": []
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| -------------- | ------- | ---- | ------------------------------------------------ |
|
||||
| `adminEmail` | string | 否 | 博主邮箱地址，需为合法邮箱 |
|
||||
| `adminBadge` | string | 否 | 博主标识文字，例如 `"博主"` |
|
||||
| `avatarPrefix` | string | 否 | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 |
|
||||
| `adminEnabled` | boolean | 否 | 是否启用博主标识相关功能 |
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ---------------- | ------- | ---- | ---------------------------------------------- |
|
||||
| `adminEmail` | string | 否 | 博主邮箱地址，需为合法邮箱 |
|
||||
| `adminBadge` | string | 否 | 博主标识文字，例如 `"博主"` |
|
||||
| `avatarPrefix` | string | 否 | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 |
|
||||
| `adminEnabled` | boolean | 否 | 是否启用博主标识相关功能 |
|
||||
| `allowedDomains` | Array | 否 | 是否允许前端调用的域名 |
|
||||
|
||||
### 成功响应
|
||||
|
||||
@@ -516,28 +506,26 @@ Token 通过登录接口获取，有效期为 24 小时。
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "保存成功"
|
||||
"message": "保存成功"
|
||||
}
|
||||
```
|
||||
|
||||
### 错误响应
|
||||
|
||||
- 邮箱格式错误：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "邮箱格式不正确"
|
||||
"message": "邮箱格式不正确"
|
||||
}
|
||||
```
|
||||
|
||||
- 内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "保存失败"
|
||||
"message": "保存失败"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## 基础信息
|
||||
|
||||
- ** **：`https://your-worker-api.workers.dev` 或你的自定义域名
|
||||
- **接口地址**：`https://your-worker-api.workers.dev` 或你的自定义域名
|
||||
- **数据格式**：JSON
|
||||
- **字符编码**：UTF-8
|
||||
|
||||
|
||||
Reference in New Issue
Block a user