# 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` 时缺少对目标路径必须位于 `support_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` 或安全辅助函数确认最终路径仍位于 `support_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 同步
* 评估手动上传升级链路的更安全替代实现
* 根据实际运行数据决定是否继续做更细的持久化优化