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:
- HTTP 方法为
GET; - 最终状态码
200; - 响应内容类型包含
text/html; - 路径不在
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 群