docs: 更新文档链接、添加favicon并完善API文档
- 更新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
@@ -4,6 +4,8 @@
|
|||||||
<head>
|
<head>
|
||||||
<meta charset="UTF-8" />
|
<meta charset="UTF-8" />
|
||||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||||
|
<link rel="shortcut icon" href="https://github.com/anghunk/cwd-comments/blob/main/icon.png?raw=true"
|
||||||
|
type="image/x-icon">
|
||||||
<title>CWD 评论系统后台</title>
|
<title>CWD 评论系统后台</title>
|
||||||
</head>
|
</head>
|
||||||
|
|
||||||
|
|||||||
@@ -3,6 +3,13 @@
|
|||||||
<header class="layout-header">
|
<header class="layout-header">
|
||||||
<div class="layout-title">CWD 评论后台</div>
|
<div class="layout-title">CWD 评论后台</div>
|
||||||
<div class="layout-actions">
|
<div class="layout-actions">
|
||||||
|
<a
|
||||||
|
class="layout-button"
|
||||||
|
href="https://cwd-comments-docs.zishu.me"
|
||||||
|
target="_blank"
|
||||||
|
>
|
||||||
|
文档
|
||||||
|
</a>
|
||||||
<a
|
<a
|
||||||
class="layout-button"
|
class="layout-button"
|
||||||
href="https://github.com/anghunk/cwd-comments"
|
href="https://github.com/anghunk/cwd-comments"
|
||||||
|
|||||||
@@ -1,10 +1,15 @@
|
|||||||
import { defineConfig } from 'vitepress'
|
import { defineConfig } from 'vitepress'
|
||||||
|
|
||||||
export default defineConfig({
|
export default defineConfig({
|
||||||
title: 'CWD 评论系统',
|
title: 'CWD 评论系统文档',
|
||||||
description: '基于 Cloudflare Workers 的轻量级评论系统文档',
|
description: '基于 Cloudflare Workers 的轻量级评论系统',
|
||||||
lang: 'zh-CN',
|
lang: 'zh-CN',
|
||||||
|
head: [
|
||||||
|
['link', {
|
||||||
|
rel: 'icon',
|
||||||
|
href: 'https://github.com/anghunk/cwd-comments/blob/main/icon.png?raw=true'
|
||||||
|
}]
|
||||||
|
],
|
||||||
themeConfig: {
|
themeConfig: {
|
||||||
nav: [
|
nav: [
|
||||||
{ text: '首页', link: '/' },
|
{ text: '首页', link: '/' },
|
||||||
|
|||||||
@@ -1,150 +1,433 @@
|
|||||||
# 管理员 API
|
# 管理员 API
|
||||||
|
|
||||||
所有管理员 API 都需要在请求头中携带 Bearer Token：
|
管理员接口用于登录后台、查看和管理评论、配置邮件通知和评论显示设置。
|
||||||
|
|
||||||
|
除登录接口外，所有管理员接口都需要在请求头中携带 Bearer Token。
|
||||||
|
|
||||||
```http
|
```http
|
||||||
Authorization: Bearer <token>
|
Authorization: Bearer <token>
|
||||||
```
|
```
|
||||||
|
|
||||||
## 管理员登录
|
Token 通过登录接口获取，有效期为 24 小时。
|
||||||
|
|
||||||
获取管理员 Token。
|
本节按 OpenAPI 风格描述每个接口的请求 / 响应结构，并补充鉴权和错误码说明。
|
||||||
|
|
||||||
### 请求
|
## POST /admin/login
|
||||||
|
|
||||||
```http
|
管理员登录，获取后续调用其他管理员接口所需的临时 Token。
|
||||||
POST /admin/login
|
|
||||||
Content-Type: application/json
|
- 方法：`POST`
|
||||||
```
|
- 路径：`/admin/login`
|
||||||
|
- 鉴权：不需要
|
||||||
|
|
||||||
|
### 请求头
|
||||||
|
|
||||||
|
| 名称 | 必填 | 示例 |
|
||||||
|
| -------------- | ---- | ------------------- |
|
||||||
|
| `Content-Type` | 是 | `application/json` |
|
||||||
|
|
||||||
### 请求体
|
### 请求体
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"username": "admin",
|
"name": "admin@example.com",
|
||||||
"password": "your_password"
|
"password": "your_password"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 响应示例
|
字段说明：
|
||||||
|
|
||||||
|
| 字段名 | 类型 | 必填 | 说明 |
|
||||||
|
| --------- | ------ | ---- | ------------------ |
|
||||||
|
| `name` | string | 是 | 管理员登录名 |
|
||||||
|
| `password`| string | 是 | 管理员登录密码 |
|
||||||
|
|
||||||
|
管理员登录名和密码由后端环境变量控制，字段为：
|
||||||
|
|
||||||
|
- `ADMIN_NAME`
|
||||||
|
- `ADMIN_PASSWORD`
|
||||||
|
|
||||||
|
### 成功响应
|
||||||
|
|
||||||
|
- 状态码：`200`
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"success": true,
|
|
||||||
"data": {
|
"data": {
|
||||||
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
"key": "f6e1e0e3-3c9b-4a24-9e88-3b1f709f1e4a"
|
||||||
"expiresIn": 604800
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## 获取评论管理列表
|
前端需要将 `data.key` 作为 Token 存储（例如 LocalStorage），并在后续请求中通过 `Authorization: Bearer <key>` 携带。
|
||||||
|
|
||||||
获取所有评论列表（包括待审核的评论）。
|
### 错误与风控
|
||||||
|
|
||||||
### 请求
|
- 登录失败（用户名或密码错误）：
|
||||||
|
|
||||||
```http
|
- 状态码：`401`
|
||||||
GET /admin/comments/list?page={page}&pageSize={pageSize}&status={status}
|
|
||||||
Authorization: Bearer <token>
|
|
||||||
```
|
|
||||||
|
|
||||||
### 参数
|
```json
|
||||||
|
{
|
||||||
|
"message": "Invalid username or password",
|
||||||
|
"failedAttempts": 3
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
- 登录失败次数过多导致 IP 被封禁：
|
||||||
| -------- | ------ | ---- | ----------------------------------- |
|
|
||||||
| page | number | 否 | 页码，默认 1 |
|
|
||||||
| pageSize | number | 否 | 每页数量，默认 20 |
|
|
||||||
| status | string | 否 | 状态筛选：pending/approved/rejected |
|
|
||||||
|
|
||||||
### 响应示例
|
- 状态码：`403`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "IP is blocked due to multiple failed login attempts"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 内部错误：
|
||||||
|
|
||||||
|
- 状态码：`500`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "错误信息"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## GET /admin/comments/list
|
||||||
|
|
||||||
|
获取评论列表，用于后台管理页面展示。
|
||||||
|
|
||||||
|
- 方法：`GET`
|
||||||
|
- 路径：`/admin/comments/list`
|
||||||
|
- 鉴权：需要（Bearer Token）
|
||||||
|
|
||||||
|
### 查询参数
|
||||||
|
|
||||||
|
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||||
|
| ------- | ----- | ------- | ---- | ----------------------- |
|
||||||
|
| `page` | query | integer | 否 | 页码，默认 `1` |
|
||||||
|
|
||||||
|
说明：
|
||||||
|
|
||||||
|
- 当前实现中每页固定大小为 `10`，暂不支持 `pageSize` 或状态过滤。
|
||||||
|
|
||||||
|
### 成功响应
|
||||||
|
|
||||||
|
- 状态码：`200`
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"success": true,
|
"data": [
|
||||||
"data": {
|
{
|
||||||
"comments": [
|
"id": 1,
|
||||||
{
|
"pubDate": "2026-01-13T10:00:00Z",
|
||||||
"id": 1,
|
"author": "张三",
|
||||||
"path": "/blog/hello-world",
|
"email": "zhangsan@example.com",
|
||||||
"author": "张三",
|
"postSlug": "/blog/hello-world",
|
||||||
"email": "zhangsan@example.com",
|
"url": "https://zhangsan.me",
|
||||||
"content": "很棒的文章！",
|
"ipAddress": "127.0.0.1",
|
||||||
"parent_id": null,
|
"contentText": "很棒的文章！",
|
||||||
"status": "pending",
|
"contentHtml": "很棒的文章！",
|
||||||
"created_at": "2026-01-13T10:00:00Z"
|
"status": "approved",
|
||||||
}
|
"avatar": "https://gravatar.com/avatar/..."
|
||||||
],
|
}
|
||||||
"total": 1,
|
],
|
||||||
|
"pagination": {
|
||||||
"page": 1,
|
"page": 1,
|
||||||
"pageSize": 20
|
"limit": 10,
|
||||||
|
"total": 1
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## 更新评论状态
|
### 鉴权错误
|
||||||
|
|
||||||
审核评论，更新评论状态。
|
- 未携带 Token 或 Token 失效：
|
||||||
|
|
||||||
### 请求
|
- 状态码：`401`
|
||||||
|
|
||||||
```http
|
```json
|
||||||
PUT /admin/comments/status
|
{
|
||||||
Authorization: Bearer <token>
|
"message": "Unauthorized"
|
||||||
Content-Type: application/json
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## PUT /admin/comments/status
|
||||||
|
|
||||||
|
更新评论状态（例如通过 / 拒绝）。
|
||||||
|
|
||||||
|
- 方法：`PUT`
|
||||||
|
- 路径：`/admin/comments/status`
|
||||||
|
- 鉴权：需要（Bearer Token）
|
||||||
|
|
||||||
|
### 查询参数
|
||||||
|
|
||||||
|
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||||
|
| -------- | ----- | ------ | ---- | -------------------------------- |
|
||||||
|
| `id` | query | number | 是 | 评论 ID |
|
||||||
|
| `status` | query | string | 是 | 评论状态，例如 `approved`、`rejected` |
|
||||||
|
|
||||||
|
当前实现中未对 `status` 值进行枚举校验，但推荐仅使用：
|
||||||
|
|
||||||
|
- `approved`：已通过
|
||||||
|
- `rejected`：已拒绝
|
||||||
|
|
||||||
|
### 成功响应
|
||||||
|
|
||||||
|
- 状态码：`200`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "Comment status updated, id: 1, status: approved."
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 错误响应
|
||||||
|
|
||||||
|
- 缺少参数：
|
||||||
|
|
||||||
|
- 状态码：`400`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "Missing id or status"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 更新失败：
|
||||||
|
|
||||||
|
- 状态码：`500`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "Update failed"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## DELETE /admin/comments/delete
|
||||||
|
|
||||||
|
删除指定评论。
|
||||||
|
|
||||||
|
- 方法：`DELETE`
|
||||||
|
- 路径：`/admin/comments/delete`
|
||||||
|
- 鉴权：需要（Bearer Token）
|
||||||
|
|
||||||
|
### 查询参数
|
||||||
|
|
||||||
|
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||||
|
| ---- | ----- | ------ | ---- | ------ |
|
||||||
|
| `id` | query | number | 是 | 评论 ID |
|
||||||
|
|
||||||
|
### 成功响应
|
||||||
|
|
||||||
|
- 状态码：`200`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "Comment deleted, id: 1."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 错误响应
|
||||||
|
|
||||||
|
- 缺少 ID：
|
||||||
|
|
||||||
|
- 状态码：`400`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "Missing id"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 删除失败：
|
||||||
|
|
||||||
|
- 状态码：`500`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "Delete operation failed"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## GET /admin/settings/email
|
||||||
|
|
||||||
|
获取当前通知邮箱配置。
|
||||||
|
|
||||||
|
- 方法：`GET`
|
||||||
|
- 路径：`/admin/settings/email`
|
||||||
|
- 鉴权：需要（Bearer Token）
|
||||||
|
|
||||||
|
### 成功响应
|
||||||
|
|
||||||
|
- 状态码：`200`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"email": "admin@example.com"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 错误响应
|
||||||
|
|
||||||
|
- 状态码：`500`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "错误信息"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## PUT /admin/settings/email
|
||||||
|
|
||||||
|
设置通知邮箱，用于接收新评论提醒。
|
||||||
|
|
||||||
|
- 方法：`PUT`
|
||||||
|
- 路径：`/admin/settings/email`
|
||||||
|
- 鉴权：需要（Bearer Token）
|
||||||
|
|
||||||
|
### 请求头
|
||||||
|
|
||||||
|
| 名称 | 必填 | 示例 |
|
||||||
|
| -------------- | ---- | ------------------- |
|
||||||
|
| `Content-Type` | 是 | `application/json` |
|
||||||
|
|
||||||
### 请求体
|
### 请求体
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"id": 1,
|
"email": "admin@example.com"
|
||||||
"status": "approved"
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 参数说明
|
### 成功响应
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
- 状态码：`200`
|
||||||
| ------ | ------ | ---- | ---------------------------------------- |
|
|
||||||
| id | number | 是 | 评论 ID |
|
|
||||||
| status | string | 是 | 状态：approved（通过）/ rejected（拒绝） |
|
|
||||||
|
|
||||||
### 响应示例
|
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"success": true,
|
"message": "保存成功"
|
||||||
"data": {
|
|
||||||
"message": "评论状态已更新"
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## 删除评论
|
### 错误响应
|
||||||
|
|
||||||
删除指定评论。
|
- 邮箱格式不正确：
|
||||||
|
|
||||||
### 请求
|
- 状态码：`400`
|
||||||
|
|
||||||
```http
|
```json
|
||||||
DELETE /admin/comments/delete?id={id}
|
{
|
||||||
Authorization: Bearer <token>
|
"message": "邮箱格式不正确"
|
||||||
```
|
}
|
||||||
|
```
|
||||||
|
|
||||||
### 参数
|
- 服务器错误：
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
- 状态码：`500`
|
||||||
|------|------|------|------|
|
|
||||||
| id | number | 是 | 评论 ID |
|
|
||||||
|
|
||||||
### 响应示例
|
```json
|
||||||
|
{
|
||||||
|
"message": "错误信息"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## GET /admin/settings/comments
|
||||||
|
|
||||||
|
获取评论配置，例如博主邮箱、徽标和头像前缀等。
|
||||||
|
|
||||||
|
- 方法：`GET`
|
||||||
|
- 路径：`/admin/settings/comments`
|
||||||
|
- 鉴权：需要（Bearer Token）
|
||||||
|
|
||||||
|
### 成功响应
|
||||||
|
|
||||||
|
- 状态码：`200`
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"success": true,
|
"adminEmail": "admin@example.com",
|
||||||
"data": {
|
"adminBadge": "博主",
|
||||||
"message": "评论已删除"
|
"avatarPrefix": "https://gravatar.com/avatar",
|
||||||
}
|
"adminEnabled": true
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
字段说明与公开接口 `/api/config/comments` 一致。
|
||||||
|
|
||||||
|
### 错误响应
|
||||||
|
|
||||||
|
- 状态码：`500`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "加载评论配置失败"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## PUT /admin/settings/comments
|
||||||
|
|
||||||
|
更新评论配置。
|
||||||
|
|
||||||
|
- 方法：`PUT`
|
||||||
|
- 路径：`/admin/settings/comments`
|
||||||
|
- 鉴权：需要（Bearer Token）
|
||||||
|
|
||||||
|
### 请求头
|
||||||
|
|
||||||
|
| 名称 | 必填 | 示例 |
|
||||||
|
| -------------- | ---- | ------------------- |
|
||||||
|
| `Content-Type` | 是 | `application/json` |
|
||||||
|
|
||||||
|
### 请求体
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"adminEmail": "admin@example.com",
|
||||||
|
"adminBadge": "站长",
|
||||||
|
"avatarPrefix": "https://cravatar.cn/avatar",
|
||||||
|
"adminEnabled": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
字段说明：
|
||||||
|
|
||||||
|
| 字段名 | 类型 | 必填 | 说明 |
|
||||||
|
| -------------- | ------- | ---- | ------------------------------------------------ |
|
||||||
|
| `adminEmail` | string | 否 | 博主邮箱地址，需为合法邮箱 |
|
||||||
|
| `adminBadge` | string | 否 | 博主标识文字，例如 `"博主"` |
|
||||||
|
| `avatarPrefix` | string | 否 | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 |
|
||||||
|
| `adminEnabled` | boolean | 否 | 是否启用博主标识相关功能 |
|
||||||
|
|
||||||
|
### 成功响应
|
||||||
|
|
||||||
|
- 状态码：`200`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "保存成功"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 错误响应
|
||||||
|
|
||||||
|
- 邮箱格式错误：
|
||||||
|
|
||||||
|
- 状态码：`400`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "邮箱格式不正确"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 内部错误：
|
||||||
|
|
||||||
|
- 状态码：`500`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "保存失败"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|||||||
@@ -2,47 +2,102 @@
|
|||||||
|
|
||||||
## 基础信息
|
## 基础信息
|
||||||
|
|
||||||
- **Base URL**: `https://your-worker.workers.dev`
|
- **Base URL**：`https://your-worker.workers.dev` 或你的自定义域名
|
||||||
- **数据格式**: JSON
|
- **数据格式**：JSON
|
||||||
- **字符编码**: UTF-8
|
- **字符编码**：UTF-8
|
||||||
|
|
||||||
## 认证方式
|
所有 API 均为 RESTful 风格，无会话 Cookie，认证全部通过 `Authorization` 请求头完成。
|
||||||
|
|
||||||
管理员 API 需要使用 Bearer Token 认证：
|
## 版本信息
|
||||||
|
|
||||||
|
当前后端版本号在根路径返回：
|
||||||
|
|
||||||
|
```http
|
||||||
|
GET /
|
||||||
|
```
|
||||||
|
|
||||||
|
成功时返回 HTML，其中包含类似文案：
|
||||||
|
|
||||||
|
```text
|
||||||
|
CWD 评论部署成功，当前版本 v0.0.1
|
||||||
|
```
|
||||||
|
|
||||||
|
说明：
|
||||||
|
|
||||||
|
- 当前 API 路径未在 URL 中显式区分版本（如 `/v1`），版本号仅通过根路径展示。
|
||||||
|
- 后续若引入不兼容变更，建议通过自定义域名路径前缀或 Worker 路由实现接口版本化，例如：
|
||||||
|
- `https://comments-api.example.com/v1`
|
||||||
|
- `https://api.example.com/comments/v1`
|
||||||
|
|
||||||
|
## 鉴权方式
|
||||||
|
|
||||||
|
公开接口与管理员接口的鉴权要求不同：
|
||||||
|
|
||||||
|
- 公开接口（Public API）
|
||||||
|
- `/api/comments`
|
||||||
|
- `/api/config/comments`
|
||||||
|
- 默认无需认证，可直接访问。
|
||||||
|
- 管理员接口（Admin API）
|
||||||
|
- 路径前缀：`/admin/*`
|
||||||
|
- 除 `/admin/login` 外，其余接口都需要携带管理员 Token。
|
||||||
|
|
||||||
|
管理员接口需要使用 Bearer Token 认证：
|
||||||
|
|
||||||
```http
|
```http
|
||||||
Authorization: Bearer <token>
|
Authorization: Bearer <token>
|
||||||
```
|
```
|
||||||
|
|
||||||
Token 通过登录接口获取，有效期为 24 小时。
|
Token 通过登录接口获取，有效期为 24 小时，服务端会在 KV 中存储会话信息并在每次请求时进行校验。
|
||||||
|
|
||||||
## 响应格式
|
## 统一字段与约定
|
||||||
|
|
||||||
### 成功响应
|
虽然当前实现没有使用统一的 `success` 包装字段，但存在一些通用约定：
|
||||||
|
|
||||||
```json
|
- 错误响应：
|
||||||
{
|
- 始终包含 `message` 字段，描述错误原因。
|
||||||
"success": true,
|
- HTTP 状态码用于表达错误类型（例如 400/401/403/429/500）。
|
||||||
"data": { ... }
|
- 列表类响应：
|
||||||
}
|
- 使用 `data` + `pagination` 结构：
|
||||||
```
|
|
||||||
|
|
||||||
### 错误响应
|
```json
|
||||||
|
{
|
||||||
|
"data": [ /* 列表数据 */ ],
|
||||||
|
"pagination": {
|
||||||
|
"page": 1,
|
||||||
|
"limit": 20,
|
||||||
|
"total": 5,
|
||||||
|
"totalCount": 100
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
```json
|
- 单项结果或配置类响应：
|
||||||
{
|
- 直接返回对象，例如：
|
||||||
"success": false,
|
|
||||||
"error": "错误信息"
|
```json
|
||||||
}
|
{
|
||||||
```
|
"email": "admin@example.com"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 操作类响应（创建、更新、删除）：
|
||||||
|
- 一般返回 `{ "message": "说明文本" }`。
|
||||||
|
|
||||||
## HTTP 状态码
|
## HTTP 状态码
|
||||||
|
|
||||||
| 状态码 | 说明 |
|
常见状态码及含义如下：
|
||||||
| ------ | ------------ |
|
|
||||||
| 200 | 请求成功 |
|
| 状态码 | 说明 | 典型场景 |
|
||||||
| 400 | 请求参数错误 |
|
| ------ | -------------------------- | ---------------------------------------------------- |
|
||||||
| 401 | 未授权 |
|
| 200 | 请求成功 | 正常查询、操作成功 |
|
||||||
| 403 | 禁止访问 |
|
| 400 | 请求参数错误 | 缺少必填字段、格式不正确等 |
|
||||||
| 404 | 资源不存在 |
|
| 401 | 未授权 | 未携带 Token 或 Token 失效 |
|
||||||
| 500 | 服务器错误 |
|
| 403 | 禁止访问 | 登录失败次数过多导致 IP 被暂时封禁 |
|
||||||
|
| 404 | 资源不存在（当前未显式使用）| 预留给未来可能的资源不存在场景 |
|
||||||
|
| 429 | 请求过于频繁 | 评论频率超过限制（默认同一 IP 10 秒内只能评论一次） |
|
||||||
|
| 500 | 服务器内部错误 | 未捕获异常、数据库错误等 |
|
||||||
|
|
||||||
|
具体到每个接口的详细请求 / 响应体和错误码，请参考：
|
||||||
|
|
||||||
|
- [公开 API](./public.md)
|
||||||
|
- [管理员 API](./admin.md)
|
||||||
|
|||||||
@@ -1,90 +1,262 @@
|
|||||||
# 公开 API
|
# 公开 API
|
||||||
|
|
||||||
## 获取评论列表
|
本节描述无需认证即可访问的公开接口，包括评论获取、评论提交以及评论设置获取。
|
||||||
|
|
||||||
获取指定页面的评论列表。
|
遵循 OpenAPI 风格进行组织，包含路径、方法、参数、请求体和响应示例。
|
||||||
|
|
||||||
### 请求
|
## GET /api/comments
|
||||||
|
|
||||||
```http
|
获取指定文章的评论列表。
|
||||||
GET /api/comments?path={path}&page={page}&pageSize={pageSize}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 参数
|
- 方法：`GET`
|
||||||
|
- 路径：`/api/comments`
|
||||||
|
- 鉴权：不需要
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
### 查询参数
|
||||||
| -------- | ------ | ---- | ----------------- |
|
|
||||||
| path | string | 是 | 页面路径 |
|
|
||||||
| page | number | 否 | 页码，默认 1 |
|
|
||||||
| pageSize | number | 否 | 每页数量，默认 10 |
|
|
||||||
|
|
||||||
### 响应示例
|
| 名称 | 位置 | 类型 | 必填 | 说明 |
|
||||||
|
| -------------- | ------ | ------- | ---- | -------------------------------------------------------------------- |
|
||||||
|
| `post_slug` | query | string | 是 | 文章唯一标识符，与前端配置中的 `postSlug` 保持一致 |
|
||||||
|
| `page` | query | integer | 否 | 页码，默认 `1` |
|
||||||
|
| `limit` | query | integer | 否 | 每页数量，默认 `20`，最大 `50` |
|
||||||
|
| `nested` | query | string | 否 | 是否返回嵌套结构，默认 `'true'` |
|
||||||
|
| `avatar_prefix`| query | string | 否 | 覆盖头像地址前缀，优先级高于服务端设置和前端配置 |
|
||||||
|
|
||||||
|
### 成功响应
|
||||||
|
|
||||||
|
- 状态码：`200`
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"success": true,
|
"data": [
|
||||||
"data": {
|
{
|
||||||
"comments": [
|
"id": 1,
|
||||||
{
|
"author": "张三",
|
||||||
"id": 1,
|
"email": "zhangsan@example.com",
|
||||||
"path": "/blog/hello-world",
|
"url": "https://example.com",
|
||||||
"author": "张三",
|
"contentText": "很棒的文章！",
|
||||||
"email": "zhangsan@example.com",
|
"contentHtml": "很棒的文章！",
|
||||||
"content": "很棒的文章！",
|
"pubDate": "2026-01-13T10:00:00Z",
|
||||||
"parent_id": null,
|
"postSlug": "/blog/hello-world",
|
||||||
"status": "approved",
|
"avatar": "https://gravatar.com/avatar/...",
|
||||||
"created_at": "2026-01-13T10:00:00Z",
|
"replies": [
|
||||||
"avatar": "https://gravatar.com/avatar/..."
|
{
|
||||||
}
|
"id": 2,
|
||||||
],
|
"author": "李四",
|
||||||
"total": 1,
|
"email": "lisi@example.com",
|
||||||
|
"url": null,
|
||||||
|
"contentText": "同感！",
|
||||||
|
"contentHtml": "同感！",
|
||||||
|
"pubDate": "2026-01-13T11:00:00Z",
|
||||||
|
"postSlug": "/blog/hello-world",
|
||||||
|
"avatar": "https://gravatar.com/avatar/...",
|
||||||
|
"parentId": 1,
|
||||||
|
"replyToAuthor": "张三"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"pagination": {
|
||||||
"page": 1,
|
"page": 1,
|
||||||
"pageSize": 10
|
"limit": 20,
|
||||||
|
"total": 1,
|
||||||
|
"totalCount": 2
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## 提交评论
|
说明：
|
||||||
|
|
||||||
提交新评论。
|
- 当 `nested=true`（默认）时，接口返回的是“根评论列表”，每条根评论包含其 `replies`。
|
||||||
|
- 当 `nested=false` 时，接口返回扁平列表，所有评论都在 `data` 中，`replies` 为空。
|
||||||
|
|
||||||
### 请求
|
### 错误响应
|
||||||
|
|
||||||
```http
|
- 缺少 `post_slug`：
|
||||||
POST /api/comments
|
|
||||||
Content-Type: application/json
|
|
||||||
```
|
|
||||||
|
|
||||||
### 请求体
|
- 状态码：`400`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "post_slug is required"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 服务器内部错误：
|
||||||
|
|
||||||
|
- 状态码：`500`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "错误信息"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## POST /api/comments
|
||||||
|
|
||||||
|
提交新评论或回复。
|
||||||
|
|
||||||
|
- 方法：`POST`
|
||||||
|
- 路径：`/api/comments`
|
||||||
|
- 鉴权：不需要
|
||||||
|
|
||||||
|
### 请求头
|
||||||
|
|
||||||
|
| 名称 | 必填 | 示例 |
|
||||||
|
| -------------- | ---- | ---------------------------- |
|
||||||
|
| `Content-Type` | 是 | `application/json` |
|
||||||
|
|
||||||
|
### 请求体（Request Body）
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"path": "/blog/hello-world",
|
"post_slug": "/blog/hello-world",
|
||||||
|
"post_title": "博客标题，可选",
|
||||||
|
"post_url": "https://example.com/blog/hello-world",
|
||||||
"author": "张三",
|
"author": "张三",
|
||||||
"email": "zhangsan@example.com",
|
"email": "zhangsan@example.com",
|
||||||
|
"url": "https://zhangsan.me",
|
||||||
"content": "很棒的文章！",
|
"content": "很棒的文章！",
|
||||||
"parent_id": null
|
"parent_id": 1
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 参数说明
|
#### 字段说明
|
||||||
|
|
||||||
| 参数 | 类型 | 必填 | 说明 |
|
| 字段名 | 类型 | 必填 | 说明 |
|
||||||
| --------- | ------ | ---- | ----------------------- |
|
| ------------ | ------ | ---- | ------------------------------------------------------------ |
|
||||||
| path | string | 是 | 页面路径 |
|
| `post_slug` | string | 是 | 文章唯一标识符，应与前端组件初始化时的 `postSlug` 值一致 |
|
||||||
| author | string | 是 | 评论者昵称 |
|
| `post_title` | string | 否 | 文章标题，用于邮件通知内容 |
|
||||||
| email | string | 是 | 评论者邮箱 |
|
| `post_url` | string | 否 | 文章 URL，用于邮件通知中的跳转链接 |
|
||||||
| content | string | 是 | 评论内容 |
|
| `author` | string | 是 | 评论者昵称 |
|
||||||
| parent_id | number | 否 | 父评论 ID（回复时使用） |
|
| `email` | string | 是 | 评论者邮箱，需为合法邮箱格式 |
|
||||||
|
| `url` | string | 否 | 评论者个人主页或站点地址 |
|
||||||
|
| `content` | string | 是 | 评论内容，内部会过滤 `<script>...</script>` 片段 |
|
||||||
|
| `parent_id` | number | 否 | 父评论 ID，用于回复功能；缺省或 `null` 表示根评论 |
|
||||||
|
|
||||||
### 响应示例
|
### 成功响应
|
||||||
|
|
||||||
|
- 状态码：`200`
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"success": true,
|
"message": "Comment submitted. Awaiting moderation."
|
||||||
"data": {
|
}
|
||||||
"id": 1,
|
```
|
||||||
"message": "评论提交成功，等待审核"
|
|
||||||
}
|
当前实现中评论会直接以 `approved` 状态写入数据库，后续如引入人工审核可在实现中调整为“待审核”状态。
|
||||||
|
|
||||||
|
### 错误响应与限流
|
||||||
|
|
||||||
|
- 请求体缺失或字段类型错误：
|
||||||
|
|
||||||
|
- 状态码：`400`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "无效的请求体"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 缺少必填字段示例：
|
||||||
|
|
||||||
|
- `post_slug` 为空：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "post_slug 必填"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `content` 为空：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "评论内容不能为空"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `author` 为空：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "昵称不能为空"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- `email` 为空或格式不正确：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "邮箱不能为空"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
或
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "邮箱格式不正确"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 评论频率限制：
|
||||||
|
|
||||||
|
- 状态码：`429`
|
||||||
|
- 逻辑：同一 IP 最近一条评论时间在 10 秒内，则拒绝此次请求。
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "评论频繁，等10s后再试"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 服务器内部错误：
|
||||||
|
|
||||||
|
- 状态码：`500`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "Internal Server Error"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## GET /api/config/comments
|
||||||
|
|
||||||
|
获取评论相关的公开配置，用于前端组件读取博主邮箱、徽标等信息。
|
||||||
|
|
||||||
|
- 方法：`GET`
|
||||||
|
- 路径：`/api/config/comments`
|
||||||
|
- 鉴权：不需要
|
||||||
|
|
||||||
|
### 成功响应
|
||||||
|
|
||||||
|
- 状态码：`200`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"adminEmail": "admin@example.com",
|
||||||
|
"adminBadge": "博主",
|
||||||
|
"avatarPrefix": "https://gravatar.com/avatar",
|
||||||
|
"adminEnabled": true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
字段说明：
|
||||||
|
|
||||||
|
| 字段名 | 类型 | 说明 |
|
||||||
|
| -------------- | ------- | ------------------------------------------------ |
|
||||||
|
| `adminEmail` | string | 博主邮箱地址，用于在前端展示“博主”标识 |
|
||||||
|
| `adminBadge` | string | 博主标识文字，例如 `"博主"` |
|
||||||
|
| `avatarPrefix` | string | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 |
|
||||||
|
| `adminEnabled` | boolean | 是否启用博主标识相关功能 |
|
||||||
|
|
||||||
|
### 错误响应
|
||||||
|
|
||||||
|
- 状态码：`500`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "加载评论配置失败"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|||||||
@@ -6,6 +6,8 @@
|
|||||||
* 拥有一个 Node.js 运行环境，版本 >= 22（本地部署需要）
|
* 拥有一个 Node.js 运行环境，版本 >= 22（本地部署需要）
|
||||||
* 拥有一个域名并托管在 Cloudflare 上（这个不是必须项，但可以提高国内访问速度，也更方便）
|
* 拥有一个域名并托管在 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` | 管理员登录名称 |
|
| `CWD_DB` | D1 绑定 | 评论数据存储数据库 |
|
||||||
| `ADMIN_PASSWORD` | 管理员登录密码 |
|
| `CWD_AUTH_KV` | KV 绑定 | 管理员登录 Token、登录尝试计数等 |
|
||||||
| `CF_FROM_EMAIL` | 作为发件人显示的邮箱地址（需在 Cloudflare Email 路由中预先配置）选填 |
|
| `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()` 直接发信。
|
**注：** 需要在 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:*`）做过滤和告警。
|
||||||
|
- 在调试阶段可以保留日志，生产环境如需减少日志量，可根据需要在代码中调整输出。
|
||||||
|
|||||||
@@ -2,42 +2,190 @@
|
|||||||
|
|
||||||
**这里仅提供一套开箱即用的方案，如果是个人开发者可以根据 API 文档自行编写前端评论组件。**
|
**这里仅提供一套开箱即用的方案，如果是个人开发者可以根据 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
|
```html
|
||||||
|
<script src="https://static.example.com/cwd-comments/cwd-comments.js"></script>
|
||||||
|
<div id="comments"></div>
|
||||||
<script>
|
<script>
|
||||||
const comments = new CWDComments({
|
const comments = new CWDComments({
|
||||||
el: '#comments', // 容器 id
|
el: '#comments',
|
||||||
apiBaseUrl: 'https://your-api.example.com', // 你部署的 api 地址
|
apiBaseUrl: 'https://your-api.example.com',
|
||||||
postSlug: 'https://example.com/my-post', // 当前页面路径，可使用博客程序支持的 url 模板路径，或者直接使用 window.location.origin
|
postSlug: 'https://example.com/my-post'
|
||||||
});
|
});
|
||||||
comments.mount();
|
comments.mount();
|
||||||
</script>
|
</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 元素 |
|
| `el` | `string \| HTMLElement` | 是 | - | 挂载元素选择器或 DOM 元素 |
|
||||||
| `apiBaseUrl` | `string` | 是 | - | API 基础地址 |
|
| `apiBaseUrl` | `string` | 是 | - | API 基础地址 |
|
||||||
| `postSlug` | `string` | 是 | - | 文章唯一标识符 |
|
| `postSlug` | `string` | 是 | - | 文章唯一标识符 |
|
||||||
| `postTitle` | `string` | 否 | - | 文章标题，用于邮件通知 |
|
| `postTitle` | `string` | 否 | 页面标题或 `postSlug` | 文章标题，用于邮件通知 |
|
||||||
| `postUrl` | `string` | 否 | - | 文章 URL，用于邮件通知 |
|
| `postUrl` | `string` | 否 | 当前页面 URL | 文章 URL，用于邮件通知 |
|
||||||
| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 |
|
| `theme` | `'light' \| 'dark'` | 否 | `'light'` | 主题模式 |
|
||||||
| `pageSize` | `number` | 否 | `20` | 每页显示评论数 |
|
| `pageSize` | `number` | 否 | `20` | 每页显示评论数 |
|
||||||
| `avatarPrefix` | `string` | 否 | `https://gravatar.com/avatar` | 头像服务前缀 |
|
| `avatarPrefix` | `string` | 否 | `https://gravatar.com/avatar` | 头像服务前缀 |
|
||||||
| `adminEmail` | `string` | 否 | - | 博主邮箱，用于显示博主标识 |
|
| `adminEmail` | `string` | 否 | - | 博主邮箱，用于显示博主标识 |
|
||||||
| `adminBadge` | `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 镜像服务：
|
||||||
|
|||||||
File diff suppressed because one or more lines are too long
@@ -2,4 +2,4 @@
|
|||||||
|
|
||||||
## 使用方法
|
## 使用方法
|
||||||
|
|
||||||
文档：[https://cwd-comments.zishu.me/guide/frontend-config.html](https://cwd-comments.zishu.me/guide/frontend-config.html)
|
文档：https://cwd-comments-docs.zishu.me/guide/frontend-config.html
|
||||||
|
|||||||
Reference in New Issue
Block a user