[新增] 更新文档

docs/design/release-model.md

@@ -1,11 +1,13 @@
 # 发布模型
 
+你会学到：OpenFlare 为什么以完整配置版本为发布单位，发布、激活、Agent 应用和回滚分别如何工作。
+
 OpenFlare 的发布模型以完整配置版本为中心，而不是在线修改节点配置。
 
 标准链路：
 
 ```text
-修改规则 -> 预览/查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
+修改规则 -> 预览 / 查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果
 ```
 
 ## 发布规则
@@ -13,25 +15,57 @@ OpenFlare 的发布模型以完整配置版本为中心，而不是在线修改
 Server 发布时必须：
 
 1. 读取全部启用的 `proxy_routes`。
-2. 读取 Server 侧 OpenResty 主配置与结构化参数。
-3. 渲染完整 OpenResty 配置。
-4. 计算 `checksum`。
-5. 写入 `config_versions`。
-6. 切换激活版本。
-7. 让 Agent 在后续 heartbeat 中发现并应用。
+2. 读取 Server 侧 OpenResty 主配置、性能参数、缓存参数和必要 Lua 资源。
+3. 读取域名与证书绑定关系。
+4. 渲染完整 OpenResty 配置。
+5. 计算 `checksum`。
+6. 写入 `config_versions`。
+7. 切换激活版本。
+8. 让 Agent 在后续 heartbeat 中发现并应用。
 
 版本号格式固定为 `YYYYMMDD-NNN`。
 
+## 预览与发布
+
+预览和 diff 是只读能力，不产生发布记录。
+
+发布会生成新的完整配置版本。版本必须包含足够信息，让未来回滚时可以基于历史快照重新应用，而不依赖当前可变配置。
+
+## 激活版本
+
+全局同时只能有一个激活版本。当前不做按节点分组的差异化版本。
+
+Agent 通过 heartbeat 获取激活版本摘要；当远端版本或 checksum 与本地状态不一致时，Agent 才进入同步流程。
+
 ## 不可变历史
 
 历史版本不可变。回滚不是修改旧版本，而是重新激活旧版本。
 
-全局同时只能有一个激活版本，当前不做按节点分组的差异化版本。
+这样做的结果是：
+
+* 每个版本都可以追溯。
+* 回滚链路与普通发布应用链路一致。
+* Agent 不需要理解“反向 patch”，只需要应用一个目标版本。
 
 ## Agent 应用策略
 
-Agent 发现新版本后会备份旧文件，写入主配置、路由配置、证书与必要 Lua 资源，再执行配置校验和 reload。
+Agent 发现新版本后会：
+
+1. 拉取目标版本详情。
+2. 备份旧文件。
+3. 写入主配置、路由配置、证书与必要 Lua 资源。
+4. 执行 OpenResty 配置校验。
+5. reload 或重建 Docker OpenResty。
+6. 上报成功、警告或失败。
 
 如果新配置激活失败，Agent 必须尝试恢复运行；回滚成功时上报警告，回滚后仍无法恢复运行时上报失败。
 
 某个目标 `version + checksum` 一旦应用失败并回退，Agent 会在本地状态中阻断该目标重复应用。只有远端激活版本或 checksum 发生变化，才允许再次尝试。
+
+## 设计约束
+
+* 发布必须读取全部启用的网站配置，而不是只渲染本次修改对象。
+* 回滚通过重新激活旧版本实现，不修改历史版本。
+* Agent API 固定使用节点专属 `agent_token`，首次接入可使用 `discovery_token`。
+* Server 不提供远程 shell 或任意命令执行入口。
+* 配置版本必须保存完整快照、渲染结果和 `checksum`。