OpenFlare/docs/design/release-model.md

发布模型

你会学到：OpenFlare 为什么以完整配置版本为发布单位，发布、激活、Agent 应用和回滚分别如何工作。

OpenFlare 的发布模型以完整配置版本为中心，而不是在线修改节点配置。

标准链路：

修改规则 -> 预览 / 查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果

发布规则

Server 发布时必须：

1. 读取全部启用的 proxy_routes。
2. 读取 Server 侧 OpenResty 主配置、性能参数、缓存参数和必要 Lua 资源。
3. 读取域名与证书绑定关系。
4. 读取 WAF 全局规则组、自定义规则组、IP 组引用与网站绑定关系。
5. 展开 WAF 规则组引用的启用 IP 组，渲染完整 OpenResty 配置与 WAF 运行时配置。
6. 计算 checksum。
7. 写入 config_versions。
8. 切换激活版本。
9. 让 Agent 在后续 heartbeat 中发现并应用。

版本号格式固定为 YYYYMMDD-NNN。

预览与发布

预览和 diff 是只读能力，不产生发布记录。

发布会生成新的完整配置版本。版本必须包含足够信息，让未来回滚时可以基于历史快照重新应用，而不依赖当前可变配置。

激活版本

全局同时只能有一个激活版本。当前不做按节点分组的差异化版本。

Agent 通过 heartbeat 获取激活版本摘要；当远端版本或 checksum 与本地状态不一致时，Agent 才进入同步流程。当 Agent WS 连接升级开启且连接可用时，Server 在发布或激活版本成功后会广播最新激活版本摘要，Agent 收到后复用普通同步流程立即拉取并应用配置。WS 不可用时仍按 HTTP heartbeat 间隔发现变更。

不可变历史

历史版本不可变。回滚不是修改旧版本，而是重新激活旧版本。

这样做的结果是：

• 每个版本都可以追溯。
• 回滚链路与普通发布应用链路一致。
• Agent 不需要理解“反向 patch”，只需要应用一个目标版本。

Agent 应用策略

Agent 发现新版本后会：

1. 拉取目标版本详情。
2. 备份旧文件。
3. 写入主配置、路由配置、证书、必要 Lua 资源与 WAF/PoW 运行时配置。
4. 执行 OpenResty 配置校验。
5. reload；如果运行时未启动，则尝试用当前配置启动 OpenResty。
6. 上报成功、警告或失败。

如果新配置激活失败，Agent 必须尝试恢复运行；回滚成功时上报警告。若本地没有历史主配置可回滚，Agent 会写入内置安全兜底配置并尝试拉起 OpenResty：该配置对外只监听 80 端口，不包含任何用户路由，统一返回 503 Service Unavailable 与 OpenFlare: No Valid Configuration，同时保留本地 stub_status 健康检查入口。兜底启动成功时仍阻断失败目标版本并上报警告；存在历史主配置但回滚后仍无法恢复运行时上报失败。

某个目标 version + checksum 一旦应用失败并回退，Agent 会在本地状态中阻断该目标重复应用。只有远端激活版本或 checksum 发生变化，才允许再次尝试。

设计约束

• 发布必须读取全部启用的网站配置，而不是只渲染本次修改对象。
• 回滚通过重新激活旧版本实现，不修改历史版本。
• Agent API 固定使用节点专属 agent_token，首次接入可使用 discovery_token。
• Server 不提供远程 shell 或任意命令执行入口。
• 配置版本必须保存完整快照、渲染结果和 checksum。
• WAF 规则组、IP 组快照和网站绑定关系必须随完整配置版本进入快照与 checksum，回滚时不得依赖当前可变 WAF 配置。