docs: add cloudflare analytics env setup guide

README.md

@@ -80,6 +80,12 @@ yarn build
 
 > For detailed steps on configuring GitHub and Google OIDC authentication, please refer to the [OIDC Authentication Guide](./docs/integrations/oidc-auth.md).
 
+## 统计配置 (Homepage Stats Configuration)
+
+首页“注册用户数 / 访问量”所需 Cloudflare 变量说明，请参阅 [Cloudflare Web Analytics 集成配置](./docs/integrations/cloudflare-web-analytics.md)。
+
+> For Cloudflare variables used by homepage stats, see the [Cloudflare Web Analytics integration guide](./docs/integrations/cloudflare-web-analytics.md).
+
 ## 开发指南 (Development Guidelines)
 
 有关详细的编码标准、架构规则和 Agent 特定说明，请参阅 [AGENTS.md](./AGENTS.md)。

docs/README.md

@@ -46,6 +46,7 @@ This directory follows a standard open-source documentation layout and mirrors t
 - Integrations
   - `integrations/databases.md`
   - `integrations/cloud.md`
+  - `integrations/cloudflare-web-analytics.md`
   - `integrations/ai-providers.md`
 - Advanced
   - `advanced/performance.md`

docs/integrations/cloudflare-web-analytics.md

@@ -0,0 +1,80 @@
+# Cloudflare Web Analytics 集成配置
+
+本页说明首页统计接口 `/api/marketing/home-stats` 依赖的 3 个 Cloudflare 环境变量如何获取，以及应配置到哪里。
+
+## 需要的环境变量
+
+```bash
+CLOUDFLARE_API_TOKEN=
+CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_WEB_ANALYTICS_SITE_TAG=
+```
+
+## 变量获取方式
+
+### 1) `CLOUDFLARE_API_TOKEN`
+
+用途：服务端调用 Cloudflare GraphQL API 读取访问量。
+
+获取路径：
+
+1. 打开 Cloudflare 控制台，右上角头像 -> **My Profile**
+2. 进入 **API Tokens**
+3. 点击 **Create Token**
+4. 建议创建仅只读 token，至少包含：**Account Analytics:Read**（作用域限定到目标 Account）
+5. 复制生成后的 token（只显示一次）
+
+### 2) `CLOUDFLARE_ACCOUNT_ID`
+
+用途：GraphQL 查询时定位账号。
+
+获取方式（任选其一）：
+
+- 在 Cloudflare 控制台 URL 中，账号路径段通常就是 account id。
+- 在账号总览页面（Overview）侧边栏/页面信息中复制 Account ID。
+
+### 3) `CLOUDFLARE_WEB_ANALYTICS_SITE_TAG`
+
+用途：定位具体 Web Analytics 站点。
+
+获取方式（任选其一）：
+
+- 你当前这类链接中可直接看到：
+  `.../web-analytics/overview?siteTag~in=<SITE_TAG>&excludeBots=Yes`
+  其中 `<SITE_TAG>` 就是变量值。
+- 在 Cloudflare Web Analytics 的站点设置/安装脚本中，`siteTag`（或 beacon token）即对应值。
+
+## 配置写入位置
+
+### 本地开发
+
+写入 `console.svc.plus/.env.local`：
+
+```bash
+CLOUDFLARE_API_TOKEN=...
+CLOUDFLARE_ACCOUNT_ID=...
+CLOUDFLARE_WEB_ANALYTICS_SITE_TAG=...
+```
+
+### 线上部署
+
+把同名变量写入 `console.svc.plus` 的部署环境（例如 Vercel/Cloud Run 的环境变量配置）。
+
+> 注意：这些变量属于服务端密钥，不要暴露到 `NEXT_PUBLIC_*`。
+
+## 联调验证
+
+部署后访问：
+
+```bash
+curl -fsSL https://console.svc.plus/api/marketing/home-stats
+```
+
+期望返回中 `visits.daily/weekly/monthly` 为数字（非 `null`）。
+
+如果是 `null`，优先检查：
+
+1. token 权限是否包含 Analytics Read
+2. Account ID 是否与 siteTag 属于同一账号
+3. 环境变量是否已在当前运行实例生效（重启/重新部署后再测）
+