diff --git a/docs/.vitepress/configs/sidebar.js b/docs/.vitepress/configs/sidebar.js index 1607015..8e857bd 100644 --- a/docs/.vitepress/configs/sidebar.js +++ b/docs/.vitepress/configs/sidebar.js @@ -24,6 +24,7 @@ export const rootSidebar = [ text: '配置', items: [ { text: '站点隔离', link: '/config/site-isolation' }, + { text: '页面浏览量', link: '/config/views-display'} ], }, { text: '反馈', link: '/guide/feedback' }, diff --git a/docs/api/admin.md b/docs/api/admin.md index e4aa329..c3a4010 100644 --- a/docs/api/admin.md +++ b/docs/api/admin.md @@ -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 存储中指定的备份文件 diff --git a/docs/api/admin/s3-backup.md b/docs/api/admin/s3-backup.md new file mode 100644 index 0000000..c282f13 --- /dev/null +++ b/docs/api/admin/s3-backup.md @@ -0,0 +1,365 @@ +# S3 备份 + +S3 备份接口用于配置 S3 兼容存储服务，并实现数据的自动备份和恢复。 + +所有接口都需要在请求头中携带 Bearer Token。 + +```http +Authorization: Bearer +``` + +## 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=""` + +返回备份文件的 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..amazonaws.com` | +| Cloudflare R2 | `https://.r2.cloudflarestorage.com` | +| Backblaze B2 | `https://s3..backblazeb2.com` | +| MinIO | `https://your-minio-server.com` | +| 阿里云 OSS | `https://oss-.aliyuncs.com` | +| 腾讯云 COS | `https://cos..myqcloud.com` | + +## 4. 备份数据格式 + +S3 备份生成的 JSON 文件格式与全量备份一致，包含以下内容： + +| 字段名 | 类型 | 说明 | +| ------------------ | ------ | ------------------------ | +| `version` | string | 备份格式版本，当前为 `1.0` | +| `timestamp` | number | 备份时间戳（毫秒） | +| `comments` | Array | 评论数据 | +| `settings` | Array | 系统配置数据 | +| `page_stats` | Array | 页面访问统计 | +| `page_visit_daily` | Array | 按日访问明细 | +| `likes` | Array | 点赞记录 | \ No newline at end of file diff --git a/docs/api/public/analytics.md b/docs/api/public/analytics.md index 66ca525..5f1a6af 100644 --- a/docs/api/public/analytics.md +++ b/docs/api/public/analytics.md @@ -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": "获取访问量失败" + } ``` diff --git a/docs/config/views-display.md b/docs/config/views-display.md new file mode 100644 index 0000000..b7459e1 --- /dev/null +++ b/docs/config/views-display.md @@ -0,0 +1,11 @@ +# 页面浏览量 + +前端组件支持在网站中显示当前页面的访问量，使用方法: 在指定位置写入以下 html 标签。 + +```html +
已有 0 人阅读本文！
+``` + +--- + +*最低支持版本：0.1.9* \ No newline at end of file