先划清边界：这是计数器，不是分析看板#

它没有趋势图、没有来源分析、没有实时在线人数，也没有归因漏斗。要这些请用 Cloudflare Web Analytics、Umami、Plausible。

它给的是三个数：

前两个好理解，第二个值得多说一句。PV 和 UV 其实都不回答「来过几次」这个问题：PV 把一次访问里翻的五页算成五，UV 又把一个人跨月来了十次算成一次。中间那个「次数」才是运营常看的指标，Umami 管它叫 visits。本站这张卡也照这个名字来。

表结构#

整个库就两张表：t_website 一个站点一行，t_web_visitor 一次访问一行。

1
CREATE TABLE IF NOT EXISTS t_website (
2
  id        INTEGER PRIMARY KEY AUTOINCREMENT,
3
  name      TEXT NOT NULL,
4
  domain    TEXT NOT NULL,
5
  create_at DATETIME DEFAULT CURRENT_TIMESTAMP,
6
  update_at DATETIME DEFAULT CURRENT_TIMESTAMP
7
);
8

9
CREATE TABLE IF NOT EXISTS t_web_visitor (
10
  id              INTEGER PRIMARY KEY AUTOINCREMENT,
11
  website_id      INTEGER NOT NULL,
12
  url_path        TEXT NOT NULL,
13
  referrer_domain TEXT NOT NULL,
14
  referrer_path   TEXT NOT NULL,
15
  visitor_ip      TEXT NOT NULL,
16
  create_at       DATETIME DEFAULT CURRENT_TIMESTAMP,
17
  update_at       DATETIME DEFAULT CURRENT_TIMESTAMP
18
);

几张表都刻意留了 update_at，虽然这套统计只写不改。create_at 按 CURRENT_TIMESTAMP 存的是 UTC，前端要显示「今日」得自己加 8 小时，这一步很容易忘。

多站点是天然支持的：t_web_visitor.website_id 一关联，正式站、测试站、localhost 各自算各自的。本站库里现在有四行：

端点一：POST /api/visit#

埋点打进来的入口，写一行记录，然后把该路径的最新 PV / UV 回给前端（文章顶部那行数字就用它）：

1
async function handleVisit(request: Request, env: Env, cors: Headers): Promise<Response> {
2
  const body = (await request.json()) as VisitPayload;
3
  const hostname = (body.hostname ?? "").trim().toLowerCase();
4
  const urlPath = (body.url ?? "/").trim() || "/";
5

6
  const websiteId = await resolveWebsiteId(db, hostname, env);
7
  if (websiteId === null) return json({ ret: "FAIL", msg: "unknown hostname" }, 400, cors);
8

9
  const ref = splitReferrer(body.referrer ?? "", hostname);
10

11
  await db
12
    .prepare(
13
      `INSERT INTO t_web_visitor (website_id, url_path, referrer_domain, referrer_path, visitor_ip)
14
       VALUES (?, ?, ?, ?, ?)`,
15
    )
16
    .bind(websiteId, urlPath, ref.domain, ref.path, visitorIp(request))
17
    .run();
18

19
  // 只回该路径的最新计数
20
  const row = await db
21
    .prepare(
22
      `SELECT COUNT(*) AS pv, COUNT(DISTINCT visitor_ip) AS uv
23
         FROM t_web_visitor
24
        WHERE website_id = ? AND url_path = ?`,
25
    )
26
    .bind(websiteId, urlPath)
27
    .first<{ pv: number; uv: number }>();
28

29
  return json({ ret: "OK", data: { pv: row?.pv ?? 0, uv: row?.uv ?? 0 } }, 200, cors);
30
}

访客 IP 取的是 CF-Connecting-IP——这是 Cloudflare 边缘注入的、最可靠的一个头，客户端伪造不了。取不到就留空，而不是写个 0.0.0.0 之类的哨兵值：哨兵值会让所有取不到 IP 的访问被 DISTINCT 合并成一个「访客」，UV 直接失真。

来源（referrer）则交给 splitReferrer() 拆成域名 + 路径，同站来源一律置空——站内互相跳转不是「外部来源」，留着只会污染数据。

端点二：GET /api/stats#

侧边栏卡片用的整站汇总，一次查询给全：

1
{
2
  "ret": "OK",
3
  "data": {
4
    "pageviews": 384,
5
    "visits": 76,
6
    "visitors": 49,
7
    "pages": 67,
8
    "todayPageviews": 0,
9
    "todayVisitors": 0,
10
    "since": "2026-07-18 14:58:53",
11
    "last": "2026-09-17 08:35:53"
12
  }
13
}

