从零打造隐私友好的公开访问统计：EdgeOne Makers 边缘函数 + KV 实战全记录

博客迁移到自研的 Go 版本之后，我一直想要一个能公开展示、又不依赖第三方 SaaS 的访问统计：像 Vercel Analytics、Plausible 那样干净好看，但数据留在自己手里，也不收集任何个人信息。最终的成品就是 stats.lscx.org，本站页脚那一行小字也是它提供的。这篇文章把整个实现从架构、数据模型、隐私设计、前端可视化到踩过的坑完整记录下来，希望对想做类似东西的朋友有参考价值。

一、需求与约束

先把目标说清楚，后面的很多设计都是被这些约束“逼”出来的：

二、整体架构

流程很简单：

1. 访客打开 www.lscx.org，页面照常经过 EdgeOne CDN 回源，主站的部署方式一行没改。
2. 页面里注入了一小段脚本（博客后台的「页脚代码注入」，放在 </body> 之前），页面加载完由浏览器直接向 https://stats.lscx.org/api/collect 发送一条浏览记录。
3. 统计服务是一个独立的 EdgeOne Makers 项目：三个 Edge Function 负责采集、查询和健康检查，同一个项目里还托管着公开的 Dashboard 静态页面。
4. 数据只以“聚合计数”的形式写进 Makers KV。

为什么一定要浏览器直连，而不是让博客源站代发？因为国家识别靠的是边缘节点给出的 Geo 信息（request.eo.geo.countryCodeAlpha2），它反映的是发起请求的那一端。如果由源站代发，所有访问都会变成“来自源站所在的国家”。

接口一览

项目结构

lscx-analytics/
├── edge-functions/api/        # Makers 按文件路由：collect.js / stats.js / health.js
├── lib/                       # 服务端逻辑
│   ├── collect.js             # 采集：校验、过滤、内存分片、写 KV
│   ├── store.js               # 读取：分片 → 小时 / 日 / 月汇总
│   ├── stats.js               # 统计 API、缓存
│   ├── aggregate.js           # 聚合文档结构、合并、窗口去重
│   ├── ua.js / referrer.js    # UA 粗分类、Bot 过滤、来源归类
│   ├── time.js / kv.js / http.js / config.js
├── src/                       # Dashboard（原生 JS + d3-geo + d3-shape）
├── public/                    # world.json（简化后的地图）、robots.txt
├── snippet/                   # 博客页脚脚本源码 → 构建出可粘贴的 HTML
├── scripts/                   # build / 本地模拟服务器 / 部署前检查 / 生成器
├── test/                      # node:test，含按 EdgeOne 行为实现的 KV 模拟
└── edgeone.json               # 构建命令、输出目录、响应头

整个服务端没有任何 npm 运行时依赖，Edge Functions 由 EdgeOne CLI 用 esbuild 打包，lib/ 下的相对 import 会被一起打进去。

三、采集端：页脚里的那段脚本

脚本源码只有两百来行，构建时压缩成一段约 4.8 KB 的 <style> + <script>，直接粘到博客后台。它做两件事：上报一次浏览，以及在页脚渲染那一行统计数字。

核心的上报逻辑：

