tcjlj/OpenFlare
1
0
Fork 0
mirror of https://github.com/Rain-kl/OpenFlare.git synced 2026-09-29 05:56:38 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
d4e38ee6fb1dc076c9602caeab6d0c173e733fed
OpenFlare/docs/improve_plan.md
T
ryan 32d90ba641 [优化] 改名
2026-03-15 16:26:56 +08:00

7.2 KiB
Raw Blame History

OpenFlare 整理维护期改进计划

1. 背景

项目当前已具备可用的 Server / Agent / OpenResty 控制链路，接下来进入整理维护期。 这一阶段不再以新增大功能为主，而是集中处理三类问题：

  • 架构层面的通信与存储开销
  • 代码质量、可维护性与复用度
  • 高风险安全问题与供应链风险

本计划遵循当前基线：

  • 不改变 Server 统一生成配置、Agent 受控落盘的核心边界
  • 优先通过收敛实现、减少重复、补齐校验和测试来提升系统质量

2. 目标

2.1 总目标

在不扩大产品边界的前提下，把 OpenFlare 从“功能可用”推进到“长期可维护、风险可控、成本可预测”。

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 同步
  • 评估手动上传升级链路的更安全替代实现
  • 根据实际运行数据决定是否继续做更细的持久化优化
Reference in New Issue View Git Blame Copy Permalink