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

docs: 更新文档链接、添加favicon并完善API文档

Browse Source 
- 更新widget/README.md中的文档链接
- 在cwd-comments-admin/index.html中添加favicon
- 更新docs/.vitepress/config.mjs中的标题和favicon配置
- 在cwd-comments-admin/src/views/LayoutView.vue中添加文档链接
- 全面重写并完善API文档结构，包括overview.md、public.md和admin.md
- 更新前端配置文档frontend-config.md和后端配置文档backend-config.md
This commit is contained in:
anghunk
2026-01-20 09:51:55 +08:00
parent 2c3eb7a063
commit 9b90f589d5
11 changed files with 1034 additions and 185 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -6,6 +6,8 @@
* 拥有一个 Node.js 运行环境，版本 >= 22（本地部署需要）
* 拥有一个域名并托管在 Cloudflare 上（这个不是必须项，但可以提高国内访问速度，也更方便）
后端项目目录为 `cwd-comments-api/`，基于 Cloudflare Workers + D1 + KV 实现。
## 部署
**以下部署指令均在该目录下执行，不在根目录下**
@@ -93,15 +95,119 @@ npm install
当然也可以使用自定义域名。
## 环境变量
## 服务启动与运行参数
### 本地开发
在本地开发阶段，可以通过 `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`](../../cwd-comments-api/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 存储与校验
- 登录失败次数和封禁状态记录
## 环境变量与绑定
后端通过 Cloudflare Worker 的绑定和环境变量控制行为，类型定义见 [`cwd-comments-api/src/bindings.ts`](../../cwd-comments-api/src/bindings.ts)。
所需环境变量如下表所示。
| 变量名 | 描述 |
| ---------------- | -------------------------------------------------------------------- |
| `ADMIN_NAME` | 管理员登录名称 |
| `ADMIN_PASSWORD` | 管理员登录密码 |
| `CF_FROM_EMAIL` | 作为发件人显示的邮箱地址（需在 Cloudflare Email 路由中预先配置）选填 |
| 名称 | 类型 | 描述 |
| ----------------- | ----------- | -------------------------------------------------------------------- |
| `CWD_DB` | D1 绑定 | 评论数据存储数据库 |
| `CWD_AUTH_KV` | KV 绑定 | 管理员登录 Token、登录尝试计数等 |
| `ALLOW_ORIGIN` | string | 预留的允许跨域来源配置，目前实现中仍使用 `*` |
| `CF_FROM_EMAIL` | string | 作为发件人显示的邮箱地址（需在 Cloudflare Email 路由中预先配置）选填 |
| `SEND_EMAIL` | send_email | Cloudflare Email 发送绑定，供通知邮件使用 |
| `ADMIN_NAME` | string | 管理员登录名称 |
| `ADMIN_PASSWORD` | string | 管理员登录密码 |
在 Cloudflare 控制台中配置方式：
- 打开 Worker 项目 -> `Settings` -> `Variables`
- 在 `Environment Variables` 中添加 `ADMIN_NAME`、`ADMIN_PASSWORD` 等变量
- 在 `D1 Databases` 中绑定 `CWD_DB`
- 在 `KV Namespaces` 中绑定 `CWD_AUTH_KV`
- 在 `Email` 中绑定 `SEND_EMAIL`（如需启用邮件通知）
**注：** 需要在 Cloudflare 控制面板中为 Email 路由开启发送权限并配置发件人域和地址，并在 `wrangler.jsonc` 中为 Worker 添加 `send_email` 绑定，以便在代码中通过 `env.SEND_EMAIL.send()` 直接发信。
@@ -121,4 +227,76 @@ npm install
}
```
参数 `CF_FROM_EMAIL` 这里填写的邮箱是你绑定域名后，创建的 email 路由，两者需保持一致
参数 `CF_FROM_EMAIL` 这里填写的邮箱是你绑定域名后创建的 Email 路由，两者需保持一致。
## 中间件配置说明
后端使用 Hono 框架，在入口文件中统一配置了 CORS 和管理员认证中间件。
入口文件位置：[`cwd-comments-api/src/index.ts`](../../cwd-comments-api/src/index.ts)
### CORS 中间件
当前实现位于 [`cwd-comments-api/src/utils/cors.ts`](../../cwd-comments-api/src/utils/cors.ts)，对 `/api/*` 和 `/admin/*` 路径统一应用：
- 允许来源：`*`
- 允许方法：`GET, POST, PUT, DELETE, OPTIONS`
- 允许请求头：`Content-Type, Authorization`
- 暴露响应头：`Content-Length`
- 不允许携带凭证（`credentials: false`）
这意味着：
- 评论组件和管理后台可以在任意域名下通过 HTTP 调用后端接口，无需浏览器端额外跨域配置。
- 由于不允许跨域携带 Cookie，认证完全通过 `Authorization: Bearer <token>` 头完成。
代码中预留了 `ALLOW_ORIGIN` 绑定，目前默认行为是允许所有来源。如果你有严格的安全需求，可以在此基础上自定义 CORS 逻辑，将 `origin` 收紧到指定域名。
### 管理员认证中间件
管理员认证中间件位于 [`cwd-comments-api/src/utils/auth.ts`](../../cwd-comments-api/src/utils/auth.ts)，对 `/admin/*` 路径统一生效（登录接口除外）：
- 从请求头 `Authorization` 中解析 Bearer Token。
- 在 `CWD_AUTH_KV` 中校验 `token:<key>` 对应的会话信息。
- Token 由 `/admin/login` 接口生成，有效期为 24 小时。
认证失败时返回：
- 状态码：`401`
- 响应体：`{ "message": "Unauthorized" }` 或 `Token expired or invalid`
## 日志配置与规范
后端主要通过 `console.log` 输出结构化日志，便于在 Cloudflare 控制台或日志采集系统中查看。
### 请求级别日志
在入口中为所有请求记录起止日志：
- `Request:start`：
- `method`：HTTP 方法
- `path`：请求路径
- `url`：完整 URL
- `hasDb`：是否成功注入 D1 绑定
- `hasAuthKv`：是否成功注入 KV 绑定
- `Request:end`：
- `method`：HTTP 方法
- `path`：请求路径
### 业务级别日志
示例（评论提交流程）：
- `PostComment:request`：记录 `postSlug`、是否为回复、邮箱是否存在、IP 等信息。
- `PostComment:inserted`：记录评论已写入数据库。
- `PostComment:mailDispatch:*`：记录邮件通知相关流程和限流结果。
错误情况：
- 统一使用 `console.error` 输出错误对象，例如邮件发送失败或数据库写入异常。
### 日志使用建议
- 不在日志中输出管理员密码、完整 Token 等敏感信息。
- 如果接入外部日志系统，可以基于日志前缀（如 `Request:*`、`PostComment:*`）做过滤和告警。
- 在调试阶段可以保留日志，生产环境如需减少日志量，可根据需要在代码中调整输出。

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

@@ -2,42 +2,190 @@
**这里仅提供一套开箱即用的方案，如果是个人开发者可以根据 API 文档自行编写前端评论组件。**
[接口 API](../api/public.md)
当前前端部分主要由两块组成：
## 初始化
- 评论组件（widget）：以 UMD 库形式输出 `cwd-comments.js`，可在任意站点中直接通过 `<script>` 引入。
- 管理后台（admin）：基于 Vite + Vue 3 的单页应用，用于管理评论和系统配置。
在初始化 `CWDComments` 实例时，可以传入以下配置参数：
> 相关 API 文档见：[公开 API](../api/public.md) 和 [管理员 API](../api/admin.md)
```html
<script src="https://cwd-comments.zishu.me/cwd-comments.js"></script>
## 环境与项目结构
前端目录结构与运行时环境：
- `widget/`：评论组件源码
- 运行环境：浏览器（支持现代浏览器）
- 构建工具：Vite
- `cwd-comments-admin/`：管理后台源码
- 运行环境：浏览器
- 构建工具：Vite + Vue 3
Node.js 版本建议使用 `>=18`，与后端保持一致即可。
### 环境变量与多环境配置
评论组件本身不依赖打包时的环境变量，只需要在运行时传入 `apiBaseUrl` 即可。
管理后台使用 Vite 环境变量进行多环境配置，推荐按以下方式区分开发 / 测试 / 生产环境：
在 `cwd-comments-admin` 目录下创建对应的环境文件：
```bash
# 开发环境
cp .env.example .env.development
# 测试环境
cp .env.example .env.test
# 生产环境
cp .env.example .env.production
```
每个环境文件中可配置以下变量：
| 变量名 | 说明 | 示例 |
| -------------------- | ----------------------------------------------- | ----------------------------------- |
| `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` 为准。
## 依赖安装与启动流程
### 评论组件（widget）
开发和构建评论组件：
```bash
cd widget
# 安装依赖
npm install
# 本地开发预览
npm run dev
# 构建 UMD 库（生成 cwd-comments.js）
npm run build
```
构建完成后，将 `widget/dist/cwd-comments.js` 部署到你的静态资源服务器或 CDN，示例：
```html
<script src="https://static.example.com/cwd-comments/cwd-comments.js"></script>
<div id="comments"></div>
<script>
const comments = new CWDComments({
el: '#comments', // 容器 id
apiBaseUrl: 'https://your-api.example.com', // 你部署的 api 地址
postSlug: 'https://example.com/my-post', // 当前页面路径，可使用博客程序支持的 url 模板路径，或者直接使用 window.location.origin
el: '#comments',
apiBaseUrl: 'https://your-api.example.com',
postSlug: 'https://example.com/my-post'
});
comments.mount();
</script>
```
## 参数说明
### 管理后台（cwd-comments-admin）
管理后台用于审核评论、删除评论和管理评论设置。
```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 地址。
## 评论组件初始化
在初始化 `CWDComments` 实例时，可以传入以下配置参数：
```html
<script src="https://cwd-comments.zishu.me/cwd-comments.js"></script>
<div id="comments"></div>
<script>
const comments = new CWDComments({
el: '#comments',
apiBaseUrl: 'https://your-api.example.com',
postSlug: 'https://example.com/my-post'
});
comments.mount();
</script>
```
### 参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
| -------------- | ----------------------- | ---- | ----------------------------- | -------------------------- |
| `el` | `string \| HTMLElement` | 是 | - | 挂载元素选择器或 DOM 元素 |
| `apiBaseUrl` | `string` | 是 | - | API 基础地址 |
| `postSlug` | `string` | 是 | - | 文章唯一标识符 |
| `postTitle` | `string` | 否 | - | 文章标题，用于邮件通知 |
| `postUrl` | `string` | 否 | - | 文章 URL，用于邮件通知 |
| `postTitle` | `string` | 否 | 页面标题或 `postSlug` | 文章标题，用于邮件通知 |
| `postUrl` | `string` | 否 | 当前页面 URL | 文章 URL，用于邮件通知 |
| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 |
| `pageSize` | `number` | 否 | `20` | 每页显示评论数 |
| `avatarPrefix` | `string` | 否 | `https://gravatar.com/avatar` | 头像服务前缀 |
| `adminEmail` | `string` | 否 | - | 博主邮箱，用于显示博主标识 |
| `adminBadge` | `string` | 否 | `博主` | 博主标识文字 |
## 跨域访问配置
前端评论组件与管理后台均通过 HTTP 与后端交互。当前后端在 `/api/*` 和 `/admin/*` 路径下统一开启了 CORS：
- `Access-Control-Allow-Origin: *`
- 允许方法：`GET, POST, PUT, DELETE, OPTIONS`
- 允许请求头：`Content-Type, Authorization`
- 不允许携带 Cookie 等凭证（`Access-Control-Allow-Credentials: false`）
因此在常见部署方式下，你只需要在前端将 `apiBaseUrl` 指向后端 Worker 地址即可，无需额外前端跨域配置，例如：
```javascript
const comments = new CWDComments({
el: '#comments',
apiBaseUrl: 'https://cwd-comments-api.example.com',
postSlug: window.location.pathname
});
comments.mount();
```
如果你在本地同时运行前端和后端，可以按以下方式联调：
- 使用 `wrangler dev` 启动后端（默认端口一般为 8787，如有需要可使用 `wrangler dev --port 8788` 指定端口）。
- 在评论组件开发页面（`widget/index.html`）中，将 API 地址设置为对应本地端口，例如 `http://localhost:8787`。
后端关于 CORS 的更详细说明见：[后端配置](./backend-config.md#跨域配置与安全性)。
## 静态资源部署规范
为了保证前端资源加载稳定，建议按如下规范部署静态资源：
- 使用 HTTPS 域名托管 `cwd-comments.js` 以及管理后台构建产物。
- 将评论组件脚本放在具备缓存能力的静态资源域名或 CDN 上，例如：
- `https://static.example.com/cwd-comments/v0.0.1/cwd-comments.js`
- 当发布新版本时，建议通过路径或文件名中的版本号进行区分，避免缓存错乱。
- 页面中引入脚本时保持路径稳定，便于后续版本升级：
```html
<script src="https://static.example.com/cwd-comments/v0.0.1/cwd-comments.js"></script>
```
管理后台的构建结果同样建议部署到独立的静态站点域名下，例如：
- `https://comments-admin.example.com` 部署 `cwd-comments-admin/dist`
## 头像服务前缀
常用的 Gravatar 镜像服务：