[文档] 设计文档V5

2026-09-29 05:56:38 +08:00 · 2026-03-12 15:22:13 +08:00
parent 42ca18681c
commit eb65c38c56
5 changed files with 197 additions and 52 deletions
@@ -11,7 +11,9 @@ Server 当前支持两类启动配置：
 1. 命令行参数
 2. 环境变量

-此外，部分运行时参数已迁入数据库 `Option` 表，可在管理端设置页中热更新，例如 Agent 运行参数与限流阈值。
+此外，部分运行时参数已迁入数据库 `Option` 表，可在管理端设置页中热更新，例如 Agent 运行参数与限流阈值。
+
+第五版（0.5.x）计划继续复用 `Option` 表承载 OpenResty 性能优化参数与缓存参数，不单独引入新的配置中心。

 ### 1.1 Server 命令行参数

@@ -114,8 +116,51 @@ volumes:

 说明：

-* 限流窗口上限不能超过 `RateLimitKeyExpirationDuration`，当前为 20 分钟
-* 限流按来源 IP 统计，若前置了 Nginx/CDN/LB，应正确透传真实客户端 IP
+* 限流窗口上限不能超过 `RateLimitKeyExpirationDuration`，当前为 20 分钟
+* 限流按来源 IP 统计，若前置了 Nginx/CDN/LB，应正确透传真实客户端 IP
+
+### 1.2.2 第五版规划中的 OpenResty 优化配置项
+
+以下配置项用于第五版开发文档定义，目标是在管理端「运维设置」中统一维护，并参与版本渲染。除特别说明外，均计划保存在 `Option` 表中。
+
+| 配置项 | 作用 | 计划默认值 |
+| --- | --- | --- |
+| `OpenRestyWorkerProcesses` | `worker_processes` 配置；支持 `auto` 或正整数 | `auto` |
+| `OpenRestyWorkerConnections` | `events { worker_connections }` 上限 | `4096` |
+| `OpenRestyWorkerRlimitNofile` | `worker_rlimit_nofile` 上限 | `65535` |
+| `OpenRestyEventsUse` | `events { use ... }` 指令；为空表示不显式渲染 | 空 |
+| `OpenRestyEventsMultiAcceptEnabled` | 是否启用 `multi_accept on` | `false` |
+| `OpenRestyKeepaliveTimeout` | `keepalive_timeout` 秒数 | `65` |
+| `OpenRestyKeepaliveRequests` | `keepalive_requests` 上限 | `1000` |
+| `OpenRestyClientHeaderTimeout` | `client_header_timeout` 秒数 | `15` |
+| `OpenRestyClientBodyTimeout` | `client_body_timeout` 秒数 | `15` |
+| `OpenRestySendTimeout` | `send_timeout` 秒数 | `30` |
+| `OpenRestyProxyConnectTimeout` | `proxy_connect_timeout` 秒数 | `5` |
+| `OpenRestyProxySendTimeout` | `proxy_send_timeout` 秒数 | `60` |
+| `OpenRestyProxyReadTimeout` | `proxy_read_timeout` 秒数 | `60` |
+| `OpenRestyProxyBufferingEnabled` | 是否启用 `proxy_buffering` | `true` |
+| `OpenRestyProxyBuffers` | `proxy_buffers` 组合值，例如 `16 16k` | `16 16k` |
+| `OpenRestyProxyBufferSize` | `proxy_buffer_size` | `8k` |
+| `OpenRestyProxyBusyBuffersSize` | `proxy_busy_buffers_size` | `64k` |
+| `OpenRestyGzipEnabled` | 是否启用 `gzip on` | `true` |
+| `OpenRestyGzipMinLength` | `gzip_min_length` 字节数 | `1024` |
+| `OpenRestyGzipCompLevel` | `gzip_comp_level` | `5` |
+| `OpenRestyCacheEnabled` | 是否启用代理缓存 | `false` |
+| `OpenRestyCachePath` | `proxy_cache_path` 目录 | 空 |
+| `OpenRestyCacheLevels` | `proxy_cache_path levels=` 值 | `1:2` |
+| `OpenRestyCacheInactive` | `proxy_cache_path inactive=` 时长 | `30m` |
+| `OpenRestyCacheMaxSize` | `proxy_cache_path max_size=` 大小 | `1g` |
+| `OpenRestyCacheKeyTemplate` | 缓存 Key 模板 | `$scheme$proxy_host$request_uri` |
+| `OpenRestyCacheLockEnabled` | 是否启用 `proxy_cache_lock` | `true` |
+| `OpenRestyCacheLockTimeout` | `proxy_cache_lock_timeout` 时长 | `5s` |
+| `OpenRestyCacheUseStale` | `proxy_cache_use_stale` 场景列表 | `error timeout updating http_500 http_502 http_503 http_504` |
+
+说明：
+
+* 第五版第一批仅开放稳定、可校验、可回滚的常用性能项；更多指令后续按相同模式扩展
+* 所有大小、时长、布尔和整数参数都应在 Server 保存前完成校验
+* `OpenRestyCacheEnabled=false` 时，缓存目录与缓存参数应允许留空或回退到默认值
+* 任何包含路径的配置项都必须在 Agent 落盘前再次校验可写性与安全边界

 ### 1.3 前端构建环境变量

