docs: 补充多站点数据隔离的配置和API文档

- 在站点隔离配置文档中详细说明 siteId 的使用方法和注意事项 - 为公开API接口添加 siteId 查询参数和请求头说明 - 更新前端配置文档，明确 siteId 为可选参数并说明默认值 - 修正常见问题中的表述和格式问题
2026-02-09 15:00:19 +08:00
parent 386bcfdeab
commit 3b429bf82c
6 changed files with 125 additions and 8 deletions
--- a/docs/api/public/analytics.md
+++ b/docs/api/public/analytics.md
@@ -30,6 +30,13 @@ POST /api/analytics/visit
 }
 ```

+**请求头**
+
+| 名称           | 必填 | 示例                         |
+| -------------- | ---- | ---------------------------- |
+| `Content-Type` | 是   | `application/json`          |
+| `X-Site-Id`    | 否   | `blog`                       |
+
 字段说明：

 | 字段名      | 类型   | 必填 | 说明                                                                 |
@@ -38,6 +45,12 @@ POST /api/analytics/visit
 | `postTitle` | string | 否   | 文章标题，用于后台展示页面名称                                        |
 | `postUrl`   | string | 否   | 文章 URL，用于后台展示页面链接和域名统计                              |

+**请求头说明：**
+
+| 名称       | 必填 | 说明                       |
+| ---------- | ---- | -------------------------- |
+| `X-Site-Id` | 否   | 站点 ID，用于多站点数据隔离，默认 `default` |
+
 **成功响应**

 - 状态码：`200`
--- a/docs/api/public/comments.md
+++ b/docs/api/public/comments.md
@@ -19,6 +19,7 @@ GET /api/comments
 | 名称        | 位置  | 类型    | 必填 | 说明                                       |
 | ----------- | ----- | ------- | ---- | ------------------------------------------ |
 | `post_slug` | query | string  | 是   | 文章 slug，与前端 `CWDComments` 的 `postSlug` 参数对应 |
+| `siteId`    | query | string  | 否   | 站点 ID，用于多站点数据隔离，默认 `default` |
 | `page`      | query | integer | 否   | 页码，默认 `1`                             |
 | `limit`     | query | integer | 否   | 每页数量，默认 `20`，最大 `50`             |
 | `nested`    | query | string  | 否   | 是否返回嵌套结构，默认 `'true'`            |
@@ -136,6 +137,13 @@ POST /api/comments
 | -------------- | ---- | ---------------------------- |
 | `Content-Type` | 是   | `application/json`          |

+**请求头**
+
+| 名称           | 必填 | 示例                         |
+| -------------- | ---- | ---------------------------- |
+| `Content-Type` | 是   | `application/json`          |
+| `X-Site-Id`    | 否   | `blog`                       |
+
 **请求体（Request Body）**

 ```json
@@ -160,12 +168,18 @@ POST /api/comments
 | `post_title` | string | 否   | 文章标题，用于邮件通知内容                                             |
 | `post_url`   | string | 否   | 文章完整 URL，用于邮件通知中的跳转链接                                  |
 | `name`       | string | 是   | 评论者昵称                                                           |
-| `email`      | string | | 是   | 评论者邮箱，需为合法邮箱格式                                         |
+| `email`      | string | 是   | 评论者邮箱，需为合法邮箱格式                                         |
 | `url`        | string | 否   | 评论者个人主页或站点地址                                             |
 | `content`    | string | 是   | 评论内容，内部会过滤 `<script>...</script>` 片段                     |
 | `parent_id`  | number | 否   | 父评论 ID，用于回复功能；缺省或 `null` 表示根评论                    |
 | `adminToken` | string | 否   | 管理员评论密钥，博主发布评论时需要先通过 `/api/verify-admin` 验证密钥后将密钥传入此字段，评论将直接通过且不受审核设置影响 |

+**请求头说明：**
+
+| 名称       | 必填 | 说明                       |
+| ---------- | ---- | -------------------------- |
+| `X-Site-Id` | 否   | 站点 ID，用于多站点数据隔离，默认 `default` |
+
 **成功响应**

 - 状态码：`200`
--- a/docs/api/public/config.md
+++ b/docs/api/public/config.md
@@ -14,6 +14,12 @@ GET /api/config/comments
 - 路径：`/api/config/comments`
 - 鉴权：不需要

+**查询参数**
+
+| 名称     | 位置  | 类型   | 必填 | 说明                       |
+| -------- | ----- | ------ | ---- | -------------------------- |
+| `siteId` | query | string | 否   | 站点 ID，用于多站点数据隔离，默认 `default` |
+
 **成功响应**

 - 状态码：`200`
--- a/docs/common-problems.md
+++ b/docs/common-problems.md
@@ -1,11 +1,11 @@
 # 常见问题

-## 1. 为什么设置完 siteId 后，评论区没有显示评论数据？
+## 1. 为什么设置完 siteId 后，评论区不显示旧的评论数据？

 因为设置了 siteId 后，接口会根据 siteId 来查询数据库带有你设置的 siteId 的评论数据。所以如果设置了 siteId，旧数据就有可能不显示，需要手动去 Cloudflare D1 控制台 Query 运行 SQL 语句来更新数据。

