官网 CMS 建站平台 v1.3.0：访客统计子系统重大更新

版本：v1.2.0 → v1.3.0　日期：2026-09-20　模块：访客统计（visitor statistics）

一、这次更新解决什么

官网页面由 nginx 直接静态托管，Node 后端看不到页面访问——因此「来访统计」无法像普通应用那样从请求链路直接拿，必须从零搭建采集与展示子系统。

本次更新把一整套来访采集与统计子系统补齐并做了生产级增强：从 nginx 日志采集 → IP 归属地 → 真实访客甄别 → 后台展示，全链路闭环。

二、核心变更

1. 采集内核 visit.js（新增，964 行）

• nginx 日志增量采集：基于 inode + 字节偏移增量读取 access.log，支持日志轮转与 .gz 历史回填（--backfill），不重不漏。
• 引号感知解析：UA / Referer 内含空格，按空格 split 必错，改为按引号配对解析。
• 页面归一化、爬虫识别、内部流量标记：来源页 / 设备 / 地域归类；排除老板与公司出口 IP，避免自己刷自己。
• 前端心跳处理：消费 /api/zry/visit/beat 上报，回填停留时长、维护在线表。
• 批量写库 + 每日聚合 + 保留期清理。
• 运维入口：node node/zry/visit.js --once | --backfill | --status | --mock。

2. 归属地 geo.js（增强：ASN / 运营商 / IP 类型）

• 离线 ip2region（.db / .xdb 自动探测）四级兜底链。
• 新增 ASN / 运营商 / IP 类型：离线 mmdb + ip138 在线兜底写入 zry_ip_geo 缓存。
• 修复历史缺陷：原 upsertVisitors 字段名错配导致 zry_visitor.geo_last 100% 空白；本次随库迁移一并历史回刷。

3. 真实心跳甄别（anti-bot 关键能力）

• 前端每 5 秒发送 t=3 心跳（site.js，后台标签不发送以省资源）。
• 新增归档表 zry_visit_beat（进入 / 离开 / 心跳全留痕，可审计回放）。
• zry_visit_online 增加 beat_count / has_heartbeat；zry_visit 增加 has_heartbeat 并历史回刷。
• 后台可据此甄别「真实访客（真人 / 真实浏览器）」与「只进入不心跳的可疑访问（bot / 无头浏览器）」。

4. 后台能力（http.js 新增 10+ 接口）

• 公开：POST /api/zry/visit/beat（前端行为上报）
• 后台（JWT 鉴权）：来访汇总、明细列表、访客档案、访客备注、数据导出、当前在线、真实心跳甄别、真实心跳历史、手动触发采集、保留期清理、反爬统计

5. 数据模型变更

升级脚本（幂等，可重复执行）：

• zry_upgrade_20260920_geo_asn.sql
• zry_upgrade_20260920_heartbeat.sql
• zry_upgrade_20260920_heartbeat_history.sql

三、统计口径说明（重要）

• 数据来自 nginx 访问日志；站点无 CDN，$remote_addr 即真实客户端 IP。
• 爬虫 / 扫描流量占比高，已做识别与排除；内部 IP 已排除，统计不含自己。
• 「真实访客」以 has_heartbeat 为准；仅进入未心跳的访问标记为可疑，不计入真实访客。
• 日志保留约 52 天，可回填近 1 年历史趋势。

四、部署与升级

1. 先执行三个 2026-09-20 升级 SQL（已含历史回刷，幂等）。
2. 设置环境变量 ZRY_JWT_SECRET（生产必填，开源版已移除内置默认密钥）。
3. 启动采集长驻进程：collector.js（pm2 独立进程）负责周期性采集。
4. 归属地回刷：采集器自动按 zry_ip_geo 缓存补全；历史空白行已随库迁移回填。

五、安全与开源说明

• 本次同步已做全面脱敏：生产数据库凭据、JWT 默认密钥、联系电话 / 邮箱、生产部署绝对路径、生产数据库端口均替换为环境变量 / 占位符 / 通用路径。
• 运维 / 挂载类脚本（node/zry/tools/）不随开源库发布：该类脚本直接读取生产库配置中的明文口令、硬编码生产绝对路径，属内部 ECS 运维脚本，对外既泄露生产内情又属不良示例；其 geo 回刷等逻辑已内化于采集器。
• 推送前已通过敏感信息门禁扫描（REAL_HITS = 0）。