mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-29 14:06:36 +08:00
ryan
4be44733e8
- Updated README.md to reflect the new support_dir for auxiliary files. - Refactored agent main.go to use support_dir instead of cert_dir. - Modified config.go to replace cert_dir with support_dir and added legacy support. - Adjusted config tests to validate support_dir usage. - Changed nginx manager to utilize support_dir for file paths. - Updated server configuration to use support_dir for SSL certificates. - Revised documentation to clarify the new configuration parameters. - Enhanced security checks for support file paths to prevent traversal attacks.
218 lines
7.2 KiB
Markdown
218 lines
7.2 KiB
Markdown
# 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 同步
|
|
* 评估手动上传升级链路的更安全替代实现
|
|
* 根据实际运行数据决定是否继续做更细的持久化优化
|