docs(deploy): document PV/UV stats and real client IP via nginx realip

README.md

@@ -22,6 +22,7 @@
 | 搜索发现与候选池 | 可用（P3） | 每小时搜索前 2 页，分类打分后写入候选池。 |
 | Telegram 通知与入库 | 可用（P3） | 入库 / 忽略 / 拉黑按钮；私聊消息手动入库。 |
 | 本地数据看板 | 可用（P2/P9） | 只读总览、视频榜、UP 主榜、内容效率、视频/UP 详情、粉丝曲线、数据说明、候选池和系统状态。 |
+| 访问统计（PV/UV） | 可用 | 前端埋点上报，按客户端 IP 与页面去重；先落内存、每分钟批量入库；系统页展示近 30 天。 |
 
 ## 核心工作流
 
@@ -176,10 +177,11 @@ uv run python app.py serve --preview --config data/preview/config.json
 - 粉丝页只绘制粉丝曲线，不叠加视频数据；支持 7/30/90/全部与自选日期，范围超过一年时按每月峰值日期聚合；最近记录默认 14 天并显示较上一成功日的增量；
 - 前端使用 History API 的干净路径路由（`/videos`、`/ups`、`/video/{aid}`、`/up/{mid}`、`/about`），不使用 `#/` hash；旧 `/rank` 链接仍可用；
 - 候选池和系统状态只读展示，操作入口指向 Telegram/CLI；
