OpenFlare/docs/development-plan.md

ATSFlare 开发计划

1. 目标

当前开发目标是完成 ATSFlare 的 MVP 闭环：

后台改规则 -> 点击发布 -> Agent 拉到新版本 -> 写入 Nginx 路由配置 -> nginx 校验并 reload -> 节点状态可见

在这个闭环完成之前，不新增高级功能。

2. 里程碑

Phase 1: Server 数据层与发布闭环

目标：

• 完成 proxy_routes
• 完成 config_versions
• 能从规则生成 Nginx 路由配置
• 能激活一个全局版本

交付：

• 新模型
• AutoMigrate
• 路由 CRUD API
• 发布 API
• 激活版本 API
• 渲染 service

完成标准：

• 后台能维护规则
• 可以生成并查看版本记录

Phase 2: Agent API 与节点状态

目标：

• 建立节点注册、心跳、版本查询、应用结果上报链路

交付：

• nodes
• apply_logs
• Agent Token 鉴权
• 节点在线状态计算
• 节点与应用日志查询接口

完成标准：

• Server 能记录节点和最近状态

Phase 3: Agent 本体

目标：

• 实现最小可运行 Agent

交付：

• 本地配置文件读取
• node_id 持久化
• 心跳循环
• 版本检查
• 下载配置
• 写入 Nginx 路由配置
• 配置校验、reload 与失败回滚
• 应用结果上报

完成标准：

• 单节点可跑通“发布到 Nginx 生效”的闭环

Phase 4: 管理端页面

目标：

• 提供 MVP 所需最小可视化界面

交付：

• 反代规则页
• 版本页
• 节点页
• 应用记录页

完成标准：

• 不依赖直接查库即可完成日常操作和排障

Phase 5: 联调与收尾

目标：

• 完成本地或测试环境联调
• 补齐运行说明

交付：

• 手工部署说明
• Agent 配置示例
• 最小联调脚本或命令说明
• 问题清单与后续迭代列表

完成标准：

• 新环境能按文档手工部署并跑通最小闭环

3. 当前建议执行顺序

建议严格按以下顺序开发：

1. Server 模型和 AutoMigrate
2. 路由 CRUD 与发布逻辑
3. Agent API 与节点状态表
4. Agent 同步、落盘、reload、回滚
5. 管理端页面
6. 联调和部署文档

不要先做以下内容：

• 权限扩展
• 缓存策略平台化
• 证书平台化
• 多节点分批发布
• 高级监控接入

4. 每阶段的验收检查

Phase 1 检查项

• 可以创建、编辑、删除反代规则
• 可以基于当前规则生成版本
• 可以查看哪个版本处于激活状态
• 激活旧版本时不会修改历史快照

Phase 2 检查项

• Agent 可以通过 Token 访问 Agent API
• 节点可以注册并重复心跳
• 节点超过超时时间会显示为离线
• 可以查询节点最近一次应用状态

Phase 3 检查项

• Agent 检测到新版本后会下载配置
• 写入前会备份旧路由配置文件
• nginx -t 或 reload 失败后会回滚
• 回滚结果会回传给 Server
• Agent 可使用独立 Nginx 路径或 Docker Nginx 容器运行

Phase 4 检查项

• 页面可直接完成规则维护和发布
• 页面可查看节点在线状态
• 页面可查看应用失败原因

Phase 5 检查项

• 按文档可完成一次从零部署
• 至少完成一次真实联调记录
• 已记录当前遗留问题和下一阶段候选项

5. 变更控制

开发中如果出现以下情况，需要先调整计划再继续编码：

• MVP 目标发生变化
• 需要引入新的中间件
• 需要新增核心数据模型
• 需要把控制面扩展到独立生成的 Nginx 路由配置文件之外

计划更新时，应同步修改：

• docs/design.md
• docs/development-guidelines.md
• docs/development-plan.md