function track() {
  var nav = w.navigator;
  var loc = w.location;
  if (nav.webdriver) return;                         // 自动化浏览器不计
  if (!/(^|\.)lscx\.org$/i.test(loc.hostname)) return;
  if (/^\/admin(\/|$)/.test(loc.pathname)) return;   // 后台不计

  // 随机匿名 ID + 上次访问时间，只存在本站的 localStorage 里
  var s = storage();
  var raw = s && s.getItem('lscx_av');
  var id = '', last = 0, isNew = 0;
  if (raw) { var parts = raw.split('.'); id = parts[0]; last = +parts[1] || 0; }
  if (!id && s) { id = randomId(); isNew = 1; }
  if (s) s.setItem('lscx_av', id + '.' + Date.now());

  var body = JSON.stringify({
    p: loc.pathname,          // 只有路径，没有 ?query 和 #hash
    t: cleanTitle(),          // 去掉“ | 露水晨曦”后缀的标题
    r: d.referrer || '',
    v: id, n: isNew, lv: last || undefined,
    tc: nav.maxTouchPoints > 1 ? 1 : 0,   // 用来识别伪装成 Mac 的 iPad
    nf: isErrorPage(),                    // 404 页面统一归到“(not found)”
  });
  fetch(ENDPOINT + '/api/collect', {
    method: 'POST',
    body: body,
    headers: { 'Content-Type': 'text/plain;charset=UTF-8' },
    credentials: 'omit',
    keepalive: true,
    mode: 'cors',
  }).catch(noop);
}

几个细节：

• Content-Type: text/plain：这样跨域 POST 属于“简单请求”，浏览器不会先发一次 OPTIONS 预检，少一次往返。服务端照样按 JSON 解析。
• keepalive: true：用户点了就走，请求也能发出去；不支持 fetch 的老浏览器退回 sendBeacon。
• 预渲染：如果页面处于 prerender 状态，会等到真正可见时再上报，避免把浏览器的预加载算成浏览。
• 全程 try/catch：统计服务挂了、被广告拦截器拦了，页脚只会显示「访问统计」四个字，博客其他部分不受任何影响。

四、服务端：Edge Functions 与运行时要点

Makers 的 Edge Function 是 V8 isolate 运行时（类似 Cloudflare Workers，不是 Node.js），按 edge-functions/ 目录做文件路由。入口文件很薄，真正的逻辑都在 lib/ 里：

// edge-functions/api/collect.js
import { handleCollect } from '../../lib/collect.js';

export async function onRequest(context) {
  try {
    return await handleCollect(context);
  } catch {
    // 任何异常都不往外抛：不计这一次，但绝不影响博客页面
    return new Response(null, { status: 204, headers: { 'Cache-Control': 'no-store' } });
  }
}

开发时需要注意的几个运行时特性：

KV 的获取我做了一层兼容，同时方便测试时注入模拟对象：

export function getKV() {
  try {
    if (typeof analytics_kv !== 'undefined' && analytics_kv) return analytics_kv;
  } catch {}
  return globalThis.__ANALYTICS_KV__ || null;   // 测试 / 本地模拟服务器注入
}

五、核心难点：在“最终一致”的 KV 上计数

这是整个项目最需要想清楚的地方。

Makers KV 是最终一致的：数据持久化在少数中心节点，边缘节点按需缓存。官方文档的描述是，写入在发起写入的节点上通常立即可见，其他节点最长会读到 60 秒前的旧值。

如果用最朴素的计数方式——读出 count，加一，写回去——会发生什么？

只要有两个以上的边缘节点在 60 秒窗口里交替写同一个键，计数就会持续丢失，而且流量越大丢得越多。KV 也没有原子自增或 CAS 之类的操作可用。

解法：每个实例只写自己的键

既然冲突来自“多个写者写同一个键”，那就让每个键只有一个写者：

• 每个 Edge Function 实例（isolate）启动时生成一个随机 ID；
• 它在内存里累计当前小时的聚合数据；
• 每次收到浏览，就把内存里的完整快照写到只属于它自己的键：s_<YYYYMMDDHH>_<实例ID>。

因为内存才是这个键的“权威数据”，写之前根本不需要读，自然也就不存在读到旧值的问题。读取时把同一小时的所有分片合并起来即可。

const ISOLATE_ID = randomId(12);
const shards = new Map(); // hourKey -> { agg, version, flushed, lastPut, inflight }

export function shardKey(hk, iso = ISOLATE_ID) {
  return `s_${hk}_${iso}`;
}

