From 311754dd5d856fd1765e095f6ff7cac4ad0f4e0a Mon Sep 17 00:00:00 2001 From: anghunk Date: Thu, 29 Jan 2026 20:55:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E6=95=B0=E6=8D=AE?= =?UTF-8?q?=E8=BF=81=E7=A7=BB=E4=B8=8E=E5=A4=87=E4=BB=BD=E6=81=A2=E5=A4=8D?= =?UTF-8?q?=E6=96=87=E6=A1=A3=E5=B9=B6=E4=BC=98=E5=8C=96=E6=A0=B7=E5=BC=8F?= =?UTF-8?q?=E7=BB=93=E6=9E=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 将内联样式迁移至独立 CSS 文件以提升可维护性 - 在数据迁移文档中新增 CWD 自身格式支持说明，并补充全量备份功能描述 - 在管理员 API 文档中扩展数据管理接口，详细说明配置、统计及全量备份的导入导出 --- docs/.vitepress/theme/custom.css | 25 +++ docs/.vitepress/theme/index.js | 1 + docs/api/admin.md | 10 +- docs/api/admin/data-migration.md | 339 +++++++++++++++++++++++++++++++ docs/function/data-migration.md | 18 +- docs/index.md | 4 - 6 files changed, 390 insertions(+), 7 deletions(-) create mode 100644 docs/.vitepress/theme/custom.css diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css new file mode 100644 index 0000000..dad860c --- /dev/null +++ b/docs/.vitepress/theme/custom.css @@ -0,0 +1,25 @@ +:root { + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #F08E1F, #ED6127); + --vp-c-brand-1: #ed6127; + --vp-c-brand-2: #ed6127; + --vp-c-brand-3: #ed6127; + --vp-c-brand-soft: rgba(237, 97, 39, 0.14); +} + +.dark { + --vp-c-brand-1: #ed6127; + --vp-c-brand-2: #ed6127; + --vp-c-brand-3: #ed6127; + --vp-c-brand-soft: rgba(240, 142, 31, 0.18); +} + +.extra-class { + max-width: 1200px; + margin: 2em auto 0; + padding: 0 24px; +} + +.image-src { + max-width: 200px !important; +} \ No newline at end of file diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js index 7afae8b..0c76980 100644 --- a/docs/.vitepress/theme/index.js +++ b/docs/.vitepress/theme/index.js @@ -1,6 +1,7 @@ import DefaultTheme from 'vitepress/theme'; import { h } from 'vue'; import FooterDoc from '../components/footerDoc.vue'; +import './custom.css'; export default { ...DefaultTheme, diff --git a/docs/api/admin.md b/docs/api/admin.md index abe007a..67ca55e 100644 --- a/docs/api/admin.md +++ b/docs/api/admin.md @@ -27,8 +27,14 @@ Token 通过登录接口获取，有效期为 48 小时。 ### [数据管理相关](./admin/data-migration.md) -- **导出所有评论数据** `GET /admin/comments/export` - 导出所有评论数据 -- **导入评论数据** `POST /admin/comments/import` - 导入评论数据 +- **导出所有评论数据** `GET /admin/comments/export` - 导出所有评论数据（仅评论） +- **导入评论数据** `POST /admin/comments/import` - 导入评论数据，支持 Twikoo / Artalk / CWD JSON +- **导出配置数据** `GET /admin/export/config` - 导出系统配置（Settings 表） +- **导入配置数据** `POST /admin/import/config` - 导入系统配置 +- **导出访问 / 点赞统计数据** `GET /admin/export/stats` - 导出访问量、按日统计和点赞明细 +- **导入访问 / 点赞统计数据** `POST /admin/import/stats` - 导入访问和点赞统计 +- **全量导出（备份）** `GET /admin/export/backup` - 一次性导出评论 + 配置 + 统计数据 +- **全量导入（恢复）** `POST /admin/import/backup` - 从备份文件恢复全部数据 ### [评论设置相关](./admin/settings.md) diff --git a/docs/api/admin/data-migration.md b/docs/api/admin/data-migration.md index dae155f..cebffdf 100644 --- a/docs/api/admin/data-migration.md +++ b/docs/api/admin/data-migration.md @@ -95,6 +95,11 @@ POST /admin/comments/import 字段说明：与导出格式一致。如果不提供 `id`，则会自动生成。 +说明： + +- 若从 CWD 自身导出的评论数据进行恢复，可直接将 `/admin/comments/export` 接口导出的 JSON 原样提交到本接口； +- 若从 Twikoo / Artalk 等其他评论系统迁移数据，可通过管理后台「评论数据导入」功能上传对应的 JSON 文件，前端会自动转换为上述结构后调用本接口。 + **成功响应** - 状态码：`200` @@ -124,3 +129,337 @@ POST /admin/comments/import "message": "导入失败" } ``` + +## 2. 配置数据导入导出 + +配置数据对应数据库中的 `Settings` 表，主要用于存储评论配置、邮件配置、功能开关等键值对信息。 + +### 2.1 导出配置数据 + +``` +GET /admin/export/config +``` + +- 方法：`GET` +- 路径：`/admin/export/config` +- 鉴权：需要（Bearer Token） + +**成功响应** + +- 状态码：`200` + +```json +[ + { + "key": "comment_admin_email", + "value": "admin@example.com" + } +] +``` + +**错误响应** + +- 导出失败： + - 状态码：`500` + + ```json + { + "message": "导出配置失败" + } + ``` + +### 2.2 导入配置数据 + +``` +POST /admin/import/config +``` + +导入配置数据，支持单个对象或对象数组。 + +- 方法：`POST` +- 路径：`/admin/import/config` +- 鉴权：需要（Bearer Token） + +**请求体** + +```json +[ + { + "key": "comment_admin_email", + "value": "admin@example.com" + } +] +``` + +字段说明： + +- `key`：配置键名，对应 Settings 表中的 `key` 字段； +- `value`：配置值，必须为字符串。 + +**成功响应** + +- 状态码：`200` + +```json +{ + "message": "成功导入 1 条配置" +} +``` + +**错误响应** + +- 导入数据为空： + - 状态码：`400` + + ```json + { + "message": "导入数据为空" + } + ``` + +- 没有有效的配置数据（缺少 key 或 value 非字符串）： + - 状态码：`400` + + ```json + { + "message": "没有有效的配置数据" + } + ``` + +- 导入失败： + - 状态码：`500` + + ```json + { + "message": "导入配置失败" + } + ``` + +## 3. 访问 / 点赞统计数据导入导出 + +统计数据包括页面访问汇总、按日访问明细以及点赞明细。 + +### 3.1 导出访问 / 点赞统计数据 + +``` +GET /admin/export/stats +``` + +- 方法：`GET` +- 路径：`/admin/export/stats` +- 鉴权：需要（Bearer Token） + +**成功响应** + +- 状态码：`200` + +```json +{ + "page_stats": [ + { + "id": 1, + "post_slug": "https://example.com/blog/hello-world", + "post_title": "Hello World", + "post_url": "https://example.com/blog/hello-world", + "pv": 100, + "last_visit_at": 1738060800000, + "created_at": 1738060800000, + "updated_at": 1738147200000 + } + ], + "page_visit_daily": [ + { + "id": 1, + "date": "2026-01-28", + "domain": "example.com", + "count": 50, + "created_at": 1738060800000, + "updated_at": 1738147200000 + } + ], + "likes": [ + { + "id": 1, + "page_slug": "https://example.com/blog/hello-world", + "user_id": "some-user-id", + "created_at": 1738060800000 + } + ] +} +``` + +**错误响应** + +- 导出失败： + - 状态码：`500` + + ```json + { + "message": "导出统计数据失败" + } + ``` + +### 3.2 导入访问 / 点赞统计数据 + +``` +POST /admin/import/stats +``` + +导入访问 / 点赞统计数据，请求体结构需与导出格式一致。 + +- 方法：`POST` +- 路径：`/admin/import/stats` +- 鉴权：需要（Bearer Token） + +**请求体** + +```json +{ + "page_stats": [], + "page_visit_daily": [], + "likes": [] +} +``` + +说明： + +- 三个字段均为可选数组，不提供则视为不导入该类数据； +- 若包含 `id` 字段，将执行插入或替换操作。 + +**成功响应** + +- 状态码：`200` + +```json +{ + "message": "成功导入 0 条统计数据" +} +``` + +**错误响应** + +- 数据格式错误（请求体不是对象）： + - 状态码：`400` + + ```json + { + "message": "数据格式错误" + } + ``` + +- 导入失败： + - 状态码：`500` + + ```json + { + "message": "导入统计数据失败" + } + ``` + +## 4. 全量备份与恢复 + +通过全量导出 / 导入，可以一次性备份或恢复评论、配置和统计数据。 + +### 4.1 全量导出（备份） + +``` +GET /admin/export/backup +``` + +- 方法：`GET` +- 路径：`/admin/export/backup` +- 鉴权：需要（Bearer Token） + +**成功响应** + +- 状态码：`200` + +```json +{ + "version": "1.0", + "timestamp": 1738147200000, + "comments": [], + "settings": [], + "page_stats": [], + "page_visit_daily": [], + "likes": [] +} +``` + +说明： + +- `comments` 字段等同于 `/admin/comments/export` 导出的结果； +- `settings` 字段等同于 `/admin/export/config` 导出的结果； +- `page_stats` / `page_visit_daily` / `likes` 字段等同于 `/admin/export/stats` 导出的结果。 + +**错误响应** + +- 导出失败： + - 状态码：`500` + + ```json + { + "message": "全量导出失败" + } + ``` + +### 4.2 全量导入（恢复） + +``` +POST /admin/import/backup +``` + +使用 `/admin/export/backup` 导出的 JSON 文件进行一键恢复。 + +- 方法：`POST` +- 路径：`/admin/import/backup` +- 鉴权：需要（Bearer Token） + +**请求体** + +```json +{ + "version": "1.0", + "timestamp": 1738147200000, + "comments": [], + "settings": [], + "page_stats": [], + "page_visit_daily": [], + "likes": [] +} +``` + +说明： + +- 若某个字段为空数组或未提供，则不会对对应数据进行导入； +- 评论导入时支持带 `id` 字段的覆盖写入。 + +**成功响应** + +- 状态码：`200` + +```json +{ + "message": "导入结果： 评论 0 条; 配置 0 条; 统计数据 0 条;" +} +``` + +**错误响应** + +- 数据格式错误（请求体不是对象）： + - 状态码：`400` + + ```json + { + "message": "数据格式错误" + } + ``` + +- 导入失败： + - 状态码：`500` + + ```json + { + "message": "全量导入失败" + } + ``` diff --git a/docs/function/data-migration.md b/docs/function/data-migration.md index 23d59fa..5857c18 100644 --- a/docs/function/data-migration.md +++ b/docs/function/data-migration.md @@ -2,6 +2,7 @@ 目前支持迁移数据的评论框架有以下，请保证导出的格式为 json 格式。 +- **CWD**（CWD 自身导出的评论 JSON，可用于备份与恢复） - **Twikoo** - **Artalk**（如果是 .artalk 后缀，导出到本地后修改后缀为 .json 即可） @@ -11,6 +12,21 @@ **使用方法：** -`后台管理 > 数据管理 > 评论数据导入`，选择你要导入的框架类型，然后选择本地文件进行导入。 +`后台管理 > 数据管理 > 评论数据` 区块下： + +- 使用「导出 JSON」按钮，可导出当前所有评论数据（CWD 原生格式），用于备份或在其他环境恢复； +- 使用「导入评论」按钮，先在下拉框中选择要导入的框架类型（CWD / Twikoo / Artalk），再选择本地 JSON 文件进行导入。 迁移程序会自动判断是否包含域名前缀（因部分框架默认不输出域名前缀），然后可以自定义前缀。 + +--- + +**其他数据导入导出：** + +在 `后台管理 > 数据管理` 页面，还提供以下操作： + +- **系统配置**：导出 / 导入 Settings 表中的配置（评论设置、邮件设置、功能开关等）； +- **访问统计**：导出 / 导入页面访问量、按日访问和点赞明细； +- **全量备份**：一键导出或导入「评论 + 配置 + 统计」全部数据，适合整站迁移或备份恢复。 + +具体接口说明可参考「管理员 API / 数据管理相关」章节。 diff --git a/docs/index.md b/docs/index.md index f21b655..86e7fb6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -45,7 +45,3 @@ features: details: 提供完整 REST API 与 SDK，一行代码嵌入，适配 Vue、React 等任意框架 --- -