@@ -183,16 +228,17 @@ go run ./cmd/agent -config ./agent.json
 使用节点专属 Token 的示例：

 ```json
-{
-	"server_url": "http://127.0.0.1:3000",
-	"agent_token": "replace-with-node-auth-token",
-	"node_name": "node-01",
-	"node_ip": "192.168.1.20",
-	"data_dir": "./data",
-	"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
-	"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/atsflare_routes.conf",
-	"cert_dir": "/usr/local/openresty/nginx/conf/certs",
-	"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs",
+{
+	"server_url": "http://127.0.0.1:3000",
+	"agent_token": "replace-with-node-auth-token",
+	"node_name": "node-01",
+	"node_ip": "192.168.1.20",
+	"data_dir": "./data",
+	"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
+	"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
+	"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/atsflare_routes.conf",
+	"cert_dir": "/usr/local/openresty/nginx/conf/certs",
+	"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs",
 	"state_path": "./data/agent-state.json",
 	"heartbeat_interval": 30000,
 	"sync_interval": 30000,
@@ -211,10 +257,11 @@ go run ./cmd/agent -config ./agent.json
 | `node_ip` | 节点 IP | 否 | 自动探测第一个可用 IPv4 | `192.168.1.20` |
 | `openresty_path` | 本机 OpenResty 可执行文件路径；设置后按本机 OpenResty 模式运行 | 否 | 空；未设置时按 Docker OpenResty 模式处理 | `/usr/local/openresty/nginx/sbin/openresty` |
 | `openresty_container_name` | Docker 模式下的 OpenResty 容器名 | 否 | `atsflare-openresty` | `atsflare-openresty` |
-| `openresty_docker_image` | Docker 模式下用于初始化/管理的 OpenResty 镜像 | 否 | `openresty/openresty:alpine` | `openresty/openresty:alpine` |
-| `docker_binary` | Docker 可执行文件名或路径 | 否 | `docker` | `/usr/bin/docker` |
-| `data_dir` | Agent 数据目录，用于存储托管配置、证书和状态文件 | 否 | 配置文件所在目录下的 `data` 子目录 | `./data` |
-| `route_config_path` | 路由配置文件写入路径 | 否 | 默认为 `data_dir` 下托管路径 | `/etc/nginx/conf.d/atsflare_routes.conf` |
+| `openresty_docker_image` | Docker 模式下用于初始化/管理的 OpenResty 镜像 | 否 | `openresty/openresty:alpine` | `openresty/openresty:alpine` |
+| `docker_binary` | Docker 可执行文件名或路径 | 否 | `docker` | `/usr/bin/docker` |
+| `data_dir` | Agent 数据目录，用于存储托管配置、证书和状态文件 | 否 | 配置文件所在目录下的 `data` 子目录 | `./data` |
+| `main_config_path` | 第五版主配置接管时 OpenResty 主配置文件写入路径 | 第五版本机模式建议必填 | Docker 模式可使用受管默认路径；本机模式建议显式设置 | `/usr/local/openresty/nginx/conf/nginx.conf` |
+| `route_config_path` | 路由配置文件写入路径 | 否 | 默认为 `data_dir` 下托管路径 | `/etc/nginx/conf.d/atsflare_routes.conf` |
 | `cert_dir` | Agent 在本机写入证书文件的目录 | 否 | 默认为 `data_dir` 下托管证书目录 | `./data/etc/nginx/certs` |
 | `openresty_cert_dir` | OpenResty 实际读取证书的目录 | 否 | 本机模式默认等于 `cert_dir`；Docker 模式默认 `/etc/nginx/atsflare-certs` | `/usr/local/openresty/nginx/conf/certs` |
 | `state_path` | Agent 本地状态文件路径 | 否 | 默认为 `data_dir` 下托管状态文件 | `./data/agent-state.json` |
@@ -228,18 +275,19 @@ go run ./cmd/agent -config ./agent.json
 * `heartbeat_interval`、`sync_interval`、`request_timeout` 支持两种写法：
 	* 毫秒整数，例如 `30000`
 	* Go duration 字符串，例如 `"30s"`
-* `node_name` 与 `node_ip` 未填写时会自动探测；若自动探测失败，配置校验会报错
-* 未配置 `openresty_path` 时，默认为 Docker OpenResty 模式
-* 配置保存时，`agent_version`、`nginx_version` 由程序运行时维护，不需要写入 JSON
-* 本机模式下的 `route_config_path` 需与节点主配置文件的 include 规则保持一致
+* `node_name` 与 `node_ip` 未填写时会自动探测；若自动探测失败，配置校验会报错
+* 未配置 `openresty_path` 时，默认为 Docker OpenResty 模式
+* 配置保存时，`agent_version`、`nginx_version` 由程序运行时维护，不需要写入 JSON
+* 第五版主配置接管完成后，本机模式下应优先通过 `main_config_path` 由 Agent 写入受管主配置，而不是依赖节点手工维护 include 规则

 ### 2.4 Agent 托管路径默认值

 当未显式设置以下字段时，Agent 会根据 `data_dir` 自动生成托管路径：

-| 字段 | 默认值 |
-| --- | --- |
-| `route_config_path` | `data_dir/etc/nginx/conf.d/atsflare_routes.conf` |
+| 字段 | 默认值 |
+| --- | --- |
+| `main_config_path` | 第五版 Docker 模式默认可落在 `data_dir/etc/nginx/nginx.conf`；本机模式建议显式配置 |
+| `route_config_path` | `data_dir/etc/nginx/conf.d/atsflare_routes.conf` |
 | `cert_dir` | `data_dir/etc/nginx/certs` |
 | `state_path` | `data_dir/var/lib/atsflare/agent-state.json` |

@@ -268,14 +316,15 @@ Docker OpenResty 模式下：
 适用于节点已经安装了宿主机 OpenResty，且 Agent 直接执行 `openresty -t` 与 `openresty -s reload`。

 ```json
