Sink 访问分析与近实时视图Cloudflare 短链统计的完整启用与原理指南【免费下载链接】Sink⚡ A Simple, Speedy, Secure, and Serverless Link Shortener with Analytics, Running Entirely on Cloudflare.项目地址: https://gitcode.com/GitHub_Trending/si/Sink访问分析Analytics是 Sink 短链服务中的可选能力借助 Cloudflare Analytics Engine 实现全链路 Serverless 的点击统计计数、趋势图、热力图、最近事件与地理位置一应俱全。本文以 docs/zh-CN/features/analytics.md 为核心骨架结合仓库中 access-log.ts、stats 系列 API 等源码实现完整讲解如何启用统计、理解数据口径、排除机器人以及如何通过仪表盘或 API 导出 CSV。访问分析是可选项缺了它短链依旧能用分析功能默认不强制。如果从未配置 Analytics EngineSink 的核心能力——短链创建与跳转、登录鉴权、链接管理——依然完全可用只是仪表盘上的图表、日志和近实时视图会一直保持为空访问也不会产生任何统计记录。换句话说是否开启统计完全取决于部署时的环境变量与 Cloudflare 侧的资源绑定这也是理解后续所有配置步骤的前提。如何启用三样东西缺一不可启用访问分析需要同时具备以下三项缺少任何一项、或名称不一致访问分析就会持续为空1. Analytics Engine 绑定变量名必须为ANALYTICSWorkers 部署通常在部署配置wrangler.jsonc中自动生成绑定数据集默认sinkPages 部署在Settings → Bindings → Add → Analytics Engine手动添加绑定见上图变量名必须是ANALYTICS数据集默认sink。如果你设置了NUXT_DATASET这里的数据集名称必须与之一致否则写入与查询会指向不同的数据集。2. 账户 IDNUXT_CF_ACCOUNT_ID把NUXT_CF_ACCOUNT_ID设置为承载本应用的 Cloudflare 账户 ID。可以在仪表盘侧边栏看到账户名或登录后在浏览器 URL 中直接看到这串 ID。3. API 令牌NUXT_CF_API_TOKEN把NUXT_CF_API_TOKEN设置为加密密钥不要在明文环境变量中暴露Cloudflare 仪表盘 → 右上角头像 →My Profile→API Tokens→Create Token→Custom Token权限仅需一项Account → Account Analytics → Read建议将令牌作用域限制到承载本应用的同一个账户。这套令牌用于服务端读取 Analytics Engine 数据来渲染统计图表因此只授予只读的 Account Analytics 权限即可符合最小权限原则。从源码看数据链路一次点击如何变成一条统计记录理解了“三要素”之后有必要从源码层面确认这些配置到底在链路中扮演什么角色。Sink 在跳转处理中调用 collectAccessLog() 收集访问信息再由 writeAccessLog() 写入ANALYTICS绑定// server/utils/access-log.ts节选 if (process.env.NODE_ENV production) { const analytics cloudflare.env.ANALYTICS if (!analytics) return analytics.writeDataPoint({ indexes: [link.id], // only one index blobs: logs2blobs(accessLogs), doubles: logs2doubles(accessLogs), }) return }从源码可以推断出几个关键实现事实写入位置是cloudflare.env.ANALYTICS这正是前文强调绑定变量名必须为ANALYTICS的原因——绑定缺失时analytics为空直接静默返回索引字段是链接 ID每条数据点以link.id作为唯一索引indexes: [link.id]后续按链接筛选即是对index1的过滤维度与位置通过 Blobs 存储blobsMap 定义了 16 个字符串维度slug、url、uaUser-Agent、ip、referer、country、region、city、timezone、language、os、browser、browserType、device、deviceType、COLOCloudflare 边缘节点经纬度通过 Doubles 存储latitude、longitude两个浮点字段来自请求的cf对象专门用于近实时页面的地球仪RealTime Globe可视化归属信息全部来自 Cloudflare 请求对象国家、地区、城市、时区、经纬度、COLO 都取自cf属性无需自己维护 IP 地理库开发环境不写数据非生产环境下直接console.log输出访问日志方便本地调试。查询侧统计 API 通过 createAnalyticsQuery() 生成 SQL并且对数据集名、标识符做了严格的白名单校验仅允许[A-Za-z_][A-Za-z0-9_]*同时禁止带参数查询compileAnalyticsQuery会拒绝含参数的 SQL从源头防止注入——这也是为什么NUXT_DATASET必须与绑定数据集完全同名匹配的原因之一。能看到什么统计面板的构成与筛选维度成功写入的访问数据会驱动仪表盘中的以下可视化模块计数器Counters访问量、访客数、来源数等总量指标趋势图Views按分钟 / 小时 / 天聚合的访问曲线热力图Heatmap按星期 × 小时分布的访问热区最近事件Recent events / Logs逐条访问记录位置分布国家 / 地区 / 城市的来源分布。这些图表共享一套查询过滤器实现见 query-filter.ts 的buildAnalyticsFilter支持按以下维度筛选维度对应字段说明链接id对应数据点索引index1可传多个链接 ID 逗号分隔时间startAt/endAtUnix 时间戳秒转换为toDateTime进行范围过滤国家/地区country/region/city来自 Cloudflarecf属性浏览器browser/browserType由ua-parser-js解析系统os由ua-parser-js解析设备device/deviceType由ua-parser-js解析来源referer从 Referer 头解析出的主机名buildAnalyticsFilter还会拒绝包含控制字符的过滤值防止构造异常的查询条件。数字是近似值理解采样机制需要特别说明的是面板数字可能是近似值。Cloudflare Analytics Engine 对高流量数据会进行采样每个数据点带有_sample_interval采样间隔字段。Sink 的 SQL 在统计时做了采样加权例如计数器与导出 API 中的去重计数-- 加权去重计数COUNT(DISTINCT col) * SUM(_sample_interval) / COUNT() ROUND(COUNT(DISTINCT col) * SUM(_sample_interval) / COUNT())而访问量则直接用SUM(_sample_interval)累加估算。因此高流量场景下数字是对真实值的近似估计低流量场景下由于采样粒度不均匀数字可能看起来分布不均或不够平滑。这是 Analytics Engine 的固有特性并非 Sink 的统计 bug。排除机器人NUXT_DISABLE_BOT_ACCESS_LOGtrue如果希望统计与 Webhook 通知中不出现检测到的机器人流量设置环境变量NUXT_DISABLE_BOT_ACCESS_LOGtrue对应源码在 collectAccessLog() 中Sink 会综合三种信号判断请求是否来自机器人——Cloudflare Bot Management 标记cf.botManagement.verifiedBotua-parser-js解析出 UA 类型为crawler或fetcher浏览器名包含spider或bot关键字。命中机器人且开启了该开关时请求会在写入之前被丢弃同时会在服务端日志打印bot access log disabled既不会污染统计也不会触发点击 Webhook。近实时页面不是真正的实时流仪表盘的近实时Realtime页面呈现最新访问事件但它不使用 WebSocket不要把它当作严格的事件流页面大约每 10 秒刷新一次新事件以大约每秒 1 条的速度回放暂停回放或浏览器标签页隐藏时会停止回放。从 app/composables/realtime.ts 可以看到前端通过时间窗口预设如last-1h最近一小时计算查询区间并携带链接筛选条件向统计 API 轮询。因此请把它当作“看起来像实时”的概览视图而非逐条完整的事件流。导出筛选后的 CSV 下载统计结果可以通过两种方式导出为 CSV仪表盘在统计页设置好筛选条件后直接下载统计导出 API请求GET /api/stats/export实现见 server/api/stats/[action].get.ts携带与统计页相同的查询参数。导出 API 返回的 CSV 包含五列列含义slug短链码url目标 URLviewer访客数加权去重 IP 数views访问量SUM(_sample_interval)referer来源数加权去重来源数导出支持startAt/endAt时间范围校验开始时间不得晚于结束时间否则接口返回参数校验错误并以sink-access-*.csv的文件名触发浏览器下载同时响应头带有Cache-Control: no-store避免导出内容被缓存。与链接 JSON 导出的区别需要注意本文讲的是统计数据的 CSV 导出而链接本身的 JSON 导出短链列表、URL、过期时间等是另一项独立功能详见导入/导出。小结访问分析是可选功能启用需同时满足三件事名为ANALYTICS的 Analytics Engine 绑定、NUXT_CF_ACCOUNT_ID账户 ID、仅含 Account Analytics 只读权限的NUXT_CF_API_TOKEN数据经 collectAccessLog 收集后以链接 ID 为索引、16 个字符串维度加经纬度写入 Analytics Engine查询端通过白名单校验与采样加权保证安全与合理近似统计数字受 Cloudflare 采样影响可能是近似值用NUXT_DISABLE_BOT_ACCESS_LOGtrue可排除检测到的机器人流量近实时页面约 10 秒轮询刷新并非真正的实时流筛选后的统计可通过仪表盘或/api/stats/export导出为 CSV。【免费下载链接】Sink⚡ A Simple, Speedy, Secure, and Serverless Link Shortener with Analytics, Running Entirely on Cloudflare.项目地址: https://gitcode.com/GitHub_Trending/si/Sink创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考