From 23c27d956250d3b615b529095dcff84a937e3a1b Mon Sep 17 00:00:00 2001
From: anghunk <anghunk@gmail.com>
Date: Tue, 20 Jan 2026 17:06:33 +0800
Subject: [PATCH] =?UTF-8?q?feat(admin):=20=E6=B7=BB=E5=8A=A0=E7=AE=A1?=
 =?UTF-8?q?=E7=90=86=E5=91=98=E8=AF=84=E8=AE=BA=E5=AF=86=E9=92=A5=E5=8A=9F?=
 =?UTF-8?q?=E8=83=BD=E5=92=8C=E5=AE=89=E5=85=A8=E8=AE=BE=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 在管理后台添加管理员评论密钥设置，前台管理员评论需验证
- 新增安全设置区块，包含允许调用域名和管理员密钥配置
- 更新相关API文档和前端配置说明
- 调整评论配置接口返回字段，增加密钥相关字段
---
 cwd-comments-admin/src/views/SettingsView.vue |  3 +-
 docs/.vitepress/config.mjs                    |  1 +
 docs/api/admin.md                             | 36 +++++++++++++------
 docs/api/public.md                            | 20 ++++++-----
 docs/function/admin-panel.md                  |  8 +++++
 docs/guide/frontend-config.md                 |  7 ++++
 6 files changed, 54 insertions(+), 21 deletions(-)

diff --git a/cwd-comments-admin/src/views/SettingsView.vue b/cwd-comments-admin/src/views/SettingsView.vue
index ef0c42f..ed4132f 100644
--- a/cwd-comments-admin/src/views/SettingsView.vue
+++ b/cwd-comments-admin/src/views/SettingsView.vue
@@ -31,8 +31,9 @@
           <label class="form-label">头像前缀（默认：https://gravatar.com/avatar）</label>
           <input v-model="avatarPrefix" class="form-input" type="text" />
         </div>
+        <h3 class="card-title">安全设置</h3>
         <div class="form-item">
-          <label class="form-label">允许调用的域名（多个域名用逗号分隔，留空则不限制）</label>
+          <label class="form-label">允许调用的域名（多个域名用逗号分隔，留空则不限制。设置后仅匹配域名可调用前台评论组件。）</label>
           <textarea
             v-model="allowedDomains"
             class="form-input"
diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs
index 4cebc4e..ecb0518 100644
--- a/docs/.vitepress/config.mjs
+++ b/docs/.vitepress/config.mjs
@@ -4,6 +4,7 @@ export default defineConfig({
 	title: 'CWD 评论系统文档',
 	description: '基于 Cloudflare Workers 的轻量级评论系统',
 	lang: 'zh-CN',
+	outline: [2, 3],
 	head: [
 		[
 			'link',
diff --git a/docs/api/admin.md b/docs/api/admin.md
index 905eb85..5f19477 100644
--- a/docs/api/admin.md
+++ b/docs/api/admin.md
@@ -432,7 +432,7 @@ Token 通过登录接口获取，有效期为 24 小时。
 
 ## GET /admin/settings/comments
 
-获取评论配置，例如博主邮箱、徽标和头像前缀等。
+获取评论配置，例如博主邮箱、徽标、头像前缀、管理员密钥等。
 
 - 方法：`GET`
 - 路径：`/admin/settings/comments`
@@ -448,11 +448,23 @@ Token 通过登录接口获取，有效期为 24 小时。
 	"adminBadge": "博主",
 	"avatarPrefix": "https://gravatar.com/avatar",
 	"adminEnabled": true,
-	"allowedDomains": []
+	"allowedDomains": [],
+	"adminKey": "your-admin-key",
+	"adminKeySet": true
 }
 ```
 
-字段说明与公开接口 `/api/config/comments` 一致。
+字段说明（相比公开接口 `/api/config/comments` 增加了管理员密钥相关字段）：
+
+| 字段名         | 类型    | 说明                                                     |
+| -------------- | ------- | -------------------------------------------------------- |
+| `adminEmail`   | string  | 博主邮箱地址，用于显示“博主”标识以及管理员身份验证     |
+| `adminBadge`   | string  | 博主标识文字，例如 `"博主"`                              |
+| `avatarPrefix` | string  | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址          |
+| `adminEnabled` | boolean | 是否启用博主标识相关展示                                 |
+| `allowedDomains` | Array\<string\> | 允许调用组件的域名列表，留空则不限制           |
+| `adminKey`     | string\|null | 管理员评论密钥（明文），仅通过管理后台接口返回 |
+| `adminKeySet`  | boolean | 是否已经设置过管理员评论密钥                            |
 
 ### 错误响应
 
@@ -486,19 +498,21 @@ Token 通过登录接口获取，有效期为 24 小时。
 	"adminBadge": "站长",
 	"avatarPrefix": "https://cravatar.cn/avatar",
 	"adminEnabled": true,
-	"allowedDomains": []
+	"allowedDomains": [],
+	"adminKey": "your-admin-key"
 }
 ```
 
 字段说明：
 
-| 字段名           | 类型    | 必填 | 说明                                           |
-| ---------------- | ------- | ---- | ---------------------------------------------- |
-| `adminEmail`     | string  | 否   | 博主邮箱地址，需为合法邮箱                     |
-| `adminBadge`     | string  | 否   | 博主标识文字，例如 `"博主"`                    |
-| `avatarPrefix`   | string  | 否   | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址 |
-| `adminEnabled`   | boolean | 否   | 是否启用博主标识相关功能                       |
-| `allowedDomains` | Array   | 否   | 是否允许前端调用的域名                         |
+| 字段名           | 类型    | 必填 | 说明                                                                 |
+| ---------------- | ------- | ---- | -------------------------------------------------------------------- |
+| `adminEmail`     | string  | 否   | 博主邮箱地址，需为合法邮箱                                           |
+| `adminBadge`     | string  | 否   | 博主标识文字，例如 `"博主"`                                          |
+| `avatarPrefix`   | string  | 否   | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址                       |
+| `adminEnabled`   | boolean | 否   | 是否启用博主标识相关展示                                             |
+| `allowedDomains` | Array   | 否   | 允许前端调用组件的域名列表                                           |
+| `adminKey`       | string  | 否   | 管理员评论密钥，留空则表示清除密钥；设置后前台管理员评论需输入密钥 |
 
 ### 成功响应
 
diff --git a/docs/api/public.md b/docs/api/public.md
index 0f051e7..d2fca93 100644
--- a/docs/api/public.md
+++ b/docs/api/public.md
@@ -112,7 +112,7 @@
   "post_slug": "https://example.com/blog/hello-world",
   "post_title": "博客标题，可选",
   "post_url": "https://example.com/blog/hello-world",
-  "author": "张三",
+  "name": "张三",
   "email": "zhangsan@example.com",
   "url": "https://zhangsan.me",
   "content": "很棒的文章！",
@@ -127,7 +127,7 @@
 | `post_slug`  | string | 是   | 文章唯一标识符，应与前端组件初始化时的 `postSlug` 值一致，`window.location.origin + window.location.pathname` |
 | `post_title` | string | 否   | 文章标题，用于邮件通知内容                                                                                    |
 | `post_url`   | string | 否   | 文章 URL，用于邮件通知中的跳转链接                                                                            |
-| `author`     | string | 是   | 评论者昵称                                                                                                    |
+| `name`       | string | 是   | 评论者昵称                                                                                                    |
 | `email`      | string | 是   | 评论者邮箱，需为合法邮箱格式                                                                                  |
 | `url`        | string | 否   | 评论者个人主页或站点地址                                                                                      |
 | `content`    | string | 是   | 评论内容，内部会过滤 `<script>...</script>` 片段                                                              |
@@ -237,18 +237,20 @@
   "adminEmail": "admin@example.com",
   "adminBadge": "博主",
   "avatarPrefix": "https://gravatar.com/avatar",
-  "adminEnabled": true
+  "adminEnabled": true,
+  "allowedDomains": []
 }
 ```
 
 字段说明：
 
-| 字段名         | 类型    | 说明                                             |
-| -------------- | ------- | ------------------------------------------------ |
-| `adminEmail`   | string  | 博主邮箱地址，用于在前端展示“博主”标识          |
-| `adminBadge`   | string  | 博主标识文字，例如 `"博主"`                      |
-| `avatarPrefix` | string  | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址  |
-| `adminEnabled` | boolean | 是否启用博主标识相关功能                         |
+| 字段名         | 类型    | 说明                                                                 |
+| -------------- | ------- | -------------------------------------------------------------------- |
+| `adminEmail`   | string  | 博主邮箱地址，用于在前端展示“博主”标识，并触发管理员身份验证流程   |
+| `adminBadge`   | string  | 博主标识文字，例如 `"博主"`                                          |
+| `avatarPrefix` | string  | 头像地址前缀，如 Gravatar 或 Cravatar 镜像地址                      |
+| `adminEnabled` | boolean | 是否启用博主标识相关展示（关闭时不显示徽标，但仍可作为管理员邮箱） |
+| `allowedDomains` | Array\<string\> | 允许调用组件的域名列表，留空则不限制                         |
 
 ### 错误响应
 
diff --git a/docs/function/admin-panel.md b/docs/function/admin-panel.md
index 785c74e..afb04b0 100644
--- a/docs/function/admin-panel.md
+++ b/docs/function/admin-panel.md
@@ -18,6 +18,14 @@
 
 开启是否显示博主标签，配置博主邮箱和标签文字，即可在评论中显示博主标签；关闭为不显示。
 
+### 允许调用的域名
+
+多个域名用逗号分隔，留空则不限制。设置后仅匹配域名可调用前台评论组件。
+
+### 管理员评论密钥
+
+设置后前台使用管理员邮箱评论需输入此密钥。
+
 ### 邮箱提醒服务
 
 目前接入了 QQ 邮箱提醒，后续会添加其他邮箱服务。
diff --git a/docs/guide/frontend-config.md b/docs/guide/frontend-config.md
index 532a757..5533eb4 100644
--- a/docs/guide/frontend-config.md
+++ b/docs/guide/frontend-config.md
@@ -29,6 +29,13 @@
 
 头像前缀、博主邮箱和标识等信息由后端接口 `/api/config/comments` 提供，无需在前端进行配置。
 
+当 `/admin/settings/comments` 中配置了“评论博主邮箱”时：
+
+- 前台组件会将该邮箱视为“管理员邮箱”；
+- 使用该邮箱发表评论时，会在邮箱输入框失焦后触发“管理员身份验证”弹窗；
+- 验证通过后，会在浏览器本地保存一次管理员密钥（仅用于本机后续请求携带 `adminToken`）；
+- 后端会在 `/api/comments` 中校验此密钥，确保管理员身份的评论需要额外验证。
+
 ## 实例方法
 
 | 方法                   | 说明                           |