OpenFlare/docs/plan/20260717-observability-redesign.md

边缘可观测与业务流量统计重构 — 实现计划

说明：本计划对应设计文档 observability-design.md。重大架构重构，按阶段交付，避免一次大爆炸。

---

0. 落地进度（2026-07-18）

• M1 看板业务趋势改读 access log；网络图文案改为已提供/接收 + 宿主机网卡
• M2 协议 v2 字段（host_metrics/edge_health/request_length）；CH 列 request_length/request_time_ms
• M3 Agent：观测口仅健康连接；payload 不再发 TrafficReport；access_logs 带 request_length
• M4 Server：停写 TrafficReport；openresty 仅存 connections；明细入库带 request_length
• 分布图 status/top domains + 节点行请求/UV 改 access log；24h UV 用 uniqExact；API bytes_provided/received
• M5：of_node_edge_health、of_access_log_hourly(+MV)；删除 request_reports/traffic_hourly/openresty_hourly/obs_openresty；写入/查询改道
• 收尾：清 openresty hourly / request_report 死路径；edge_health 写全 status；cleanup 命名 node_edge_health；hourly 回填 SQL + UV 策略文档
• 协议/API 去兼容层（Agent 销毁重建）：删除 TrafficReport / openresty_observation / snapshot 别名 / request_reports API 字段 / openresty_rx|tx
• 前端 UV 文案：24h/查询窗口独立访客；趋势图不绘分时 UV
• 真实环境 ClickHouse 迁移 + 202607180003 回填（本机 Docker 未起时需运维执行）

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

• 需求背景：看板「OpenResty 入/出站」与 Zone「已提供数据」不一致；Agent 预聚合与访问日志双轨；openresty_tx 与 bytes_sent 业务语义重复。
• 开发范围 (Scope)：
  • 必做：业务趋势统一为访问日志聚合；UI 字段与文案收敛；协议补齐 request_length；停用预聚合作为权威源；Agent 瘦身。
  • 后续：废弃 CH 表清理、hourly rollup 性能优化、Relay 指标对齐。
• Out of Scope：通用日志平台、替换 ClickHouse、APM。

---

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

• 核心对象：以 of_node_access_logs 为 L1 权威；主机 snapshot 为 L3；OpenResty 仅健康/连接为 L2。
• 传输模型（示例与频率）：见 observability-transport-model.md。
• 协议与表结构：见 observability-data-model.md（NodePayload v2、落库流水线、DDL、废弃表）。
• API：看板与 Zone 共用聚合语义；bytes_provided / bytes_received（兼容 bytes_sent 别名）。
• 数据流：见 observability-design.md §5。
• 权衡：性能用 Server 侧 rollup，不恢复 Agent 预聚合。

---

3. 阶段与修改清单 (Proposed Changes)

阶段 M1 — 读路径切换（优先对账）

• [MODIFY] internal/apps/openflare/dashboard/*、observability/analytics.go

  • 业务 24h 趋势改为 access log 聚合（全局）。
  • 网络趋势中业务曲线与主机网卡分离。

• [MODIFY] 前端 dashboard 组件与文案

  • 「OpenResty 出站/入站」→「已提供数据/接收数据」或拆卡片。

• [MODIFY] Zone stats 字段对齐（如需别名）

• 验收：单 Zone 流量时看板已提供 ≈ Zone 已提供。

阶段 M2 — 协议与入库补齐

• [MODIFY] pkg/protocol/agent.go — NodeAccessLog.request_length

• [MODIFY] Agent 解析与 CH 写入列

• [MODIFY] goose ClickHouse migration（如缺列）

阶段 M3 — 停写预聚合权威路径

• [MODIFY] Server persist：TrafficReport / openresty rx/tx 不再驱动看板

• 可选：直接停写以减 CH 压力

阶段 M4 — Agent 瘦身

• [MODIFY] 移除 TrafficReport 构建主路径、Lua 业务 dict 计数、state 内业务累计

• [MODIFY] 心跳仅明细 + snapshot + 连接/健康

阶段 M5 — 清理

• 删除废弃 API 字段、前端类型、CH 表/MV、相关测试夹具
• 更新 agent-design / changelog（代码变更时）

---

4. 验证计划 (Verification Plan)

自动化

• go test：zone stats、dashboard 聚合、agent access log 解析
• 前端：zone / dashboard 文案与字段测试

手动

• 制造已知大小响应，对比 Zone 与看板 24h 已提供数据
• 确认宿主机网卡曲线与业务已提供数据分区展示、数值可不一致且文案不诱导对账

质量门禁

• make swagger（若 API 变更）
• make code-check
• make prettier

---

5. 依赖与风险

• 明细量大时 M1 需同步评估 hourly rollup（仍 Server 侧）。
• 旧 Agent 无 request_length 时接收数据为空，需 UI 降级。