+- 系统状态页展示访问统计（近 30 天每日 PV/UV 与 Top 页面）：前端在整页加载与站内路由切换时通过 `navigator.sendBeacon("/api/visit")` 上报，服务端按客户端 IP 与归一化路由聚合，先写内存缓冲、每分钟批量落库（详见 [访问统计与真实来源 IP](#访问统计与真实来源-ip)）；
 - 首页、视频榜、UP 主榜、视频/UP 详情、粉丝页和数据说明页对访客可见；
 - 配置 `web.auth_token` 后，“候选”和“系统”页面及其接口需要登录，启用登录页和 HttpOnly Cookie；访客的底部导航只显示公开页面；
 - 本地回环地址且未配置 token 时视为无鉴权，全部页面可见；非回环地址且未配置 token 时拒绝启动；
-- 所有业务接口只接受 GET，写方法返回 `405`；
+- 所有业务接口只接受 GET，写方法返回 `405`；仅显式放行 `POST /api/visit`（访问统计埋点）与 `POST /login`（会话），其余 POST/PUT/PATCH/DELETE 仍统一 `405`；
 - 首页/榜单聚合结果缓存 1 小时，粉丝结果缓存 24 小时；快照、发现、入库/忽略/拉黑、候选清理和粉丝 CSV 导入会立即让对应缓存失效。
 
 ### 预览数据
@@ -227,6 +229,28 @@ uv run python tools/import_fans_csv.py --csv E:\Downloads\history.csv --replace
 - 写入前建议先备份 `data/app.db`，例如 `data/backup/app-pre-fans-YYYYMMDD.db`；
 - 容器内运行时用 `--db /data/app.db` 或 `--config /config/config.json`，避免默认去找 `/app/config.json`。
 
+## 访问统计与真实来源 IP
+
+看板提供基础访问统计（PV/UV）。前端在整页加载与站内路由切换时通过
+`navigator.sendBeacon("/api/visit")` 上报路径；服务端按 `(日期, 客户端 IP, 归一化路由)`
+聚合，**先写入进程内缓冲、每分钟批量落库**到 `visit` 表，`/system` 系统状态页展示近
+30 天每日 PV/UV 与 Top 页面。
+
+统计按客户端 IP 去重，因此反代必须还原真实客户端 IP。链路为
+`域名 → CDN → 公网 EIP → 云服务器内网 → 宿主机 nginx → 127.0.0.1:8080(容器)`：
+容器内看到的 socket 对端是 Docker 网关，真实 IP 只能来自 nginx 注入的请求头。
+
+- nginx 用 `realip` 模块按 CDN 网段把真实 IP 归一化到 `$remote_addr`，再写
+  `X-Real-IP` 传给容器；直连公网 EIP 时 `$remote_addr` 本身就是客户端；
+- 应用只读 `X-Real-IP`，且仅当 socket 对端属于可信代理网段时采信，否则回退对端，
+  因此直连请求伪造的 `CF-Connecting-IP` / `EO-Connecting-IP` / `X-Forwarded-For` 无效；
+- 三种来源（直连 EIP / Cloudflare / EdgeOne）的完整 nginx 配置、网段刷新脚本与
+  配置项说明见 [`deploy/nginx/README.md`](deploy/nginx/README.md)。
+
+`config.json` 中的 `web.track` 控制统计行为：`enabled` / `header_order` /
+`trusted_proxies` / `count_bots` / `flush_seconds` / `keep_days` /
+`max_hits_per_ip_path_per_day`；默认过滤常见爬虫 UA、每分钟落库、保留 180 天。
+
 ## 快速部署（Docker）
 
 仓库根目录已包含 `Dockerfile`、`compose.example.yml`、`.dockerignore` 和 `config.docker.example.json`。Compose 文件是示例，需要显式指定：
@@ -298,6 +322,7 @@ Copy-Item config.example.json config.json
 - `track_fans`：需要每日追踪粉丝数的 UP mid；
 - `discover`：搜索关键词、页数与时间窗（`keywords` / `pages` / `window_days`）；
 - `storage`：数据库与备份目录；
+- `web`：绑定地址、端口、访问令牌与 `web.track`（访问统计开关、可信代理网段、上报头顺序、落库周期与保留期）；
 - `schedule` / `notify` / `classify` / `heat_weights`：任务节奏、通知阈值、分类规则和热度权重。
 
 配置每 60 秒检查一次 mtime，凭据、分类规则等变更无需重启即可在下次任务读取；但 `schedule.discover_minutes` 与 `schedule.snapshot_at` 在启动时固化，修改后需重启 `run` 进程。
@@ -398,6 +423,8 @@ uv run python tests/test_auth.py            # Cookie 合并、设备指纹、Set
 uv run python tests/test_moves.py           # 排序移动脚本：随机排列与头部用例
 uv run python tests/test_favsort_http.py    # favsort httpx 请求头与匿名回退
 uv run python tests/test_config.py          # 配置加载、校验、ENV 覆盖与热加载
+uv run python tests/test_client_ip.py       # 来源 IP 提取、路由归一化与机器人判定（纯函数）
+uv run python tests/test_visits.py          # 访问统计内存缓冲、批量落库与保留期清理
 uv run python tests/test_migrations.py      # 迁移、备份、回滚与保留期
 uv run python tests/test_database.py        # 单写队列、事务与并发
 uv run python tests/test_repository.py      # 收藏夹/视频状态机与黑名单
@@ -416,8 +443,8 @@ uv run python tests/test_timeutil.py        # 上海时区与每日任务时间
 uv run python tests/test_analytics.py      # 热度、互动率、增长与封面
 uv run python tests/test_preview_seed.py   # 预览库回填、确定性与安全边界
 uv run python tests/test_fans_csv.py       # 粉丝 CSV 解析、替换与幂等回填
-uv run python tests/test_web_queries.py    # 看板查询层与冷启动
-uv run python tests/test_web_server.py     # 只读路由、鉴权、静态资源与预览模式
+uv run python tests/test_web_queries.py    # 看板查询层、冷启动与访问统计聚合
+uv run python tests/test_web_server.py     # 只读路由、鉴权、静态资源、访问统计与预览模式
 uv run python tests/test_scheduler.py       # 内置调度器到期/失败隔离
 uv run python tests/test_provider.py        # 凭据变化重建客户端与配置 revision
 uv run python tests/test_favsort_run.py     # 排序参数校验与混合资源类型