[文档] 设计文档V5

docs/design.md

@@ -8,6 +8,7 @@
 
 * 第一版、第二版、第三版均已完成
 * 前端改造已完成，`atsf_server/web` 新版工程已成为正式基线
+* 第五版（0.5.x）已立项，目标聚焦 OpenResty 反代与缓存性能优化
 * 已完成阶段的实现细节以代码与 Git 历史为准，不再在本文档中维护过程性设计
 
 ---
@@ -24,6 +25,8 @@ ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部
 * Agent 上报 OpenResty 运行健康状态与错误摘要
 * OpenResty 配置写入、校验、reload 与失败回滚
 * Server 向 Agent 下发受限运行指令（当前仅支持 OpenResty 重启）
+* Server 统一管理 OpenResty 主配置模板与性能优化参数
+* 反向代理链路的连接、缓冲、超时、压缩与缓存性能优化
 * HTTPS/TLS 路由支持
 * 证书托管与域名管理
 * 节点管理、节点专属 `agent_token`、全局 `discovery_token`
@@ -49,11 +52,18 @@ ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部
 * WAF、限流防护平台化、Bot 管理
 * 节点分组、灰度百分比发布、按节点差异化下发
 * Redis、消息队列、对象存储、Prometheus 等新基础设施前置依赖
-* 复杂缓存策略、分层缓存、mid-tier
+* 平台化缓存产品能力、分层缓存、mid-tier
 * 证书自动签发与自动续期
 * 审批流、审计中台、Purge 平台化能力
 * 平台化抽象对象，如 `zone`、`origin_pool`、`policy`、`deployment`
 
+第五版边界补充：
+
+* 允许在 OpenResty 单节点层面引入受控的代理缓存能力，但只服务于当前反代链路优化，不扩展为独立缓存产品
+* 主配置文件由 Server 统一生成并由 Agent 受控落地，不开放节点侧手改后再回传合并
+* 性能优化参数统一在 Server 配置，不支持按节点分叉不同性能模板
+* 第五版不开放任意自定义 Nginx/OpenResty 片段上传，不提供任意指令执行入口, 但是需要保留拓展能力, 为后续开放准备
+
 新增能力超出上述边界时，必须先更新本文档，再进入实现。
 
 ---
@@ -69,6 +79,7 @@ ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部
 * SQLite
 * 现有 ATSFlare 登录体系
 * 托管 `atsf_server/web` 静态构建产物
+* 托管 OpenResty 主配置模板、性能参数与缓存参数
 
 ### 4.2 Agent
 
@@ -79,6 +90,7 @@ ATSFlare 当前定位为内部自用的反向代理控制面，不面向外部
 * `openresty_path` 优先
 * 未配置 `openresty_path` 时默认使用 Docker OpenResty
 * 生成资源默认落在 `./data`，可由 `data_dir` 覆盖
+* 负责接管 OpenResty 主配置文件与受管 include 文件
 
 ### 4.3 Frontend
 
@@ -110,8 +122,8 @@ ATSFlare Agent (register / heartbeat / sync / apply / update)
 
 职责分工：
 
-* Server 负责配置、版本、节点、设置与管理端 UI
-* Agent 负责本地落盘、校验、reload、回滚、自更新
+* Server 负责配置、版本、节点、设置、管理端 UI 以及 OpenResty 主配置渲染
+* Agent 负责本地落盘、校验、reload、回滚、自更新，不负责维护独立于 Server 的主配置真相
 * 发布通过“生成完整版本并激活”完成
 * 历史版本不可变
 
@@ -136,8 +148,11 @@ ATSFlare Agent (register / heartbeat / sync / apply / update)
 * `config_versions` 必须保存完整快照、渲染结果与 `checksum`
 * 全局同时只能有一个激活版本
 * 回滚通过重新激活旧版本实现
+* 激活版本中的 OpenResty 渲染结果必须包含主配置与路由配置的统一快照
 * 域名与证书匹配同时支持精确匹配与通配符匹配
 * 节点专属 `agent_token` 必须可立即失效
+* OpenResty 性能优化参数与缓存参数统一由 Server 设置管理，不允许节点侧形成额外配置源
+* Agent 只应用受控主配置文件，不提供任意配置片段拼接入口
 
 ---
 
@@ -152,11 +167,12 @@ ATSFlare Agent (register / heartbeat / sync / apply / update)
 发布规则：
 
 1. 读取全部启用的 `proxy_routes`
-2. 渲染完整 OpenResty 配置
-3. 计算 `checksum`
-4. 写入 `config_versions`
-5. 切换激活版本
-6. Agent 在后续同步中发现并应用
+2. 读取 Server 侧受管 OpenResty 性能参数与缓存参数
+3. 渲染完整 OpenResty 配置
+4. 计算 `checksum`
+5. 写入 `config_versions`
+6. 切换激活版本
+7. Agent 在后续同步中发现并应用
 
 版本规则：
 
@@ -176,6 +192,8 @@ ATSFlare Agent (register / heartbeat / sync / apply / update)
 * Agent API
 * 数据存储
 * 配置渲染
+* OpenResty 主配置模板管理
+* OpenResty 性能参数与缓存参数管理
 * 发布与激活
 * 节点状态与设置管理
 
@@ -186,7 +204,7 @@ ATSFlare Agent (register / heartbeat / sync / apply / update)
 * 首次注册与凭证置换
 * 周期性心跳与同步
 * 运行参数接收
-* 本地路由与证书文件写入
+* 主配置文件、路由配置与必要证书文件写入
 * 执行 `openresty -t` / `openresty -s reload`
 * 失败回滚
 * 自我更新
@@ -229,6 +247,7 @@ Agent 接口当前覆盖：
 * 管理端与 Agent API 均使用 JSON
 * Agent API 固定放在 `/api/agent/*`
 * Agent 鉴权统一使用 `X-Agent-Token`
+* OpenResty 性能优化相关配置通过现有设置域统一管理，不新增节点直连配置入口
 
 ---