async function putShard(kv, hk, s) {
  if (s.flushed >= s.version) return;          // 没有新数据就不写
  const v = s.version;
  s.inflight++;
  s.lastPut = Date.now();
  try {
    await kv.put(shardKey(hk), JSON.stringify({ ...s.agg, seq: v, ts: s.lastPut }));
    if (v > s.flushed) s.flushed = v;
  } finally {
    s.inflight--;
  }
}

再加一点细节：同一个分片 1 秒内最多写一次，更密集的写入会合并到一次延迟写里（放进 waitUntil，不拖慢响应）；某次写入失败，计数仍留在内存，下一次浏览会把完整快照重新写一遍，自愈。

如果平台每个请求都新开一个 isolate，最坏情况就是一次浏览一个分片——依然正确，只是键多一些。实测 Makers 的实例会被复用，一个小时通常只有个位数的分片。

汇总：小时 → 日 → 月

光有分片还不够：查询“近 30 天”如果每次都去合并几百个分片，既慢又费 KV 读。于是把数据逐级汇总：

关键在于“封存”：一个小时结束 5 分钟后（大于 KV 60 秒的传播时间），所有边缘节点对这个小时的写入都已经全局可见，这时它的分片内容就不会再变了。对一个已封存的时段做汇总，结果是确定的——两个节点同时算，算出来的是同一份文档，谁覆盖谁都无所谓。所以整个系统不需要任何锁。

汇总是“查询时惰性计算”的：读到哪个小时，发现汇总还不存在，就当场从分片算出来写回去：

async hour(hk) {
  if (hk >= this.sealedHour) {
    // 还没封存的小时（当前小时）：直接实时合并分片，不缓存、不写回
    return this.shardsOf(hk);
  }
  const key = `h_${hk}`;
  if (memo.has(key)) return memo.get(key);          // 已封存的汇总永不变化，实例内存缓存
  const stored = await readJSON(this.kv, key);
  if (stored) return remember(key, normalizeAgg(stored));
  if (hk.slice(0, 8) < (await this.startDay())) return remember(key, emptyAgg());
  const agg = trimAgg(await this.shardsOf(hk), { p: 300, r: 120 });
  this.write(key, { ...agg, ts: this.now });          // 放进 waitUntil，不阻塞响应
  return remember(key, agg);
}

清理也遵循“只删已经安全的东西”：分片只有在对应的小时汇总写入 10 分钟以上之后才会删除（48 小时后），小时汇总在日汇总存在之后 15 天删除。博客页脚每次页面浏览都会请求一次汇总接口，所以只要博客有访问，汇总和清理就会持续推进，不需要任何定时任务。

聚合文档长什么样

所有 KV 值都是同一种结构，字段名刻意取得很短：

{
  "pv": 132, "uv": 41, "nv": 18,
  "g": { "n": 18, "1": 9, "3": 6, "32": 8 },
  "c": { "CN": 60, "US": 31, "AU": 20 },
  "p": { "/": 45, "/2737.html": 12 },
  "t": { "/2737.html": "使用腾讯云免费SSL 实现网站添加https访问" },
  "r": { "Direct": 20, "Google": 14, "GitHub": 3 },
  "d": { "Desktop": 90, "Mobile": 40, "Tablet": 2 },
  "b": { "Chrome": 70, "Safari": 35, "Edge": 20 },
  "o": { "Windows": 55, "iOS": 30, "macOS": 25 }
}

p（页面）和 r（来源）这种长尾字段在不同层级会截断成 Top N，其余合并成 __other__，保证单个文档大小可控。

六、访客（UV）是怎么算的

这是我觉得最有意思的一部分。

不靠 IP，也不靠指纹

访客的识别完全基于浏览器本地存储里的那个随机 ID：一个浏览器算一位访客。IP 只在服务器内存里加盐哈希后用于限流（每分钟 40 次）和去重，从不落盘；UA 只用来粗分类设备 / 浏览器 / 系统。

服务端不存访客列表，却能算出精确的窗口去重

