[文档] 设计文档V5

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` 校验场景与失败回滚场景
 
 ---