This repository was archived by the owner on Jul 6, 2026. It is now read-only.
添加第一方匿名访问 UV/PV 统计 - #90
Merged
Merged
Conversation
Track anonymous page visits separately from diagnosis usage so admin stats can report real PV/UV without third-party analytics.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景与为什么要改
当前后台
/admin里已有“请求数 / IP”等统计，但这些指标来自usage_log，本质上统计的是用户发起诊断、生成、解析等业务请求，不是用户访问页面的真实 PV/UV。这会带来几个问题：
/app页面但没有发起诊断的用户不会被统计到。/admin放在一起看。所以这次改为第一方、服务端、自有数据库里的匿名访问统计：保留原有业务请求统计，同时新增真正的页面 PV/UV。
这次改了什么
1. 新增第一方访问打点接口
新增
POST /api/visit，用于记录页面访问。实现点：
backend/app/api/visit_api.py。IP + User-Agent + VISITOR_HASH_SALT生成不可逆visitor_hash。visitor_hash、user_agent_hash、访问路径和时间。visit_log。visit_log，避免 URL 中可能携带敏感参数。navigator.sendBeacon常见的text/plain;charset=UTF-8JSON body。2. 数据库启动时自动补表
在后端启动初始化逻辑里新增
visit_log表和索引：visit_logidx_visit_createdidx_visit_visitoridx_visit_path这样线上旧库升级时不需要跑
make data，只要后端正常启动，就会自动补齐新表结构。3. 后台
/admin改成真实访问 PV/UV/admin/api/stats新增这些字段：total_pvtotal_uvtoday_pvtoday_uvvisits_by_pathvisit_hourly_24h后台页面展示也调整为：
也就是说：访问统计和诊断请求统计分开，不再把业务请求 IP 当作真实访问 UV。
4. React
/app页面打点前端新增
trackVisit()，并在BrowserRouter basename="/app"内根据路由变化打点。这样用户访问：
/app//app/report/app/history/app/diagnosing这类 SPA 页面时，后台都能看到真实路径访问分布。
5. 静态页面也加入打点
以下静态页
<head>中加入同样的第一方访问打点脚本：docs/research_whitepaper.htmldocs/privacy.htmldocs/terms.html这样非 React 页面也会进入统一 PV/UV 统计。
6. 隐私政策文案同步更新
docs/privacy.html原文写的是“不追踪您的浏览行为”，但新增第一方访问统计后，这句话不再准确。本次更新为明确披露：
能解决什么问题
/app/、/privacy、/terms等。usage_log统计，不影响现有诊断请求、token、耗时、分类等业务分析。可能带来的好处
/admin，不需要额外接入分析平台。visit_log后续可以继续支持路径趋势、来源概览、页面转化等，但本 PR 没做过度扩展。可能的坏处 / 风险 / 注意事项
visit_log，因此不会凭空拥有历史 PV/UV；历史诊断数据仍保留在usage_log。visit_log。目前写入很轻量，但高流量下 SQLite 仍需要关注磁盘和写锁情况。backend/data/baseline.db是运行时数据，里面包含业务历史和访问日志，不能随代码发布覆盖，也不应该提交到 GitHub。make data：make data是本地初始化/演示数据生成流程，会重建 baseline 数据，不适合线上保留业务数据的环境。上线 / 运维注意事项
上线前建议：
备份线上数据库：
cp backend/data/baseline.db backend/data/baseline.db.bak.$(date +%Y%m%d%H%M%S)更新代码。
重启后端服务，让启动逻辑自动创建
visit_log表和索引。不要执行
make data。打开
/admin检查：total_pv / total_uv正常显示。/app/后 PV 有增长。本地验证
已在本地执行：
make -C /Users/flashingchen/Coding/VibeCoding/noterx test14 passed, 1 warningnpm --prefix /Users/flashingchen/Coding/VibeCoding/noterx/frontend exec tsc -- --noEmitnpx --prefix /Users/flashingchen/Coding/VibeCoding/noterx/frontend vite build/admin/api/stats?password=pageonetotal_pv / total_uv / today_pv / today_uv / visits_by_path/api/visitsendBeacon风格的text/plain;charset=UTF-8payload 可正常写入不包含什么
backend/data/baseline.db。