浏览器上报时带上“上次访问时间” lv，服务端算出距离上次访问隔了几天（按 Brisbane 时区的日历日），记作 gap：

• gap = 0：今天已经来过，不是今日新访客；
• gap ≥ 1：今天第一次来，计入当日 UV，并在当天的gap 直方图 g 里记一笔（32 天以上封顶记为 32）；
• 全新浏览器：记作 n，同时计入“新访客”。

有了每天的 gap 直方图，任意不超过 32 天的窗口都能算出精确的去重访客数：某天的一次“首访”属于窗口内第一次出现，当且仅当这位访客的上一次访问早于窗口起点，也就是 gap 大于“这一天距离窗口起点的天数”。

// dayAggs[0] 是窗口第一天
export function windowUniques(dayAggs) {
  let total = 0;
  dayAggs.forEach((a, i) => {
    for (const k in a.g) {
      if (k === 'n' || Number(k) > i) total += a.g[k];
    }
  });
  return total;
}

举个例子：某位访客 1 号首次访问，2 号又来（gap=1），4 号又来（gap=2）。

三种窗口都只算 1 人，而服务端自始至终不知道“这个人是谁”。月度去重访客用的是同一个思路（gap 大于“当月第几天减一”）。累计访客则就是所有“新访客”之和。

七、Bot 过滤、UA 分类与来源归类

只统计真实浏览，过滤分了好几层：

1. 不执行 JavaScript 的抓取（curl、Python requests、各种 RSS 阅读器、自己写的爬虫）根本不会运行页脚脚本，天然不计；
2. 浏览器侧：navigator.webdriver 为真直接不报；
3. 服务端：UA 为空、过短、不以 Mozilla/ 开头的一律视为程序；再用一个正则匹配常见爬虫、监控和无头浏览器：

const BOT_RE = new RegExp([
  'bot\\b', 'bot[/_;)-]', 'crawl', 'spider', 'slurp', 'facebookexternalhit',
  'headlesschrome', 'phantomjs', 'puppeteer', 'playwright', 'selenium', 'lighthouse',
  'curl/', 'wget/', 'python', 'okhttp', 'go-http-client', 'axios',
  'gptbot', 'claudebot', 'perplexity', 'ccbot', 'bytespider', 'petalbot', /* … */
].join('|'), 'i');

// 机型名里带 "bot" 的手机（比如 CUBOT）不能误杀
const BOT_FALSE_POSITIVE_RE = /cubot|\bbot(?:anic|tle)/i;

有个容易误伤的地方值得一提：Pinterest、Snapchat、搜狗浏览器等 App 内置浏览器的 UA 里也带着品牌名，如果简单地按 pinterest、sogou 去匹配，会把真实用户当成爬虫，所以规则里只匹配它们爬虫专用的标识。

UA 分类只保留三个粗粒度标签：

iPadOS 的 Safari 会伪装成 Mac 桌面 UA，所以脚本额外报告 maxTouchPoints > 1：一台“能触摸的 Mac”就是 iPad。

来源（Referrer）只看主机名：Google、Bing、百度、DuckDuckGo、GitHub、V2EX、知乎、微信、ChatGPT 等常见来源归成友好的名字，其余显示裸域名；站内跳转不算来源，没有 referrer 记为 Direct。路径会去掉查询参数和锚点、解码中文、去掉末尾斜杠，/admin、/static 这类路径和静态文件扩展名一律忽略。

八、隐私设计

这一条有专门的测试来守住：模拟一次带邮箱参数、带搜索词来源的访问，然后把 KV 里所有内容拼起来，断言里面找不到 IP、UA 片段、访客 ID、查询参数：

test('privacy: KV holds only aggregates (no IP, UA, visitor id, query)', async () => {
  await pageview(
    { p: '/2737.html?email=a@b.c', v: 'secretvisitorid42', r: 'https://www.google.com/search?q=private+words' },
    { ip: '203.0.113.99', ua: UA.iphone },
  );
  await getStats();
  const dump = [...kv.data.entries()].map(([k, v]) => k + '=' + v).join('\n');
  for (const needle of ['203.0.113.99', 'secretvisitorid42', 'iPhone OS', 'Mozilla', 'email', 'private', 'q=']) {
    assert.equal(dump.includes(needle), false, needle);
  }
});

