Initial commit
This commit is contained in:
anghunk
103
docs/guide/backend-config.md
Normal file
103
docs/guide/backend-config.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# 后端配置
|
||||
|
||||
## 部署条件
|
||||
|
||||
* 拥有一个 Cloudflare 账号（使用邮箱即可注册，[官网地址](https://www.cloudflare.com/)）
|
||||
* 拥有一个 Node.js 运行环境，版本 >= 22（本地部署需要）
|
||||
* 拥有一个域名并托管在 Cloudflare 上（这个不是必须项，但可以提高国内访问速度，也更方便）
|
||||
|
||||
## 部署
|
||||
|
||||
### 本地部署
|
||||
|
||||
#### 1. 下载代码，安装依赖
|
||||
|
||||
可以直接克隆仓库代码
|
||||
|
||||
```
|
||||
npm install
|
||||
```
|
||||
|
||||
#### 2. 配置 Cloudflare Workers
|
||||
|
||||
对于 D1 和 KV 配置，有两种方法，第一种是直接使用命令行配置，第二种是使用网页面板创建后填写配置文件，这里推荐使用第一种方法。如果想要使用之前 Cloudflare 上面已经创建的数据库，可以选择自行配置 `wrangler.jsonc` 文件。
|
||||
|
||||
下面介绍第一种方法。
|
||||
|
||||
* **登录到 Cloudflare**
|
||||
```bash
|
||||
npx wrangler login
|
||||
```
|
||||
* **创建数据库和数据库表**，如果遇到提示，请按回车继续
|
||||
```bash
|
||||
npx wrangler d1 create CWD_DB
|
||||
npx wrangler d1 execute CWD_DB --remote --file=./schemas/comment.sql
|
||||
```
|
||||
运行完成后可以确认一下 `wrangler.jsonc` 中是否有如下配置
|
||||
```jsonc
|
||||
"d1_databases": [
|
||||
{
|
||||
"binding": "CWD_DB",
|
||||
"database_name": "CWD_DB",
|
||||
"database_id": "xxxxxx" // D1 数据库 ID
|
||||
}
|
||||
]
|
||||
```
|
||||
如果`binding`字段不是`CWD_DB`，请修改为`CWD_DB`
|
||||
* **创建 KV 存储**，如果遇到提示，按回车继续
|
||||
```bash
|
||||
npx wrangler kv namespace create CWD_AUTH_KV
|
||||
```
|
||||
运行完成后可以确认一下 `wrangler.jsonc` 中是否有如下配置
|
||||
```jsonc
|
||||
"kv_namespaces": [
|
||||
{
|
||||
"binding": "CWD_AUTH_KV",
|
||||
"id": "xxxxxxx" // KV 存储 ID
|
||||
}
|
||||
]
|
||||
```
|
||||
* **部署上线**
|
||||
```bash
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
没有异常报错后，可以进入Cloudflare Workers 面板查看是否部署成功，若显示存在一个名称为 `cwd-backend-worker` 的项目即推送成功。
|
||||
|
||||
#### 3. 配置环境变量
|
||||
|
||||
* 登录 Worker 面板，点击项目右侧的 Settings (设置) 选项卡，选择`查看设置`
|
||||
* 点击变量和机密右侧的添加按钮，给项目添加环境变量，环境变量[参考](#环境变量)
|
||||
* 部署生效：点击底部的 Save and deploy (保存并部署)。
|
||||
|
||||
#### 4. 检测部署情况
|
||||
|
||||
部署成功后回得到一个域名，即为后端的域名（格式一般为`https://cwd-backend-worker.xxx.workers.dev`。访问该域名，如果显示后端管理页面并可以正常登录则部署成功，将此域名填写到博客的配置文件中即可使用评论功能。
|
||||
|
||||
当然也可以使用自定义域名，注意不要使用三级域名，即`*.*.example.com`。
|
||||
|
||||
## 环境变量
|
||||
|
||||
所需环境变量如下表所示，请参考 [`.dev.vars.example`](.dev.vars.example) 文件
|
||||
|
||||
| 变量名 | 描述 |
|
||||
| ------------------- | -------------------------------------------------------------------------------- |
|
||||
| `ALLOW_ORIGIN` | 允许跨域请求的域名，用逗号分隔 |
|
||||
| `RESEND_API_KEY` | Resend API Key，用于启用邮件通知服务，如**果不需要邮件通知服务，可以不填** |
|
||||
| `RESEND_FROM_EMAIL` | Resend 发送邮件的邮箱，用于邮件通知服务，**如果不需要邮件通知服务，可以不填** |
|
||||
| `EMAIL_ADDRESS` | 管理员接收通知邮件的邮箱，用于邮件通知服务，**如果不需要邮件通知服务，可以不填** |
|
||||
| `ADMIN_NAME` | 管理员登录名称，默认为 admin |
|
||||
| `ADMIN_PASSWORD` | 管理员登录密码，默认密码为 password |
|
||||
|
||||
**注:** [Resend 官网](https://resend.com/)
|
||||
|
||||
|
||||
## 本地测试
|
||||
|
||||
如果需要本地测试，环境变量可以使用 `.dev.vars` 文件来设置
|
||||
|
||||
```bash
|
||||
cp .dev.vars.example .dev.vars
|
||||
# 编辑 .dev.vars 文件
|
||||
npm run dev
|
||||
```
|
||||
75
docs/guide/frontend-config.md
Normal file
75
docs/guide/frontend-config.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# 前端配置
|
||||
|
||||
**这里仅提供一套开箱即用的方案，如果是个人开发者可以根据 API 文档自行编写前端评论组件。**
|
||||
|
||||
[接口 API](../api/public.md)
|
||||
|
||||
## 初始化
|
||||
|
||||
在初始化 `CWDComments` 实例时，可以传入以下配置参数：
|
||||
|
||||
```html
|
||||
<script src="cwd-comments.js"></script>
|
||||
```
|
||||
|
||||
```html
|
||||
<script>
|
||||
const comments = new CWDComments({
|
||||
el: '#comments',
|
||||
apiBaseUrl: 'https://your-api.example.com',
|
||||
postSlug: 'my-post',
|
||||
postTitle: '文章标题',
|
||||
postUrl: 'https://example.com/my-post',
|
||||
theme: 'light',
|
||||
pageSize: 20,
|
||||
avatarPrefix: 'https://gravatar.com/avatar',
|
||||
adminEmail: 'admin@example.com',
|
||||
adminBadge: '博主'
|
||||
});
|
||||
comments.mount();
|
||||
</script>
|
||||
```
|
||||
|
||||
## 参数说明
|
||||
|
||||
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|
||||
| -------------- | ----------------------- | ---- | ----------------------------- | -------------------------- |
|
||||
| `el` | `string \| HTMLElement` | 是 | - | 挂载元素选择器或 DOM 元素 |
|
||||
| `apiBaseUrl` | `string` | 是 | - | API 基础地址 |
|
||||
| `postSlug` | `string` | 是 | - | 文章唯一标识符 |
|
||||
| `postTitle` | `string` | 否 | - | 文章标题，用于邮件通知 |
|
||||
| `postUrl` | `string` | 否 | - | 文章 URL，用于邮件通知 |
|
||||
| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 |
|
||||
| `pageSize` | `number` | 否 | `20` | 每页显示评论数 |
|
||||
| `avatarPrefix` | `string` | 否 | `https://gravatar.com/avatar` | 头像服务前缀 |
|
||||
| `adminEmail` | `string` | 否 | - | 博主邮箱，用于显示博主标识 |
|
||||
| `adminBadge` | `string` | 否 | `博主` | 博主标识文字 |
|
||||
|
||||
## 头像服务前缀
|
||||
|
||||
常用的 Gravatar 镜像服务：
|
||||
|
||||
| 服务 | 前缀地址 |
|
||||
| --------------- | -------------------------------- |
|
||||
| Gravatar 官方 | `https://gravatar.com/avatar` |
|
||||
| Cravatar (国内) | `https://cravatar.cn/avatar` |
|
||||
| 自定义镜像 | `https://your-mirror.com/avatar` |
|
||||
|
||||
## 实例方法
|
||||
|
||||
| 方法 | 说明 |
|
||||
| ---------------------- | ------------------------------ |
|
||||
| `mount()` | 挂载组件到 DOM |
|
||||
| `unmount()` | 卸载组件 |
|
||||
| `updateConfig(config)` | 更新配置（支持动态切换主题等） |
|
||||
| `getConfig()` | 获取当前配置 |
|
||||
|
||||
## 使用示例
|
||||
|
||||
```javascript
|
||||
// 动态切换主题
|
||||
comments.updateConfig({ theme: 'dark' });
|
||||
|
||||
// 切换文章
|
||||
comments.updateConfig({ postSlug: 'another-post' });
|
||||
```
|
||||
34
docs/guide/getting-started.md
Normal file
34
docs/guide/getting-started.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# 快速开始
|
||||
|
||||
## 简介
|
||||
|
||||
CWD 评论系统是一个基于 Cloudflare Workers 的轻量级评论解决方案，使用 Hono 框架构建，数据存储使用 Cloudflare D1（SQLite）和 KV。
|
||||
|
||||
## 特性
|
||||
|
||||
- ⚡️ **极速响应**：基于 Cloudflare 全球边缘网络
|
||||
- 🔒 **安全可靠**：内置管理员认证、CORS 保护
|
||||
- 📧 **邮件通知**：支持 Resend 邮件服务
|
||||
- 🎨 **易于集成**：提供完整的 REST API
|
||||
|
||||
## 前置要求
|
||||
|
||||
- Node.js 16+
|
||||
- Cloudflare 账号
|
||||
- Wrangler CLI
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
# 克隆项目
|
||||
git clone https://github.com/anghunk/cwd-comments
|
||||
cd cwd-comments
|
||||
|
||||
# 安装依赖
|
||||
npm install
|
||||
```
|
||||
|
||||
## 配置
|
||||
|
||||
- [后端配置](./backend-config.md)
|
||||
- [前端配置](./frontend-config.md)
|
||||
Reference in New Issue
Block a user