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

docs: 更新文档并添加项目图标

Browse Source 
添加项目图标到README和文档首页
重构前端配置文档，移除冗余内容
新增管理后台部署指南文档
修改默认postSlug为完整URL路径
This commit is contained in:
anghunk
2026-01-20 10:07:30 +08:00
parent 9b90f589d5
commit 1c0c4b5657
6 changed files with 86 additions and 185 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -1,6 +1,8 @@
> [!WARNING]
> 目前仍处于 Beta 测试阶段，欢迎反馈测试结果。
<img src="https://github.com/anghunk/cwd-comments/blob/main/icon.png?raw=true" width="128" />
# cwd-comments
Cloudflare Worker 版本基于 Cloudflare Workers + D1 + KV 实现，无需服务器即可部署运行的评论组件。

1
cwd-comments-admin/public/cwd-comments.js Normal file
View File

File diff suppressed because one or more lines are too long

65
docs/guide/admin-dashboard.md Normal file
View File

@@ -0,0 +1,65 @@
# 管理后台
管理后台用于审核评论、删除评论和管理评论设置。
使用时可选择自部署，也可以使用官方提供的管理后台（最新版本）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` 为准。
## 头像服务前缀
常用的 Gravatar 镜像服务：
| 服务 | 前缀地址 |
| --------------- | -------------------------------- |
| Gravatar 官方 | `https://gravatar.com/avatar` |
| Cravatar (国内) | `https://cravatar.cn/avatar` |
| 自定义镜像 | `https://your-mirror.com/avatar` |

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

@@ -2,113 +2,6 @@
**这里仅提供一套开箱即用的方案，如果是个人开发者可以根据 API 文档自行编写前端评论组件。**
当前前端部分主要由两块组成：
- 评论组件（widget）：以 UMD 库形式输出 `cwd-comments.js`，可在任意站点中直接通过 `<script>` 引入。
- 管理后台（admin）：基于 Vite + Vue 3 的单页应用，用于管理评论和系统配置。
> 相关 API 文档见：[公开 API](../api/public.md) 和 [管理员 API](../api/admin.md)
## 环境与项目结构
前端目录结构与运行时环境：
- `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',
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` 实例时，可以传入以下配置参数：
@@ -117,84 +10,24 @@ npm run preview
<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();
const comments = new CWDComments({
el: '#comments',
apiBaseUrl: 'https://your-api.example.com',
postSlug: window.location.origin + window.location.pathname,
});
comments.mount();
</script>
```
### 参数说明
| 参数 | 类型 | 必填 | 默认值 | 说明 |
| -------------- | ----------------------- | ---- | ----------------------------- | -------------------------- |
| `el` | `string \| HTMLElement` | 是 | - | 挂载元素选择器或 DOM 元素 |
| `apiBaseUrl` | `string` | 是 | - | API 基础地址 |
| `postSlug` | `string` | 是 | - | 文章唯一标识符 |
| `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 镜像服务：
| 服务 | 前缀地址 |
| --------------- | -------------------------------- |
| Gravatar 官方 | `https://gravatar.com/avatar` |
| Cravatar (国内) | `https://cravatar.cn/avatar` |
| 自定义镜像 | `https://your-mirror.com/avatar` |
| 参数 | 类型 | 必填 | 默认值 | 说明 |
| ------------ | ----------------------- | ---- | ---------------------------------------------------------------- | ------------------------- |
| `el` | `string \| HTMLElement` | 是 | - | 挂载元素选择器或 DOM 元素 |
| `apiBaseUrl` | `string` | 是 | - | API 基础地址 |
| `postSlug` | `string` | 是 | 当前页面 URL `window.location.origin + window.location.pathname` | 文章唯一标识符 |
| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 |
| `pageSize` | `number` | 否 | `20` | 每页显示评论数 |
## 实例方法

6
docs/index.md
View File

@@ -4,6 +4,9 @@ layout: home
hero:
name: "CWD 评论系统"
tagline: 轻量级、高性能的评论解决方案, 基于 Cloudflare Workers + D1 + KV 构建
image:
src: https://github.com/anghunk/cwd-comments/blob/main/icon.png?raw=true
alt: 文档封面
actions:
- theme: brand
text: 快速开始
@@ -19,9 +22,6 @@ features:
- icon: 🔒
title: 安全可靠
details: 内置管理员认证、CORS 保护、SQL 注入防护
- icon: 📧
title: 邮件通知
details: 支持 Resend 邮件服务，实时通知新评论
- icon: 🎨
title: 易于集成
details: 提供完整的 REST API，支持任意前端框架

4
widget/src/dev.js
View File

@@ -11,8 +11,8 @@ const STORAGE_KEY = 'cwd-dev-config';
const DEFAULT_CONFIG = {
el: '#comments',
apiBaseUrl: 'http://localhost:8788',
postSlug: window.location.pathname,
theme: 'light',
postSlug: window.location.origin + window.location.pathname,
theme: 'light', // 默认 light / dark
};
let widgetInstance = null;