GoPress Analytics 插件

gopress-analytics 是 GoPress 官方自托管访问统计插件，无需接入第三方 Analytics 服务，即可在后台 Dashboard 查看 PV、UV、新访客、会话数、每日趋势、热门页面、访客构成和 IP 归属国家分布。

采集方式

插件通过 middleware.early 在页面缓存之前注册中间件，因此缓存命中也会计数。它只采集前台成功的 GET HTML 响应，并排除后台、API、静态资源、健康检查、Swagger、sitemap、robots、favicon 和已识别爬虫。

请求线程只把事件投递到有界内存队列；插件 worker 以 5 秒为一个窗口，先按访客、会话、日期和页面维度在内存中聚合，再批量写 PostgreSQL，数据库写入不位于页面渲染关键路径。默认窗口最多保留 2000 个原始事件，超过容量的事件会被丢弃并计入内部 dropped 计数，避免异常流量导致内存无限增长或持续放大数据库写入。

数据与隐私

插件自有表保存事件、访客、会话、每日汇总、页面汇总、精确 UV 去重桥接记录、每日维度汇总，以及用于维度 UV 精确去重的维度/访客桥接记录。原始事件包含：

页面路径、语言、来源站点和 UTM 归因。
明文 IP，以及使用站点密钥生成的不可逆 IP Hash。
User-Agent，以及归一化设备类型、平台、厂商、浏览器和操作系统。
本地 DB-IP Lite GeoIP 库可用时解析得到的国家代码。

明文 IP 和 User-Agent 属于原始个人数据。设置页可选择 30、60、90 或 180 天保留期，到期后自动删除事件和会话；每日聚合与匿名访客/日期去重桥接记录长期保留，确保历史 7/30/90 天报表仍准确。在适用地区启用前，应同步更新隐私政策和 Cookie 告知。

GeoIP 归属库

插件可在 plugins/gopress-analytics/data/dbip-country-lite.csv.gz 保存本地 DB-IP Lite 国家库。设置页会显示文件是否已加载、记录数和文件时间；拥有 plugin.update 权限的用户可以点击 GeoIP 更新按钮，把当前月份国家库下载到插件目录。

GeoIP 查询在文件加载后使用内存索引完成，请求链路不会访问外部服务。国家维度写入通用 daily_dimensions 表，并通过维度访客桥接表保证 UV 精确去重。如果文件缺失、文件无效，或访问 IP 是私网/本机地址，国家字段会保持为空，采集流程继续正常工作。使用默认 DB-IP Lite 下载源时，请按其授权、署名和隐私要求处理站点部署合规。

权限

Dashboard JSON 接口和原始事件查询接口强制要求 analytics.read。超级管理员通过通配策略拥有该权限，编辑角色在插件激活期间获得只读能力，其他角色不能读取统计数据。插件设置仍由 core 的 plugin.read / plugin.update 权限保护，GeoIP 文件更新接口明确要求 plugin.update。

当前 MVP 边界

第一版聚焦聚合访问统计和国家分布。停留时间、转化事件、设备分布、实时访客、漏斗、导出和更完整的原始事件排查界面留待后续版本。