-{
-	"server_url": "http://127.0.0.1:3000",
-	"agent_token": "replace-with-node-auth-token",
-	"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
-	"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/atsflare_routes.conf",
-	"cert_dir": "/usr/local/openresty/nginx/conf/certs",
-	"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs"
-}
+{
+	"server_url": "http://127.0.0.1:3000",
+	"agent_token": "replace-with-node-auth-token",
+	"openresty_path": "/usr/local/openresty/nginx/sbin/openresty",
+	"main_config_path": "/usr/local/openresty/nginx/conf/nginx.conf",
+	"route_config_path": "/usr/local/openresty/nginx/conf/conf.d/atsflare_routes.conf",
+	"cert_dir": "/usr/local/openresty/nginx/conf/certs",
+	"openresty_cert_dir": "/usr/local/openresty/nginx/conf/certs"
+}
 ```

 ---
@@ -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. 文档维护要求

 当部署方式、配置字段、节点接入方式或联调流程变化时，同步更新本文档。
@@ -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 性能优化相关配置通过现有设置域统一管理，不新增节点直连配置入口

 ---

@@ -9,6 +9,7 @@
 * 第一版、第二版、第三版已完成
 * `docs/design.md` 是当前系统边界的唯一设计基线
 * `atsf_server/web` 新版前端已完成迁移并成为正式基线
+* 第五版（0.5.x）将以 OpenResty 性能优化与主配置接管为主线

 超出设计边界的需求，必须先更新 [docs/design.md](./design.md)。

@@ -29,6 +30,7 @@

 * 默认不引入 Redis、MQ、对象存储等新基础设施
 * 不为未确认的平台化能力预埋复杂抽象
+* OpenResty 性能参数与缓存参数优先复用现有 `Option` 体系管理，不为单一版本额外引入配置中心

 ### 2.2 Agent

@@ -92,6 +94,7 @@
 * 每个模块职责单一
 * 外部命令调用集中封装
 * 状态落盘与配置落盘分离
+* 主配置文件写入、备份、校验、回滚与受管 include 写入应归并到 OpenResty 运行时管理模块

 ### 3.3 Frontend

@@ -123,6 +126,7 @@
 * `apply_logs`
 * `tls_certificates`
 * `managed_domains`
+* `options`（运行时参数与 OpenResty 调优参数继续复用现有配置表，不扩展为独立新实体）

 通用约束：

@@ -131,6 +135,7 @@
 * `config_versions` 必须保存完整快照与渲染结果
 * 全局同时只能有一个激活版本
 * 回滚通过重新激活旧版本实现
+* 第五版新增的 OpenResty 性能参数必须由 Server 统一保存与校验，并参与版本渲染
 * 域名证书匹配必须同时支持精确匹配与通配符匹配
 * 节点专属 `agent_token` 必须可立即失效

@@ -173,6 +178,7 @@ Agent：
 * 将本地 OpenResty 操作暴露为远程执行接口
 * 用通用 shell/命令执行方式替代受限节点操作接口
 * 在日志中打印完整 Token
+* 为性能优化需求开放任意 OpenResty 文本片段上传或任意指令下发

 ---

@@ -181,11 +187,19 @@ Agent：
 发布逻辑必须保持以下事实：

 * 发布时读取全部启用的 `proxy_routes`
+* 发布时同时读取 Server 侧 OpenResty 主配置参数、反代性能参数与缓存参数
 * 生成完整 OpenResty 配置
 * 计算 `checksum`
 * 写入 `config_versions`
 * 通过切换 `is_active` 激活版本

+第五版新增要求：
+
+* “完整 OpenResty 配置”至少包括主配置文件与路由配置文件
+* 主配置文件的真相源在 Server，Agent 只负责受控写入、校验与回滚
+* 性能优化参数必须通过结构化字段渲染，禁止直接拼接未经校验的自由文本
+* 新增参数命名统一采用 `OpenResty...` 前缀，布尔值、整数、大小单位和时间单位必须在更新入口做校验
+
 版本号格式保持：

 ```text
