访问统计插件

给官网/站群用的轻量访问统计:服务端采 PV/UV、IP 归属地、来源与设备,自带 /visit 分析后台,不引第三方脚本。

最后更新

Known.Visit 是 Known 的访问统计插件。它用服务端中间件记录每一次真实页面访问, 把「谁(IP + 归属地)、什么时间、看了哪个页面、从哪来、什么设备」落进数据库, 并自带一个 /visit 分析后台。整条链路不依赖前端 JS,也不向百度/GA 发任何请求。

能回答什么问题

维度 记录内容
谁 IP、国家/省/市、运营商、访客 ID、会话 ID、登录用户(有则记)
何时 精确时间、按天(VisitDate)、按小时(VisitHour)
看了什么 页面路径、查询串、页面标题、状态码、耗时
从哪来 来源类型(直接 / 站内 / 搜索引擎 / 社交媒体 / 外部链接)、来源域名、完整 Referrer
什么设备 User-Agent、浏览器、操作系统、桌面/移动/平板、是否爬虫

报表侧提供:概览(PV/UV/会话/IP、环比、24 小时趋势)、页面排行、访客明细, 以及来源、地域、设备、浏览器、爬虫、未解析归属地六张排行。已过去的日期读按天汇总表, 今天读明细;日期在写入时已预计算,换 SQLite / SQL Server / MySQL 都不用改 SQL。

接入一个站点

三步,两个官网(Website 与 ERPLite Website)的现有接线可以直接照抄:

// Program.cs —— Build 之前
builder.Services.AddKnownVisit(o => builder.Configuration.GetSection("Visit").Bind(o));

// Build 之后、端点执行之前
app.MapVisitEndpoints();   // /visit/auth、/visit/logout、/visit/retry-location
app.UseKnownVisit();       // 采集 + 后台门禁
@* App.razor —— 让 Blazor 扫到插件页面 *@
<Router AppAssembly="typeof(Program).Assembly"
        AdditionalAssemblies="new[] { typeof(Known.Visit.Pages.VisitOverview).Assembly }" />

插件会通过 AddPluginSetup 自动建 SysVisitLog(明细)、SysVisitIpLocation(归属地缓存) 与 SysVisitDailyStat(按天汇总)三张表,无需手写迁移。

配置

{
  "Visit": {
    "SiteId": "known",
    "SiteName": "Known 官网",
    "AdminKey": "",
    "IpLocationEndpoint": "http://ip-api.com/json/{ip}?lang=zh-CN&fields=status,country,regionName,city,isp",
    "IpLocationTimeoutSeconds": 3,
    "RetentionDays": 180,
    "PageTitles": { "/": "首页", "/docs": "文档中心" }
  }
}
  • SiteId:站点唯一键。两个官网共用一个库也不会串数据;报表只统计本 SiteId。
  • AdminKey:/visit 后台的访问密钥。留空 = 后台显式关闭(/visit 直接 503), 采集本身照常。生产环境用环境变量 Visit__AdminKey 注入,不要提交真实密钥。
  • IpLocationEndpoint:公网 IP 归属地接口,{ip} 为占位符。兼容 ip-api.com 与 ipinfo.io 两种字段命名。
  • PageTitles:路径 → 中文名。未配置的路径直接显示原路径。

登录方式:浏览器打开 /visit,未授权会跳到 /visit/login,输入密钥后写一个 SHA-256(SiteId|AdminKey) 摘要 Cookie(7 天),不落明文。退出走 /visit/logout。

明暗主题

后台没有自己的配色和主题脚本,所有颜色都引用宿主页面的主题令牌:官网的 --bg / --surface / --line / --text / --brand,或框架 web.css 的 --bg-app / --bg-card / --border-color / --text-primary。visit.css 顶部的 --visit-* 只做一层别名与回落,派生色(悬停、虚线、提示底、阴影)用 color-mix 计算。

