mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-10-03 23:06:36 +08:00
docs: plan V2 development - HTTPS, token mgmt, node groups, custom headers, config preview
Co-authored-by: Rain-kl <63696351+Rain-kl@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
+152
-96
@@ -8,56 +8,31 @@
|
||||
后台改规则 -> 点击发布 -> Agent 拉到新版本 -> 写入 Nginx 路由配置 -> nginx 校验并 reload -> 节点状态可见
|
||||
```
|
||||
|
||||
在这个闭环完成之前，不新增高级功能。
|
||||
MVP 已于第一版完成。当前进入第二版迭代。
|
||||
|
||||
## 2. 里程碑
|
||||
## 2. 第一版里程碑（已完成）
|
||||
|
||||
### Phase 1: Server 数据层与发布闭环
|
||||
|
||||
目标：
|
||||
|
||||
* 完成 `proxy_routes`
|
||||
* 完成 `config_versions`
|
||||
* 能从规则生成 Nginx 路由配置
|
||||
* 能激活一个全局版本
|
||||
### Phase 1: Server 数据层与发布闭环 ✅
|
||||
|
||||
交付：
|
||||
|
||||
* 新模型
|
||||
* 新模型（proxy_routes、config_versions）
|
||||
* AutoMigrate
|
||||
* 路由 CRUD API
|
||||
* 发布 API
|
||||
* 激活版本 API
|
||||
* 渲染 service
|
||||
|
||||
完成标准：
|
||||
|
||||
* 后台能维护规则
|
||||
* 可以生成并查看版本记录
|
||||
|
||||
### Phase 2: Agent API 与节点状态
|
||||
|
||||
目标：
|
||||
|
||||
* 建立节点注册、心跳、版本查询、应用结果上报链路
|
||||
### Phase 2: Agent API 与节点状态 ✅
|
||||
|
||||
交付：
|
||||
|
||||
* `nodes`
|
||||
* `apply_logs`
|
||||
* Agent Token 鉴权
|
||||
* `nodes`、`apply_logs`
|
||||
* Agent Token 鉴权（全局单 Token）
|
||||
* 节点在线状态计算
|
||||
* 节点与应用日志查询接口
|
||||
|
||||
完成标准：
|
||||
|
||||
* Server 能记录节点和最近状态
|
||||
|
||||
### Phase 3: Agent 本体
|
||||
|
||||
目标：
|
||||
|
||||
* 实现最小可运行 Agent
|
||||
### Phase 3: Agent 本体 ✅
|
||||
|
||||
交付：
|
||||
|
||||
@@ -70,15 +45,7 @@
|
||||
* 配置校验、reload 与失败回滚
|
||||
* 应用结果上报
|
||||
|
||||
完成标准：
|
||||
|
||||
* 单节点可跑通“发布到 Nginx 生效”的闭环
|
||||
|
||||
### Phase 4: 管理端页面
|
||||
|
||||
目标：
|
||||
|
||||
* 提供 MVP 所需最小可视化界面
|
||||
### Phase 4: 管理端页面 ✅
|
||||
|
||||
交付：
|
||||
|
||||
@@ -87,91 +54,180 @@
|
||||
* 节点页
|
||||
* 应用记录页
|
||||
|
||||
完成标准：
|
||||
|
||||
* 不依赖直接查库即可完成日常操作和排障
|
||||
|
||||
### Phase 5: 联调与收尾
|
||||
|
||||
目标：
|
||||
|
||||
* 完成本地或测试环境联调
|
||||
* 补齐运行说明
|
||||
### Phase 5: 联调与收尾 ✅
|
||||
|
||||
交付：
|
||||
|
||||
* 手工部署说明
|
||||
* Agent 配置示例
|
||||
* 最小联调脚本或命令说明
|
||||
* 问题清单与后续迭代列表
|
||||
* 联调验证记录
|
||||
|
||||
## 3. 第二版里程碑
|
||||
|
||||
### V2 Phase 1: HTTPS/TLS 支持
|
||||
|
||||
目标：
|
||||
|
||||
* 支持通过控制面配置 HTTPS 路由
|
||||
* 渲染出包含 443 端口的 `server` 块
|
||||
* 支持 HTTP → HTTPS 重定向块
|
||||
|
||||
交付：
|
||||
|
||||
* `proxy_routes` 新增字段：`enable_https`、`ssl_cert_path`、`ssl_key_path`、`redirect_http`
|
||||
* 渲染器支持 HTTPS server 块生成
|
||||
* 前端反代规则页增加 HTTPS 配置表单
|
||||
* AutoMigrate 覆盖新字段
|
||||
|
||||
完成标准：
|
||||
|
||||
* 新环境能按文档手工部署并跑通最小闭环
|
||||
* 创建含 HTTPS 字段的路由并发布，Agent 拉取后 Nginx 能以 HTTPS 正确转发
|
||||
* HTTP 重定向配置生效
|
||||
* 未开启 HTTPS 的路由渲染行为与第一版保持一致
|
||||
|
||||
## 3. 当前建议执行顺序
|
||||
### V2 Phase 2: Agent Token 管理
|
||||
|
||||
目标：
|
||||
|
||||
* 支持多个命名 Token
|
||||
* Token 可通过管理界面创建和撤销
|
||||
* 中间件改为查库验证
|
||||
|
||||
交付：
|
||||
|
||||
* `agent_tokens` 表与模型
|
||||
* agent-auth 中间件改造（查表验证）
|
||||
* 全局 Token 环境变量降级为 bootstrap 模式
|
||||
* Token CRUD API
|
||||
* 前端 Token 管理页
|
||||
|
||||
完成标准：
|
||||
|
||||
* 新建 Token 后 Agent 可用该 Token 访问 Agent API
|
||||
* 撤销 Token 后 Agent 请求立即返回 401
|
||||
* 全局环境变量 Token 仅在数据库无有效记录时生效
|
||||
|
||||
### V2 Phase 3: 节点分组与差异化下发
|
||||
|
||||
目标：
|
||||
|
||||
* 节点可按分组管理
|
||||
* 发布时可选择目标分组，生成分组专属版本
|
||||
* Agent 按分组拉取对应激活版本
|
||||
|
||||
交付：
|
||||
|
||||
* `node_groups` 表与模型
|
||||
* `nodes` 新增 `group_id` 字段
|
||||
* `config_versions` 新增 `group_id` 字段（nullable，null 表示全量）
|
||||
* 发布 API 接受可选 `group_id` 参数
|
||||
* Agent API 按节点分组返回对应激活版本
|
||||
* Agent `agent.json` 新增 `group_id` 配置项
|
||||
* 前端节点分组管理页与节点页分组字段
|
||||
|
||||
完成标准：
|
||||
|
||||
* 同一系统内 staging 和 production 分组各有独立激活版本
|
||||
* staging 节点拉取 staging 版本，production 节点拉取 production 版本
|
||||
* 不属于任何分组的节点拉取全量（group_id = null）版本
|
||||
|
||||
### V2 Phase 4: 路由自定义头
|
||||
|
||||
目标：
|
||||
|
||||
* 每条路由支持追加自定义 `proxy_set_header` 指令
|
||||
|
||||
交付：
|
||||
|
||||
* `proxy_routes` 新增 `custom_headers` 字段（JSON，`[{"key":"X-My-Header","value":"foo"}]`）
|
||||
* 渲染器按 `custom_headers` 在 `location /` 块中注入额外 header 指令
|
||||
* 前端反代规则页增加自定义头编辑器
|
||||
|
||||
完成标准：
|
||||
|
||||
* 路由配置自定义头后发布，渲染结果包含对应 `proxy_set_header` 指令
|
||||
* 不配置自定义头的路由渲染行为与之前保持一致
|
||||
|
||||
### V2 Phase 5: 配置预览与变更摘要
|
||||
|
||||
目标：
|
||||
|
||||
* 发布前可预览渲染结果
|
||||
* 发布前可查看与当前激活版本的变更摘要
|
||||
|
||||
交付：
|
||||
|
||||
* `GET /api/config-versions/preview` 接口（返回渲染后的 Nginx 配置，不写库）
|
||||
* `GET /api/config-versions/diff` 接口（返回新增/删除/修改的域名列表）
|
||||
* 前端发布版本页增加"预览"按钮和变更摘要展示弹窗
|
||||
|
||||
完成标准：
|
||||
|
||||
* 点击预览可查看即将生成的 Nginx 配置文本
|
||||
* 变更摘要正确列出相对于当前激活版本的域名变化
|
||||
* 预览和 diff 操作不产生版本记录
|
||||
|
||||
## 4. 第二版建议执行顺序
|
||||
|
||||
建议严格按以下顺序开发：
|
||||
|
||||
1. Server 模型和 `AutoMigrate`
|
||||
2. 路由 CRUD 与发布逻辑
|
||||
3. Agent API 与节点状态表
|
||||
4. Agent 同步、落盘、reload、回滚
|
||||
5. 管理端页面
|
||||
6. 联调和部署文档
|
||||
1. HTTPS/TLS 支持（对现有渲染链路影响最小，独立可测）
|
||||
2. Agent Token 管理（安全性改善，早做早稳）
|
||||
3. 节点分组（数据模型扩展，影响面最广，需要 Agent 配合）
|
||||
4. 路由自定义头（纯增量，对现有结构影响小）
|
||||
5. 配置预览与变更摘要（纯只读接口，最后补充）
|
||||
|
||||
不要先做以下内容：
|
||||
|
||||
* 权限扩展
|
||||
* 缓存策略平台化
|
||||
* 证书平台化
|
||||
* 多节点分批发布
|
||||
* 高级监控接入
|
||||
* 证书托管
|
||||
* 灰度百分比发布
|
||||
* WAF、限流
|
||||
* Redis、Prometheus
|
||||
* 多租户
|
||||
|
||||
## 4. 每阶段的验收检查
|
||||
## 5. 第二版每阶段验收检查
|
||||
|
||||
### Phase 1 检查项
|
||||
### V2 Phase 1 检查项
|
||||
|
||||
* 可以创建、编辑、删除反代规则
|
||||
* 可以基于当前规则生成版本
|
||||
* 可以查看哪个版本处于激活状态
|
||||
* 激活旧版本时不会修改历史快照
|
||||
* `enable_https=true` 的路由发布后生成 443 端口 server 块
|
||||
* `redirect_http=true` 的路由生成 80 → 443 重定向块
|
||||
* 未开启 HTTPS 的路由渲染结果不受影响
|
||||
* Agent 拉取后 Nginx reload 成功
|
||||
|
||||
### Phase 2 检查项
|
||||
### V2 Phase 2 检查项
|
||||
|
||||
* Agent 可以通过 Token 访问 Agent API
|
||||
* 节点可以注册并重复心跳
|
||||
* 节点超过超时时间会显示为离线
|
||||
* 可以查询节点最近一次应用状态
|
||||
* 可通过管理界面创建 Token
|
||||
* 新 Token 可被 Agent 使用
|
||||
* 撤销 Token 后访问立即失败
|
||||
* 全局 Token 环境变量在数据库有记录时失效
|
||||
|
||||
### Phase 3 检查项
|
||||
### V2 Phase 3 检查项
|
||||
|
||||
* Agent 检测到新版本后会下载配置
|
||||
* 写入前会备份旧路由配置文件
|
||||
* `nginx -t` 或 reload 失败后会回滚
|
||||
* 回滚结果会回传给 Server
|
||||
* Agent 可使用独立 Nginx 路径或 Docker Nginx 容器运行
|
||||
* 可创建分组并将节点归入分组
|
||||
* 可发布面向指定分组的版本
|
||||
* 分组节点只拉取该分组的激活版本
|
||||
* 无分组节点拉取全量激活版本
|
||||
|
||||
### Phase 4 检查项
|
||||
### V2 Phase 4 检查项
|
||||
|
||||
* 页面可直接完成规则维护和发布
|
||||
* 页面可查看节点在线状态
|
||||
* 页面可查看应用失败原因
|
||||
* 路由可添加自定义头
|
||||
* 渲染结果中正确包含自定义 header 指令
|
||||
* 无自定义头的路由渲染结果不受影响
|
||||
|
||||
### Phase 5 检查项
|
||||
### V2 Phase 5 检查项
|
||||
|
||||
* 按文档可完成一次从零部署
|
||||
* 至少完成一次真实联调记录
|
||||
* 已记录当前遗留问题和下一阶段候选项
|
||||
* 预览接口返回正确的 Nginx 配置文本
|
||||
* diff 接口返回正确的域名变更列表
|
||||
* 两个接口均不产生数据库写入
|
||||
|
||||
## 5. 变更控制
|
||||
## 6. 变更控制
|
||||
|
||||
开发中如果出现以下情况，需要先调整计划再继续编码：
|
||||
|
||||
* MVP 目标发生变化
|
||||
* 需要引入新的中间件
|
||||
* V2 目标发生变化
|
||||
* 需要引入新的中间件（Redis、MQ 等）
|
||||
* 需要新增核心数据模型
|
||||
* 需要把控制面扩展到独立生成的 Nginx 路由配置文件之外
|
||||
* 需要把控制面扩展到 Nginx 全局配置
|
||||
|
||||
计划更新时，应同步修改：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user