公开的统计接口自然也只返回聚合数据。

九、统计 API 与缓存

/api/stats 的响应大致如下（节选）：

{
  "ok": true,
  "range": "30d",
  "kpi": {
    "totalViews": 7600, "visitors": 2600, "countries": 30,
    "today": { "date": "2026-10-07", "pv": 139, "uv": 61 },
    "todayChange": 0.103
  },
  "summary": { "pv": 4300, "uv": 1900 },
  "series": { "unit": "day", "points": [{ "key": "2026-09-08", "pv": 121, "uv": 58 }] },
  "countries": [{ "code": "CN", "pv": 1400 }],
  "pages": [{ "path": "/2737.html", "pv": 412, "title": "…" }],
  "referrers": [{ "name": "Google", "pv": 530 }],
  "devices": [], "browsers": [], "os": [],
  "site": { "name": "LSCX", "domain": "www.lscx.org", "timezone": "Australia/Brisbane" }
}

“今日较昨日”只在昨天同一时刻已有至少 10 次浏览时才给出百分比（按小时对齐、当前小时按分钟折算），数据太少宁可不显示，也不制造一个没有意义的 +500%。

缓存分了三层：

另外，已封存的小时 / 日 / 月汇总永远不会再变，所以实例内存里会长期缓存它们。实测在有 75 天数据的情况下，一个冷启动的实例算一次 30 天统计，CPU 时间约 3ms、KV 读取不超过 70 次，离 200ms 的 CPU 限制非常远；一次采集只有 1 次 KV 写。

十、Dashboard：好看、克制、能看懂

前端没有用任何框架，原生 JavaScript + d3-shape（曲线）+ d3-geo（地图投影）+ topojson-client，esbuild 打包后 JS 约 45 KB（gzip），不加载任何第三方 CDN、字体或脚本，国内访问也不受影响。

一些设计上的取舍：

• 配色：只用一个主色（绿色表示 PV）加一个辅色（蓝色表示 UV），两色都经过色觉障碍模拟校验，浅色和深色模式分别取了不同的色阶，而不是简单反色；
• 趋势图：数据点多时用单调三次曲线（平滑但不会“冲过头”），点少时（比如按月）直接用折线；网格线只有 3 条；最后一个时段还在进行中，画成虚线，免得“今天才过一半”看起来像流量暴跌；
• 范围切换：今天（按小时）/ 7 天 / 30 天 / 全部（按月），切换时曲线有一次轻微的绘制动画；
• 数字：大数字用 128.4K 这种紧凑格式，悬停能看到精确值；
• 状态：加载时是骨架屏，没有数据时有专门的空状态，接口出错时保留布局并给出“重试”，绝不白屏。

世界地图

地图用的是 Natural Earth 的国界数据（公共领域），原始数据是 1:10m 精度、十几 MB 的 Shapefile。我写了一个生成脚本，把它转成 TopoJSON，再用 topojson-simplify 只保留 2% 的顶点并重新量化，最后只有约 100 KB（gzip 后 33 KB），每个国家直接以 ISO 两位代码作为 id，和统计数据一一对应。

颜色是单一色相的连续色阶，访问量取对数后映射（否则一个大国会让其他国家全部褪成同一个浅色），无访问的国家保持低调的灰色。新加坡、巴林这类在这个比例尺下几乎看不见的国家，会在中心点画一个小圆点。

有一个很典型的 SVG 坑：鼠标悬停时给国家描一圈边。如果直接改这个 path 的 stroke，相邻国家的边界会被后绘制的邻国盖住一半——于是海岸线是粗的、陆地边界是细的，看起来非常别扭。解决办法是把高亮描边画到一个位于所有国家之上的独立图层里：

