shumengya/cwd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新文档内容及结构调整

Browse Source 
- 修复文档中的格式问题和错误
- 新增功能文档：数据迁移和管理后台
- 调整文档目录结构，将管理后台移至功能分类
- 更新API文档中的字段说明和响应示例
- 优化后端配置文档，移除冗余内容
This commit is contained in:
anghunk
2026-01-20 15:32:51 +08:00
parent 9d3d4f79a9
commit 4a4349e0b9
10 changed files with 216 additions and 299 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
docs/guide/admin-panel.md
View File

@@ -1,85 +0,0 @@
# 管理后台
管理后台用于审核评论、删除评论和管理评论设置。
## 设置
### 头像服务前缀
常用的 Gravatar 镜像服务：
| 服务 | 前缀地址 |
| --------------- | -------------------------------- |
| Gravatar 官方 | `https://gravatar.com/avatar` |
| Cravatar (国内) | `https://cravatar.cn/avatar` |
| 自定义镜像 | `https://your-mirror.com/avatar` |
### 显示博主标签
开启是否显示博主标签，配置博主邮箱和标签文字，即可在评论中显示博主标签；关闭为不显示。
### 邮箱提醒服务
目前接入了 QQ 邮箱提醒，后续会添加其他邮箱服务。
1. QQ 邮箱
- 登录 QQ 邮箱，进入“设置” > “账户”
- 开启“POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务”，并获取授权码
- 在管理后台设置中配置 QQ 邮箱账号和授权码
## 使用官方管理后台
使用官方提供的管理后台（最新版本）https://cwd-comments.zishu.me。
## 自部署
```bash
cd cwd-comments-admin
# 安装依赖
npm install
# 开发环境启动（默认端口见 vite.config.ts，一般为 1226）
npm run dev
# 生产环境构建
npm run build
# 本地预览生产构建结果
npm run preview
```
将 `cwd-comments-admin/dist` 目录部署到任意静态站点托管服务（如 Cloudflare Pages、Vercel、Netlify 等），并确保浏览器可以访问到后端 API 地址。
- 管理后台（admin）：基于 Vite + Vue 3 的单页应用，用于管理评论和系统配置。
- `cwd-comments-admin/`：管理后台源码
- 运行环境：浏览器
- 构建工具：Vite + Vue 3
### 环境变量与多环境配置
评论组件本身不依赖打包时的环境变量，只需要在运行时传入 `apiBaseUrl` 即可。
管理后台使用 Vite 环境变量进行多环境配置，推荐按以下方式区分开发 / 测试 / 生产环境：
在 `cwd-comments-admin` 目录下创建对应的环境文件：
```bash
# 开发环境
cp .env.example .env
```
每个环境文件中可配置以下变量：
| 变量名 | 说明 | 示例 |
| --------------------- | ----------------------------------------------- | ----------------------------------- |
| `VITE_API_BASE_URL` | 后端 API 地址（Cloudflare Worker 域名或自定义） | `https://cwd-comments-api.test.com` |
| `VITE_ADMIN_NAME` | 登录页默认管理员账号占位值 | `admin@example.com` |
| `VITE_ADMIN_PASSWORD` | 登录页默认密码占位值 | `123456` |
说明：
- `VITE_API_BASE_URL` 会作为管理后台的默认 API 地址，实际请求地址可以在登录页修改，并持久化到 `localStorage`。
- `VITE_ADMIN_NAME` 和 `VITE_ADMIN_PASSWORD` 仅用于自动填充登录表单，真正的认证信息以后端环境变量 `ADMIN_NAME`、`ADMIN_PASSWORD` 为准。

113
docs/guide/backend-config.md
View File

@@ -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`（默认已配置好）

18
docs/guide/frontend-config.md
View File

@@ -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` 提供，无需在前端进行配置。