@@ -205,7 +219,7 @@ Agent 必须满足：
 * 未显式配置 `node_ip` 时自动探测本机 IP
 * 周期性心跳与同步
 * 发现新版本时先备份旧文件
-* 写入新路由与必要证书文件
+* 写入新的主配置、路由配置与必要证书文件
 * 先执行 `openresty -t`
 * 成功后执行 `openresty -s reload`
 * 失败时自动回滚并上报最终结果
@@ -214,6 +228,7 @@ Agent 必须满足：
 * 支持接收 Server 下发运行参数
 * 支持接收 Server 下发的受限运行指令，当前仅允许 OpenResty 重启
 * 支持自我更新，但失败不影响心跳与同步
+* 主配置接管模式下，必须保证主配置与受管 include 一起回滚，不能只回滚其中一部分

 ---

@@ -271,6 +286,8 @@ Agent 必须满足：
 * 节点在线状态判定
 * 证书导入与匹配
 * 自定义请求头渲染
+* OpenResty 主配置渲染
+* OpenResty 性能参数与缓存参数校验
 * Agent 同步、回滚、本地状态读写
 * 自动注册与 Token 置换
 * Agent 设置下发与更新链路
@@ -281,6 +298,7 @@ Agent 必须满足：
 * 先补单元测试或服务层测试
 * 再补联调验证步骤
 * 涉及发布链路、Agent 链路、鉴权链路的改动，必须补回归测试