所以站点在 <html> 上切 data-theme 时,/visit 会跟着一起变,不需要插件自己的 JS, 后台也不额外放主题按钮——在站点上切好再进来即可。接入方不需要改任何样式或脚本。

采集口径与排除

只有同时满足下面四条才记一条 PV:

  1. HTTP 方法为 GET;
  2. 最终状态码 200;
  3. 响应内容类型包含 text/html;
  4. 路径不在 ExcludePathPrefixes(默认排除 /visit、/api、/demo、/downloads、 /health、/sitemap.xml、/robots.txt、/favicon.ico、/not-found、/error)。

静态资源靠扩展名二次过滤(.css、.js、.png 等)。/not-found 与 /error 必须排除: 状态码回退页会被 StatusCodePages 重新执行一次管道,不拦住就会把每一次 404 记成一次访问。

访客身份用两个 Cookie:known_visit_vid(365 天)与 known_visit_sid(30 分钟滑动)。 两者都是 HttpOnly + SameSite=Lax,只用于 UV/会话去重,不参与登录。

失败时看到什么

  • 归属地解析失败:显式落「未知」,同时记 Success=0、FailCount、LastError; 成功与失败都缓存(正缓存 24 小时、负缓存 10 分钟),不会每个请求都打远端接口。 概览页显示「未解析归属地 N 条」并提供重试补全(POST /visit/retry-location)。
  • 队列满:采集走有界内存队列(默认 10000),写库由后台服务批量完成; 队列满时丢弃并计入 VisitHealth.Dropped,可在健康检查里看到,不会阻塞用户请求。
  • 未配密钥:后台 503 并在启动日志里记 Warning,而不是静默暴露一个空后台。

数据量与按天汇总

明细表再大也不会把报表拖垮,因为查询分两段:

  • 今天:直接读 SysVisitLog,保证概览上的今日数字是实时的;
  • 昨天及更早:读 SysVisitDailyStat,每个「站点 + 日期 + 维度(总计/页面/来源/域名/地区/设备/浏览器)
    • 是否爬虫」一行,报表只做 sum / group by,代价和明细总量无关。

汇总由后台任务维护:启动后补最近 RollupBackfillDays 天(默认 30)的缺口, 之后每 RollupIntervalMinutes 分钟(默认 30)重算一次昨天。某一天的汇总缺失时, 报表读取会自动补算那一天,不会出现「昨天是空的」这种静默错误。

口径上要注意:跨天区间的 UV、访问次数、IP 数是「按天去重后求和」,同一个人连续两天访问 会被计 2 次;新访客按「历史上第一次访问落在当天」逐日累加,这个口径是精确的。 需要精确跨天去重只能回明细扫,不建议在报表里做。

新增维度时,同时改 VisitRollup.Dimensions(聚合列白名单)与报表里对应的 RankAsync 调用,两边不一致会漏掉该维度。

数据保留

明细默认自动清理:VisitCleanupWorker 每天执行一次,删除早于「今天 − RetentionDays」的明细, 默认保留 180 天;把 RetentionDays 设为 0 即永久保留。

删除前会先把这些日期的汇总补齐(VisitRollup.CleanupAsync),所以:

  • 历史报表不受影响,PV / UV / 趋势 / 排行仍按汇总表出数;
  • 只失去对应日期在「访客明细」页的下钻;
  • 只删除本 SiteId 的明细,同库的其它站点不受影响。

有一个口径副作用要提前知道:超过保留期的明细被删后,老访客再回来时已经没有更早的访问记录, 会被「首次访问」判定算成新访客,NewUv 相应偏大。需要长期精确的新访客口径,就把 RetentionDays 设为 0 或调大保留窗口。

首次启用清理时,如果历史明细从未汇总过,会在后台先把这些日期补算一遍再删, 数据量大时第一次会多花一些时间。

SysVisitLog、SysVisitIpLocation、SysVisitDailyStat 都是 [GlobalTable],跨租户汇总; 站点隔离由 SiteId 列保证。

微信公众号二维码 扫码关注公众号
QQ 交流群二维码 扫码加入 QQ 群