网页统计的首屏 HTML 也要做验收
网页统计先写入 HTML,再由浏览器脚本用实时接口更新,因此爬虫看到的数值可能和浏览器不同。minia2a 的监控曾将 20 个位置误报为过期,根因是用于校验的台账缺少四个统计键。
AI 深度解读
浏览器里的仪表盘数字是对的,监控却报了 20 处过期。minia2a 团队查到,页面刚被定时任务正确写过,监控用来核对的日志却漏了字段。它只好拿静态 HTML 去比实时接口,把两次更新之间的正常差值当成了故障。
如果你的页面先在 HTML 里放一份统计数据,再用 JavaScript 刷新,这个案例给了一个可直接照搬的检查思路。先确认页面上是不是最近一次发布的值,再检查那次发布距今多久。浏览器里看到的最新数字,只能回答其中一部分问题。
浏览器刷新后,谁还在读 HTML 里的数字?
minia2a 在博客之外有 202 个数据位置,复用 9 个统计键,覆盖服务目录、试用、钱包用户、独立 IP、链上支付和付费调用等数据。定时任务每小时把数字写进 <span data-stat="…">,浏览器里的 /js/live-stats.js 再用实时接口的数据刷新一遍。
用 curl 取页面,或者由只抓取原始 HTML 的索引器读取页面时,拿到的是定时任务写进去的那份。前端同学打开浏览器看到新值,最多能确认客户端刷新生效。原始 HTML 是否发布了正确的值,还得单独查。
作者给出的发布时快照是 1,888 个服务,5,458 个不同地址用掉 44,550 次试用调用,其中 300 个签署了钱包,另有 416 笔支付在链上结算。作者说这些数字同时出现在页面 HTML 和 /api/stats。文首标注的计费模式是 x402 按次付费,仅支持 Base 上的 USDC,每个签名钱包有 5 次免费试用,无积分和充值通道。
为什么刚更新过的页面会报 20 处过期?
02:45 UTC,监控在 13 个页面上报了 20 个 STALE,全都集中在 trials 和 users。例如 index.html:767 的试用次数是 44,548,实时值是 44,550。index.html:771 的用户数是 5,457,实时值是 5,458。写入任务在 02:29:02 UTC 已经报告成功。这十几分钟里,实时值继续增长很正常。
监控原本会先查写入日志。如果页面值与最近一次写入记录相符,而且任务刚跑过,它就是正常滞后。如果页面值和最近一次写入记录对不上,即使任务刚报成功,也要查页面写入或发布链路。
问题在于,当时日志只记了 services、wallets、agents、requests 和 trialEndpoints。每小时实际写入的 trials(19 处)、users(3 处)、onchain(2 处)和 calls(1 处)都没进日志。监控找不到这些键,就退回去和实时值比较。原文列的这些位置数是各键的覆盖范围,当次告警是其中 20 处。2026-10-02,agents 也曾因为写了页面却漏记日志,导致每次有新注册就报红,直到下一轮任务。
怎么证明这次测试真能抓到漏字段?
团队让写入任务记录全部 9 个键,并在监控的 LEDGER_FIELDS 里补全映射。下面这段测试用写入端的原始字段检查监控是否会漏掉那 4 个键。
raw_writer = {"services": 1888, "wallets": 300, "agents": 300,
"trials": 44548, "users": 5457, "calls": 384, "onchain": 416,
"requests": 9707759, "trialEndpoints": 1643}
logged = ledger_expected(raw_writer)
for k in ("trials", "users", "calls", "onchain"):
if k not in logged:
fails.append(f"writer logs {k}= but ledger_expected() drops it")
关键是 logged = ledger_expected(raw_writer)。如果直接手填 logged,测试就绕过了可能丢字段的映射。作者还恢复了旧的 5 键映射,确认同一测试会立刻在 trials 上失败。
作者也贴出了修复后的现场检查,先跑写入脚本,再跑监控。
$ python3 scripts/wire-page-stats.py --audit
live: services=1888 … trials=44550 users=5458 calls=384 onchain=416 …
changed: 18 file(s)
$ python3 tools/span-freshness-guard.py
slots checked against live values: 202
blog/ slots excluded by design: 8
STATUS: clean — every served slot outside blog/ is live and every key is maintained
changed: 18 file(s) 表明这次 --audit 运行报告了文件变动。监控检查了 202 处,按设计排除了 blog/ 的 8 处。
我的判断
这套办法适合有固定发布节奏、能拿到写入记录的页面。对每小时更新一次的 HTML,直接和实时 API 比相等,会把更新频率的差异算成错误。连续两次漏字段,以及恢复旧映射后测试确实失败,都是作者在自己项目里报告的结果。至于误报会让团队逐渐忽略告警,原文没有给出对照数据,这是经验判断。
如果 HTML 和 API 本来就读同一份快照,用快照版本核对也能判断页面有没有发布到位。遇到 CDN 缓存或分批部署,还要想清楚监控请求拿到的是哪个版本、允许落后多久,原文没给出这部分的配置。另一个边界是,作者建议从同一份字段清单生成页面写入和日志,文中实际展示的是补齐日志、补齐映射并加回归测试,共用清单是否已经落地没有交代。
能拿来做什么
- 给带统计数字的前端页面加一条原始响应检查。用
curl查 HTML 里的data-stat,确认客户端脚本运行之前,每个公开指标就有可读的值。 - 如果用 Node 定时生成页面,从同一份字段定义生成 HTML 和结构化写入日志。监控先核对最近发布的值,再按任务周期判断更新是否超时。
- 让 AI 编程助手补这类回归测试时,要求它走生产代码里的字段映射,并临时删掉一个映射键确认测试会失败。手填一份完整的预期日志容易把故障点绕过去。