OpenFlare/docs/plan/20260719-access-log-ip-tab.md

访问日志 IP 明细 Tab — 实现计划

1. 目标与背景 (Goal & Context)

• 需求背景：运维需要按 IP 维度快速查看时间窗内的访问量与流量，并下钻单 IP 情报；原先 IP 分析嵌在「单条访问日志详情」中，入口弱、列表能力缺失。
• 开发范围 (Scope) V1：
  • 访问日志页新增第三 Tab 「IP 明细」（?tab=ips）。
  • IP 列表：时间筛选（快捷 24h/7d/15d/30d + 自定义 since/until）、分页、按请求数 / 入站 / 出站 / 最后访问 / 2xx 比例排序。
  • 列表列：IP、地区、请求数、2xx 比例（2xx 数 / 总请求）、入站流量、出站流量、最后访问。
  • 行详情：弹窗展示完整 IP 情报（分析 + 趋势 + Top 分布 + 加入 WAF IP 组）。
  • 日志明细详情弹窗仅展示单条请求字段，不再内嵌 IP 情报；如需分析请到 IP 明细。
• Out of Scope（V1 不做）：
  • 独立 /access-logs/ip 子路由全页。
  • IP 列表 UI 暴露节点 / host 筛选（后端可保留兼容参数，前端首版不放）。
  • 入/出站带宽时间序列（趋势图仍为请求数）。
  • 实时 GeoIP 二次查询（沿用入库 region）。

2. 设计与决策 (Design & Decisions)

2.1 页面与交互

Tab	URL	内容
概览	/access-logs	不变
IP 明细	/access-logs?tab=ips	新
日志明细	/access-logs?tab=list	不变；详情弹窗瘦身

• 时间筛选（IP 明细）：
  • 快捷：hours ∈ {24, 168, 360, 720}，默认 168（7d）。
  • 自定义：since + until（RFC3339）；同时提供时覆盖 hours。
• 详情形态：留在列表页的 Dialog（非独立子页）。
• 日志详情瘦身：access-log-detail-dialog 只渲染请求字段（时间、节点、IP、地区、host、path、UA、cache、status 等）及必要操作；删除 analysis/trend/WAF 组内嵌区块。WAF「按 IP 加入组」仅保留在 IP 详情弹窗。

2.2 API 设计（扩展现有端点，不新建）

GET /api/v1/d/access-logs/ip-summary

参数	说明
hours	1–720；默认 168；在无 since/until 时生效
since / until	可选 RFC3339；同时有效时优先于 hours
sort_by	total_requests（默认）| request_length（入站）| bytes_sent（出站）| last_seen_at | success_ratio
sort_order	asc | desc
p / page_size	分页，page_size 上限 200
remote_addr / node_id / host	兼容保留；V1 UI 可不暴露

响应行字段（扩展）

remote_addr          string
region               string   // 窗内 argMax(region, logged_at) 或等价
total_requests       uint64
success_2xx_count    uint64   // status_code 200–299
success_ratio        float64  // success_2xx_count / total_requests；total=0 时为 0
bytes_received       uint64   // sum(request_length) 入站
bytes_sent           uint64   // sum(bytes_sent) 出站
last_seen_at         time

• recent_requests：可停止计算或固定返回 0；UI 不展示。避免与可配置时间窗语义冲突。
• 详情下钻仍用现有：
  • GET .../ip-summary/analysis?remote_addr=&hours=（或 since/until，若后续扩展；V1 将列表当前窗映射为 hours 或 since/until 与后端约定一致）
  • GET .../ip-summary/trend?remote_addr=&hours=&bucket_minutes=

分析/趋势时间窗对齐：打开 IP 详情时，将列表当前时间窗传入 analysis/trend（优先 since/until；仅有 hours 则传 hours）。

2.3 数据层（ClickHouse）

• 表：of_node_access_logs（已有 bytes_sent、request_length、status_code、region）。
• 聚合：GROUP BY remote_addr，在 NodeAccessLogFilter.Since/Until 上过滤。
• 2xx：countIf(status_code >= 200 AND status_code < 300)。
• region：argMax(region, logged_at)。
• 排序：服务端 ORDER BY 对应表达式；success_ratio 注意除零（if(total=0,0,ratio)）。

2.4 设计决策权衡