hostname 参数可以省略：会依次从 ?hostname=、Referer 头、请求自身的 host 里推断，怎么都能拿到。

访问数怎么算：窗口函数现算#

这是整套后端里唯一有点技巧的地方。库里没有会话字段，visits 必须每次现算：把同一个 IP 的记录按时间排好，相邻两条间隔超过 30 分钟就算一次新会话。

好在 SQLite 支持窗口函数（3.25+，D1 满足），一条 SQL 就能表达：

1
SELECT COUNT(*) AS visits
2
  FROM (
3
    SELECT create_at,
4
           LAG(create_at) OVER (PARTITION BY visitor_ip ORDER BY create_at, id) AS prev
5
      FROM t_web_visitor
6
     WHERE website_id = ?
7
  )
8
 WHERE prev IS NULL
9
    OR (julianday(create_at) - julianday(prev)) * 1440 > ?   -- 30 分钟

LAG(...) OVER (PARTITION BY visitor_ip ORDER BY create_at, id) 取的是同一访客的上一条记录；prev IS NULL 说明是该访客的第一条，必然是新会话；否则用 julianday() 把两个时间转成天、乘 1440 换算成分钟，超过阈值就计数。

ORDER BY 里那个 id 不是多余的——同一秒内可能有多条记录（CURRENT_TIMESTAMP 只精确到秒），只按 create_at 排序时相邻关系的顺序是不确定的。

窗口是 30 分钟，也做成了可配的 SESSION_GAP_MINUTES 环境变量。

一次配好 wrangler.jsonc#

后端零依赖，所以配置文件比代码还长。最要紧的三块：

1
{
2
  "name": "blog-analytics",
3
  "main": "src/index.ts",
4
  "compatibility_date": "2025-07-03",
5

6
  // 自定义域名：custom_domain: true 会让 wrangler 自动建 DNS 记录与证书
7
  "routes": [{ "pattern": "webana.142588.xyz", "custom_domain": true }],
8

9
  "d1_databases": [
10
    {
11
      "binding": "ANALYTICS_DB",
12
      "database_name": "web_analytics",
13
      "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
14
    }
15
  ],
16

17
  "vars": {
18
    "ALLOWED_ORIGINS": "https://blog.142588.xyz,http://localhost:4321",
19
    "SITE_HOSTS": "blog.142588.xyz",
20
    "SESSION_GAP_MINUTES": "30"
21
  }
22
}

三个细节值得单独说：

• custom_domain: true 不只是路由。它会让 wrangler 顺带把 webana.142588.xyz 的 DNS 记录和证书一起建好。这个子域名之前指向一个已删除的源站，一直报 CF 1016 origin_dns_error，部署这一步就顺手修掉了——不用再手动去控制台加记录。
• ALLOWED_ORIGINS 是 CORS 白名单，逗号分隔，命中才回显 Access-Control-Allow-Origin。换域名时最容易忘的就是这里，症状是浏览器报 CORS 而 Worker 日志里一切正常。
• SITE_HOSTS 是「允许自动登记」的域名白名单。库里已有的域名不受它约束；但陌生 hostname 想新建站点，必须命中白名单。没有这道闸，任何人构造一个请求就能往你的库里灌垃圾站点。

workers.dev 域名在中国大陆被 DNS 污染、直连不通，所以自托管统计必须走自有域名——这也是为什么要费劲绑 webana.142588.xyz 而不是直接用默认域名。

建库与部署#

假设数据库已经建好（首次要 npx wrangler d1 create web_analytics，把返回的 database_id 填进配置，再 npx wrangler d1 execute web_analytics --remote --file=./schema.sql 建表），日常部署就一条命令：

1
cd workers/analytics
2
npx wrangler deploy

⚠️ 本机环境有个坑：CLOUDFLARE_API_TOKEN / CLOUDFLARE_ACCOUNT_ID 这两个环境变量存在但无效（残留的旧凭据），wrangler 读到就会报认证错误 10000。显式清掉再跑就行：

1
env -u CLOUDFLARE_API_TOKEN -u CLOUDFLARE_ACCOUNT_ID npx -y wrangler deploy

部署成功后 GET https://webana.142588.xyz/ 应该返回一句健康检查，GET /api/stats 拿到整站数据，就算通了。

