docs: 文档更新
This commit is contained in:
anghunk
@@ -24,6 +24,7 @@ export const rootSidebar = [
|
||||
text: '配置',
|
||||
items: [
|
||||
{ text: '站点隔离', link: '/config/site-isolation' },
|
||||
{ text: '页面浏览量', link: '/config/views-display'}
|
||||
],
|
||||
},
|
||||
{ text: '反馈', link: '/guide/feedback' },
|
||||
|
||||
@@ -65,3 +65,12 @@ Token 通过登录接口获取，有效期为 48 小时。
|
||||
|
||||
- **获取功能设置** `GET /admin/settings/feature` - 获取功能开关设置（评论点赞、文章点赞）
|
||||
- **更新功能设置** `PUT /admin/settings/feature` - 更新功能开关设置
|
||||
|
||||
### [S3 备份相关](./admin/s3-backup.md)
|
||||
|
||||
- **获取 S3 配置** `GET /admin/settings/s3` - 获取 S3 存储配置信息
|
||||
- **更新 S3 配置** `PUT /admin/settings/s3` - 更新 S3 存储配置信息
|
||||
- **触发备份** `POST /admin/backup/s3` - 手动触发数据备份到 S3
|
||||
- **获取备份列表** `GET /admin/backup/s3/list` - 获取 S3 存储中的备份文件列表
|
||||
- **下载备份** `GET /admin/backup/s3/download` - 从 S3 下载指定的备份文件
|
||||
- **删除备份** `DELETE /admin/backup/s3` - 删除 S3 存储中指定的备份文件
|
||||
|
||||
365
docs/api/admin/s3-backup.md
Normal file
365
docs/api/admin/s3-backup.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# S3 备份
|
||||
|
||||
S3 备份接口用于配置 S3 兼容存储服务，并实现数据的自动备份和恢复。
|
||||
|
||||
所有接口都需要在请求头中携带 Bearer Token。
|
||||
|
||||
```http
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
## 1. S3 配置管理
|
||||
|
||||
### 1.1 获取 S3 配置
|
||||
|
||||
```
|
||||
GET /admin/settings/s3
|
||||
```
|
||||
|
||||
获取当前 S3 存储配置信息。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/admin/settings/s3`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"endpoint": "https://s3.example.com",
|
||||
"accessKeyId": "your-access-key-id",
|
||||
"secretAccessKey": "your-secret-access-key",
|
||||
"bucket": "your-bucket-name",
|
||||
"region": "auto"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| ----------------- | ------ | ----------------------------------- |
|
||||
| `endpoint` | string | S3 服务端点地址 |
|
||||
| `accessKeyId` | string | 访问密钥 ID |
|
||||
| `secretAccessKey` | string | 访问密钥 |
|
||||
| `bucket` | string | 存储桶名称 |
|
||||
| `region` | string | 区域，默认为 `auto` |
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "加载 S3 配置失败"
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 更新 S3 配置
|
||||
|
||||
```
|
||||
PUT /admin/settings/s3
|
||||
```
|
||||
|
||||
更新 S3 存储配置信息。
|
||||
|
||||
- 方法：`PUT`
|
||||
- 路径：`/admin/settings/s3`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
**请求体**
|
||||
|
||||
```json
|
||||
{
|
||||
"endpoint": "https://s3.example.com",
|
||||
"accessKeyId": "your-access-key-id",
|
||||
"secretAccessKey": "your-secret-access-key",
|
||||
"bucket": "your-bucket-name",
|
||||
"region": "auto"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 必填 | 说明 |
|
||||
| ----------------- | ------ | ---- | ----------------------------------- |
|
||||
| `endpoint` | string | 否 | S3 服务端点地址 |
|
||||
| `accessKeyId` | string | 否 | 访问密钥 ID |
|
||||
| `secretAccessKey` | string | 否 | 访问密钥 |
|
||||
| `bucket` | string | 否 | 存储桶名称 |
|
||||
| `region` | string | 否 | 区域，默认为 `auto` |
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "保存成功"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "保存失败"
|
||||
}
|
||||
```
|
||||
|
||||
## 2. 备份操作
|
||||
|
||||
### 2.1 触发备份
|
||||
|
||||
```
|
||||
POST /admin/backup/s3
|
||||
```
|
||||
|
||||
手动触发一次数据备份，将评论、配置和统计数据上传到 S3 存储。
|
||||
|
||||
- 方法：`POST`
|
||||
- 路径：`/admin/backup/s3`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
**前置条件**
|
||||
|
||||
需要先完成 S3 配置，否则将返回错误。
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "备份成功",
|
||||
"file": "cwd-backup-2026-01-15-1737593600000.json"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| --------- | ------ | ---------------------------- |
|
||||
| `message` | string | 操作结果信息 |
|
||||
| `file` | string | 备份文件名称 |
|
||||
|
||||
**错误响应**
|
||||
|
||||
- S3 配置不完整：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "S3 配置不完整，请先配置 S3 信息"
|
||||
}
|
||||
```
|
||||
|
||||
- 备份失败：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "S3 备份失败"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 获取备份列表
|
||||
|
||||
```
|
||||
GET /admin/backup/s3/list
|
||||
```
|
||||
|
||||
获取 S3 存储中的备份文件列表。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/admin/backup/s3/list`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
**前置条件**
|
||||
|
||||
需要先完成 S3 配置，否则将返回错误。
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"files": [
|
||||
{
|
||||
"key": "cwd-backup-2026-01-15-1737593600000.json",
|
||||
"lastModified": "2026-01-15T10:00:00.000Z",
|
||||
"size": 102400
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| -------------- | ------ | ------------------ |
|
||||
| `files` | Array | 备份文件列表 |
|
||||
| `files[].key` | string | 文件名（唯一标识） |
|
||||
| `files[].lastModified` | string | 最后修改时间（ISO 8601 格式） |
|
||||
| `files[].size` | number | 文件大小（字节） |
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "获取备份列表失败"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 下载备份
|
||||
|
||||
```
|
||||
GET /admin/backup/s3/download
|
||||
```
|
||||
|
||||
从 S3 存储下载指定的备份文件。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/admin/backup/s3/download`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
**查询参数**
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ----- | ----- | ------ | ---- | ------------------ |
|
||||
| `key` | query | string | 是 | 备份文件名（Key） |
|
||||
|
||||
**前置条件**
|
||||
|
||||
需要先完成 S3 配置，否则将返回错误。
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
- Content-Type：`application/json`
|
||||
- Content-Disposition：`attachment; filename="<key>"`
|
||||
|
||||
返回备份文件的 JSON 内容，格式与全量备份一致：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"timestamp": 1737593600000,
|
||||
"comments": [],
|
||||
"settings": [],
|
||||
"page_stats": [],
|
||||
"page_visit_daily": [],
|
||||
"likes": []
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 缺少 `key` 参数：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "缺少 key 参数"
|
||||
}
|
||||
```
|
||||
|
||||
- 下载失败：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "下载备份失败"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 删除备份
|
||||
|
||||
```
|
||||
DELETE /admin/backup/s3
|
||||
```
|
||||
|
||||
删除 S3 存储中指定的备份文件。
|
||||
|
||||
- 方法：`DELETE`
|
||||
- 路径：`/admin/backup/s3`
|
||||
- 鉴权：需要（Bearer Token）
|
||||
|
||||
**查询参数**
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ----- | ----- | ------ | ---- | ------------------ |
|
||||
| `key` | query | string | 是 | 备份文件名（Key） |
|
||||
|
||||
**前置条件**
|
||||
|
||||
需要先完成 S3 配置，否则将返回错误。
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "删除成功"
|
||||
}
|
||||
```
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 缺少 `key` 参数：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "缺少 key 参数"
|
||||
}
|
||||
```
|
||||
|
||||
- 删除失败：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "删除备份失败"
|
||||
}
|
||||
```
|
||||
|
||||
## 3. 支持的 S3 兼容存储
|
||||
|
||||
本系统支持所有 S3 兼容的存储服务，包括但不限于：
|
||||
|
||||
| 服务商 | 端点示例 |
|
||||
| ------------------ | ------------------------------------- |
|
||||
| AWS S3 | `https://s3.<region>.amazonaws.com` |
|
||||
| Cloudflare R2 | `https://<account-id>.r2.cloudflarestorage.com` |
|
||||
| Backblaze B2 | `https://s3.<region>.backblazeb2.com` |
|
||||
| MinIO | `https://your-minio-server.com` |
|
||||
| 阿里云 OSS | `https://oss-<region>.aliyuncs.com` |
|
||||
| 腾讯云 COS | `https://cos.<region>.myqcloud.com` |
|
||||
|
||||
## 4. 备份数据格式
|
||||
|
||||
S3 备份生成的 JSON 文件格式与全量备份一致，包含以下内容：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| ------------------ | ------ | ------------------------ |
|
||||
| `version` | string | 备份格式版本，当前为 `1.0` |
|
||||
| `timestamp` | number | 备份时间戳（毫秒） |
|
||||
| `comments` | Array | 评论数据 |
|
||||
| `settings` | Array | 系统配置数据 |
|
||||
| `page_stats` | Array | 页面访问统计 |
|
||||
| `page_visit_daily` | Array | 按日访问明细 |
|
||||
| `likes` | Array | 点赞记录 |
|
||||
@@ -80,5 +80,64 @@ POST /api/analytics/visit
|
||||
```json
|
||||
{
|
||||
"message": "记录访问数据失败"
|
||||
! }
|
||||
}
|
||||
```
|
||||
|
||||
## 获取页面访问量
|
||||
|
||||
```
|
||||
GET /api/analytics/pv
|
||||
```
|
||||
|
||||
获取指定页面的访问量（PV），用于在前端展示页面访问次数。
|
||||
|
||||
- 方法：`GET`
|
||||
- 路径：`/api/analytics/pv`
|
||||
- 鉴权：不需要
|
||||
|
||||
**查询参数**
|
||||
|
||||
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||
| ----------- | ----- | ------ | ---- | ----------------------------------------- |
|
||||
| `post_slug` | query | string | 是 | 文章唯一标识符 |
|
||||
| `siteId` | query | string | 否 | 站点 ID，用于多站点数据隔离，默认 `default` |
|
||||
|
||||
**成功响应**
|
||||
|
||||
- 状态码：`200`
|
||||
|
||||
```json
|
||||
{
|
||||
"pv": 100,
|
||||
"postSlug": "https://example.com/blog/hello-world"
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段名 | 类型 | 说明 |
|
||||
| ---------- | ------ | ------------------------ |
|
||||
| `pv` | number | 页面访问量（PV） |
|
||||
| `postSlug` | string | 文章唯一标识符 |
|
||||
|
||||
**错误响应**
|
||||
|
||||
- 缺少 `post_slug`：
|
||||
|
||||
- 状态码：`400`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "post_slug is required"
|
||||
}
|
||||
```
|
||||
|
||||
- 服务器内部错误：
|
||||
|
||||
- 状态码：`500`
|
||||
|
||||
```json
|
||||
{
|
||||
"message": "获取访问量失败"
|
||||
}
|
||||
```
|
||||
|
||||
11
docs/config/views-display.md
Normal file
11
docs/config/views-display.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# 页面浏览量
|
||||
|
||||
前端组件支持在网站中显示当前页面的访问量，使用方法: 在指定位置写入以下 html 标签。
|
||||
|
||||
```html
|
||||
<div>已有 <span id="cwd-page-pv">0</span> 人阅读本文！</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*最低支持版本：0.1.9*
|
||||
Reference in New Issue
Block a user