outline() {
  this.hl.replaceChildren();
  for (const code of new Set([this.hovered, this.selected])) {
    if (!code) continue;
    for (const el of this.paths.get(code) || []) {
      const copy = el.cloneNode(false);      // 复制形状，不复制填色和事件
      copy.removeAttribute('data-code');
      copy.removeAttribute('style');
      copy.setAttribute('class', 'hl-shape'); // fill: none; stroke 统一粗细
      this.hl.appendChild(copy);
    }
  }
}

列表与设备分布

列表没有用表格，而是“一行一个条目 + 背景比例条”。热门页面直接显示文章标题（路径作为副标题），因为 /2737.html 这种路径对读者毫无意义。来源和浏览器的单色图标是构建时从 simple-icons（CC0）里抽取的路径数据，没有的就用首字母徽标，风格保持统一。设备分布用一条带 2px 间隙的堆叠条，而不是饼图。

移动端与深色模式

所有颜色都定义成 CSS 变量，深色模式在 prefers-color-scheme: dark 下整体替换；手机端 KPI 变成两列，触摸点击即可查看图表和地图的提示框，点别处或滚动就收起。我用无头浏览器在 1440 / 820 / 390 / 320 像素宽度下逐一截图检查，确保不出现横向滚动条。

十一、页脚那一行字

页脚的样式直接复用博客自己的 CSS 变量，所以会自动跟随博客的明暗主题。一个小需求是“无论屏幕多窄都保持一行”，做法是逐级降级：完整文字放不下就换成短标签，再放不下就逐步缩小字号（最低 10px），最后才用省略号兜底。

function fit(wrap, a) {
  var room = wrap.clientWidth;
  a.className = 'lscx-stats';
  a.style.fontSize = '';
  // a 设置了 max-width:100%，offsetWidth 会被截住，所以要量内容宽度 scrollWidth
  if (!room || a.scrollWidth <= room) return;
  a.className = 'lscx-stats lscx-short';       // 切换为短标签
  var size = parseFloat(getComputedStyle(a).fontSize) || 12.5;
  while (a.scrollWidth > room && size > 10) {
    size -= 0.5;
    a.style.fontSize = size + 'px';
  }
}

窗口尺寸变化（比如手机横竖屏切换）时会用 requestAnimationFrame 节流后重新计算。

十二、踩过的坑

1. KV 的 list() 返回的是 key，不是 name

上线之后博客明明一直有人访问，统计却一直是 0。

排查过程是先给健康检查接口加了一个需要密钥才能触发的深度自检：实际执行一次 put / get / list / delete，并报告各类键的数量（不返回任何键名和数据）。结果一目了然：写入正常，读取正常，但 list() 返回的每个元素长这样：

{ "key": "s_2026100701_xxxx", "expirationTtl": 0, "expiration": 0, "meta": null }

而我照着文档写的是 k.name，于是所有分片都“列不出来”，统计自然全是 0。修复只要一行：

const name = typeof k === 'string' ? k : k && (k.key || k.name);

但更隐蔽的是连带问题：在“看不见分片”的那段时间里，已经封存的小时被当成“没有数据”，生成了空的小时汇总——而汇总一旦存在就不会再重算，会把那段时间的访问永久盖成 0。好在分片保留了 48 小时，删掉那批错误汇总、再重新部署一次清空各实例的内存缓存，数据就完整地恢复了。

教训有两条：一是本地测试用的 KV 模拟对象要以平台实测行为为准，现在模拟对象返回的就是和线上一模一样的结构；二是写入失败、读取异常这类问题不能静默吞掉，现在采集接口写 KV 失败时会在响应头里给出 store-failed 和错误原因。

2. CLI 构建时会把环境变量“烤”进函数代码