选项	结论
扩展 /ip-summary vs 新 /ip-list	扩展现有，前端 service 已有 listIPSummaries
详情弹窗 vs 子页	弹窗，与现有明细交互一致
IP 情报放日志详情 vs 独立 IP 详情	仅 IP 明细详情；日志详情只展示请求信息
时间：仅快捷 vs 仅自定义	两者都要，自定义优先

2.5 数据流（示意）

flowchart LR
  UI_IP[IP 明细 Tab] --> API_List[GET /ip-summary]
  API_List --> CH[(of_node_access_logs)]
  UI_IP --> UI_Dlg[IP 详情 Dialog]
  UI_Dlg --> API_A[GET /ip-summary/analysis]
  UI_Dlg --> API_T[GET /ip-summary/trend]
  API_A --> CH
  API_T --> CH
  UI_List[日志明细 Tab] --> API_Logs[GET /access-logs]
  UI_List --> UI_LogDlg[日志详情 Dialog]
  UI_LogDlg -.->|不请求 IP 分析| X[仅请求字段]

3. 具体修改文件清单 (Proposed Changes)

后端 Server

• [MODIFY] internal/repository/analytics/node_access_log_stats.go（及 filter 如有）

  • IPSummariesNodeAccessLogs：时间窗、sum 入/出、2xx count、ratio、region、扩展 sort。

• [MODIFY] internal/apps/openflare/observability/access_log_logics.go

  • Query/View 类型扩展；解析 hours/since/until；去掉或忽略 recent 3h 硬编码。

• [MODIFY] internal/apps/openflare/observability/routers.go / handler

  • 绑定新 query；Swagger 注释。

• [MODIFY] 相关单元测试（logics / repository 若有）

前端 Web

• [MODIFY] frontend/app/(main)/access-logs/page.tsx

  • 第三 Tab ips；resolveTab / handleTabChange。

• [NEW] frontend/app/(main)/access-logs/components/ip-tab.tsx

  • 列表、时间筛选、排序、分页、打开详情。

• [NEW] frontend/app/(main)/access-logs/components/ip-detail-dialog.tsx

  • IP 入口详情壳。

• [NEW] frontend/app/(main)/access-logs/components/ip-analysis-panel.tsx

  • 从现有 access-log-detail-dialog 迁出 分析/趋势/排行/WAF IP 组逻辑。

• [MODIFY] frontend/app/(main)/access-logs/components/access-log-detail-dialog.tsx

  • 删除 IP 情报相关 UI 与 getIPAnalysis / getIPTrend 请求；仅请求日志字段展示。

• [MODIFY] frontend/app/(main)/access-logs/components/access-log-utils.ts

  • tab 类型、IP 排序选项、时间筛选辅助。

• [MODIFY] frontend/lib/services/openflare/access-log.service.ts + types.ts

  • listIPSummaries 参数与 AccessLogIPSummaryItem 字段同步。

文档

• [MODIFY] docs/changelog/index.md — [Unreleased] 用户可见说明

• [MODIFY] docs/design/observability-design.md 或 data-model（如有访问日志 UI 约定）— 补充 IP 明细 Tab 与 API 字段（中文）

• [MODIFY] docs/plan/index.md — 挂上本计划链接

4. 验证计划 (Verification Plan)

自动化

go test ./internal/apps/openflare/observability/ ./internal/repository/analytics/
# 前端：相关 tsc / 页面无类型错误
make code-check   # 完成后按项目门禁
make prettier
make swagger      # API 注释变更后

手动

1. /access-logs?tab=ips 默认 7d 列表有数据；切换 24h/自定义区间结果变化。
2. 分别按请求数、入站、出站、2xx 比例、最后访问排序正确。
3. 2xx 比例 = 2xx/总数；0 请求不出现 NaN/Infinity。
4. 点 IP 打开详情：指标/趋势/Top/WAF 组可用；时间窗与列表一致。
5. 日志明细 → 详情：仅请求信息，无 IP 分析/趋势区块。
6. 概览 Tab 行为无回归。

5. 状态

• 需求澄清与方案确认
• 实现（后端 ip-summary 扩展 + 前端 IP 明细 Tab + 日志详情瘦身）
• 测试与 changelog（go test 相关包通过；changelog 已更新）
• 提交合并