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

- 修复文档中的格式问题和错误
- 新增功能文档:数据迁移和管理后台
- 调整文档目录结构,将管理后台移至功能分类
- 更新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

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`(默认已配置好)