Sink 访问分析与近实时视图:基于 Cloudflare Analytics Engine 的配置、原理与实战指南
Sink 访问分析与近实时视图:基于 Cloudflare Analytics Engine 的配置、原理与实战指南
本文基于 Sink 官方文档 docs/features/analytics.md 编写,并结合仓库源码(
server/api/stats/*、server/utils/access-log.ts、server/utils/analytics-sql.ts、app/composables/useRealtimeLogs.ts等)对底层实现进行纵深解读。
Sink 是一个完全运行在 Cloudflare 上的开源短链服务。本篇技术指南围绕其访问分析(Analytics)与近实时(Realtime)视图展开,说明如何在 Sink 中启用并配置这套统计能力,理解计数器、图表、热力图、最近事件与地理位置等数据从何而来,以及如何筛选、排除机器人并导出 CSV。读完本文,你将掌握 Sink 分析功能的完整配置流程、可观测数据的含义、近实时页面的工作原理,以及统计导出 API 的调用方式。
一、分析功能是可选能力
Sink 的访问分析是**可选(optional)**功能。这一点在源码与配置层面均有体现:
- 未配置分析功能时,短链、登录、链接管理依旧正常工作;
- 唯一的差别是仪表盘中的图表、日志和近实时视图为空(empty)。
也就是说,分析模块是叠加在核心短链能力之上的旁路能力,是否启用完全由部署者的 Cloudflare 配置决定,不会影响主流程可用性。这与 Sink 将写入逻辑放在 collectAccessLog / writeAccessLog(见 server/utils/access-log.ts)中、并在缺少 ANALYTICS 绑定时静默返回的设计是一致的:没有绑定就什么都不写,绝不阻塞跳转。
二、启用分析的三个必要条件(缺一不可)
启用分析需要同时满足以下三个条件。文档明确指出:"If any one is missing or mismatched, analytics stays empty."——任何一项缺失或名称不一致,分析数据就会一直为空。
2.1 Analytics Engine 绑定(名称必须是 ANALYTICS)
- Workers 部署:通常由部署配置自动创建,默认数据集名为
sink; - Pages 部署:手动添加——Settings → Bindings → Add → Analytics Engine;
- 变量名(Variable name):必须是
ANALYTICS; - 数据集(Dataset):默认
sink。如果你设置了NUXT_DATASET环境变量,则此处必须使用相同的名称。
绑定名与运行时配置必须严格对齐。Sink 在 collectAccessLog 中正是通过 cloudflare.env.ANALYTICS 读取该绑定(见 server/utils/access-log.ts),一旦绑定缺失或名称不一致,analytics 为 undefined,写入逻辑直接返回。
2.2 账户 ID(NUXT_CF_ACCOUNT_ID)
将 NUXT_CF_ACCOUNT_ID 设置为承载本应用的 Cloudflare 账户 ID:
- 获取方式:Cloudflare 仪表盘侧边栏的账户名,或登录后浏览器 URL 中可见的账户标识。
该变量在 nuxt.config.ts 中声明为 cfAccountId: '',运行时通过 useRuntimeConfig(event).cfAccountId 读取(见 server/utils/cloudflare.ts)。它是调用 Cloudflare Analytics Engine SQL API 时 URL 路径的一部分:
https://api.cloudflare.com/client/v4/accounts/${cfAccountId}/analytics_engine/sql
2.3 API 令牌(NUXT_CF_API_TOKEN)
将 NUXT_CF_API_TOKEN 设置为加密密钥(secret),创建方式:
- Cloudflare 仪表盘 → 右上角头像 → My Profile → API Tokens → Create Token → Custom Token;
- 权限(Permission)仅需:Account → Account Analytics → Read;
- 建议将令牌限制到承载本应用的同一账户(最小权限原则)。
该令牌在查询时通过 Authorization: Bearer ${cfApiToken} 请求头传给 Cloudflare API(见 server/utils/cloudflare.ts)。注意:如果 cfAccountId 或 cfApiToken 任一为空,useWAE 会直接返回 { data: [] },即查询静默降级为空结果。
2.4 配置项速查表
| 配置项 | 环境变量 | 默认值 | 作用 |
|---|---|---|---|
| Analytics 绑定 | ANALYTICS(绑定名) |
无 | Workers 读取写入数据点;Pages 需手动绑定 |
| 数据集名 | NUXT_DATASET |
sink |
查询与写入使用的 Analytics Engine 数据集 |
| 账户 ID | NUXT_CF_ACCOUNT_ID |
'' |
用于构造 AE SQL API 请求地址 |
| API 令牌 | NUXT_CF_API_TOKEN |
'' |
Bearer 认证,权限仅需 Account Analytics Read |
| 机器人日志开关 | NUXT_DISABLE_BOT_ACCESS_LOG |
false |
为 true 时从统计与 Webhook 排除机器人 |
以上默认值均可在 nuxt.config.ts 的 runtimeConfig 中核实。
三、能看到什么:数据维度与筛选能力
启用后,**成功的访问(successful visits)**会进入以下可视化与数据载体:
- 计数器(counters):访问量、访客数、来源数;
- 图表(charts):按分钟 / 小时 / 天聚合的时间序列;
- 热力图(heatmap):星期 × 小时的热力分布;
- 最近事件(recent events):最新点击明细;
- 地理位置(locations):国家 / 地区 / 城市分布。
所有可视化均支持按以下维度筛选(filter):
- 链接(link)
- 时间(time)
- 国家/地区(country / region / city)
- 浏览器(browser、browserType)
- 系统(os)
- 设备(device、deviceType)
- 来源(referer)
这些筛选维度在源码中体现为 shared/schemas/query.ts 的 QuerySchema:除 id(对应 AE 索引 index1,即链接 ID)与 startAt / endAt 时间范围外,其余字段逐一映射到写入数据点时的 blob 列。buildAnalyticsFilter(见 server/utils/query-filter.ts)会把每个维度转换为 AE SQL 的 IN (...) 条件,并对 timestamp 使用 toDateTime() 限定时间范围。
3.1 数字是近似值
文档明确指出:数字可能是近似值(approximate),原因是 Cloudflare 会对大流量进行采样(sampling)。同样的原因也导致低流量时数据看起来"不均匀"。
这一点在源码中有非常直接的体现:所有聚合查询都使用 _sample_interval 字段做加权还原,例如 server/api/stats/counters.get.ts:
SUM(_sample_interval) -- 访问量(加权求和)
ROUND(COUNT(DISTINCT ip) * SUM(_sample_interval) / COUNT()) -- 去重访客数(加权去重)
即通过 COUNT(DISTINCT col) * SUM(_sample_interval) / COUNT() 估算真实去重值。理解这一点有助于正确解读低流量时段或小规模测试数据——它们可能因采样而显得有波动。
3.2 排除机器人(Bot)
要从统计与点击 Webhook 中排除机器人,设置:
NUXT_DISABLE_BOT_ACCESS_LOG=true
机器人识别逻辑位于 server/utils/access-log.ts:
- 使用 Cloudflare 的
cf.botManagement.verifiedBot标记; - 结合
ua-parser-js扩展(Crawlers、Fetchers、CLIs、Emails、InApps、MediaPlayers、Vehicles 等)解析 UA; - 当 UA 类型为
crawler/fetcher,或名称包含spider/bot时判定为机器人。
命中机器人且开关开启时,collectAccessLog 直接返回 undefined——该访问既不会写入 Analytics Engine,也不会触发 Webhook,从而保证统计与通知数据的"纯净"。
四、近实时页面:不是直播,是"看起来像实时"
Sink 的近实时(Realtime)页面有明确的定位:
它不是实时流(live stream)。该页面不使用 WebSocket,大约每 10 秒刷新一次,并以约每秒 1 个事件的速度回放新事件。暂停或标签页隐藏(hidden tab)会停止回放。
把它当作"看起来像实时(live-looking)的概览",而不是完美的事件流。
4.1 源码级实现印证
前端轮询与回放逻辑在 app/composables/useRealtimeLogs.ts 中实现,关键机制包括:
- 轮询取数:
refresh()通过useAPI<LogEvent[]>('/api/logs/events', ...)拉取最新事件(默认每次取 100 条),数据源即 Analytics Engine; - 回放节流:
useIntervalFn(playNext, REPLAY_INTERVAL, ...),REPLAY_INTERVAL = 1000毫秒,即每秒回放一个事件; - 可见性控制:
useDocumentVisibility()监听页面是否可见,visibility.value !== 'visible' || isPaused.value时暂停;回到前台后仅保留最近 20 条待回放事件(INITIAL_REPLAY_LIMIT)继续播放; - 去重与容量:
knownIds集合最多记住 1000 个事件 ID(MAX_KNOWN_LOGS),待回放队列上限 100 条(MAX_PENDING_LOGS),列表最多展示 100 条(MAX_VISIBLE_LOGS)。
事件去重 ID 由服务端生成:server/api/logs/events.get.ts 会按事件所有字段计算 FNV 风格哈希并追加出现序号作为 id(wae_<hash>_<occurrence>),避免同一事件重复回放。
4.2 近实时数据与地球仪联动
近实时日志不只是列表:useRealtimeLogs 的 replayEvent 默认走 useTrafficEventBus().emit,将每个事件派发给 Realtime 页面的 3D 地球可视化。在 app/composables/useTrafficEvent.ts 中:
- 事件携带访客的
latitude/longitude(来自 Cloudflare 请求头cf-iplatitude/cf-iplongitude)与 Cloudflare 边缘节点代号COLO; - 若访客位置与目标 COLO 距离很近(纬度差与经度差均小于 5),只绘制目的地涟漪(ripple);
- 否则绘制一条从访客位置到 COLO 的弧线(arc),起点涟漪约 0.8 秒、终点涟漪约 1.2 秒,与每秒回放节奏契合。
COLO 坐标映射数据来自仓库公开资源 public/colos.json。也就是说,你在地球上看到的每一次弧线动画,都对应一次真实的 Analytics Engine 数据点写入。
五、导出 CSV:筛选后统计的离线分析
文档提供两种导出入口:
- 仪表盘导出:在仪表盘中按筛选条件(链接、时间、国家等)过滤后,一键下载 CSV;
- 统计导出 API:
/api/stats/export,下载的 CSV 包含以下列:slug(短链码)、url(目标 URL)、viewer(访客数)、views(访问量)、referer(来源数)。
5.1 导出 API 的实现
导出端点位于 server/api/stats/[action].get.ts,路由参数 action 必须为 export,否则返回 404。核心行为:
- 使用与计数器相同的加权去重算法计算
viewer与referer(weightedDistinct/weightedReferers); - 按
slug、url分组,按访问量降序排列; - 返回的响应头包含
Content-Type: text/csv; charset=utf-8与Content-Disposition: attachment; filename="sink-access-<时间戳>.csv"(文件名由 shared/utils/export-file.ts 的createExportFilename生成)。
5.2 导出与链接 JSON 导出的区别
链接 JSON 导出是另一项独立功能,导出的是链接库本身(而非访问统计),相关用法见导入/导出指南。二者互补:CSV 回答"流量情况如何",JSON 回答"链接清单有哪些"。
六、从写入到查询:一条数据点的完整旅程
为帮助你从原理层面理解整套机制,这里给出数据流全链路:
-
写入(write):访问命中短链跳转时,
collectAccessLog从请求头收集cf-connecting-ip、referer、accept-language、user-agent,结合 Cloudflare 请求对象的cf属性(country、region、city、timezone、colo、经纬度)组装访问日志,writeAccessLog在NODE_ENV=production下调用analytics.writeDataPoint({ indexes: [link.id], blobs, doubles })写入 Analytics Engine(见 server/utils/access-log.ts)。非生产环境仅打印到控制台。 -
存储结构:数据点使用 1 个索引(
index1= 链接 ID),16 个 blob(slug、url、ua、ip、referer、country、region、city、timezone、language、os、browser、browserType、device、deviceType、COLO)与 2 个 double(latitude、longitude),映射定义在 server/utils/access-log.ts。 -
查询(query):所有统计 API 先经
buildAnalyticsFilter构造筛选条件,再用createAnalyticsQuery(dataset)以 Kysely 冷编译器生成纯 SQL(无参数绑定,见 server/utils/analytics-sql.ts),最终由useWAE通过 Cloudflare Analytics Engine SQL API(POST /accounts/{accountId}/analytics_engine/sql)执行并返回(见 server/utils/cloudflare.ts)。 -
渲染(render):前端各统计组件消费
/api/stats/*端点(counters、metrics、views、heatmap)与/api/logs/events,绘制计数器、图表、热力图、最近事件与地理分布。
这条链路中值得注意的安全细节:createAnalyticsQuery 会对数据集名和所有标识符做 ^<a href="https://link.gitcode.com/i/d2f9a7071e9e91c2f1cc1fb6c2f9b1a1" target="_blank">A-Za-z_][A-Za-z0-9_]*$ 校验,且禁止 SQL 带参数,从源头上防止注入(见 [server/utils/analytics-sql.ts)。
七、统计 API 端点一览
仓库中可用的统计相关端点(均可通过 shared/schemas/query.ts 的公共查询参数筛选):
| 端点 | 说明 | 关键参数 |
|---|---|---|
GET /api/stats/counters |
访问量、访客数、来源数(加权去重) | id、startAt、endAt、各筛选维度 |
GET /api/stats/metrics |
按维度聚合 Top N(如国家、浏览器、设备) | type(枚举自 blob/double 字段)、limit |
GET /api/stats/views |
时间序列图(分钟 / 小时 / 天) | unit(minute/hour/day)、clientTimezone |
GET /api/stats/heatmap |
星期 × 小时热力图 | clientTimezone |
GET /api/stats/export |
筛选后 CSV 导出 | 同上,另校验 startAt <= endAt |
GET /api/logs/events |
近实时事件流(供前端轮询回放) | limit(默认拉取 100) |
时间序列与热力图均支持 clientTimezone 参数(默认 Etc/UTC),由 getSafeTimezone 校验后传入 formatDateTime / toDateTime 做本地化聚合(见 server/api/stats/views.get.ts、server/api/stats/heatmap.get.ts)。limit 上限由 NUXT_LIST_QUERY_LIMIT 控制(默认 500,见 nuxt.config.ts)。
八、常见问题排查
| 现象 | 可能原因 | 处理建议 |
|---|---|---|
| 图表 / 日志 / 近实时一直为空 | ANALYTICS 绑定缺失或名称不一致 |
检查绑定变量名是否为 ANALYTICS,数据集是否与 NUXT_DATASET 一致 |
| 查询静默返回空结果 | NUXT_CF_ACCOUNT_ID 或 NUXT_CF_API_TOKEN 未设置 |
补齐账户 ID 与 API 令牌,确认令牌有 Account Analytics Read 权限 |
| 数字看起来"不均匀"或有波动 | Cloudflare 对高流量采样 | 属于正常近似行为,低流量时段更明显 |
| 统计中混入爬虫流量 | 未开启机器人排除 | 设置 NUXT_DISABLE_BOT_ACCESS_LOG=true |
| 近实时页面暂停不播放 | 页面隐藏或手动暂停 | 这是设计行为,非实时流;回到前台后自动续播 |
延伸阅读
- 导入/导出(链接 JSON 导出):与访问统计 CSV 导出相互独立的链接库迁移功能;
- 点击 Webhook 配置:
NUXT_DISABLE_BOT_ACCESS_LOG同时影响统计与 Webhook 的机器人过滤; - 部署指南(Workers / Pages):
ANALYTICS绑定在 Workers 部署中的自动创建方式; - 架构指南:理解 Sink 各模块在 Cloudflare 上的运行边界。