135 lines
7.2 KiB
Markdown
135 lines
7.2 KiB
Markdown
# 状态机、恢复阶梯与检查点语义
|
||
|
||
这是整个产品的核心。差异化不在"能跑命令"，在**跑挂了之后会发生什么**。
|
||
|
||
当前实现：`engine/states.py`（Run 转移表）、`engine/recovery.py`（恢复纯函数）、
|
||
`events/recorder.py`（事件与投影写入口）以及 `services/runs.py`（内置模拟编排）。
|
||
Step 租约状态机与独立 runtime 属于下一阶段。
|
||
|
||
---
|
||
|
||
## 1. Run 状态机
|
||
|
||
```
|
||
┌──────────┐
|
||
│ QUEUED │ 等资源（DUT/主机独占锁）
|
||
└────┬─────┘
|
||
│ 锁到手
|
||
┌────▼─────┐
|
||
│ PREFLIGHT│ 安全门禁：序列号绑定、系统盘保护、
|
||
└──┬────┬──┘ 破坏性白名单、环境指纹冻结
|
||
门禁拒绝 │ │ 全过
|
||
┌────▼┐ │
|
||
│REJEC│ │
|
||
│ TED │ │
|
||
└─────┘ │
|
||
┌───────▼──────┐
|
||
┌─────────▶│ RUNNING │◀────────┐
|
||
│ └──┬───┬───┬───┘ │ 恢复成功，
|
||
│ 人工继续 │ │ │ │ 从检查点续跑
|
||
┌────┴───┐ │ │ │ ┌────┴──────┐
|
||
│ PAUSED │◀───────┘ │ └───────▶│ RECOVERING│
|
||
└────────┘ 人工暂停 │ 心跳超时/ └────┬──────┘
|
||
│ 蓝屏/掉盘 │ 阶梯耗尽
|
||
全部循环完成 │ 或数据完整性失败
|
||
┌─────▼─────┐ ┌────▼────┐
|
||
│ COMPLETED │ │ FROZEN │ 冻结现场，
|
||
│ PASS/FAIL │ └─────────┘ 停止一切覆盖性动作
|
||
└───────────┘
|
||
```
|
||
|
||
任何非终态 → `ABORTED`（紧急停止：Web / 物理按钮 / 带外均可触发）。
|
||
|
||
**终态**：`COMPLETED` / `ABORTED` / `FROZEN` / `REJECTED`。终态不可再转移，
|
||
`assert_transition()` 会抛 `IllegalTransition`——这个异常在生产里意味着有代码
|
||
绕过了事件溯源，属于必须修的 bug，不是可以吞掉的告警。
|
||
|
||
转移表是 `states.py` 里的一份纯数据 `RUN_TRANSITIONS: Dict[RunState, FrozenSet[RunState]]`。
|
||
加新状态时只改这张表 + 补一条单测，不改 `runtime.py`。
|
||
|
||
## 2. Step 状态机
|
||
|
||
```
|
||
PENDING ──▶ DISPATCHED ──▶ RUNNING ──┬──▶ SUCCEEDED
|
||
▲ ├──▶ FAILED ──┐
|
||
│ ├──▶ TIMED_OUT┤
|
||
└──── 重试（attempt+1）◀───────────┴─────────────┘
|
||
└──▶ CANCELLED / SKIPPED
|
||
```
|
||
|
||
- `DISPATCHED`：控制平面已把步骤租给某个 Agent，等待 Agent 确认接手。
|
||
租约有超时——Agent 领了活就死了，租约到期步骤回到 `PENDING` 重新派发。
|
||
- 重试次数由工作流步骤的 `retry` 声明，**默认 0**。
|
||
危险步骤（刷写、Format）默认不重试：重试一次刷写可能把盘刷成砖。
|
||
|
||
## 3. 五级恢复阶梯
|
||
|
||
对应方案 §7.2。触发条件是**双通道观测**的判定结果，不是单一信号：
|
||
|
||
| 级别 | 动作 | 前提 | 典型触发 |
|
||
|---|---|---|---|
|
||
| L1 | `AGENT_SOFT` Agent 优雅停止/软重启进程 | Agent 心跳还在 | 测试脚本卡死、进程僵死 |
|
||
| L2 | `OS_REBOOT` 通过 OS 远程通道重启 | 主机网络还通 | Agent 进程崩溃、驱动异常 |
|
||
| L3 | `OOB_RESET` 带外触发主板 Reset | 带外控制器在线 | 心跳超时 + 带外仍在线（蓝屏典型） |
|
||
| L4 | `OOB_ATX_POWER` 带外模拟 ATX 长按关机再开机 | 带外控制器在线 | Reset 无效（挂在 BIOS/固件态） |
|
||
| L5 | `OOB_AC_CYCLE` 整机 AC 断电 → 安全间隔 → 上电 | 带外控制器在线 | ATX 无效；也是 DUT 掉盘的最后手段 |
|
||
| — | `FREEZE` 冻结现场，停止自动恢复 | — | 超过限定次数；或**数据完整性失败立即触发** |
|
||
|
||
**关键规则（`recovery.py` 里是硬编码的，不给配置覆盖）：**
|
||
|
||
1. **数据完整性失败直接跳到 FREEZE**，不走阶梯。
|
||
哈希/读回比较不一致意味着现场有价值，任何重启都可能毁掉证据。
|
||
2. **带外控制器离线时，L3-L5 不可用**，直接降级到 FREEZE 并标记
|
||
`INFRA_FAILURE`——不能因为带外没接就把 DUT 判成坏盘。
|
||
3. **每一级恢复都要留证**：恢复前抓画面/串口/温度，恢复后验证 DUT 重新枚举。
|
||
`recovery_actions` 表记录每一级的 trigger / outcome / evidence_uri。
|
||
4. **恢复成功 ≠ 步骤成功**。恢复只是把系统救回可执行状态，
|
||
原步骤按检查点语义决定是续跑还是重跑。
|
||
|
||
## 4. 检查点与断点续跑
|
||
|
||
检查点在**步骤边界**创建，不在步骤中间——中间态无法保证幂等。
|
||
|
||
```
|
||
loop_index=37, step=fio-workload, state=SUCCEEDED
|
||
└─▶ checkpoint 写入：{loop_index: 37, next_step: verify-enumeration, dut_fw: "A"}
|
||
```
|
||
|
||
恢复后的续跑规则：
|
||
|
||
| 挂在哪 | 恢复后 |
|
||
|---|---|
|
||
| 步骤已 `SUCCEEDED`，检查点已落 | 从下一步继续 |
|
||
| 步骤 `RUNNING` 时挂了，步骤幂等（`idempotent: true`） | 重跑该步骤 |
|
||
| 步骤 `RUNNING` 时挂了，步骤非幂等（默认，如刷写） | **不重跑**，标记 `INCONCLUSIVE`，进入人工确认 |
|
||
| 步骤是循环体中的一环 | 回到该 `loop_index` 的起点重跑整轮 |
|
||
|
||
非幂等步骤不自动重跑，是这一层最保守也最重要的默认值。
|
||
"自动重试把盘刷坏"是这个产品最容易砸招牌的失败模式。
|
||
|
||
## 5. 心跳与失联判定
|
||
|
||
```
|
||
Agent 心跳间隔 5s
|
||
├─ 15s 无心跳 → 主机 DEGRADED，记事件，不动作
|
||
├─ 30s 无心跳 → 判定失联，查带外：
|
||
│ ├─ 带外在线 + 主机有电 → 走恢复阶梯 L3
|
||
│ ├─ 带外在线 + 主机无电 → INFRA_FAILURE（供电问题，不是 DUT）
|
||
│ └─ 带外也离线 → INFRA_FAILURE + FREEZE（不能瞎判）
|
||
└─ 心跳恢复 → 校验 Run 状态一致性，续跑
|
||
```
|
||
|
||
阈值在 `config.py`，但**判定逻辑在 `state_machine.py` 里是纯函数**：
|
||
输入 `(last_heartbeat_age, oob_online, oob_power_state, now)`，输出判定。
|
||
所以"30 秒超时"这种行为可以不等 30 秒就测出来。
|
||
|
||
## 6. 怎么给状态机加东西（后续几波会反复做）
|
||
|
||
1. 在 `states.py` 加状态/事件枚举 + 改转移表
|
||
2. 在 `state_machine.py::decide()` 加分支，返回新的 `Effect`
|
||
3. 在 `runtime.py` 加该 `Effect` 的施加逻辑（唯一碰 I/O 的地方）
|
||
4. 在 `tests/test_state_machine.py` 加纯函数单测——不起库、不 sleep
|
||
|
||
如果第 2 步发现需要在 `decide()` 里做 I/O，说明抽象漏了，
|
||
应该把需要的数据加进 `Snapshot`，而不是在纯函数里开个口子。
|