From 295340dc4b53d7648b8dbeb3e33d9d12bef16613 Mon Sep 17 00:00:00 2001 From: ryan Date: Sat, 14 Mar 2026 10:45:23 +0800 Subject: [PATCH] =?UTF-8?q?[=E4=BC=98=E5=8C=96]=20=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E5=BC=80=E5=8F=91=E8=AE=A1=E5=88=92=E6=96=87=E6=A1=A3=EF=BC=8C?= =?UTF-8?q?=E6=98=8E=E7=A1=AE=E7=AC=AC=E5=85=AD=E7=89=88=E7=9B=AE=E6=A0=87?= =?UTF-8?q?=E4=B8=8E=E5=AE=9E=E6=96=BD=E6=AD=A5=E9=AA=A4=EF=BC=8C=E5=A2=9E?= =?UTF-8?q?=E5=8A=A0=E8=8A=82=E7=82=B9=E6=95=B0=E6=8D=AE=E9=87=87=E9=9B=86?= =?UTF-8?q?=E4=B8=8E=E8=AE=BF=E9=97=AE=E5=88=86=E6=9E=90=E8=83=BD=E5=8A=9B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/design.md | 52 ++++++- docs/development-guidelines.md | 44 +++++- docs/development-plan.md | 264 ++++++++++++++++++++++++--------- 3 files changed, 289 insertions(+), 71 deletions(-) diff --git a/docs/design.md b/docs/design.md index cc79d63f..aad2da87 100644 --- a/docs/design.md +++ b/docs/design.md @@ -8,7 +8,8 @@ * 第一版、第二版、第三版均已完成 * 前端改造已完成，`atsf_server/web` 新版工程已成为正式基线 -* 第五版（0.5.x）已立项，目标聚焦 OpenResty 反代与缓存性能优化 +* 第五版（0.5.x）已完成，OpenResty 反代、缓存性能优化与主配置接管已落地 +* 第六版（0.6.x）已立项，目标聚焦节点流量数据采集、访问分析与数据看板升级 * 已完成阶段的实现细节以代码与 Git 历史为准，不再在本文档中维护过程性设计 --- @@ -29,6 +30,12 @@ ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部 * 反向代理链路的连接、缓冲、超时、压缩与缓存性能优化 * HTTPS/TLS 路由支持 * 证书托管与域名管理 +* 节点侧请求数据采集、随 heartbeat 批量上报与服务端聚合分析 +* 节点系统画像采集与展示，包括操作系统、内核、架构、CPU、内存、磁盘与在线时长 +* 节点实时资源快照、网络流量快照与 24 小时趋势展示 +* 节点健康事件归并与异常摘要展示 +* 管理端总览大盘与节点详情页的数据看板升级 +* 首页总览展示整套系统的可用性、容量、流量、异常与配置追平状态 * 节点管理、节点专属 `agent_token`、全局 `discovery_token` * 配置变更摘要 * Agent 运行参数下发 @@ -65,6 +72,18 @@ ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部 * 第五版不开放任意自定义 Nginx/OpenResty 片段上传，不提供任意指令执行入口, 但是需要保留拓展能力, 为后续开放准备 * 允许在管理端提供 OpenResty 主配置模板编辑能力，但模板必须保留 ATSFlare 预留占位符，确保性能参数、证书目录与受管路由 include 继续由 Server 统一渲染 +第六版边界补充： + +* 节点通过 heartbeat 上报最近周期内的请求明细、资源占用快照和网络流量快照，Server 负责入库、聚合与看板展示 +* 第六版参考轻量探针产品的常见数据分层方式，将节点观测拆分为“静态系统画像、周期资源快照、窗口流量聚合、健康异常事件”四类数据，而不是持续向 `nodes` 主表堆叠字段 +* 第六版的数据分析目标聚焦当前反代链路的运营观测：QPS、访问次数、访问人数、访问来源分布、访问趋势、状态码分布，以及节点级 CPU、内存、存储、磁盘 IO、入站/出站流量 +* 首页总览需要能回答“系统整体是否健康、容量是否逼近阈值、流量是否异常、是否存在配置未追平节点”这四类核心问题，可借鉴 WAF/安全大屏的信息组织方式，但不扩展为安全运营平台 +* 世界地图看板仅用于展示节点分布与节点状态，不扩展为 GeoDNS、调度、路由编排或全球流量调度系统 +* 节点详情页聚焦系统信息、实时资源、网络流量、24 小时趋势和目标版本，不继续堆积低价值静态字段 +* 在不引入 Prometheus、ClickHouse、Kafka 等新基础设施前提下完成第六版；数据采集、聚合与查询继续落在现有 Server/SQLite 基线内 +* 原始请求数据不作为长期日志平台对外开放；第六版允许保留受控时间窗口内的明细，用于聚合分析、趋势计算与节点详情辅助排查 +* 第六版不做完整 APM、调用链追踪、日志检索平台、任意 SQL 分析接口或自定义报表系统 + 新增能力超出上述边界时，必须先更新本文档，再进入实现。 --- @@ -125,10 +144,27 @@ ATSFlare Agent (register / heartbeat / sync / apply / update) * Server 负责配置、版本、节点、设置、管理端 UI 以及 OpenResty 主配置模板渲染 * Agent 负责本地落盘、校验、reload、回滚、自更新，不负责维护独立于 Server 的主配置真相 +* Agent 负责本机观测数据的轻量采集、窗口聚合与体积控制，不直接承担长期历史查询职责 * 发布通过“生成完整版本并激活”完成 * 历史版本不可变 * Agent 常规轮询以 heartbeat 为主；heartbeat 响应返回当前激活版本的 `version` 与 `checksum` 摘要，Agent 仅在发现不一致时再拉取完整配置 +第六版观测分层： + +* `nodes` 只承担节点身份、接入凭证、配置状态、运行控制状态等控制面字段 +* `node_system_profiles` 承担低频变化的节点系统画像，如操作系统、内核、架构、CPU 型号、逻辑核数、内存总量、磁盘布局、启动时间与 Agent 能力声明 +* `node_metric_snapshots` 承担周期性运行快照，如 CPU、负载、内存、文件系统占用、磁盘 IO、OpenResty 连接数与入站/出站吞吐 +* `node_request_reports` 承担最近心跳窗口内的请求批次或受控明细，不作为长期日志平台 +* `traffic_analytics_rollups` 承担分钟级、小时级的访问聚合结果，支持总览维度、节点维度和域名维度查询 +* `node_health_events` 承担状态变化与异常事件，如节点离线、OpenResty 不健康、配置未追平、资源逼近阈值、错误率突增 + +第六版 heartbeat 扩展思路： + +* `profile`：低频系统画像，仅在首次注册、显著变化或周期性校准时上报 +* `snapshot`：每次 heartbeat 附带的实时资源快照 +* `traffic_report`：当前窗口的请求聚合结果与必要 TopN 分布 +* `health_events`：当前窗口内新增或恢复的异常事件 + --- ## 6. 核心对象 @@ -138,9 +174,14 @@ ATSFlare Agent (register / heartbeat / sync / apply / update) * `proxy_routes`：域名到源站的反向代理规则 * `config_versions`：完整发布快照与渲染结果 * `nodes`：节点状态、版本、凭证与 Agent 设置相关状态 +* `node_system_profiles`：节点系统画像与硬件/软件事实信息 * `apply_logs`：节点应用版本结果 * `tls_certificates`：托管证书与私钥 * `managed_domains`：域名资产及默认证书关系 +* `node_request_reports`：节点通过 heartbeat 批量上报的请求明细或请求批次 +* `node_metric_snapshots`：节点实时资源、磁盘 IO 与网络流量快照 +* `traffic_analytics_rollups`：按时间窗口聚合后的访问指标，用于总览与节点详情看板 +* `node_health_events`：节点运行状态变化、阈值异常与配置偏差事件 稳定约束： @@ -153,9 +194,16 @@ ATSFlare Agent (register / heartbeat / sync / apply / update) * 激活版本中的 OpenResty 渲染结果必须包含主配置与路由配置的统一快照 * 域名与证书匹配同时支持精确匹配与通配符匹配 * 节点专属 `agent_token` 必须可立即失效 +* `nodes` 不承担高频观测事实存储；高频运行时字段必须进入快照、聚合或事件表 * OpenResty 性能优化参数与缓存参数统一由 Server 设置管理，不允许节点侧形成额外配置源 * OpenResty 主配置模板允许编辑，但必须保留系统要求的占位符，不能绕过结构化参数校验与受管 include 注入 * Agent 只应用受控主配置文件，不提供任意配置片段拼接入口 +* 节点请求数据必须随 heartbeat 按批次上报，Server 不主动反向拉取节点日志文件 +* 指标看板使用服务端聚合结果，不在前端重复做大规模统计计算 +* 节点资源快照与请求明细必须能按时间排序并绑定节点，保证 24 小时趋势与节点详情可回放 +* 原始请求明细、聚合统计与节点基础状态必须在时间窗口上可对齐 +* 首页总览的系统状态必须基于统一服务端口径生成，不能由多个历史列表接口在前端临时拼装推导 +* 健康事件必须支持“触发中/已恢复”状态，避免首页异常永远累积 --- @@ -207,6 +255,7 @@ ATSFlare Agent (register / heartbeat / sync / apply / update) * 首次注册与凭证置换 * 周期性心跳与同步 * 运行参数接收 +* 采集最近周期内的请求明细、资源占用和网络流量 * 主配置文件、路由配置与必要证书文件写入 * 执行 `openresty -t` / `openresty -s reload` * 失败回滚 @@ -218,6 +267,7 @@ ATSFlare Agent (register / heartbeat / sync / apply / update) 负责： * 管理端页面、布局、交互与主题 +* 总览世界地图、访问分析看板与节点详情监控视图 * 规则、版本、节点、证书、域名、用户、设置、性能等页面 * 统一请求层与前端状态管理 diff --git a/docs/development-guidelines.md b/docs/development-guidelines.md index a48ecc1b..6cb5810c 100644 --- a/docs/development-guidelines.md +++ b/docs/development-guidelines.md @@ -9,7 +9,8 @@ * 第一版、第二版、第三版已完成 * `docs/design.md` 是当前系统边界的唯一设计基线 * `atsf_server/web` 新版前端已完成迁移并成为正式基线 -* 第五版（0.5.x）将以 OpenResty 性能优化与主配置接管为主线 +* 第五版（0.5.x）已完成 +* 第六版（0.6.x）以节点流量数据采集、访问分析与看板升级为主线 超出设计边界的需求，必须先更新 [docs/design.md](./design.md)。 @@ -125,9 +126,14 @@ * `proxy_routes` * `config_versions` * `nodes` +* `node_system_profiles` * `apply_logs` * `tls_certificates` * `managed_domains` +* `node_request_reports` +* `node_metric_snapshots` +* `traffic_analytics_rollups` +* `node_health_events` * `options`（运行时参数与 OpenResty 调优参数继续复用现有配置表，不扩展为独立新实体） 通用约束： @@ -140,6 +146,14 @@ * 第五版新增的 OpenResty 性能参数必须由 Server 统一保存与校验，并参与版本渲染 * 域名证书匹配必须同时支持精确匹配与通配符匹配 * 节点专属 `agent_token` 必须可立即失效 +* `nodes` 只保留控制面与摘要状态，不直接承接第六版新增的高频资源字段、完整系统画像和大块统计结果 +* `node_system_profiles` 负责存储低频变化的节点事实信息；只有需要列表摘要展示的极少数字段可以回写到 `nodes` +* 第六版新增的请求明细、资源快照和聚合统计必须按节点与时间窗口关联 +* `node_metric_snapshots` 必须是追加式时间序列快照，不通过覆盖 `nodes` 当前值替代历史 +* `traffic_analytics_rollups` 必须区分时间粒度与统计范围，优先存储窗口聚合而不是无限制保留原始逐请求明细 +* `node_health_events` 必须具备事件类型、严重级别、首次触发时间、最近触发时间和恢复时间，便于首页总览做异常归并 +* 访问分析优先复用现有 Server/SQLite 基线，不为第六版引入新的时序数据库或消息队列 +* 聚合统计与原始明细的保留策略必须明确，避免无限制累积 --- @@ -151,6 +165,7 @@ * 成功与失败都必须返回清晰 `message` * 列表接口返回稳定字段 * Agent API 固定放在 `/api/agent/*` +* 第六版总览页与节点详情页优先新增专用聚合接口，不继续依赖多个旧列表接口在前端拼装 统一响应结构保持现有风格： @@ -223,6 +238,7 @@ Agent 必须满足： * 未显式配置 `node_ip` 时自动探测本机 IP * 周期性心跳与同步 * 常规同步判定优先通过 heartbeat 响应中的激活版本 `version` / `checksum` 摘要完成；仅在 Agent 本地状态与摘要不一致时，再请求完整激活配置 +* heartbeat 请求体允许携带最近周期内的系统画像变更、资源快照、磁盘 IO 快照、入站/出站流量快照、访问聚合批次和健康事件 * 发现新版本时先备份旧文件 * 写入新的主配置、路由配置与必要证书文件 * 先执行 `openresty -t` @@ -234,6 +250,32 @@ Agent 必须满足： * 支持接收 Server 下发的受限运行指令，当前仅允许 OpenResty 重启 * 支持自我更新，但失败不影响心跳与同步 * 主配置接管模式下，必须保证主配置与受管 include 一起回滚，不能只回滚其中一部分 +* 请求明细采集失败、聚合失败或单次 heartbeat 上报失败时，不得阻断后续心跳与配置同步主链路 +* 节点侧指标采集必须优先读取 OpenResty 与本机运行时状态，不允许引入任意 shell 采集脚本拼接执行 +* 大批量请求上报必须具备批次边界和体积控制，避免单次 heartbeat 无限制膨胀 +* 节点侧应优先做窗口聚合后再上报，避免把逐请求原始日志持续搬运到 Server +* 低频系统画像应支持变更检测，避免每次 heartbeat 重复上报大块静态信息 +* UV、来源分布、状态码分布等统计应在节点侧或服务端按窗口聚合，禁止前端再对原始明细做重型计算 + +第六版新增规范： + +* 总览页默认展示世界地图节点分布、核心访问指标、趋势图和关键异常，不再以多个对称摘要卡片作为唯一主结构 +* 总览页必须能直接展示系统整体运行状况，至少覆盖节点在线率、OpenResty 健康、配置追平状态、容量风险与流量异常 +* 总览页异常区优先展示可行动的问题，如离线节点、配置落后节点、资源逼近阈值节点、错误率异常节点 +* 节点详情页第一屏至少覆盖系统信息、实时资源占用、网络流量与 24 小时历史趋势 +* 系统信息卡片除现有 Agent 版本、Nginx 版本、当前配置外，新增操作系统、CPU 型号、在线时长 +* 实时资源卡片展示 CPU、内存、存储占用，优先以仪表盘或等效高密度可视化呈现 +* 网络流量卡片展示经过 OpenResty 的入站和出站流量，并按 KB/MB/GB 自动换算 +* 节点详情页保留“当前目标版本”等高价值运维信息，但应下移到趋势区之后，避免抢占首屏 +* 节点详情页需要区分“静态画像”和“实时状态”，禁止把二者混在一组无层次字段列表中 + +第六版实现约束补充： + +* 优先新增 `dashboard` / `node detail` 聚合 service，避免在旧 `node` service 上不断打补丁叠加查询逻辑 +* SQLite 查询应优先围绕“节点 + 时间窗口 + 粒度”建立索引与查询入口，避免首页每次全表扫描历史快照 +* TopN 榜单、来源分布、状态码分布等复杂结果允许以受控 JSON 结构写入聚合表，但必须保证字段稳定可测试 +* 异常阈值判断必须收敛在服务端统一实现，前端只负责展示，不复制阈值逻辑 +* 测试至少覆盖 heartbeat 扩展兼容性、聚合正确性、异常恢复状态切换和关键 dashboard 查询口径 --- diff --git a/docs/development-plan.md b/docs/development-plan.md index 5411f80c..b7e35e5b 100644 --- a/docs/development-plan.md +++ b/docs/development-plan.md @@ -1,103 +1,229 @@ # ATSFlare 开发计划 -## 维护期说明 - -在当前 0.5.x 功能基线基础上，项目已进入整理维护期。 -本阶段新增一份专项计划文档 [docs/improve_plan.md](./improve_plan.md)，用于集中推进代码质量、性能优化与安全治理。 -若后续维护任务与本文件的阶段描述存在冲突，以 `docs/improve_plan.md` 中的优先级顺序为准。 - -## 1. 当前阶段 +## 1. 当前状态 当前结论： -* 第一版已完成并稳定运行 -* 第二版已完成并补齐 HTTPS、证书、域名、节点与预览能力 -* 第三版已完成，运维体验优化相关能力已经落地 -* 第四版已完成前端细节打磨与 UI 优化，但未单独维护专项计划文档 -* 当前正式进入第五版（0.5.x）开发，目标聚焦 OpenResty 反代与缓存性能优化，以及主配置文件接管 +* 第一版至第五版主线能力均已完成 +* 已完成阶段的过程性任务不再继续展开维护 +* 当前主线切换到第六版（0.6.x） + +第六版主目标： + +* 为节点增加请求数据采集、资源采集与 heartbeat 上报能力 +* 在 Server 侧完成访问分析、趋势计算与聚合查询 +* 改造管理端总览页与节点详情页，提升信息密度、数据层次和监控可读性 +* 建立可持续扩展的观测数据分层，避免在旧节点模型和旧首页接口上继续补丁式堆功能 --- -## 2. 已完成范围归档 +## 2. 已完成范围压缩归档 -### 2.1 已完成能力 +已完成能力统一归档为以下几类： -* 规则管理、配置发布、激活、回滚 -* Agent 注册、心跳、同步、应用、回滚 -* HTTPS/TLS 路由、证书托管、域名管理 -* 节点管理、专属 `agent_token`、全局 `discovery_token` -* 配置预览、变更摘要、自定义请求头 -* 运维设置热更新 -* Server 下发 Agent 运行参数 -* Agent 自我更新与一键部署 -* Server 版本检查与自升级 -* 新版前端工程、主题切换与统一页面框架 +* 反代规则、配置版本、预览、发布、激活、回滚 +* Agent 注册、心跳、同步、应用、失败回滚 +* HTTPS/TLS、证书托管、域名管理 +* 节点管理、令牌体系、部署与更新链路 +* OpenResty 性能优化、缓存配置与主配置托管 +* 新版管理端前端、主题与统一交互框架 -### 2.2 归档原则 +归档原则： -* 已完成阶段的实现细节以代码与 Git 历史为准 -* 不再为已完成工作维护过程性计划、迁移步骤或分阶段验收清单 -* 新的大功能阶段启动前，再补充新的计划文档 +* 第一版至第五版的实施细节以代码与 Git 历史为准 +* 本文件只维护当前有效主线，不再保留已完成阶段的过程性拆分 +* `docs/improve_plan.md` 继续作为并行整理清单存在，但不覆盖第六版主线优先级 --- -## 3. 第五版目标 +## 3. 第六版范围 -第五版主目标： +### 3.1 第六版要做 -* 提升 OpenResty 在当前反代链路下的连接、缓冲、超时、压缩与缓存性能 -* 由 Server 统一托管 OpenResty 主配置文件，Agent 不再依赖节点手工维护主配置 -* 所有新增优化项都进入 Server 统一配置面，由管理端维护、版本发布、Agent 拉取与应用 +1. 节点数据采集与上报 + * Agent 在每次 heartbeat 时上报最近周期内的请求数据 + * Agent 同步上报节点系统画像、CPU/内存/存储快照、磁盘 IO、OpenResty 入站/出站流量 + * 新增在线时长、操作系统、内核、架构、CPU 型号、逻辑核数、总内存、磁盘布局等节点维度信息 + * 采集节点健康事件，覆盖离线、OpenResty 不健康、配置未追平、资源逼近阈值和错误率异常 -第五版不做： +2. 服务端访问分析 + * 基于请求数据计算当前节点 QPS、访问次数、访问人数 + * 统计访问来源分布、访问趋势、状态码分布等核心指标 + * 支持总览维度与节点维度两套查询视图 + * 生成系统整体健康摘要，回答“是否健康、是否有风险、问题集中在哪些节点” -* 平台化缓存产品、Purge 系统、分层缓存、节点差异化缓存策略 -* 任意文本片段注入、任意 OpenResty 指令执行、节点侧自定义模板合并 -* 绕过占位符约束的主配置模板直写 -* 引入 Redis、Prometheus、消息队列等新基础设施作为第五版前置条件 +3. 总览页改造 + * 首屏新增世界地图看板，用于展示全部节点分布与在线状态 + * 调整总览信息结构，不再以单一“四卡摘要”作为主布局 + * 增加趋势、分布、Top 榜单、容量风险和异常信号展示 + * 引入类似 WAF/安全运营面板的信息组织方式，但聚焦 ATSFlare 当前系统健康与流量状态 -## 4. 第五版实施顺序 +4. 节点详情页改造 + * 第一行重构为三块核心卡片：系统信息、实时资源占用、网络流量监控 + * 第二行展示最近 24 小时历史趋势，至少覆盖 CPU、网络、磁盘 IO + * 第三行接续当前目标版本与应用记录等运维信息 + * 清理低价值、重复、信息密度低的展示模块 + +5. 架构可扩展性治理 + * 将节点观测拆分为静态画像、动态快照、窗口聚合、健康事件四类数据 + * 为总览页和节点详情页建立专用聚合接口，不继续依赖旧列表接口临时拼装 + * 控制原始数据保留窗口和聚合粒度，避免后期查询、存储和维护成本失控 + +### 3.2 第六版不做 + +* 不引入 Prometheus、ClickHouse、Kafka、ElasticSearch 等新基础设施 +* 不建设通用日志检索平台、APM 平台、调用链追踪平台 +* 不扩展为 GeoDNS、全球流量调度、节点智能选路系统 +* 不做任意自定义报表、任意维度 OLAP 查询或外部 BI 接入 + +--- + +## 4. 第六版实施顺序 建议按以下顺序推进： -1. 补齐 Server 侧 OpenResty 性能参数模型、默认值、校验规则与性能页入口，并补充主配置模板编辑能力 -2. 扩展配置渲染结果，使版本快照覆盖主配置文件与路由配置文件 -3. 调整 Agent 本地应用链路，支持主配置写入、校验、reload、失败回滚 -4. 补齐预览、diff、应用结果与日志，确保第五版能力可观测 -5. 以本机 OpenResty 与 Docker OpenResty 两种模式完成联调和回归 +1. 定义数据模型与 heartbeat 扩展协议 + * 明确系统画像结构、请求数据批次结构、资源快照结构、聚合结果结构与健康事件结构 + * 补齐保留策略、体积限制和失败回退规则 -## 5. 第五版验收标准 +2. 完成 Agent 采集链路 + * 采集请求窗口聚合 + * 采集系统画像与运行时性能指标 + * 采集 OpenResty 入站/出站流量 + * 归并节点健康事件并挂入 heartbeat 上报 -完成第五版时至少满足： +3. 完成 Server 入库与分析链路 + * 接收并校验 heartbeat 扩展数据 + * 入库存储系统画像、原始批次、资源快照和健康事件 + * 生成总览页与节点详情页所需聚合统计与系统健康摘要 -* 管理端可以查看并修改第一批 OpenResty 性能优化项 -* 管理端提供独立“性能”页面，支持结构化设置与主配置模板编辑/预览 -* 性能优化项保存后进入统一发布链路，而不是节点即时生效 -* Agent 可以接管主配置文件，并在 `openresty -t` 失败时完整回滚 -* 配置预览或 diff 能体现主配置与关键性能参数变化 -* 本机模式与 Docker 模式都能完成一次成功发布和一次失败回滚验证 -* 所有优化选项都由 Server 统一管理，不存在节点侧独立真相源 +4. 完成总览页改造 + * 世界地图看板 + * 系统健康摘要区 + * 核心访问指标区 + * 访问趋势与来源分布区 + * 节点状态、配置追平与异常摘要区 -## 6. 当前执行原则 +5. 完成节点详情页改造 + * 系统信息卡片 + * 实时仪表盘与网络流量卡片 + * 24 小时趋势图 + * 下移并重组当前目标版本、健康事件与应用记录 -第五版执行时遵循： - -* 先遵守 `docs/design.md` 的系统边界 -* 再遵守 `docs/development-guidelines.md` 与 `docs/frontend-development-guidelines.md` -* OpenResty 优化参数优先复用现有 `Option` 与设置页结构，避免引入新配置中心 -* 主配置文件接管必须和发布链路、回滚链路一起设计，不能只补局部写文件能力 -* 需求不改变边界时，直接按现有模型与结构增量实现 -* 需求改变边界时，先补设计，再补计划，再编码 +6. 补齐回归验证 + * Agent 心跳主链路 + * 聚合统计正确性 + * 健康事件触发/恢复正确性 + * 总览页与节点详情页的亮暗主题和空态/错误态 --- -## 7. 新需求进入条件 +## 5. 第六版分阶段计划 -满足以下任一情况时，才需要新增计划项： +### 5.1 阶段一：采集协议与存储落地 -* 引入新的核心业务对象或系统边界 -* 引入新的基础设施依赖 -* 调整部署模式或运行方式 -* 大规模重构前后端主干结构 +目标： -否则默认按常规开发任务处理，不再单独维护阶段计划。 +* 打通“节点采集 -> heartbeat 上报 -> Server 接收 -> 入库”主链路 + +任务： + +* 扩展 Agent heartbeat payload +* 新增系统画像、请求数据批次、资源快照和健康事件模型 +* 为请求明细、性能快照和聚合统计建立查询入口 +* 控制单次 heartbeat 体积，避免影响现有同步稳定性 + +验收标准： + +* 节点可随 heartbeat 成功上报系统画像、请求数据与性能快照 +* heartbeat 扩展失败不影响配置同步主链路 +* Server 能按节点和时间窗口查询到原始上报数据与健康事件 + +### 5.2 阶段二：服务端分析与指标计算 + +目标： + +* 形成总览页和节点详情页可直接消费的数据接口 + +任务： + +* 计算当前节点 QPS、访问次数、访问人数 +* 计算访问来源分布、访问趋势、状态码分布 +* 生成最近 24 小时 CPU、网络、磁盘 IO 趋势数据 +* 统一总览级与节点级查询口径 +* 生成整体健康摘要与异常节点清单 + +验收标准： + +* 同一时间窗口下总览与节点详情的数据口径一致 +* 核心统计字段可被测试覆盖，避免明显统计偏差 +* 24 小时趋势查询在现有基线上可接受，不出现明显不可用卡顿 +* 首页可直接定位离线、异常、配置落后和容量风险节点 + +### 5.3 阶段三：总览页改造 + +目标： + +* 让总览页从“摘要入口页”升级为“运营与状态看板页” + +任务： + +* 实现世界地图节点看板 +* 重构首屏布局，减少对称摘要卡片堆叠 +* 增加系统健康摘要、趋势图、来源分布、状态码分布、节点异常摘要 +* 为地图、趋势和分布图补齐加载态、空态和错误态 + +验收标准： + +* 总览首屏可直接看到全部节点分布 +* 总览页能展示比旧版更多的实时、趋势与健康信息 +* 页面在桌面和移动端都能稳定显示 + +### 5.4 阶段四：节点详情页改造 + +目标： + +* 让节点详情页回到运维排障视角，提升信息密度和首屏价值 + +任务： + +* 第一行实现系统信息、实时资源占用、网络流量三块核心卡片 +* 系统信息新增操作系统、内核、架构、CPU 型号、在线时长 +* 网络流量卡片展示 OpenResty 入站/出站流量，自适应单位 +* 第二行实现最近 24 小时 CPU、网络、磁盘 IO 趋势图 +* 第三行承接当前目标版本、OpenResty 健康、健康事件与应用记录等现有高价值模块 +* 移除低价值重复信息 + +验收标准： + +* 节点详情首屏信息密度明显高于旧版 +* 第一屏即可完成系统识别、资源判断和流量判断 +* 趋势图可用于观察节点最近 24 小时性能变化 + +--- + +## 6. 第六版执行原则 + +第六版执行时遵循： + +* 先遵守 `docs/design.md` 的系统边界 +* 再遵守 `docs/development-guidelines.md` 与 `docs/frontend-development-guidelines.md` +* 数据采集优先走 heartbeat 批量上报，不新增独立常驻推流通道 +* 前端优先消费服务端聚合结果，不在浏览器做重型统计 +* 优先建设新的观测聚合链路，不继续在旧 `nodes` 列表接口与旧首页卡片上补丁式叠加字段 +* 总览页与节点详情页都必须同时覆盖加载态、空态、错误态和亮暗主题 +* 若第六版实现过程中需要新增基础设施或改变保留策略，必须先更新设计文档 + +--- + +## 7. 第六版总体验收标准 + +完成第六版时至少满足： + +* Agent 能在 heartbeat 中稳定上报请求数据、系统信息和性能快照 +* Server 能基于上报数据计算 QPS、访问次数、访问人数、访问来源分布、访问趋势、状态码统计 +* Server 能稳定生成系统健康摘要、异常节点清单和配置追平状态 +* 总览页包含世界地图看板，并替换旧版以摘要卡片为主的单调结构 +* 节点详情页包含系统信息卡、实时资源占用卡、网络流量卡、健康事件区与最近 24 小时趋势图 +* 节点详情页保留当前目标版本等关键运维信息，但整体层级比旧版更清晰 +* 第六版不破坏现有 Agent 心跳、同步、发布、回滚主链路