From 17f88917f4fd5eea5048c49231cbaeb02f3755c4 Mon Sep 17 00:00:00 2001
From: ryan <ryan@arctel.net>
Date: Fri, 13 Mar 2026 15:44:26 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=E6=95=B4=E7=90=86?=
 =?UTF-8?q?=E7=BB=B4=E6=8A=A4=E6=9C=9F=E6=94=B9=E8=BF=9B=E8=AE=A1=E5=88=92?=
 =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E9=9B=86=E4=B8=AD=E6=8E=A8=E8=BF=9B?=
 =?UTF-8?q?=E4=BB=A3=E7=A0=81=E8=B4=A8=E9=87=8F=E4=B8=8E=E5=AE=89=E5=85=A8?=
 =?UTF-8?q?=E6=B2=BB=E7=90=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/development-plan.md |   6 ++
 docs/improve_plan.md     | 217 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 223 insertions(+)
 create mode 100644 docs/improve_plan.md

diff --git a/docs/development-plan.md b/docs/development-plan.md
index 2353310c..5411f80c 100644
--- a/docs/development-plan.md
+++ b/docs/development-plan.md
@@ -1,5 +1,11 @@
 # ATSFlare 开发计划
 
+## 维护期说明
+
+在当前 0.5.x 功能基线基础上，项目已进入整理维护期。
+本阶段新增一份专项计划文档 [docs/improve_plan.md](./improve_plan.md)，用于集中推进代码质量、性能优化与安全治理。
+若后续维护任务与本文件的阶段描述存在冲突，以 `docs/improve_plan.md` 中的优先级顺序为准。
+
 ## 1. 当前阶段
 
 当前结论：
