docs: 完善数据迁移与备份恢复文档并优化样式结构
- 将内联样式迁移至独立 CSS 文件以提升可维护性 - 在数据迁移文档中新增 CWD 自身格式支持说明，并补充全量备份功能描述 - 在管理员 API 文档中扩展数据管理接口，详细说明配置、统计及全量备份的导入导出
This commit is contained in:
anghunk
25
docs/.vitepress/theme/custom.css
Normal file
25
docs/.vitepress/theme/custom.css
Normal file
@@ -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;
|
||||
}
|
||||
@@ -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,
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
@@ -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": "全量导入失败"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
目前支持迁移数据的评论框架有以下，请保证导出的格式为 json 格式。
|
||||
|
||||
- **CWD**（CWD 自身导出的评论 JSON，可用于备份与恢复）
|
||||
- **Twikoo**
|
||||
- **Artalk**（如果是 .artalk 后缀，导出到本地后修改后缀为 .json 即可）
|
||||
|
||||
@@ -11,6 +12,21 @@
|
||||
|
||||
**使用方法：**
|
||||
|
||||
`后台管理 > 数据管理 > 评论数据导入`，选择你要导入的框架类型，然后选择本地文件进行导入。
|
||||
`后台管理 > 数据管理 > 评论数据` 区块下：
|
||||
|
||||
- 使用「导出 JSON」按钮，可导出当前所有评论数据（CWD 原生格式），用于备份或在其他环境恢复；
|
||||
- 使用「导入评论」按钮，先在下拉框中选择要导入的框架类型（CWD / Twikoo / Artalk），再选择本地 JSON 文件进行导入。
|
||||
|
||||
迁移程序会自动判断是否包含域名前缀（因部分框架默认不输出域名前缀），然后可以自定义前缀。
|
||||
|
||||
---
|
||||
|
||||
**其他数据导入导出：**
|
||||
|
||||
在 `后台管理 > 数据管理` 页面，还提供以下操作：
|
||||
|
||||
- **系统配置**：导出 / 导入 Settings 表中的配置（评论设置、邮件设置、功能开关等）；
|
||||
- **访问统计**：导出 / 导入页面访问量、按日访问和点赞明细；
|
||||
- **全量备份**：一键导出或导入「评论 + 配置 + 统计」全部数据，适合整站迁移或备份恢复。
|
||||
|
||||
具体接口说明可参考「管理员 API / 数据管理相关」章节。
|
||||
|
||||
@@ -45,7 +45,3 @@ features:
|
||||
details: 提供完整 REST API 与 SDK，一行代码嵌入，适配 Vue、React 等任意框架
|
||||
---
|
||||
|
||||
<style>
|
||||
.extra-class{max-width:1200px;margin:2em auto 0;padding:0 24px;}
|
||||
.image-src{max-width:200px !important;}
|
||||
</style>
|
||||
|
||||
Reference in New Issue
Block a user