坑一：脚本的「启动块」必须放在最后#

这是整套前端里最阴的一个。SiteStats.astro 的脚本结构大致是：

1
function boot() { /* 用到 started / observer */ }
2
let started = false;
3
let observer: IntersectionObserver | null = null;
4

5
if (BASE && CFG.enable) {   // ← 启动块
6
  boot();
7
  window.swup?.hooks?.on("page:view", boot);
8
}

如果把启动块写在顶层、但排在 let started / observer 声明之前，boot() 里访问 started 就会踩 TDZ（暂时性死区）：

1
Uncaught ReferenceError: Cannot access 'started' before initialization

整段脚本当场挂掉，卡片永远停在「-」。而 Astro 编译不报错、astro check 不报错、语法检查也过——因为语法本身完全合法，只是执行顺序不对。定位它靠的是把脚本真跑一遍，不是读代码。

结论很简单：启动块一律放脚本最后。这不是风格问题，是正确性问题。

坑二：不要编假数字#

很多统计卡片会在接口失败时显示一组写死的数字「撑场面」。本站最初也这么干，后来改掉了：fallbackStats 默认 null，接口挂了就保持「-」。

理由是那行数字的意义就是「真实」。显示一组假的，比显示「-」更糟——访客以为自己看到了数据，站主也失去了「后端挂了」这个无声的信号。（顺带一提，如果确实想要原站那种行为，显式配 fallbackStats: { pageviews: 1000, … } 就行。）

坑三：SITE_HOSTS 白名单不能省#

前面提过一次，但值得再强调：埋点接口是公开的，谁都能 POST。如果不做任何限制，别人只要构造一个 hostname: "abc.com" 的请求，你的库里就会多出一个站点、并开始累计垃圾数据。

本站在 resolveWebsiteId() 里分成两步：库里已有记录的域名照常放行（localhost、pages.dev 这些历史域名不能被拦），新域名则必须命中 SITE_HOSTS 白名单才会被登记，否则直接 400 拒绝。

症状：页面正常，后台不动#

某天发现侧边栏的统计数字一直在涨，但文章的 PV / UV 数字卡住了。页面本身没有任何异常：没有报错弹窗、没有加载失败、控制台也没有红色。

原因藏在埋点的 catch 里——统计失败是静默处理的（这是对的，统计不该影响页面），所以后端挂了，前端一声不吭。

定位：CF 1016 与一条 NXDOMAIN#

把 webana.142588.xyz 拿到浏览器里直接访问，得到的是 Cloudflare 的 1016 origin_dns_error（HTTP 530）：源站不存在。

也就是说，这个域名指向的那个 Worker 已经被整个删掉了，而不是代码报错或数据库故障。埋点从那天起就一直在失败，只是没人知道——因为它是静默的。

转折：数据一条没丢#

真正让人松一口气的是下一步：D1 库还在。

统计数据和 Worker 是两码事。Worker 被删了，数据仍然躺在账号的 D1 里：

两个月的数据、一条记录都没丢。所以这次不是「从零重建」，而是把后端原地接回来。

恢复：沿用同一个库，前端一行不改#

重建时只需要守住一条原则：请求 / 响应格式与原来完全一致。

• database_id 指向原来的 web_analytics，不建新库、不导数据；
• POST /api/visit 的入参（hostname / url / referrer）和返回（{ ret, data: { pv, uv } }）照旧；
• routes 用 custom_domain: true 把 webana.142588.xyz 重新绑回来，DNS 记录和证书自动重建，顺手把 1016 修掉。

结果就是前端配置一个字都不用改——webvisoConfig.baseUrl 还是那个地址，只是它背后的 Worker 换了个实现。

部署上线后实测：

历史数据无缝接上，文章顶部那行「N 次浏览 / N 位访客」也跟着一起复活了。

这次事故留下的三条经验#

1. 「前端正常」不等于「后端正常」。静默失败的埋点是最危险的一类——它不会报错，只会安静地不干活。定期 GET /api/stats 看一眼 last 字段（最后一条记录的时间）就能发现异常。
2. 数据和计算要分开存。这次能全身而退，唯一的原因是数据在 D1 里、而 D1 没被删。如果统计是「Worker 内存里计数、定期落盘」那种设计，Worker 一删就全没了。
3. 接口格式是前后端的契约。正是因为重建时严格保持了响应格式，前端才做到了零改动——这条约束在平时看着多余，出事时就是救命的那根绳。