+* 涉及 OpenResty 主配置或缓存行为的改动，必须补 `openresty -t` 校验场景与失败回滚场景

 ---

@@ -7,9 +7,8 @@
 * 第一版已完成并稳定运行
 * 第二版已完成并补齐 HTTPS、证书、域名、节点与预览能力
 * 第三版已完成，运维体验优化相关能力已经落地
-* 前端改造已完成，新版管理端已经切换为正式基线
-
-本文件不再维护已完成版本的阶段拆解，只保留当前状态与后续执行原则。
+* 第四版已完成前端细节打磨与 UI 优化，但未单独维护专项计划文档
+* 当前正式进入第五版（0.5.x）开发，目标聚焦 OpenResty 反代与缓存性能优化，以及主配置文件接管

 ---

@@ -36,18 +35,55 @@

 ---

-## 3. 当前执行原则
+## 3. 第五版目标

-后续开发以维护和增量优化为主，执行时遵循：
+第五版主目标：
+
+* 提升 OpenResty 在当前反代链路下的连接、缓冲、超时、压缩与缓存性能
+* 由 Server 统一托管 OpenResty 主配置文件，Agent 不再依赖节点手工维护主配置
+* 所有新增优化项都进入 Server 统一配置面，由管理端维护、版本发布、Agent 拉取与应用
+
+第五版不做：
+
+* 平台化缓存产品、Purge 系统、分层缓存、节点差异化缓存策略
+* 任意文本片段注入、任意 OpenResty 指令执行、节点侧自定义模板合并
+* 引入 Redis、Prometheus、消息队列等新基础设施作为第五版前置条件
+
+## 4. 第五版实施顺序
+
+建议按以下顺序推进：
+
+1. 补齐 Server 侧 OpenResty 性能参数模型、默认值、校验规则与设置页入口
+2. 扩展配置渲染结果，使版本快照覆盖主配置文件与路由配置文件
+3. 调整 Agent 本地应用链路，支持主配置写入、校验、reload、失败回滚
+4. 补齐预览、diff、应用结果与日志，确保第五版能力可观测
+5. 以本机 OpenResty 与 Docker OpenResty 两种模式完成联调和回归
+
+## 5. 第五版验收标准
+
+完成第五版时至少满足：
+
+* 管理端可以查看并修改第一批 OpenResty 性能优化项
+* 性能优化项保存后进入统一发布链路，而不是节点即时生效
+* Agent 可以接管主配置文件，并在 `openresty -t` 失败时完整回滚
+* 配置预览或 diff 能体现主配置与关键性能参数变化
+* 本机模式与 Docker 模式都能完成一次成功发布和一次失败回滚验证
+* 所有优化选项都由 Server 统一管理，不存在节点侧独立真相源
+
+## 6. 当前执行原则
+
+第五版执行时遵循：

 * 先遵守 `docs/design.md` 的系统边界
 * 再遵守 `docs/development-guidelines.md` 与 `docs/frontend-development-guidelines.md`
+* OpenResty 优化参数优先复用现有 `Option` 与设置页结构，避免引入新配置中心
+* 主配置文件接管必须和发布链路、回滚链路一起设计，不能只补局部写文件能力
 * 需求不改变边界时，直接按现有模型与结构增量实现
 * 需求改变边界时，先补设计，再补计划，再编码

 ---

-## 4. 新需求进入条件
+## 7. 新需求进入条件

 满足以下任一情况时，才需要新增计划项：