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
2026-01-20 09:51:55 +08:00
parent 2c3eb7a063
commit 9b90f589d5
11 changed files with 1034 additions and 185 deletions
--- a/cwd-comments-admin/index.html
+++ b/cwd-comments-admin/index.html
@@ -4,6 +4,8 @@
 <head>
 	<meta charset="UTF-8" />
 	<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>
 </head>

--- a/cwd-comments-admin/src/views/LayoutView.vue
+++ b/cwd-comments-admin/src/views/LayoutView.vue
@@ -3,6 +3,13 @@
    <header class="layout-header">
      <div class="layout-title">CWD 评论后台</div>
      <div class="layout-actions">
+        <a
+          class="layout-button"
+          href="https://cwd-comments-docs.zishu.me"
+          target="_blank"
+        >
+          文档
+        </a>
        <a
          class="layout-button"
          href="https://github.com/anghunk/cwd-comments"
--- a/docs/.vitepress/config.mjs
+++ b/docs/.vitepress/config.mjs
@@ -1,10 +1,15 @@
 import { defineConfig } from 'vitepress'

 export default defineConfig({
-  title: 'CWD 评论系统',
-  description: '基于 Cloudflare Workers 的轻量级评论系统文档',
+  title: 'CWD 评论系统文档',
+  description: '基于 Cloudflare Workers 的轻量级评论系统',
  lang: 'zh-CN',
-
+  head: [
+    ['link', {
+      rel: 'icon',
+      href: 'https://github.com/anghunk/cwd-comments/blob/main/icon.png?raw=true'
+    }]
+  ],
  themeConfig: {
    nav: [
      { text: '首页', link: '/' },
--- a/docs/api/admin.md
+++ b/docs/api/admin.md
@@ -1,150 +1,433 @@
 # 管理员 API

-所有管理员 API 都需要在请求头中携带 Bearer Token：
+管理员接口用于登录后台、查看和管理评论、配置邮件通知和评论显示设置。
+
+除登录接口外，所有管理员接口都需要在请求头中携带 Bearer Token。

 ```http
 Authorization: Bearer <token>
 ```

-## 管理员登录
+Token 通过登录接口获取，有效期为 24 小时。

-获取管理员 Token。
+本节按 OpenAPI 风格描述每个接口的请求 / 响应结构，并补充鉴权和错误码说明。

-### 请求
+## POST /admin/login

-```http
-POST /admin/login
-Content-Type: application/json
-```
+管理员登录，获取后续调用其他管理员接口所需的临时 Token。
+
+- 方法：`POST`
+- 路径：`/admin/login`
+- 鉴权：不需要
+
+### 请求头
+
+| 名称           | 必填 | 示例                |
+| -------------- | ---- | ------------------- |
+| `Content-Type` | 是   | `application/json` |

 ### 请求体

 ```json
 {
-  "username": "admin",
+  "name": "admin@example.com",
  "password": "your_password"
 }
 ```

-### 响应示例
+字段说明：
+
+| 字段名    | 类型   | 必填 | 说明               |
+| --------- | ------ | ---- | ------------------ |
+| `name`    | string | 是   | 管理员登录名       |
+| `password`| string | 是   | 管理员登录密码     |
+
+管理员登录名和密码由后端环境变量控制，字段为：
+
+- `ADMIN_NAME`
+- `ADMIN_PASSWORD`
+
+### 成功响应
+
+- 状态码：`200`

 ```json
 {
-  "success": true,
  "data": {
-    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
-    "expiresIn": 604800
+    "key": "f6e1e0e3-3c9b-4a24-9e88-3b1f709f1e4a"
  }
 }
 ```

-## 获取评论管理列表
+前端需要将 `data.key` 作为 Token 存储（例如 LocalStorage），并在后续请求中通过 `Authorization: Bearer <key>` 携带。

-获取所有评论列表（包括待审核的评论）。
+### 错误与风控

-### 请求
+- 登录失败（用户名或密码错误）：

-```http
-GET /admin/comments/list?page={page}&pageSize={pageSize}&status={status}
-Authorization: Bearer <token>
-```
+  - 状态码：`401`

-### 参数
+  ```json
+  {
+    "message": "Invalid username or password",
+    "failedAttempts": 3
+  }
+  ```

-| 参数     | 类型   | 必填 | 说明                                |
-| -------- | ------ | ---- | ----------------------------------- |
-| page     | number | 否   | 页码，默认 1                        |
-| pageSize | number | 否   | 每页数量，默认 20                   |
-| status   | string | 否   | 状态筛选：pending/approved/rejected |
+- 登录失败次数过多导致 IP 被封禁：

-### 响应示例
+  - 状态码：`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
 {
-  "success": true,
-  "data": {
-    "comments": [
-      {
-        "id": 1,
-        "path": "/blog/hello-world",
-        "author": "张三",
-        "email": "zhangsan@example.com",
-        "content": "很棒的文章！",
-        "parent_id": null,
-        "status": "pending",
-        "created_at": "2026-01-13T10:00:00Z"
-      }
-    ],
-    "total": 1,
+  "data": [
+    {
+      "id": 1,
+      "pubDate": "2026-01-13T10:00:00Z",
+      "author": "张三",
+      "email": "zhangsan@example.com",
+      "postSlug": "/blog/hello-world",
+      "url": "https://zhangsan.me",
+      "ipAddress": "127.0.0.1",
+      "contentText": "很棒的文章！",
+      "contentHtml": "很棒的文章！",
+      "status": "approved",
+      "avatar": "https://gravatar.com/avatar/..."
+    }
+  ],
+  "pagination": {
    "page": 1,
-    "pageSize": 20
+    "limit": 10,
+    "total": 1
  }
 }
 ```

-## 更新评论状态
+### 鉴权错误

-审核评论，更新评论状态。
+- 未携带 Token 或 Token 失效：

-### 请求
+  - 状态码：`401`

-```http
-PUT /admin/comments/status
-Authorization: Bearer <token>
-Content-Type: application/json
+  ```json
+  {
+    "message": "Unauthorized"
+  }
+  ```
+
+## 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
 {
-  "id": 1,
-  "status": "approved"
+  "email": "admin@example.com"
 }
 ```

-### 参数说明
+### 成功响应

-| 参数   | 类型   | 必填 | 说明                                     |
-| ------ | ------ | ---- | ---------------------------------------- |
-| id     | number | 是   | 评论 ID                                  |
-| status | string | 是   | 状态：approved（通过）/ rejected（拒绝） |
-
-### 响应示例
+- 状态码：`200`

 ```json
 {
-  "success": true,
-  "data": {
-    "message": "评论状态已更新"
-  }
+  "message": "保存成功"
 }
 ```

-## 删除评论
+### 错误响应

-删除指定评论。
+- 邮箱格式不正确：

-### 请求
+  - 状态码：`400`

-```http
-DELETE /admin/comments/delete?id={id}
-Authorization: Bearer <token>
-```
+  ```json
+  {
+    "message": "邮箱格式不正确"
+  }
+  ```

-### 参数
+- 服务器错误：

-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| id | number | 是 | 评论 ID |
+  - 状态码：`500`

-### 响应示例
+  ```json
+  {
+    "message": "错误信息"
+  }
+  ```
+
+## GET /admin/settings/comments
+
+获取评论配置，例如博主邮箱、徽标和头像前缀等。
+
+- 方法：`GET`
+- 路径：`/admin/settings/comments`
+- 鉴权：需要（Bearer Token）
+
+### 成功响应
+
+- 状态码：`200`

 ```json
 {
-  "success": true,
-  "data": {
-    "message": "评论已删除"
-  }
+  "adminEmail": "admin@example.com",
+  "adminBadge": "博主",
+  "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": "保存失败"
+  }
+  ```
--- a/docs/api/overview.md
+++ b/docs/api/overview.md
@@ -2,47 +2,102 @@

 ## 基础信息

- **Base URL**: `https://your-worker.workers.dev`
- **数据格式**: JSON
- **字符编码**: UTF-8
+- **Base URL**：`https://your-worker.workers.dev` 或你的自定义域名
+- **数据格式**：JSON
+- **字符编码**：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
 Authorization: Bearer <token>
 ```

-Token 通过登录接口获取，有效期为 24 小时。
+Token 通过登录接口获取，有效期为 24 小时，服务端会在 KV 中存储会话信息并在每次请求时进行校验。

-## 响应格式
+## 统一字段与约定

-### 成功响应
+虽然当前实现没有使用统一的 `success` 包装字段，但存在一些通用约定：

-```json
-{
-  "success": true,
-  "data": { ... }
-}
-```
+- 错误响应：
+  - 始终包含 `message` 字段，描述错误原因。
+  - HTTP 状态码用于表达错误类型（例如 400/401/403/429/500）。
+- 列表类响应：
+  - 使用 `data` + `pagination` 结构：

-### 错误响应
+    ```json
+    {
+      "data": [ /* 列表数据 */ ],
+      "pagination": {
+        "page": 1,
+        "limit": 20,
+        "total": 5,
+        "totalCount": 100
+      }
+    }
+    ```

-```json
-{
-  "success": false,
-  "error": "错误信息"
-}
-```
+- 单项结果或配置类响应：
+  - 直接返回对象，例如：
+
+    ```json
+    {
+      "email": "admin@example.com"
+    }
+    ```
+
+- 操作类响应（创建、更新、删除）：
+  - 一般返回 `{ "message": "说明文本" }`。

 ## HTTP 状态码

-| 状态码 | 说明         |
-| ------ | ------------ |
-| 200    | 请求成功     |
-| 400    | 请求参数错误 |
-| 401    | 未授权       |
-| 403    | 禁止访问     |
-| 404    | 资源不存在   |
-| 500    | 服务器错误   |
+常见状态码及含义如下：
+
+| 状态码 | 说明                       | 典型场景                                             |
+| ------ | -------------------------- | ---------------------------------------------------- |
+| 200    | 请求成功                   | 正常查询、操作成功                                   |
+| 400    | 请求参数错误               | 缺少必填字段、格式不正确等                           |
+| 401    | 未授权                     | 未携带 Token 或 Token 失效                           |
+| 403    | 禁止访问                   | 登录失败次数过多导致 IP 被暂时封禁                   |
+| 404    | 资源不存在（当前未显式使用）| 预留给未来可能的资源不存在场景                      |
+| 429    | 请求过于频繁               | 评论频率超过限制（默认同一 IP 10 秒内只能评论一次） |
+| 500    | 服务器内部错误             | 未捕获异常、数据库错误等                             |
+
+具体到每个接口的详细请求 / 响应体和错误码，请参考：
+
+- [公开 API](./public.md)
+- [管理员 API](./admin.md)
--- a/docs/api/public.md
+++ b/docs/api/public.md
@@ -1,90 +1,262 @@
 # 公开 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
 {
-  "success": true,
-  "data": {
-    "comments": [
-      {
-        "id": 1,
-        "path": "/blog/hello-world",
-        "author": "张三",
-        "email": "zhangsan@example.com",
-        "content": "很棒的文章！",
-        "parent_id": null,
-        "status": "approved",
-        "created_at": "2026-01-13T10:00:00Z",
-        "avatar": "https://gravatar.com/avatar/..."
-      }
-    ],
-    "total": 1,
+  "data": [
+    {
+      "id": 1,
+      "author": "张三",
+      "email": "zhangsan@example.com",
+      "url": "https://example.com",
+      "contentText": "很棒的文章！",
+      "contentHtml": "很棒的文章！",
+      "pubDate": "2026-01-13T10:00:00Z",
+      "postSlug": "/blog/hello-world",
+      "avatar": "https://gravatar.com/avatar/...",
+      "replies": [
+        {
+          "id": 2,
+          "author": "李四",
+          "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,
-    "pageSize": 10
+    "limit": 20,
+    "total": 1,
+    "totalCount": 2
  }
 }
 ```

-## 提交评论
+说明：

-提交新评论。
+- 当 `nested=true`（默认）时，接口返回的是“根评论列表”，每条根评论包含其 `replies`。
+- 当 `nested=false` 时，接口返回扁平列表，所有评论都在 `data` 中，`replies` 为空。

-### 请求
+### 错误响应

-```http
-POST /api/comments
-Content-Type: application/json
-```
+- 缺少 `post_slug`：

-### 请求体
+  - 状态码：`400`
+
+  ```json
+  {
+    "message": "post_slug is required"
+  }
+  ```
+
+- 服务器内部错误：
+
+  - 状态码：`500`
+
+  ```json
+  {
+    "message": "错误信息"
+  }
+  ```
+
+## POST /api/comments
+
+提交新评论或回复。
+
+- 方法：`POST`
+- 路径：`/api/comments`
+- 鉴权：不需要
+
+### 请求头
+
+| 名称           | 必填 | 示例                         |
+| -------------- | ---- | ---------------------------- |
+| `Content-Type` | 是   | `application/json`          |
+
+### 请求体（Request Body）

 ```json
 {
-  "path": "/blog/hello-world",
+  "post_slug": "/blog/hello-world",
+  "post_title": "博客标题，可选",
+  "post_url": "https://example.com/blog/hello-world",
  "author": "张三",
  "email": "zhangsan@example.com",
+  "url": "https://zhangsan.me",
  "content": "很棒的文章！",
-  "parent_id": null
+  "parent_id": 1
 }
 ```

-### 参数说明
+#### 字段说明

-| 参数      | 类型   | 必填 | 说明                    |
-| --------- | ------ | ---- | ----------------------- |
-| path      | string | 是   | 页面路径                |
-| author    | string | 是   | 评论者昵称              |
-| email     | string | 是   | 评论者邮箱              |
-| content   | string | 是   | 评论内容                |
-| parent_id | number | 否   | 父评论 ID（回复时使用） |
+| 字段名       | 类型   | 必填 | 说明                                                         |
+| ------------ | ------ | ---- | ------------------------------------------------------------ |
+| `post_slug`  | string | 是   | 文章唯一标识符，应与前端组件初始化时的 `postSlug` 值一致    |
+| `post_title` | string | 否   | 文章标题，用于邮件通知内容                                   |
+| `post_url`   | string | 否   | 文章 URL，用于邮件通知中的跳转链接                           |
+| `author`     | string | 是   | 评论者昵称                                                   |
+| `email`      | string | 是   | 评论者邮箱，需为合法邮箱格式                                 |
+| `url`        | string | 否   | 评论者个人主页或站点地址                                     |
+| `content`    | string | 是   | 评论内容，内部会过滤 `<script>...</script>` 片段             |
+| `parent_id`  | number | 否   | 父评论 ID，用于回复功能；缺省或 `null` 表示根评论           |

-### 响应示例
+### 成功响应
+
+- 状态码：`200`

 ```json
 {
-  "success": true,
-  "data": {
-    "id": 1,
-    "message": "评论提交成功，等待审核"
-  }
+  "message": "Comment submitted. Awaiting moderation."
+}
+```
+
+当前实现中评论会直接以 `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": "加载评论配置失败"
 }
 ```
--- a/docs/guide/backend-config.md
+++ b/docs/guide/backend-config.md
@@ -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:*`）做过滤和告警。
+- 在调试阶段可以保留日志，生产环境如需减少日志量，可根据需要在代码中调整输出。
--- a/docs/guide/frontend-config.md
+++ b/docs/guide/frontend-config.md
@@ -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 镜像服务：
--- a/docs/public/cwd-comments.js
+++ b/docs/public/cwd-comments.js
--- a/icon.png
+++ b/icon.png
--- a/widget/README.md
+++ b/widget/README.md
@@ -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