mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-01 22:46:38 +08:00
docs(obs): 边缘可观测 SSOT 设计与实施计划
补充 observability 设计/数据模型/传输模型，更新架构与 Agent 文档侧栏， 并写入 M5 迁移与小时汇总回填运维说明。
This commit is contained in:
ryan
@@ -0,0 +1,99 @@
|
||||
# 边缘可观测与业务流量统计重构 — 实现计划
|
||||
|
||||
说明：本计划对应设计文档 [observability-design.md](../design/observability-design.md)。重大架构重构，按阶段交付，避免一次大爆炸。
|
||||
|
||||
---
|
||||
|
||||
## 0. 落地进度（2026-07-18）
|
||||
|
||||
* [x] M1 看板业务趋势改读 access log；网络图文案改为已提供/接收 + 宿主机网卡
|
||||
* [x] M2 协议 v2 字段（host_metrics/edge_health/request_length）；CH 列 `request_length`/`request_time_ms`
|
||||
* [x] M3 Agent：观测口仅健康连接；payload 不再发 TrafficReport；access_logs 带 request_length
|
||||
* [x] M4 Server：停写 TrafficReport；openresty 仅存 connections；明细入库带 request_length
|
||||
* [x] 分布图 status/top domains + 节点行请求/UV 改 access log；24h UV 用 uniqExact；API bytes_provided/received
|
||||
* [x] M5：`of_node_edge_health`、`of_access_log_hourly`(+MV)；删除 request_reports/traffic_hourly/openresty_hourly/obs_openresty；写入/查询改道
|
||||
* [x] 收尾：清 openresty hourly / request_report 死路径；edge_health 写全 status；cleanup 命名 `node_edge_health`；hourly 回填 SQL + UV 策略文档
|
||||
* [x] 协议/API 去兼容层（Agent 销毁重建）：删除 TrafficReport / openresty_observation / snapshot 别名 / request_reports API 字段 / openresty_rx|tx
|
||||
* [x] 前端 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](../design/observability-transport-model.md)。
|
||||
* **协议与表结构**：见 [observability-data-model.md](../design/observability-data-model.md)（NodePayload v2、落库流水线、DDL、废弃表）。
|
||||
* **API**：看板与 Zone 共用聚合语义；`bytes_provided` / `bytes_received`（兼容 `bytes_sent` 别名）。
|
||||
* **数据流**：见 [observability-design.md](../design/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 降级。
|
||||
@@ -0,0 +1,71 @@
|
||||
# ClickHouse 观测表迁移与小时汇总回填（运维手册）
|
||||
|
||||
适用：M5 观测存储（`of_node_edge_health`、`of_access_log_hourly`、删旧表）及历史小时回填。
|
||||
|
||||
## 前提
|
||||
|
||||
* 控制面 `config.yaml` / 环境变量中 ClickHouse 已启用，账号可写 `openflare` 库。
|
||||
* 备份策略已就绪（可选：对 `of_node_access_logs` 做快照）。
|
||||
* **Agent 升级策略为销毁重建**；勿混跑旧 Agent（旧协议字段已从 Server 删除）。
|
||||
|
||||
## 1. 自动迁移（推荐）
|
||||
|
||||
进程启动时 `migrator.MigrateClickHouse()` 会按 goose 顺序执行：
|
||||
|
||||
| 版本 | 作用 |
|
||||
| --- | --- |
|
||||
| `202607180001` | access log 增加 `request_length` / `request_time_ms` |
|
||||
| `202607180002` | 建 `of_node_edge_health`、`of_access_log_hourly`(+MV)；删 request_reports / openresty 吞吐表 |
|
||||
| `202607180003` | 从明细 ANTI JOIN 回填近 90 天 `of_access_log_hourly` |
|
||||
|
||||
启动 API / all 模式一次即可：
|
||||
|
||||
```bash
|
||||
# 示例：本地
|
||||
./bin/openflare api
|
||||
# 或
|
||||
make run # 以项目实际入口为准
|
||||
```
|
||||
|
||||
查看 goose 版本表（ClickHouse）确认三版本均已应用。
|
||||
|
||||
## 2. 仅回填（迁移已执行、MV 创建前缺历史）
|
||||
|
||||
若只需重跑回填 SQL：
|
||||
|
||||
```bash
|
||||
clickhouse-client --host 127.0.0.1 --port 9000 \
|
||||
--user default --password "$CLICKHOUSE_PASSWORD" \
|
||||
--database openflare \
|
||||
--multiquery < internal/db/migrator/goose/clickhouse/202607180003_backfill_access_log_hourly.sql
|
||||
```
|
||||
|
||||
（goose 文件含 `+goose Up` 注释，若 client 报错可去掉注释行后执行 INSERT 主体。）
|
||||
|
||||
回填可重复：`ANTI JOIN` 跳过已有 `(node_id, hour, host)`。
|
||||
|
||||
## 3. 验收
|
||||
|
||||
```sql
|
||||
-- 新表存在
|
||||
SHOW TABLES FROM openflare LIKE 'of_node_edge_health';
|
||||
SHOW TABLES FROM openflare LIKE 'of_access_log_hourly';
|
||||
|
||||
-- 旧表应不存在
|
||||
SHOW TABLES FROM openflare LIKE 'of_node_request_reports';
|
||||
SHOW TABLES FROM openflare LIKE 'of_node_obs_openresty';
|
||||
|
||||
-- 小时汇总有数据（有历史访问时）
|
||||
SELECT count() FROM of_access_log_hourly;
|
||||
SELECT min(hour), max(hour), sum(request_count) FROM of_access_log_hourly;
|
||||
```
|
||||
|
||||
看板 24h 请求趋势应优先走 hourly；UV 卡片为整窗独立访客，**不等于**小时 UV 之和。
|
||||
|
||||
## 4. 本机执行记录
|
||||
|
||||
| 日期 | 环境 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| 2026-07-18 | 开发机 | Docker daemon 未启动，未能 live 迁移；SQL 与 goose 文件已入库 |
|
||||
|
||||
运维在目标环境按 §1–§3 执行后更新本表。
|
||||
@@ -15,6 +15,7 @@
|
||||
|
||||
* [Zone 与域名资源重构](./20260712-zone-domain-refactor.md)：以 Zone 和正规化 Zone 域名替代托管域名及反代路由中的域名/证书冗余字段。
|
||||
* [WAF 可编排规则](./20260713-waf-orchestration.md)：使用 React Flow 编辑 DAG 规则，发布时编译并由 OpenResty 纯内存执行。
|
||||
* [边缘可观测与业务流量统计重构](./20260717-observability-redesign.md)：访问日志为业务唯一真相；Agent 只上报明细与主机读数；收敛「出站/已提供」双字段。
|
||||
|
||||
## 使用建议
|
||||
|
||||
|
||||
Reference in New Issue
Block a user