code-to10 v6 A10: release gate single evaluator via wiring adapter
(cherry picked from commit 77ed1c3094798f75bc41323f9aa60f744f5ba507)
This commit is contained in:
host committed
1 parent
31edc5cda9
commit
e7acc143db
3 files changed
+126
-117
No files matched your search
@@ -1,13 +1,14 @@
|
||||
# 发布端点接线准备 + 账本锚点运维流程
|
||||
|
||||
> 本轨性质：**接线准备，不是发布端点本身**。本轨不新建 live
|
||||
> 发布端点、不碰生产、不跑 `deploy.py`、不合并、不部署。
|
||||
> 发布端点是否立项、锚点存哪里、校验周期多长，均属用户侧
|
||||
> 本轨性质：**接线准备 + 归一说明**。发布端点现已实现，见 §2；本轨不新建其它 live
|
||||
> 发布端点；本轨不碰生产、不跑 `deploy.py`、不合并、不部署。
|
||||
> 锚点存哪里、校验周期多长，均属用户侧
|
||||
> 拍板项（见 §6），本文只给推荐值与判断依据，不替用户定。
|
||||
>
|
||||
> 基底：堆叠于 PR #247（`feat-audit-wiring`，`217a27f`），
|
||||
> 合并顺序：#209 → #240 → #244 → #241 → #247 → 本轨。
|
||||
> 本轨代码：`cloud/release_gate.py`（纯只读 evaluator）、
|
||||
> 本轨代码：`cloud/audit_loop_wiring.py` 的 `evaluate_release_gate`（纯只读唯一实现）、
|
||||
> `cloud/release_gate.py`（其薄转发适配器，保留旧契约形状）、
|
||||
> `cloud/tests/test_release_gate.py`（11 项契约测试）、
|
||||
> `tools/ledger_anchor_check.py`（只读校验脚本）、
|
||||
> `cloud/tests/test_ledger_anchor_check.py`（脚本退出码测试）。
|
||||
@@ -22,16 +23,16 @@
|
||||
五项之间做 AND：任一阻塞即 409、状态不变，并在响应里附
|
||||
`audit_pushback` 对象（`merge_blocked` / `release_blocked` /
|
||||
`blocked_by="audit_pushback"` / `round` / `failed_checks`）。
|
||||
- 但本仓库**没有独立的发布端点**：`release_blocked` 今天只是
|
||||
随合并响应返回的一个字段，由“未来的发布端点用同一 reader
|
||||
强制”。在那之前，合并放行后、发布前没有任何服务端检查
|
||||
会再读一次链。
|
||||
- 发布端点现已实现（`POST /tasks/{id}/release`，见 §2）：
|
||||
合并放行后、发布前，服务端按 §3 顺序重读一次链、重算
|
||||
硬门禁、核任务状态；`release_blocked` 不再只是随合并响应
|
||||
返回的字段。
|
||||
- 账本（#241）已有导出头哈希，但**没有库外锚点存放与定期
|
||||
校验的运维流程**：头哈希只在导出响应里出现一次，不存下来
|
||||
就等于没有锚点；尾巴删除单靠库内校验发现不了（#241 已明
|
||||
说），必须靠“旧锚点 vs 当前链”的比对。
|
||||
|
||||
## 2. 未来发布端点接口契约（建议，待立项后实现）
|
||||
## 2. 发布端点接口契约（已实现，唯一实现为 wiring 版）
|
||||
|
||||
### 2.1 端点
|
||||
|
||||
@@ -39,14 +40,17 @@
|
||||
|---|---|---|
|
||||
| 方法 + 路径 | `POST /tasks/{id}/release` | 与 `POST /tasks/{id}/merge` 对仗；`{id}` 为任务 id，路径风格与现有任务端点一致 |
|
||||
| 请求体 | `{}` 或 `{"confirm": true}`（二选一，立项时定） | 本轨不规定体字段；关键在服务端**不信任**体里的任何门禁结论，只信任自己重算的结果 |
|
||||
| 成功 | `200` + 任务对象 + `release_gate` 决策对象 | 决策对象即 `evaluate_release` 的返回值原样返回，不另起一套字段 |
|
||||
| 成功 | `200` + 任务对象 + `release_gate` 决策对象 | 决策对象即 wiring `evaluate_release_gate` 的返回值原样返回，不另起一套字段（`blocked_sources` 为源名，如 `task_status` / `hard_gate` / `audit_pushback`；`release_gate` 适配器的旧形状——`blocked_sources` 为码 + 顶层 `blocks` / `failed_checks` / `round` / `modules`——仅用于 `test_release_gate.py` 的契约测试，不经过端点） |
|
||||
| 阻塞 | `409` + `{"error": "release blocked", "release_gate": {...}}` | 见 §2.4 的阻塞码；阻塞时**不改任务状态、不发布、不写链** |
|
||||
| 任务不存在 | `404` | 与 merge 端点一致 |
|
||||
| 无权 | `403` | 见 §2.2 |
|
||||
|
||||
本轨**没有实现这个端点**：`cloud/release_gate.py` 只有 evaluator，
|
||||
没有路由、没有 HTTP plumbing、没有任务状态变更、没有发布动作。
|
||||
契约测试直接测 evaluator（见 §4），不测一个不存在的端点。
|
||||
发布端点**已经实现**：路由见 `handler_lifecycle._release_task`
|
||||
（`POST /tasks/{id}/release`），唯一实现是
|
||||
`audit_loop_wiring.evaluate_release_gate`；`cloud/release_gate.py`
|
||||
只是把 wiring 决策译回旧契约形状的薄转发适配器，不再是
|
||||
第二个 evaluator。契约测试直接测该适配器（见 §4），端点
|
||||
行为另由 `test_server_audit_loop` 等端点测试覆盖。
|
||||
|
||||
### 2.2 鉴权：与 verify/export 同源、但为写动作
|
||||
|
||||
@@ -66,9 +70,9 @@
|
||||
|
||||
### 2.3 接线点：发布前必做的三件事（顺序即 §3 的求值顺序）
|
||||
|
||||
未来端点在执行任何发布动作之前，必须按顺序做：
|
||||
发布端点在执行任何发布动作之前，必须按顺序做：
|
||||
|
||||
1. **重读链**：调 `evaluate_release`，它内部调
|
||||
1. **重读链**：调 wiring 的 `evaluate_release_gate`（经由 `release_gate.evaluate_release` 适配器亦同），它内部调
|
||||
`cloud/audit_wiring.pushback_block_for_task`（与 merge 端点
|
||||
同一个 reader）。读到的必须是**发布时刻**的链状态。
|
||||
2. **重算硬门禁**：用**发布时刻的新证据**重新跑
|
||||
@@ -89,6 +93,12 @@
|
||||
`blocked_by`（首要阻塞源）、`blocked_sources`（全部阻塞源），
|
||||
端点必须原样返回整个对象，不能只返回首要码——否则修好
|
||||
一个源后才发现另一个源仍阻塞，运维会被误导。
|
||||
注意：端点返回的是 wiring 决策（`blocked_sources` 为源名，
|
||||
硬门禁细节在 `hard_gate` 子对象里、审计细节在
|
||||
`audit_pushback` 子对象里）；下表“附加字段”列的顶层
|
||||
`blocks` / `failed_checks` / `round` / `modules` 是
|
||||
`release_gate` 适配器的旧契约形状，仅见于契约测试，不见
|
||||
于端点响应。
|
||||
|
||||
| 阻塞源 | `code` | `blocked_by` | HTTP | 附加字段 | 修复路径 |
|
||||
|---|---|---|---|---|---|
|
||||
@@ -149,7 +159,7 @@ reader 返回“无推回状态”（链从未写过），不算读链失败。
|
||||
用**唯一阻塞**构造钉住这一点：若纠正本身能解封，该测试
|
||||
必失败（测试注释说明了为何不用“纠正 + 另一失败”的掩盖构造）。
|
||||
|
||||
## 3. evaluator 求值顺序（`cloud/release_gate.py`）
|
||||
## 3. evaluator 求值顺序（唯一实现：`cloud/audit_loop_wiring.py`；`cloud/release_gate.py` 为薄转发适配器）
|
||||
|
||||
1. 读链。异常 → `release_blocked_state_unavailable`，短路
|
||||
（没有可信链读数时，其它结论都不可信）。
|
||||
@@ -168,9 +178,8 @@ reader 返回“无推回状态”（链从未写过），不算读链失败。
|
||||
|
||||
## 4. 契约测试（`cloud/tests/test_release_gate.py`，11 项）
|
||||
|
||||
测试只测 evaluator + 本地 SQLite 链（`TemporaryDirectory`，
|
||||
跑完删除），**不部署、不调用生产发布流程**（生产本就没有
|
||||
发布端点可调）。覆盖：
|
||||
测试只测适配器 + 本地 SQLite 链（`TemporaryDirectory`，
|
||||
跑完删除），**不部署、不调用生产发布流程**。覆盖：
|
||||
|
||||
| 测试 | 断言 |
|
||||
|---|---|
|
||||
@@ -238,7 +247,7 @@ reader 返回“无推回状态”（链从未写过），不算读链失败。
|
||||
| 触发 | 动作 |
|
||||
|---|---|
|
||||
| 每日定时（cron/定时任务，运维账号） | 取最新锚点 → 全链校验 + 前缀比对；通过则取新锚点（轮换见 §5.4） |
|
||||
| 每次发布前（未来发布端点立项后） | 发布流程先跑一次锚点校验；校验失败即发布 409（与 §2.4 的链读失败同级处理，属未来端点行为，本轨不实现） |
|
||||
| 每次发布前 | 发布流程先跑一次锚点校验；校验失败即发布 409（与 §2.4 的链读失败同级处理，属运维流程接线，不在本轨代码内自动执行） |
|
||||
| 每次合并门禁异常/人工介入后 | 运维手动跑一次，确认链未被介入改动 |
|
||||
| 锚点轮换时 | 新锚点必须先通过旧锚点的前缀校验，才能成为“当前锚点”（见 §5.4） |
|
||||
|
||||
@@ -259,8 +268,8 @@ reader 返回“无推回状态”（链从未写过），不算读链失败。
|
||||
任务日志与运维值班渠道留一条可查记录，不能只打印到
|
||||
没人看的日志文件里）。
|
||||
- **是否冻结**：校验失败期间，**发布立即冻结**（不发布；
|
||||
未来发布端点立项后以校验失败作 409 条件之一；立项前由
|
||||
运维人工冻结发布操作）。合并是否冻结由当值全局管理员
|
||||
发布端点以校验失败作 409 条件之一（接线见上）；校验流程
|
||||
未跑时由运维人工冻结发布操作）。合并是否冻结由当值全局管理员
|
||||
当场决定并记录——本轨不以代码自动冻结合并（那会是
|
||||
新的门禁语义，须另行立项），但 runbook 要求管理员在
|
||||
收到告警后 1 个工作日内给出“冻结合并与否”的书面决定，
|
||||
@@ -357,7 +366,7 @@ Postgres URL）。输出为单 JSON 对象，便于定时任务解析。
|
||||
它部署的是**平台本身**（服务端代码），不是某个任务的
|
||||
合并产物；它没有任务 id、没有调用方提交的门禁证据、
|
||||
不走服务端 HTTP 鉴权（走 SSH deploy key），与
|
||||
`POST /tasks/{id}/merge` / 未来 `POST /tasks/{id}/release`
|
||||
`POST /tasks/{id}/merge` / `POST /tasks/{id}/release`
|
||||
根本不在同一层。
|
||||
- **为什么不在门禁内**：门禁的客体是“任务能否合并/发布”，
|
||||
deploy.py 的客体是“平台代码能否上线”。把 deploy.py 绑到
|
||||
@@ -369,29 +378,30 @@ Postgres URL）。输出为单 JSON 对象，便于定时任务解析。
|
||||
1. 部署完成后，运维手动跑一次 §5.2 的锚点校验（部署不
|
||||
应改链；若校验失败，按 §5.3 处理，与部署成功与否分开判）；
|
||||
2. 部署说明里写明“部署 ≠ 任务发布”：推新平台版本不等于
|
||||
发布任何任务，任务发布仍走未来发布端点。
|
||||
发布任何任务，任务发布仍走 `POST /tasks/{id}/release`。
|
||||
- 若未来有人提议“deploy.py 发布前查链”，须先回答：查哪
|
||||
个任务的链？以谁的身份？回滚时查不查？答不上来就不纳入
|
||||
——本轨已把这三个问题写进 PR 正文，供立项时复核。
|
||||
|
||||
## 7. 未做项与诚实边界（本轨明确不声称的）
|
||||
|
||||
- 未建发布端点：无路由、无 HTTP 测试、无任务状态变更、
|
||||
无真实发布动作；`release_gate.py` 只是 evaluator + 契约。
|
||||
- 发布端点已建（路由 + 端点测试在位），但无真实发布动作
|
||||
之外的部署行为；`release_gate.py` 只是 wiring 的薄转发
|
||||
适配器 + 契约，不再是独立 evaluator。
|
||||
- 未部署、未跑 `deploy.py`、未动生产、主机 env、系统 key、
|
||||
sub2api、生产网关、仓库可见性、GitHub App 权限、生产容器。
|
||||
- 未在真实 PG 上验证：PG 触发器语法、PG 上的链校验与锚点
|
||||
流程，均只以常量/导出模式写清，须生产 PG 手动执行并验证。
|
||||
- 未替用户拍板：发布端点是否立项、锚点对象存储选型与
|
||||
- 未替用户拍板：锚点对象存储选型与
|
||||
账号、校验周期（推荐每日 + 每次发布前）、告警渠道、
|
||||
锚点保留期下限、合并冻结与否的默认策略——见 §8。
|
||||
- 未改 v1.1 契约、分支保护决策、已有 PR 分支与主 checkout。
|
||||
|
||||
## 8. 用户侧仍需拍板的点（本轨不擅自决定）
|
||||
|
||||
1. 发布端点是否立项：立项则按 §2 实现 `POST /tasks/{id}/release`；
|
||||
不立项则 `release_blocked` 继续只随合并响应返回，发布仍无
|
||||
服务端强制——该风险须用户知晓。
|
||||
1. 发布端点已实现（`POST /tasks/{id}/release`，见 §2）；
|
||||
剩余待拍板的是锚点校验是否自动接进发布流程（见 §5.2），
|
||||
而非端点本身是否立项。
|
||||
2. 锚点存放：对象存储选型（厂商/桶/账号）与过渡方案是否启用。
|
||||
3. 校验周期：推荐每日定时 + 每次发布前；是否接受该周期。
|
||||
4. 告警渠道：校验失败通知全局管理员与当值运维的具体渠道。
|
||||
|
||||
Reference in new issue
Block a user