diff --git a/docs/improve_plan.md b/docs/improve_plan.md
new file mode 100644
index 00000000..8a62e272
--- /dev/null
+++ b/docs/improve_plan.md
@@ -0,0 +1,217 @@
+# ATSFlare 整理维护期改进计划
+
+## 1. 背景
+
+项目当前已具备可用的 Server / Agent / OpenResty 控制链路，接下来进入整理维护期。
+这一阶段不再以新增大功能为主，而是集中处理三类问题：
+
+* 架构层面的通信与存储开销
+* 代码质量、可维护性与复用度
+* 高风险安全问题与供应链风险
+
+本计划遵循当前基线：
+
+* 不改变 Server 统一生成配置、Agent 受控落盘的核心边界
+* 优先通过收敛实现、减少重复、补齐校验和测试来提升系统质量
+
+---
+
+## 2. 目标
+
+### 2.1 总目标
+
+在不扩大产品边界的前提下，把 ATSFlare 从“功能可用”推进到“长期可维护、风险可控、成本可预测”。
+
+### 2.2 具体目标
+
+* 降低 Agent 与 Server 的无效通信和无谓数据库写入
+* 降低节点列表、配置发布、日志输出等热点路径的额外开销
+* 用更明确的校验、错误处理和回归测试提升健壮性
+* 优先清除高危安全风险，特别是认证绕过、路径穿越、远程执行链路和更新链路信任问题
+
+---
+
+## 3. 现状评估
+
+### 3.1 架构与性能现状
+
+当前通信链路已经有一个正确方向：
+
+* 心跳接口只返回 `version/checksum` 摘要
+* Agent 仅在版本或 checksum 不一致时才拉取完整配置
+
+这意味着“全量配置频繁下发”已经被避免，基础设计没有明显错误。但仍有几个维护期值得优化的点：
+
+* 心跳会持续触发数据库写入，即使多数运行字段没有变化
+* 节点列表查询存在按节点逐条读取最近应用日志的模式，节点数增大后会出现明显的 N+1 查询开销
+* Agent 与 Server 在心跳、同步、HTTP 请求等路径上存在较多 `info` 级别日志，线上节点数增多后会放大 I/O 与排障噪音
+* Active Config 仍是整包返回，后续可继续收敛为“元数据 + 必要文件”的更细粒度同步模式
+
+### 3.2 代码质量现状
+
+当前代码总体结构清晰，但已经出现维护期典型问题：
+
+* 控制器层大量重复 `success/message/data` 响应拼装，错误返回风格不够统一
+* 部分边界校验仍分散在控制器、服务和运行时路径里，难以形成稳定约束
+* 一些实现已经接近“自造轮子”，例如日志文件处理、更新校验、静态安全检查流程，还没有引入成熟工具链
+
+### 3.3 安全现状
+
+维护期内优先处理以下高风险或高敏感问题：
+
+* Agent 写入 `support_files` 时缺少对目标路径必须位于 `cert_dir` 内的强约束，存在路径穿越风险
+* 手动上传 Server 二进制后会执行 `--version` 检测，属于高敏感执行链路，必须进一步加固
+
+---
+
+## 4. 优先级策略
+
+### 4.1 P0：先止血
+
+这部分先处理，未完成前不建议继续做中期重构。
+
+1. 修复 Agent 证书/附属文件写入路径穿越风险
+2. 补齐相关回归测试，确保问题不会回归
+
+### 4.2 P1：高收益优化
+
+在 P0 完成后推进。
+
+1. 减少心跳导致的数据库写放大
+2. 消除节点列表的 N+1 查询
+3. 降低高频路径日志噪音
+4. 收敛重复日志与响应封装实现
+
+### 4.3 P2：维护性增强
+
+在 P1 稳定后持续推进。
+
+1. 引入静态分析、安全扫描、依赖漏洞扫描到日常流程
+2. 梳理通用校验与错误模型
+3. 评估可以替换自研实现的成熟库
+4. 补充基准测试、容量指标和回归清单
+
+---
+
+## 5. 分项计划
+
+### 5.1 工作流一：安全治理
+
+#### 5.1.1 目标
+
+先解决高危风险，再补齐防线。
+
+#### 5.1.2 任务
+
+* 为 Agent 支持文件写入增加安全路径校验
+  * 拒绝绝对路径
+  * 拒绝 `..` 跳目录
+  * 通过 `filepath.Rel` 或安全辅助函数确认最终路径仍位于 `cert_dir` 内
+  * `writeSupportFiles`、`restore`、未来新增的写文件入口全部复用同一套安全函数
+* 收紧手动上传升级链路
+  * 明确只允许 root 用户
+  * 增加二次确认信息和文件摘要展示
+
+
+#### 5.1.3 验收标准
+
+* 构造 `../`、绝对路径、混合分隔符路径时，Agent 必须拒绝写入
+
+### 5.2 工作流二：架构与性能优化
+
+#### 5.2.1 目标
+
+在不改变总体架构的前提下，减少高频开销。
+
+#### 5.2.2 任务
+
+* 优化心跳写库策略
+  * 将“状态变化字段”与“仅 last_seen_at 更新时间”区分处理
+  * 仅在 IP、版本、OpenResty 状态、错误信息变化时更新对应字段
+  * 节点状态的离线判定优先在查询层或内存逻辑中计算，避免频繁写回数据库
+* 优化节点列表查询
+  * 将“最近一次 apply_log”改为批量查询或子查询一次取回
+  * 避免 `ListNodeViews` 中对每个节点单独查询最近日志
+* 优化配置同步链路
+  * 保留当前“心跳摘要 + 版本不一致再拉全量配置”的模型
+  * 为后续版本预留“支持文件 manifest/checksum”能力，避免未来证书文件较多时重复传输整包内容
+  * 评估为 Agent 全量配置接口启用 gzip 压缩
+* 优化日志成本
+  * 将心跳成功、HTTP 请求成功、无变更同步等高频日志降为 `debug`
+  * 保留发布、应用失败、回滚、认证失败等关键事件为 `info/warn/error`
+
+#### 5.2.3 验收标准
+
+* 在节点数量增长时，节点列表查询不再出现明显线性附加 SQL 次数
+* 心跳高频场景下数据库写入量明显下降
+* 默认 `info` 日志聚焦关键事件，不再持续刷出无变更同步日志
+
+### 5.3 工作流三：代码质量与可维护性
+
+#### 5.3.1 目标
+
+减少重复代码，让后续维护成本下降。
+
+#### 5.3.2 任务
+
+* 统一 API 响应与错误处理
+  * 提供统一响应助手函数
+  * 让控制器层只负责参数解析、调用 service、返回统一结构
+* 收敛校验逻辑
+  * 将路径、模板占位符、OpenResty 参数、上传文件等校验集中封装
+  * 避免同一规则散落在多个层级
+* 清理“功能可跑但长期难维护”的实现
+  * 减少控制器内重复 JSON decode 与错误返回样板代码
+  * 减少 service 中过长函数
+  * 对高频路径补充更精确的单元测试和表驱动测试
+
+#### 5.3.3 可优先引入的成熟开源能力
+
+* `staticcheck`
+  * 作为 Go 静态分析主工具
+* `govulncheck`
+  * 用于 Go 依赖漏洞扫描
+* `gosec`
+  * 用于高危安全模式扫描
+* `gitleaks` 或 `trufflehog`
+  * 用于仓库敏感信息扫描
+
+说明：
+
+* 这里优先引入“工程工具”和“稳定基础库”
+* 不建议为了维护期而大规模替换 Web 框架、ORM、HTTP 框架等核心依赖
+
+#### 5.3.4 验收标准
+
+* 控制器响应风格统一，重复样板代码减少
+* 新增规则优先通过统一校验函数落地，而不是散落在多个入口
+
+---
+
+## 6. 建议实施顺序
+
+### 第一阶段：安全止血
+
+* 修复路径穿越风险
+* 清理敏感示例配置
+* 为更新链路加校验
+* 接入 `gosec`、`govulncheck`、密钥扫描
+
+### 第二阶段：热点路径优化
+
+* 优化心跳写库
+* 优化节点列表查询
+* 调整日志级别
+* 补充压力下的基线数据
+
+### 第三阶段：代码收敛
+
+* 统一 API 响应帮助函数
+* 收敛校验与错误模型
+* 补充回归测试模板
+
+### 第四阶段：延伸优化
+
+* 评估配置接口压缩与更细粒度 manifest 同步
+* 评估手动上传升级链路的更安全替代实现
+* 根据实际运行数据决定是否继续做更细的持久化优化
\ No newline at end of file