81 lines
2.1 KiB
Markdown
81 lines
2.1 KiB
Markdown
# 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. 环境变量是否已在当前运行实例生效（重启/重新部署后再测）
|
||
|