[文档] 设计文档V5

docs/deployment.md

@@ -1,6 +1,6 @@
 # ATSFlare 部署说明
 
-本文档仅保留当前可用基线的最小部署方式，用于第三版开发前后的本地部署、联调与回归验证。
+本文档仅保留当前可用基线的最小部署方式，并补充第五版（0.5.x）开发期间与 OpenResty 主配置接管相关的联调约束。
 
 ---
 
@@ -18,6 +18,7 @@
 * 对 Agent 数据目录有写权限
 * 若使用独立 OpenResty 模式：可执行 `openresty -t` 与 `openresty -s reload`
 * 若使用 Docker 模式：具备 Docker 执行权限
+* 第五版主配置接管模式下，Agent 对 OpenResty 主配置目标路径必须具备写权限
 
 ---
 
@@ -182,6 +183,15 @@ swag init -g main.go -o docs
 * `node_name` 与 `node_ip` 可省略，未填写时自动探测
 * 未配置 `openresty_path` 时，默认使用 Docker OpenResty 容器
 
+z### 3.3 第五版新增部署约束
+
+第五版开发完成后，OpenResty 主配置将进入 Agent 受管范围。部署与联调时应满足：
+
+* 本机 OpenResty 模式需要为 Agent 显式提供主配置文件写入路径
+* Docker OpenResty 模式需要保证主配置、路由配置和证书目录位于同一套受管挂载路径中
+* 节点现存手工维护的主配置如继续保留，必须先迁移为 Server 渲染模板的等价配置，再切换到受管模式
+* 主配置切换前必须预留回滚副本，并通过一次 `openresty -t` 失败演练验证回滚
+
 ---
 
 ## 4. Agent 启动
@@ -225,7 +235,7 @@ go build -o atsflare-agent ./cmd/agent
 1. Agent 完成心跳与同步
 2. 自动注册模式下完成 Token 置换
 3. 拉取激活版本
-4. 写入路由配置与必要证书文件
+4. 写入主配置、路由配置与必要证书文件
 5. 执行 `openresty -t`
 6. 执行 `openresty -s reload`
 7. 上报应用结果
@@ -244,6 +254,7 @@ go build -o atsflare-agent ./cmd/agent
 人为制造 `openresty -t` 失败后再次发布，预期：
 
 * Agent 回滚旧配置
+* 主配置与路由配置一起回滚
 * 节点 `last_error` 更新
 * 应用记录中出现失败记录
 
@@ -371,13 +382,25 @@ GitHub Release 中的 Agent 二进制命名格式：
 
 ---
 
-## 10. 当前已知限制
+## 10. 第五版性能优化联调重点
+
+第五版联调时，至少补以下验证：
+
+* 调整连接类参数后，能成功生成新版本并由 Agent 应用
+* 启用或关闭代理缓存后，主配置预览、diff 与实际落盘一致
+* 缓存目录、缓存大小、失效时间等参数非法时，Server 拒绝保存
+* 主配置渲染异常或 `openresty -t` 失败时，Agent 不应留下半更新状态
+* 本机模式与 Docker 模式都要验证一次主配置接管
+
+---
+
+## 11. 当前已知限制
 
 * Docker 模式仍是 MVP 级封装
 * 联调以手工步骤为主
 
 ---
 
-## 11. 文档维护要求
+## 12. 文档维护要求
 
 当部署方式、配置字段、节点接入方式或联调流程变化时，同步更新本文档。