- `abc`: 你要设置的 siteId
- `example.com`: 查找包含指定域名的评论数据
+- `abc` 你要设置的 siteId
+- `example.com` 查找包含指定域名的评论数据

 ```sql
 UPDATE Comment
--- a/docs/config/site-isolation.md
+++ b/docs/config/site-isolation.md
@@ -1,9 +1,92 @@
 # 站点隔离

-配置支持站点数据隔离。
+CWD 评论系统支持通过 `siteId` 参数实现多站点数据隔离。当你需要为多个不同的网站或博客使用同一套评论系统后端时，可以通过 `siteId` 来区分不同站点的评论数据。

-通过前端实例调用时进行配置：
+## 功能说明

+- **数据隔离**：每个 `siteId` 对应独立的评论数据，不同站点的评论互不干扰
+- **统一管理**：所有站点共用同一个后端 API 和管理后台，通过 siteId 进行区分
+
+## 前端配置
+
+在初始化评论组件时，通过 `siteId` 参数指定站点标识：
+
+```html
+<div id="comments"></div>
+<script src="https://unpkg.com/cwd-widget@0.0.x/dist/cwd.js"></script>
+
+<script>
+	const comments = new CWDComments({
+		el: '#comments',
+		apiBaseUrl: 'https://your-api.example.com',
+		siteId: 'blog', // 站点 ID，例如：blog, docs, forum
+	});
+	comments.mount();
+</script>
 ```

-```
+### 参数说明
+
+| 参数      | 类型   | 必填 | 说明                       |
+| --------- | ------ | ---- | -------------------------- |
+| `siteId`  | string | 否   | 站点标识符，用于隔离不同站点的评论数据 |
+
+### siteId 命名建议
+
+- 使用小写字母、数字和连字符，如 `blog`、`docs`、`my-site-1`
+- 避免使用特殊字符和空格
+- 建议使用有意义的名称，便于识别不同站点
+
+## API 调用
+
+当使用站点隔离功能时，所有公开 API 请求都需要在查询参数中携带 `siteId`：
+
+```javascript
+// 获取评论列表
+GET /api/comments?post_slug=hello-world&siteId=blog
+
+// 提交评论
+POST /api/comments
+{
+  "post_slug": "hello-world",
+  "name": "张三",
+  "email": "zhangsan@example.com",
+  "content": "很棒的文章！"
+}
+// 请求头：X-Site-Id: blog
+
+// 获取配置
+GET /api/config/comments?siteId=blog
+```
+
+## 多站点示例
+
+如果你有多个站点，可以为每个站点配置不同的 `siteId`：
+
+```html
+<!-- 博客站点 -->
+<div id="blog-comments"></div>
+<script>
+	const blogComments = new CWDComments({
+		el: '#blog-comments',
+		apiBaseUrl: 'https://your-api.example.com',
+		siteId: 'blog',
+	});
+	blogComments.mount();
+</script>
+
+<!-- 文档站点 -->
+<div id="docs-comments"></div>
+<script>
+	const docsComments = new CWDComments({
+		el: '#docs-comments',
+		apiBaseUrl: 'https://your-api.example.com',
+		siteId: 'docs',
+	});
+	docsComments.mount();
+</script>
+```
+
+## 注意事项
+
+[为什么设置完 siteId 后，评论区不显示旧的评论数据？](/common-problems.html#_1-为什么设置完-siteid-后-评论区不显示旧的评论数据)
--- a/docs/guide/frontend-config.md
+++ b/docs/guide/frontend-config.md
@@ -28,7 +28,7 @@ CWD 评论组件采用 **Shadow DOM** 技术构建，基于独立根节点渲染
 	const comments = new CWDComments({
 		el: '#comments',
 		apiBaseUrl: 'https://your-api.example.com', // 换成你的 API 地址
-		siteId: 'your-site-id', // 换成你的站点 ID（关键词），比如 blog
+		siteId: 'blog', // 换成你的站点 ID（可选），如需多站点隔离请配置
 	});
 	comments.mount();
 </script>
@@ -52,6 +52,7 @@ https://cwd.js.org/cwd.js
 | -------------- | ----------------------- | ---- | --------- | ---------------------------------------- |
 | `el`           | `string \| HTMLElement` | 是   | -         | 挂载元素选择器或 DOM 元素                |
 | `apiBaseUrl`   | `string`                | 是   | -         | API 基础地址                             |
+| `siteId`       | `string`                | 否   | `default` | 站点 ID，用于多站点数据隔离              |
 | `theme`        | `'light' \| 'dark'`     | 否   | `'light'` | 主题模式                                 |
 | `pageSize`     | `number`                | 否   | `20`      | 每页显示评论数                           |
 | `customCssUrl` | `string`                | 否   | -         | 自定义样式表 URL，追加到 Shadow DOM 底部 |