From eb65c38c563a18a932e6fcfcc317ddd66df610fe Mon Sep 17 00:00:00 2001 From: ryan Date: Thu, 12 Mar 2026 15:22:13 +0800 Subject: [PATCH] =?UTF-8?q?[=E6=96=87=E6=A1=A3]=20=E8=AE=BE=E8=AE=A1?= =?UTF-8?q?=E6=96=87=E6=A1=A3V5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/app-config.md | 113 +++++++++++++++++++++++---------- docs/deployment.md | 31 +++++++-- docs/design.md | 37 ++++++++--- docs/development-guidelines.md | 20 +++++- docs/development-plan.md | 48 ++++++++++++-- 5 files changed, 197 insertions(+), 52 deletions(-) diff --git a/docs/app-config.md b/docs/app-config.md index bd779161..76cf7058 100644 --- a/docs/app-config.md +++ b/docs/app-config.md @@ -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" +} ``` --- diff --git a/docs/deployment.md b/docs/deployment.md index 5b92b278..2f47d3fe 100644 --- a/docs/deployment.md +++ b/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. 文档维护要求 当部署方式、配置字段、节点接入方式或联调流程变化时，同步更新本文档。 diff --git a/docs/design.md b/docs/design.md index 70ded5e0..074b44f8 100644 --- a/docs/design.md +++ b/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 性能优化相关配置通过现有设置域统一管理，不新增节点直连配置入口 --- diff --git a/docs/development-guidelines.md b/docs/development-guidelines.md index 353243c9..7bb48d3b 100644 --- a/docs/development-guidelines.md +++ b/docs/development-guidelines.md @@ -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` 校验场景与失败回滚场景 --- diff --git a/docs/development-plan.md b/docs/development-plan.md index 7e3da8d3..7c6d1556 100644 --- a/docs/development-plan.md +++ b/docs/development-plan.md @@ -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. 新需求进入条件 满足以下任一情况时，才需要新增计划项：