mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-09-28 05:46:36 +08:00
Merge pull request #1 from Rain-kl/copilot/plan-v2-development-schedule
docs: plan ATSFlare V2 development
This commit is contained in:
Rain
+251
-74
@@ -12,9 +12,9 @@
|
||||
|
||||
---
|
||||
|
||||
## 2. 第一版范围
|
||||
## 2. 第一版范围（已完成）
|
||||
|
||||
### 要做
|
||||
### 已做
|
||||
|
||||
* Web 管理端维护反代规则
|
||||
* 配置发布生成版本
|
||||
@@ -23,7 +23,7 @@
|
||||
* 节点注册、心跳、在线状态展示
|
||||
* 展示每个节点当前生效版本和最近一次应用结果
|
||||
|
||||
### 不做
|
||||
### 不做（第一版）
|
||||
|
||||
* 多租户
|
||||
* WAF、限流、Bot、防刷
|
||||
@@ -38,6 +38,56 @@
|
||||
|
||||
---
|
||||
|
||||
## 2.5 第二版范围
|
||||
|
||||
在 MVP 闭环稳定运行的基础上，第二版聚焦以下增量能力。
|
||||
|
||||
### 要做
|
||||
|
||||
**2.5.1 HTTPS/TLS 支持**
|
||||
|
||||
* `proxy_routes` 增加 HTTPS 相关字段：`enable_https`、`ssl_cert_path`、`ssl_key_path`
|
||||
* 渲染器根据字段生成 HTTPS `server` 块（443 端口），并可选生成 HTTP → HTTPS 重定向块
|
||||
* 证书文件仍由节点本地预先准备，控制面只记录路径，不托管证书
|
||||
|
||||
**2.5.2 节点分组与差异化下发**
|
||||
|
||||
* 新增 `node_groups` 表：管理分组（如 staging、production）
|
||||
* `nodes` 增加 `group_id` 字段，节点可归属某个分组
|
||||
* 发布时可选择目标分组，生成面向该分组的版本
|
||||
* 不指定分组时，默认行为与第一版相同（全量下发）
|
||||
* Agent 在心跳时携带自身分组信息，Server 按分组返回对应激活版本
|
||||
|
||||
**2.5.3 Agent Token 管理**
|
||||
|
||||
* 新增 `agent_tokens` 表：支持创建多个命名 Token，记录备注、创建人、过期时间
|
||||
* 认证中间件改为查表验证，不再依赖单个全局环境变量
|
||||
* 提供 Token CRUD 管理 API 及前端页面
|
||||
* 旧的全局 Token 环境变量作为引导 Token，仅在数据库无 Token 记录时生效（bootstrap 模式）
|
||||
|
||||
**2.5.4 路由增强**
|
||||
|
||||
* `proxy_routes` 增加 `custom_headers` 字段（JSON 格式），支持每条路由追加自定义 `proxy_set_header` 指令
|
||||
* 渲染器按 `custom_headers` 内容注入到对应 `server` 块
|
||||
|
||||
**2.5.5 配置预览与变更摘要**
|
||||
|
||||
* 新增"配置预览"接口：在不实际发布的情况下，返回基于当前启用规则渲染的 Nginx 配置
|
||||
* 新增"变更摘要"接口：对比当前激活版本与新渲染结果，返回新增、删除、修改的域名列表
|
||||
* 前端发布页接入预览与变更摘要，让管理员在点击发布前确认变化
|
||||
|
||||
### 仍不做（第二版）
|
||||
|
||||
* 多租户
|
||||
* WAF、限流、Bot、防刷
|
||||
* 对象存储、消息队列、Redis、Prometheus
|
||||
* 证书托管与自动签发
|
||||
* Purge、中台审计、审批流
|
||||
* mid-tier / 分层缓存
|
||||
* 复杂缓存策略配置
|
||||
|
||||
---
|
||||
|
||||
## 3. 技术约束
|
||||
|
||||
### Server
|
||||
@@ -120,9 +170,7 @@ Agent 使用 Go 单体程序：
|
||||
|
||||
## 5. 核心对象
|
||||
|
||||
第一版只保留最少的数据模型。
|
||||
|
||||
### 5.1 proxy_routes
|
||||
### 5.1 proxy_routes（第一版）
|
||||
|
||||
反代规则表，控制 `Host -> Origin` 映射。
|
||||
|
||||
@@ -142,7 +190,15 @@ Agent 使用 Go 单体程序：
|
||||
* `origin_url` 必须是合法的 `http://` 或 `https://`
|
||||
* 第一版一条域名只对应一个源站，不做源站池
|
||||
|
||||
### 5.2 config_versions
|
||||
第二版新增字段：
|
||||
|
||||
* `enable_https` — 是否启用 HTTPS（bool，默认 false）
|
||||
* `ssl_cert_path` — 节点本地证书文件路径（string）
|
||||
* `ssl_key_path` — 节点本地私钥文件路径（string）
|
||||
* `redirect_http` — 是否将 HTTP 重定向到 HTTPS（bool，默认 false）
|
||||
* `custom_headers` — 自定义 `proxy_set_header` 指令（JSON 格式，存字符串）
|
||||
|
||||
### 5.2 config_versions（第一版）
|
||||
|
||||
发布版本表，保存不可变快照。
|
||||
|
||||
@@ -163,7 +219,11 @@ Agent 使用 Go 单体程序：
|
||||
* `rendered_config` 保存渲染后的 Nginx 路由配置
|
||||
* 第一版直接存 SQLite，不单独上对象存储
|
||||
|
||||
### 5.3 nodes
|
||||
第二版新增字段：
|
||||
|
||||
* `group_id` — 关联目标分组（nullable，null 表示全量发布）
|
||||
|
||||
### 5.3 nodes（第一版）
|
||||
|
||||
节点表，保存当前状态。
|
||||
|
||||
@@ -182,7 +242,11 @@ Agent 使用 Go 单体程序：
|
||||
* `created_at`
|
||||
* `updated_at`
|
||||
|
||||
### 5.4 apply_logs
|
||||
第二版新增字段：
|
||||
|
||||
* `group_id` — 所属节点分组（nullable，无分组时为 null）
|
||||
|
||||
### 5.4 apply_logs（第一版）
|
||||
|
||||
节点应用记录。
|
||||
|
||||
@@ -195,6 +259,33 @@ Agent 使用 Go 单体程序：
|
||||
* `message`
|
||||
* `created_at`
|
||||
|
||||
### 5.5 node_groups（第二版新增）
|
||||
|
||||
节点分组表，用于差异化下发。
|
||||
|
||||
建议字段：
|
||||
|
||||
* `id`
|
||||
* `name` — 分组名称，唯一（如 `staging`、`production`）
|
||||
* `remark` — 备注
|
||||
* `created_at`
|
||||
* `updated_at`
|
||||
|
||||
### 5.6 agent_tokens（第二版新增）
|
||||
|
||||
Agent Token 管理表，替代全局单一 Token。
|
||||
|
||||
建议字段：
|
||||
|
||||
* `id`
|
||||
* `token` — Token 值，唯一，不可变
|
||||
* `name` — Token 备注名称
|
||||
* `created_by` — 创建人
|
||||
* `expires_at` — 过期时间（nullable，null 表示永不过期）
|
||||
* `is_active` — 是否有效
|
||||
* `created_at`
|
||||
* `updated_at`
|
||||
|
||||
---
|
||||
|
||||
## 6. 配置发布模型
|
||||
@@ -399,49 +490,63 @@ Agent 每次上报：
|
||||
|
||||
## 11. API 设计
|
||||
|
||||
### 11.1 管理端 API
|
||||
### 11.1 管理端 API（第一版，已实现）
|
||||
|
||||
* `GET /api/routes`
|
||||
* `POST /api/routes`
|
||||
* `PUT /api/routes/:id`
|
||||
* `DELETE /api/routes/:id`
|
||||
* `GET /api/versions`
|
||||
* `POST /api/versions/publish`
|
||||
* `POST /api/versions/:id/activate`
|
||||
* `GET /api/nodes`
|
||||
* `GET /api/apply-logs`
|
||||
* `GET /api/proxy-routes/`
|
||||
* `POST /api/proxy-routes/`
|
||||
* `PUT /api/proxy-routes/:id`
|
||||
* `DELETE /api/proxy-routes/:id`
|
||||
* `GET /api/config-versions/`
|
||||
* `GET /api/config-versions/active`
|
||||
* `POST /api/config-versions/publish`
|
||||
* `PUT /api/config-versions/:id/activate`
|
||||
* `GET /api/nodes/`
|
||||
* `GET /api/apply-logs/`
|
||||
|
||||
### 11.2 Agent API
|
||||
### 11.2 Agent API（第一版，已实现）
|
||||
|
||||
* `POST /api/agent/register`
|
||||
* `POST /api/agent/heartbeat`
|
||||
* `GET /api/agent/version/active`
|
||||
* `GET /api/agent/versions/:version`
|
||||
* `POST /api/agent/apply-result`
|
||||
* `POST /api/agent/nodes/register`
|
||||
* `POST /api/agent/nodes/heartbeat`
|
||||
* `GET /api/agent/config-versions/active`
|
||||
* `POST /api/agent/apply-logs`
|
||||
|
||||
### 11.3 鉴权方案
|
||||
### 11.3 第二版新增管理端 API
|
||||
|
||||
* `GET /api/node-groups/` — 分组列表
|
||||
* `POST /api/node-groups/` — 创建分组
|
||||
* `PUT /api/node-groups/:id` — 更新分组
|
||||
* `DELETE /api/node-groups/:id` — 删除分组
|
||||
* `GET /api/agent-tokens/` — Token 列表
|
||||
* `POST /api/agent-tokens/` — 创建 Token
|
||||
* `DELETE /api/agent-tokens/:id` — 撤销 Token
|
||||
* `GET /api/config-versions/preview` — 预览当前启用规则的渲染结果（不写库）
|
||||
* `GET /api/config-versions/diff` — 对比当前激活版本与待发布的变更摘要
|
||||
|
||||
### 11.4 鉴权方案
|
||||
|
||||
管理端：
|
||||
|
||||
* 直接沿用 gin-template 的登录态
|
||||
|
||||
Agent：
|
||||
Agent（第一版）：
|
||||
|
||||
* 第一版使用预共享 Token
|
||||
* 例如请求头 `X-Agent-Token`
|
||||
* 后续再升级 mTLS
|
||||
* 预共享 Token，请求头 `X-Agent-Token`，Token 值来自环境变量
|
||||
|
||||
Agent（第二版）：
|
||||
|
||||
* Token 改为查 `agent_tokens` 表验证
|
||||
* 环境变量 Token 仅作 bootstrap 引导 Token，数据库有记录时不再使用
|
||||
* 后续可升级 mTLS
|
||||
|
||||
---
|
||||
|
||||
## 12. 页面设计
|
||||
|
||||
第一版只保留最少页面。
|
||||
|
||||
### 12.1 登录页
|
||||
|
||||
沿用 gin-template 现有登录。
|
||||
|
||||
### 12.2 反代规则页
|
||||
### 12.2 反代规则页（第一版，已实现）
|
||||
|
||||
展示和编辑：
|
||||
|
||||
@@ -450,7 +555,15 @@ Agent：
|
||||
* 是否启用
|
||||
* 备注
|
||||
|
||||
### 12.3 发布版本页
|
||||
第二版新增字段：
|
||||
|
||||
* 是否启用 HTTPS
|
||||
* SSL 证书路径
|
||||
* SSL 私钥路径
|
||||
* 是否 HTTP → HTTPS 重定向
|
||||
* 自定义请求头（JSON 编辑器）
|
||||
|
||||
### 12.3 发布版本页（第一版，已实现）
|
||||
|
||||
展示：
|
||||
|
||||
@@ -464,7 +577,12 @@ Agent：
|
||||
* 立即发布
|
||||
* 激活旧版本
|
||||
|
||||
### 12.4 节点页
|
||||
第二版新增：
|
||||
|
||||
* 发布目标分组选择（可选，不选则全量）
|
||||
* 发布前展示配置预览与变更摘要
|
||||
|
||||
### 12.4 节点页（第一版，已实现）
|
||||
|
||||
展示：
|
||||
|
||||
@@ -475,7 +593,11 @@ Agent：
|
||||
* 最后心跳时间
|
||||
* 最近错误
|
||||
|
||||
### 12.5 应用记录页
|
||||
第二版新增：
|
||||
|
||||
* 所属分组
|
||||
|
||||
### 12.5 应用记录页（第一版，已实现）
|
||||
|
||||
展示：
|
||||
|
||||
@@ -485,19 +607,45 @@ Agent：
|
||||
* 错误信息
|
||||
* 时间
|
||||
|
||||
### 12.6 Token 管理页（第二版新增）
|
||||
|
||||
展示：
|
||||
|
||||
* Token 名称
|
||||
* 创建人
|
||||
* 过期时间
|
||||
* 是否有效
|
||||
|
||||
动作：
|
||||
|
||||
* 创建 Token
|
||||
* 撤销 Token
|
||||
|
||||
### 12.7 节点分组页（第二版新增）
|
||||
|
||||
展示：
|
||||
|
||||
* 分组名称
|
||||
* 备注
|
||||
* 该分组下节点数
|
||||
|
||||
动作：
|
||||
|
||||
* 创建分组
|
||||
* 编辑分组
|
||||
* 删除分组
|
||||
|
||||
---
|
||||
|
||||
## 13. 代码组织建议
|
||||
|
||||
### Server
|
||||
|
||||
建议直接在现有 `atsf_server` 下新增以下内容：
|
||||
### Server（第一版，已实现）
|
||||
|
||||
```text
|
||||
atsf_server/
|
||||
controller/
|
||||
route.go
|
||||
version.go
|
||||
proxy_route.go
|
||||
config_version.go
|
||||
node.go
|
||||
agent.go
|
||||
model/
|
||||
@@ -508,58 +656,73 @@ atsf_server/
|
||||
router/
|
||||
api-router.go
|
||||
service/
|
||||
publisher.go
|
||||
renderer.go
|
||||
proxy_route.go
|
||||
config_version.go
|
||||
agent.go
|
||||
```
|
||||
|
||||
### Agent
|
||||
### Server（第二版新增）
|
||||
|
||||
建议新建独立目录：
|
||||
```text
|
||||
atsf_server/
|
||||
controller/
|
||||
node_group.go # 节点分组 CRUD
|
||||
agent_token.go # Token 管理
|
||||
model/
|
||||
node_group.go # NodeGroup 模型
|
||||
agent_token.go # AgentToken 模型
|
||||
service/
|
||||
node_group.go # 分组逻辑
|
||||
agent_token.go # Token 创建与验证
|
||||
renderer.go # 抽离渲染逻辑（HTTPS 支持扩展）
|
||||
middleware/
|
||||
agent-auth.go # 改为查表验证
|
||||
```
|
||||
|
||||
### Agent（第一版，已实现）
|
||||
|
||||
```text
|
||||
atsf_agent/
|
||||
cmd/agent/main.go
|
||||
internal/config/config.go
|
||||
internal/heartbeat/heartbeat.go
|
||||
internal/sync/sync.go
|
||||
internal/nginx/nginx.go
|
||||
internal/heartbeat/service.go
|
||||
internal/sync/service.go
|
||||
internal/nginx/manager.go
|
||||
internal/state/state.go
|
||||
internal/httpclient/client.go
|
||||
internal/protocol/agent_api.go
|
||||
```
|
||||
|
||||
### Agent（第二版）
|
||||
|
||||
第二版 Agent 无需新增模块，只需在现有模块内扩展：
|
||||
|
||||
* `config`: 新增 `group_id` 配置项
|
||||
* `heartbeat`: 心跳请求中携带 `group_id`
|
||||
* `sync`: 按分组获取对应激活版本（Server 端路由区分）
|
||||
|
||||
---
|
||||
|
||||
## 14. 开发顺序
|
||||
|
||||
按下面的顺序最稳。
|
||||
### 第一版（已完成）
|
||||
|
||||
### 第一阶段
|
||||
1. Server 建表、AutoMigrate
|
||||
2. 反代规则 CRUD 与发布逻辑
|
||||
3. Agent API 与节点状态表
|
||||
4. Agent 同步、落盘、reload、回滚
|
||||
5. 管理端页面
|
||||
6. 联调和部署文档
|
||||
|
||||
先把 Server 跑通：
|
||||
### 第二版（当前阶段）
|
||||
|
||||
* 建表
|
||||
* 反代规则 CRUD
|
||||
* 发布版本表
|
||||
* 版本渲染逻辑
|
||||
按以下顺序执行，前项完成后再推进下一项：
|
||||
|
||||
### 第二阶段
|
||||
|
||||
做 Agent 最小闭环：
|
||||
|
||||
* 注册
|
||||
* 心跳
|
||||
* 拉取激活版本
|
||||
* 写入 Nginx 路由配置
|
||||
* `nginx -t && nginx -s reload`
|
||||
* 应用结果上报
|
||||
|
||||
### 第三阶段
|
||||
|
||||
补管理端页面：
|
||||
|
||||
* 规则页
|
||||
* 版本页
|
||||
* 节点页
|
||||
* 应用日志页
|
||||
1. HTTPS/TLS 支持（ProxyRoute 扩展字段 + 渲染器 + 前端表单）
|
||||
2. Agent Token 管理（agent_tokens 表 + 中间件改造 + 前端 Token 管理页）
|
||||
3. 节点分组与差异化下发（node_groups 表 + 发布分组逻辑 + Agent 携带 group_id）
|
||||
4. 路由增强（custom_headers 字段 + 渲染器注入 + 前端表单）
|
||||
5. 配置预览与变更摘要（preview 接口 + diff 接口 + 前端发布确认弹窗）
|
||||
|
||||
---
|
||||
|
||||
@@ -580,3 +743,17 @@ atsf_agent/
|
||||
```
|
||||
|
||||
这就是当前阶段最需要的 MVP。
|
||||
|
||||
### 第二版取舍
|
||||
|
||||
* HTTPS 支持不托管证书，只记录本地路径，避免引入证书存储和签发复杂度
|
||||
* 节点分组不做跨分组继承，每个分组独立一套激活版本，降低理解负担
|
||||
* Token 管理不做细粒度权限（如只读 Token），第二版所有 Token 权限一致
|
||||
* 路由自定义头不做模板变量，只支持静态 key-value，避免过早引入 DSL
|
||||
* 配置预览只展示渲染结果，不实际验证 Nginx 语法，真实校验仍由 Agent 完成
|
||||
|
||||
第二版成功标准：
|
||||
|
||||
```text
|
||||
HTTPS 路由可生效 + 节点可按分组差异化下发 + Token 可在界面管理 + 发布前可预览变更
|
||||
```
|
||||
|
||||
@@ -2,19 +2,27 @@
|
||||
|
||||
## 1. 适用范围
|
||||
|
||||
本规范适用于 ATSFlare 当前 MVP 阶段。
|
||||
本规范适用于 ATSFlare 第一版与第二版阶段。
|
||||
|
||||
项目当前只做以下能力：
|
||||
项目第一版已完成以下能力：
|
||||
|
||||
* 配置发布与同步
|
||||
* 节点心跳检测
|
||||
* Nginx 反向代理配置下发
|
||||
|
||||
当前明确不做：
|
||||
第二版在此基础上新增以下能力：
|
||||
|
||||
* HTTPS/TLS 路由支持
|
||||
* Agent Token 管理
|
||||
* 节点分组与差异化下发
|
||||
* 路由自定义请求头
|
||||
* 配置预览与变更摘要
|
||||
|
||||
当前明确仍不做：
|
||||
|
||||
* 多租户
|
||||
* WAF、限流、Bot、防刷
|
||||
* 灰度发布、分组发布、百分比发布
|
||||
* 百分比灰度发布
|
||||
* Redis、MQ、对象存储、Prometheus
|
||||
* 复杂缓存策略、证书托管、Purge、审批流
|
||||
* mid-tier、分层缓存、复杂策略编排
|
||||
@@ -107,32 +115,38 @@ Agent 放在 `atsf_agent`，使用 Go 单体程序开发。
|
||||
所有实现都必须遵守以下原则：
|
||||
|
||||
* 先完成闭环，再做抽象。
|
||||
* 不为了“以后可能会支持”提前引入复杂模型。
|
||||
* 不为了"以后可能会支持"提前引入复杂模型。
|
||||
* Server 只管状态和配置，不直接 SSH 改节点。
|
||||
* Agent 是唯一落地入口。
|
||||
* 所有发布都是“新版本激活”，不是在线覆盖编辑。
|
||||
* 所有节点默认拉同一份全量配置，不做差异化编排。
|
||||
* 所有发布都是"新版本激活"，不是在线覆盖编辑。
|
||||
* 第一版：所有节点默认拉同一份全量配置；第二版：可按节点分组差异化下发。
|
||||
* 能用 SQLite 解决的问题，不引入额外中间件。
|
||||
* 新功能优先复用现有 gin-template 结构，不平行造第二套框架。
|
||||
|
||||
## 5. 数据模型规范
|
||||
|
||||
第一版只允许引入以下核心实体：
|
||||
第一版核心实体（已实现）：
|
||||
|
||||
* `proxy_routes`
|
||||
* `config_versions`
|
||||
* `nodes`
|
||||
* `apply_logs`
|
||||
|
||||
约束：
|
||||
第二版新增实体：
|
||||
|
||||
* `node_groups` — 节点分组
|
||||
* `agent_tokens` — Agent Token 管理
|
||||
|
||||
约束（全版本）：
|
||||
|
||||
* 不新增 `zone`、`origin_pool`、`policy`、`deployment` 这类平台化对象
|
||||
* `proxy_routes` 一条域名只对应一个 `origin_url`
|
||||
* `config_versions` 必须保存完整快照和渲染后的 Nginx 路由配置
|
||||
* 激活版本全局只能有一个
|
||||
* 回滚通过“激活旧版本”实现，不直接修改历史记录
|
||||
* 同一分组内激活版本只能有一个；全量版本（group_id = null）全局只能有一个
|
||||
* 回滚通过"激活旧版本"实现，不直接修改历史记录
|
||||
* `agent_tokens` 中的 Token 值不可更新，只能创建或撤销
|
||||
|
||||
如需新增表，必须先证明它服务于 MVP 主链路。
|
||||
如需新增表，必须先证明它服务于当前迭代版本的主链路。
|
||||
|
||||
## 6. Server 开发规范
|
||||
|
||||
@@ -181,12 +195,19 @@ Server 代码按以下职责拆分：
|
||||
|
||||
* 继续复用 gin-template 的登录、角色和 session 体系
|
||||
|
||||
Agent：
|
||||
Agent（第一版）：
|
||||
|
||||
* 第一版使用预共享 Token
|
||||
* 预共享单 Token，来自环境变量
|
||||
* 请求头统一使用 `X-Agent-Token`
|
||||
* Agent 与管理端认证逻辑必须分开
|
||||
|
||||
Agent（第二版）：
|
||||
|
||||
* Token 改为查 `agent_tokens` 表验证
|
||||
* 环境变量 Token 降级为 bootstrap 模式：数据库存在有效 Token 记录时，环境变量 Token 不再有效
|
||||
* Token 创建时生成随机值，不允许外部传入
|
||||
* Token 值不可更新，仅支持撤销（设 `is_active=false`）
|
||||
|
||||
注意：
|
||||
|
||||
* 不要让 Agent 接口走用户登录态
|
||||
@@ -339,7 +360,7 @@ MVP 前端只做最小管理界面，不重做整套后台。
|
||||
|
||||
## 10. 测试与验收规范
|
||||
|
||||
### 10.1 最低测试要求
|
||||
### 10.1 第一版最低测试要求（已完成）
|
||||
|
||||
Server 至少覆盖：
|
||||
|
||||
@@ -356,9 +377,21 @@ Agent 至少覆盖：
|
||||
* `nginx -t` 或 `nginx -s reload` 失败分支
|
||||
* 本地状态文件读写
|
||||
|
||||
### 10.2 联调验收标准
|
||||
### 10.2 第二版新增测试要求
|
||||
|
||||
MVP 完成至少要通过以下手工验证：
|
||||
Server 新增覆盖：
|
||||
|
||||
* HTTPS server 块渲染正确性（`enable_https=true` 时生成 443 块，`redirect_http=true` 时生成重定向块）
|
||||
* HTTP-only 路由渲染结果不受 HTTPS 字段影响
|
||||
* `custom_headers` 注入到渲染结果的正确性
|
||||
* `agent_tokens` 创建与查表验证逻辑
|
||||
* Token 撤销后验证失败
|
||||
* bootstrap Token 降级行为（数据库有 Token 时环境变量 Token 失效）
|
||||
* 分组发布逻辑（group_id 筛选激活版本）
|
||||
* 预览接口不写库
|
||||
* diff 接口变更摘要计算正确性
|
||||
|
||||
### 10.3 联调验收标准（第一版，已完成）
|
||||
|
||||
1. 管理端新增反代规则并成功发布版本
|
||||
2. Agent 能检测到新版本并拉取
|
||||
@@ -367,15 +400,26 @@ MVP 完成至少要通过以下手工验证：
|
||||
5. 节点页能看到当前版本和最后心跳
|
||||
6. 当 reload 失败时，Agent 能回滚到旧配置并上报失败
|
||||
|
||||
### 10.4 联调验收标准（第二版）
|
||||
|
||||
1. 创建含 HTTPS 字段的路由并发布，Nginx 能以 HTTPS 正确转发
|
||||
2. 通过管理界面创建 Token，Agent 使用新 Token 成功访问
|
||||
3. 撤销 Token 后 Agent 请求返回 401
|
||||
4. 创建分组并按分组发布，不同分组节点拉到不同版本
|
||||
5. 路由配置自定义头后，渲染结果包含对应指令
|
||||
6. 发布页预览展示正确渲染结果
|
||||
7. 变更摘要正确列出域名变化
|
||||
|
||||
## 11. 文档维护规范
|
||||
|
||||
出现以下情况时必须同步更新文档：
|
||||
|
||||
* MVP 范围变化
|
||||
* 产品版本范围变化（V1 → V2 → V3）
|
||||
* API 发生破坏性变更
|
||||
* 数据模型新增或删除
|
||||
* Agent 本地文件路径变更
|
||||
* 部署方式变化
|
||||
* 新增或撤销对中间件/基础设施的依赖
|
||||
|
||||
优先更新：
|
||||
|
||||
|
||||
+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