docs: 更新文档内容及结构调整
- 修复文档中的格式问题和错误 - 新增功能文档：数据迁移和管理后台 - 调整文档目录结构，将管理后台移至功能分类 - 更新API文档中的字段说明和响应示例 - 优化后端配置文档，移除冗余内容
This commit is contained in:
anghunk
File diff suppressed because one or more lines are too long
@@ -1,49 +1,56 @@
|
||||
import { defineConfig } from 'vitepress'
|
||||
import { defineConfig } from 'vitepress';
|
||||
|
||||
export default defineConfig({
|
||||
title: 'CWD 评论系统文档',
|
||||
description: '基于 Cloudflare Workers 的轻量级评论系统',
|
||||
lang: 'zh-CN',
|
||||
head: [
|
||||
['link', {
|
||||
rel: 'icon',
|
||||
href: 'https://github.com/anghunk/cwd-comments/blob/main/icon.png?raw=true'
|
||||
}]
|
||||
],
|
||||
themeConfig: {
|
||||
nav: [
|
||||
{ text: '首页', link: '/' },
|
||||
{ text: '配置', link: '/guide/getting-started' },
|
||||
{ text: 'API', link: '/api/overview' }
|
||||
],
|
||||
title: 'CWD 评论系统文档',
|
||||
description: '基于 Cloudflare Workers 的轻量级评论系统',
|
||||
lang: 'zh-CN',
|
||||
head: [
|
||||
[
|
||||
'link',
|
||||
{
|
||||
rel: 'icon',
|
||||
href: 'https://github.com/anghunk/cwd-comments/blob/main/icon.png?raw=true',
|
||||
},
|
||||
],
|
||||
],
|
||||
themeConfig: {
|
||||
nav: [
|
||||
{ text: '首页', link: '/' },
|
||||
{ text: '配置', link: '/guide/getting-started' },
|
||||
{ text: 'API', link: '/api/overview' },
|
||||
],
|
||||
|
||||
sidebar: [
|
||||
{
|
||||
text: '配置',
|
||||
items: [
|
||||
{ text: '快速开始', link: '/guide/getting-started' },
|
||||
{ text: '后端配置', link: '/guide/backend-config' },
|
||||
{ text: '前端配置', link: '/guide/frontend-config' },
|
||||
{ text: '管理后台', link: '/guide/admin-panel' },
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'API 文档',
|
||||
items: [
|
||||
{ text: '概览', link: '/api/overview' },
|
||||
{ text: '公开 API', link: '/api/public' },
|
||||
{ text: '管理员 API', link: '/api/admin' }
|
||||
]
|
||||
}
|
||||
],
|
||||
sidebar: [
|
||||
{
|
||||
text: '配置',
|
||||
items: [
|
||||
{ text: '快速开始', link: '/guide/getting-started' },
|
||||
{ text: '后端配置', link: '/guide/backend-config' },
|
||||
{ text: '前端配置', link: '/guide/frontend-config' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: '功能',
|
||||
items: [
|
||||
{ text: '管理后台', link: '/function/admin-panel' },
|
||||
{ text: '数据迁移', link: '/function/data-migration' },
|
||||
],
|
||||
},
|
||||
{
|
||||
text: 'API 文档',
|
||||
items: [
|
||||
{ text: '概览', link: '/api/overview' },
|
||||
{ text: '公开 API', link: '/api/public' },
|
||||
{ text: '管理员 API', link: '/api/admin' },
|
||||
],
|
||||
},
|
||||
],
|
||||
|
||||
socialLinks: [
|
||||
{ icon: 'github', link: 'https://github.com/anghunk/cwd-comments' }
|
||||
],
|
||||
socialLinks: [{ icon: 'github', link: 'https://github.com/anghunk/cwd-comments' }],
|
||||
|
||||
footer: {
|
||||
message: '基于 Cloudflare Workers 构建',
|
||||
copyright: 'Copyright © 2026'
|
||||
}
|
||||
}
|
||||
})
|
||||
footer: {
|
||||
message: '基于 Cloudflare Workers 构建',
|
||||
copyright: 'Copyright © 2026',
|
||||
},
|
||||
},
|
||||
});
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -23,14 +23,16 @@
|
||||
目前接入了 QQ 邮箱提醒，后续会添加其他邮箱服务。
|
||||
|
||||
1. QQ 邮箱
|
||||
- 登录 QQ 邮箱，进入“设置” > “账户”
|
||||
- 开启“POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务”，并获取授权码
|
||||
- 登录 QQ 邮箱，进入 `设置 > 账户`
|
||||
- 开启 `POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV 服务`，并获取授权码
|
||||
- 在管理后台设置中配置 QQ 邮箱账号和授权码
|
||||
|
||||
## 使用官方管理后台
|
||||
|
||||
使用官方提供的管理后台（最新版本）https://cwd-comments.zishu.me。
|
||||
|
||||
登陆时填入你的 api 地址、账号和密码。
|
||||
|
||||
## 自部署
|
||||
|
||||
```bash
|
||||
@@ -81,5 +83,3 @@ cp .env.example .env
|
||||
|
||||
- `VITE_API_BASE_URL` 会作为管理后台的默认 API 地址，实际请求地址可以在登录页修改，并持久化到 `localStorage`。
|
||||
- `VITE_ADMIN_NAME` 和 `VITE_ADMIN_PASSWORD` 仅用于自动填充登录表单，真正的认证信息以后端环境变量 `ADMIN_NAME`、`ADMIN_PASSWORD` 为准。
|
||||
|
||||
|
||||
11
docs/function/data-migration.md
Normal file
11
docs/function/data-migration.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# 数据迁移
|
||||
|
||||
目前支持从 Twikoo, Artalk 评论系统迁移数据。
|
||||
|
||||
其他评论框架逐步支持，欢迎提交反馈，可以将你想要迁移进来的框架以及相关结构提交到评论区，我会尽快添加支持。
|
||||
|
||||
**使用方法：**
|
||||
|
||||
`后台管理 > 数据导入`，选择你要导入框架类型，然后选择本地文件进行导入。
|
||||
|
||||
迁移程序会自动判断是否包含前缀（因部分框架默认不输出前缀），然后可以自定义前缀。
|
||||
@@ -6,9 +6,9 @@
|
||||
* 拥有一个 Node.js 运行环境，版本 >= 22（本地部署需要）
|
||||
* 拥有一个域名并托管在 Cloudflare 上（这个不是必须项，但可以提高国内访问速度，也更方便）
|
||||
|
||||
后端项目目录为 `/cwd-comments-api/`，基于 Cloudflare Workers + D1 + KV 实现。
|
||||
后端项目目录为 `/cwd-comments-api`，基于 Cloudflare Workers + D1 + KV 实现。
|
||||
|
||||
## 部署
|
||||
## 自部署
|
||||
|
||||
**以下部署指令均在该目录下执行，不在根目录下**
|
||||
|
||||
@@ -56,7 +56,7 @@ npm install
|
||||
]
|
||||
```
|
||||
|
||||
如果`binding`字段不是`CWD_DB`，请修改为`CWD_DB`
|
||||
如果 `binding` 字段不是 `CWD_DB`，请修改为 `CWD_DB`。
|
||||
|
||||
* **创建 KV 存储**，如果遇到提示，按回车继续
|
||||
|
||||
@@ -85,105 +85,19 @@ npm install
|
||||
|
||||
#### 3. 配置环境变量
|
||||
|
||||
* 登录 Worker 面板，点击项目右侧的 Settings (设置) 选项卡，选择`查看设置`
|
||||
* 点击变量和机密右侧的添加按钮，给项目添加环境变量，环境变量[参考](#环境变量)
|
||||
* 登录 Worker 面板，点击项目右侧的 Settings (设置) 选项卡，选择 `查看设置`
|
||||
* 点击变量和机密右侧的添加按钮，给项目添加环境变量，环境变量 [参考](#环境变量)
|
||||
* 部署生效：点击底部的 Save and deploy (保存并部署)。
|
||||
|
||||
#### 4. 检测部署情况
|
||||
|
||||
部署成功后回得到一个域名，即为后端的域名（格式一般为`https://cwd-comments-api.xxx.workers.dev`。访问该域名，如果显示部署成功页面，说明 API 部署成功，可以到管理后台进行登录。
|
||||
部署成功后回得到一个域名，即为后端的域名（格式一般为`https://cwd-comments-api.xxx.workers.dev`。访问该域名，如果显示部署成功页面，说明 API 部署成功，可以到管理后台进行登录，当然也可以使用自定义域名。
|
||||
|
||||
当然也可以使用自定义域名。
|
||||
可以直接访问域名，确认是否部署成功。如果成功，则会显示
|
||||
|
||||
## 服务启动与运行参数
|
||||
|
||||
### 本地开发
|
||||
|
||||
在本地开发阶段，可以通过 `wrangler dev` 启动本地 Worker：
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
# 等价于
|
||||
wrangler dev
|
||||
```
|
||||
|
||||
常用参数：
|
||||
|
||||
- `--port <number>`：指定本地开发端口，例如：
|
||||
|
||||
```bash
|
||||
wrangler dev --port 8788
|
||||
```
|
||||
|
||||
如果你使用评论组件开发页面（`widget/`）进行联调，可以将前端中的 `apiBaseUrl` 配置为：
|
||||
|
||||
```text
|
||||
http://localhost:8788
|
||||
```
|
||||
|
||||
- `--env <name>`：指定 wrangler 环境（如有配置多环境）。
|
||||
|
||||
> 注意：线上环境的运行参数完全由 Cloudflare Workers 控制，一般无需额外手动配置，只需在控制台或 `wrangler.jsonc` 中正确配置绑定和变量。
|
||||
|
||||
## 数据库与 KV 连接配置
|
||||
|
||||
后端使用 Cloudflare D1 作为数据库，使用 KV 作为会话存储。
|
||||
|
||||
### D1 数据库
|
||||
|
||||
1. 创建数据库和表结构：
|
||||
|
||||
```bash
|
||||
npx wrangler d1 create CWD_DB
|
||||
npx wrangler d1 execute CWD_DB --remote --file=./schemas/comment.sql
|
||||
```
|
||||
|
||||
2. 在 `wrangler.jsonc` 中确保存在如下配置：
|
||||
|
||||
```jsonc
|
||||
"d1_databases": [
|
||||
{
|
||||
"binding": "CWD_DB",
|
||||
"database_name": "CWD_DB",
|
||||
"database_id": "xxxxxx"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
其中：
|
||||
|
||||
- `binding` 必须为 `CWD_DB`，与代码中的 `env.CWD_DB` 一致。
|
||||
- `database_name` 和 `database_id` 根据 Cloudflare 实际创建结果填写。
|
||||
|
||||
数据库结构定义见 `schemas/comment.sql`。
|
||||
|
||||
### KV 存储
|
||||
|
||||
1. 创建 KV 命名空间：
|
||||
|
||||
```bash
|
||||
npx wrangler kv namespace create CWD_AUTH_KV
|
||||
```
|
||||
|
||||
2. 在 `wrangler.jsonc` 中添加：
|
||||
|
||||
```jsonc
|
||||
"kv_namespaces": [
|
||||
{
|
||||
"binding": "CWD_AUTH_KV",
|
||||
"id": "xxxxxxx"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
其中：
|
||||
|
||||
- `binding` 必须为 `CWD_AUTH_KV`，与代码中的 `env.CWD_AUTH_KV` 一致。
|
||||
|
||||
KV 主要用于：
|
||||
|
||||
- 管理员登录 Token 存储与校验
|
||||
- 登录失败次数和封禁状态记录
|
||||
CWD 评论部署成功，当前版本...
|
||||
```
|
||||
|
||||
## 环境变量与绑定
|
||||
|
||||
@@ -193,11 +107,6 @@ KV 主要用于：
|
||||
|
||||
| 名称 | 类型 | 描述 |
|
||||
| ------------------ | ----------- | --------------------------------------------------------------------- |
|
||||
| `CWD_DB` | D1 绑定 | 评论数据存储数据库 |
|
||||
| `CWD_AUTH_KV` | KV 绑定 | 管理员登录 Token、登录尝试计数等 |
|
||||
| `ALLOW_ORIGIN` | string | 预留的允许跨域来源配置，目前实现中仍使用 `*` |
|
||||
| `MAIL_GATEWAY_URL` | string | 外部邮件网关 HTTP 地址，由此网关转发到 QQ SMTP 或其他邮箱服务（可选） |
|
||||
| `MAIL_GATEWAY_TOKEN` | string | 调用外部邮件网关使用的鉴权 Token（可选） |
|
||||
| `ADMIN_NAME` | string | 管理员登录名称 |
|
||||
| `ADMIN_PASSWORD` | string | 管理员登录密码 |
|
||||
|
||||
@@ -205,5 +114,5 @@ KV 主要用于：
|
||||
|
||||
- 打开 Worker 项目 -> `Settings` -> `Variables`
|
||||
- 在 `Environment Variables` 中添加 `ADMIN_NAME`、`ADMIN_PASSWORD` 等变量
|
||||
- 在 `D1 Databases` 中绑定 `CWD_DB`
|
||||
- 在 `KV Namespaces` 中绑定 `CWD_AUTH_KV`
|
||||
- 在 `D1 Databases` 中绑定 `CWD_DB`（默认已配置好）
|
||||
- 在 `KV Namespaces` 中绑定 `CWD_AUTH_KV`（默认已配置好）
|
||||
|
||||
@@ -1,18 +1,18 @@
|
||||
# 前端配置
|
||||
|
||||
**这里仅提供一套开箱即用的方案，如果是个人开发者可以根据 API 文档自行编写前端评论组件。**
|
||||
**这里仅提供一套开箱即用的方案，如果是个人开发者可以根据 [API 文档](../api/overview) 自行编写前端评论组件。**
|
||||
|
||||
## 评论组件初始化
|
||||
|
||||
在初始化 `CWDComments` 实例时，可以传入以下配置参数：
|
||||
|
||||
```html
|
||||
<script src="https://cwd-comments.zishu.me/cwd-comments.js"></script>
|
||||
<div id="comments"></div>
|
||||
<script src="https://cwd-comments.zishu.me/cwd-comments.js"></script>
|
||||
<script>
|
||||
const comments = new CWDComments({
|
||||
el: '#comments',
|
||||
apiBaseUrl: 'https://your-api.example.com',
|
||||
apiBaseUrl: 'https://your-api.example.com', // 你部署的后端接口地址
|
||||
});
|
||||
comments.mount();
|
||||
</script>
|
||||
@@ -20,12 +20,12 @@
|
||||
|
||||
### 参数说明
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
| ------------ | ----------------------- | ---- | ---------------------------------------------------------------- | ------------------------- |
|
||||
| `el` | `string \| HTMLElement` | 是 | - | 挂载元素选择器或 DOM 元素 |
|
||||
| `apiBaseUrl` | `string` | 是 | - | API 基础地址 |
|
||||
| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 |
|
||||
| `pageSize` | `number` | 否 | `20` | 每页显示评论数 |
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
| ------------ | ----------------------- | ---- | --------- | ------------------------- |
|
||||
| `el` | `string \| HTMLElement` | 是 | - | 挂载元素选择器或 DOM 元素 |
|
||||
| `apiBaseUrl` | `string` | 是 | - | API 基础地址 |
|
||||
| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 |
|
||||
| `pageSize` | `number` | 否 | `20` | 每页显示评论数 |
|
||||
|
||||
头像前缀、博主邮箱和标识等信息由后端接口 `/api/config/comments` 提供，无需在前端进行配置。
|
||||
|
||||
|
||||
@@ -25,7 +25,8 @@ function loadConfigFromStorage() {
|
||||
if (saved) {
|
||||
return { ...DEFAULT_CONFIG, ...JSON.parse(saved) };
|
||||
}
|
||||
} catch (e) {}
|
||||
} catch (e) {
|
||||
}
|
||||
return DEFAULT_CONFIG;
|
||||
}
|
||||
|
||||
@@ -35,7 +36,8 @@ function loadConfigFromStorage() {
|
||||
function saveConfigToStorage(config) {
|
||||
try {
|
||||
localStorage.setItem(STORAGE_KEY, JSON.stringify(config));
|
||||
} catch (e) {}
|
||||
} catch (e) {
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -115,6 +117,7 @@ function toggleTheme() {
|
||||
const config = getConfigFromInputs();
|
||||
config.theme = newTheme;
|
||||
saveConfigToStorage(config);
|
||||
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -124,7 +127,8 @@ function clearConfig() {
|
||||
try {
|
||||
localStorage.removeItem(STORAGE_KEY);
|
||||
populateInputs(DEFAULT_CONFIG);
|
||||
} catch (e) {}
|
||||
} catch (e) {
|
||||
}
|
||||
}
|
||||
|
||||
// 将函数挂载到 window 对象，使其在 HTML 中可访问
|
||||
@@ -134,6 +138,8 @@ window.clearConfig = clearConfig;
|
||||
|
||||
// 页面加载完成后自动初始化
|
||||
document.addEventListener('DOMContentLoaded', () => {
|
||||
|
||||
|
||||
// 从本地存储加载配置并填充到输入框
|
||||
const savedConfig = loadConfigFromStorage();
|
||||
populateInputs(savedConfig);
|
||||
|
||||
@@ -620,10 +620,6 @@
|
||||
font-family: inherit;
|
||||
}
|
||||
|
||||
.cwd-page-num:hover {
|
||||
background: var(--cwd-bg-hover, #f6f8fa);
|
||||
}
|
||||
|
||||
.cwd-page-num-active {
|
||||
color: #ffffff;
|
||||
background: var(--cwd-primary, #0969da);
|
||||
|
||||
Reference in New Issue
Block a user