用 edgeone makers deploy 部署时，CLI 会在本地构建 Edge Functions，并把环境变量内联进产物。我读了一下 CLI 的实现：如果项目根目录有 .env，就只注入 .env 的内容；如果没有，它会把当前 shell 的全部环境变量都写进去。

这显然不能接受，所以部署脚本前面加了一道检查：

// scripts/check-env.mjs（节选）
if (!existsSync(file)) fail('Missing .env — run `cp .env.example .env` …');
if (!env.ANALYTICS_HASH_SECRET || env.ANALYTICS_HASH_SECRET === 'change-me') fail('…');
if (env.ANALYTICS_DEV === 'true') fail('ANALYTICS_DEV=true is for local development only');
const extra = Object.keys(env).filter((k) => !allowed.has(k));
if (extra.length) fail(`Unexpected keys in .env (they would be bundled into the function): ${extra}`);

npm run deploy = 检查 .env + lint + 测试 + 部署，任何一步不通过都不会上线。.env 本身当然在 .gitignore 里。

3. 名字里只能有字母、数字、下划线

KV 的键名如此，KV 命名空间的名字也如此（lscx-analytics 会被拒绝，要写成 lscx_analytics）。所以所有键都设计成 s_、h_、d_、m_ 加数字的形式，时间也用 YYYYMMDDHH 这种紧凑格式，顺便还保证了字典序就是时间序。

4. 两个处理地图数据时的小坑

• Shapefile 的 .dbf 文本字段是用 \0 填充的定长字段，trim() 去不掉 NUL，导致所有国家代码匹配失败、所有国家都没有 id；
• topojson-simplify 的 quantile(topology, p) 是对权重降序排列后取分位数，p 实际上是“保留的顶点比例”。第一次按直觉写成 1 - p，结果简化后还有 14 MB。

十三、测试与验证

本地开发用一个模拟 Makers 的小服务器：静态资源 + 三个真实的 Edge Function 模块 + 内存 KV（数据落盘到本地文件），还能一键生成几十天的演示数据，文中的截图就是这么来的。

npm install
npm run check        # lint + 测试 + 构建
npm run dev:demo     # http://localhost:8788，带演示数据

十四、部署步骤（简要）

1. EdgeOne Makers 控制台 → 存储 → KV 存储：申请开通（免费 1 GB），创建命名空间（只能用字母、数字、下划线）；
2. 本地准备 .env（ANALYTICS_HASH_SECRET 用 openssl rand -hex 32 生成，其余是允许的来源、时区、站点名）；
3. npx edgeone login --site global，然后 npm run deploy，首次会自动创建项目；
4. 项目 → KV 存储 → 绑定命名空间，变量名填代码里约定的全局变量名，再部署一次；
5. 项目 → 域名管理 → 添加自定义域名，按提示在 DNS 服务商处添加 CNAME，证书会自动签发；
6. 打开 /api/health 确认 "kv":"ok"，再把 snippet/footer-snippet.html 的内容粘贴到博客后台的「页脚代码注入」。

加速区域建议和主站保持一致；如果选择包含中国大陆的区域，自定义域名需要先完成备案。

十五、局限与后续

• 访客识别依赖 localStorage：同一个人用多个浏览器会算多位；无痕窗口、清除数据、Safari 长时间不访问后存储被清理，都会被算成新访客；
• 没有会话概念，所以没有跳出率、停留时长这类指标，这是刻意保持的简单；
• 同一个实例内两个并发请求的写入理论上可能乱序落地，最坏丢失这个小时最后的几次计数，下一次写入会自愈；对个人博客的并发量可以忽略；
• 后续可能会加：按页面查看趋势、来源细分到搜索词以外的路径维度、导出 CSV。

做这个项目最大的收获，是在一个“最终一致、没有原子操作”的 KV 上把计数做对：让每个键只有一个写者，让需要合并的数据在不再变化之后才合并——想通这两点，剩下的都是工程细节。

欢迎去 stats.lscx.org 看看实时数据，有问题也欢迎在下面留言交流。