dsh_ai1net_server/dsh-server-docs/交接单/覆盖网络-序25-实例逐步拉起.md

# 交接单 · Manager 重启后「逐步拉起」既有实例

- **序号**：覆盖网络线 **序 ㉕ · 规划棒**
- **立单**：2026-09-17 20:3x
- **用户拍板**：**「Manager 重启后是否自动拉起既有实例：逐步拉起」**（2026-09-17 20:2x）
- **上游依据**：档案 **30**（`dsh-server-docs/04-调整方案/30-编排器孤儿实例清理.md`）／序⑲ §8.8-1（"按需拉起、无 reconciler"的实测）／序⑬ P3（`OBS-09` 因无实例而 SKIP）
- **状态**：**待执行**

---

## §0 摘要 ＋ ⚠️ 一条必须先说的反直觉事实

用户拍板 = **"逐步拉起"**（staggered rehydrate）。但**读源码发现：现在的架构与目标不是"缺一个 reconciler"，而是"启动时主动清空"** ——

| 位置 | 现状 | 与目标的差距 |
|---|---|---|
| `src/supervisor/orchestrator.ts:208`（构造函数） | `this.cleanAllStaleScopes()` —— **portal 启动即清掉全部实例 scope** | 🔴 **这是"逐步拉起"的直接阻碍**：重启后 **N=0**，没有任何可接管的实例 |
| `:1225` | `stopScopesByPrefix('dsh-', /^dsh-\d+-[0-9a-f]+\.scope$/)` | 清得**很干净**（连"哪些曾经在线"的信息一起丢了） |
| `:1218` | `cleanStaleScopes(uid)` —— spawn 前清**同 uid** 名下的残留 scope | ⚠️ 这一条是**必要的**（档案 30 的根因：双实例共 profile ⇒ 写冲突）⇒ **⛔ 不许为了"逐步拉起"把它去掉** |

**根因链（档案 30 原文）**：实例真实生命周期在 **OS 层（systemd scope）**，而编排器**只靠内存 map 追踪** ⇒ 重启后 map 空 ⇒ 旧 scope 变**孤儿**（编排器不认识）⇒ 双实例共享 profile ⇒ session/settings 写冲突 ⇒ "模型连接异常"。当时的修法是"**统一清掉防孤儿**"。

⇒ **本单的核心判断**：**"逐步拉起"= 把"清空"换成"接管"** —— 启动时**不要清**，而是**扫描 OS 层既有 scope ⇒ 逐个回填进内存 map ⇒ 按节流逐个 probe/rehydrate**。⚠️ **前提是先有"可恢复的实例账本"**（否则"清"是唯一安全的做法）。

---

## §1 目标（可判定"做完了没有"）

| # | 判据 | 期望 | 怎么测 |
|---|---|---|---|
| **E1** | 重启后实例**不被清掉** | `restart dshs` 后 5 s 内，重启前在跑的 scope **仍在** | 先起 2 个实例 ⇒ `restart dshs` ⇒ `systemctl list-units 'dsh-*.scope'` **仍为 2** |
| **E2** | **逐个**（节流）接管，⛔ 不风暴 | 接管速率受限（`REHYDRATE_CONCURRENCY` / `REHYDRATE_STAGGER_MS` 阈值内） | 4 个实例 ⇒ 日志逐条时间差 ≥ 阈值；⛔ 无"同一秒 4 条" |
| **E3** | 任一实例都是**原实例**（不是新起） | 接管后 `port` 不变、无新 scope 产生 | 对比重启前后的 scope 名与 `--port` 参数 |
| **E4** | 单实例保证**仍成立**（⛔ 不回归档案 30） | 接管后同 uid **只有 1 个** scope；新 spawn 前仍清同 uid 残留 | 断言 `dsh-<uid>-*` 计数 = 1 |
| **E5** | 无实例时**不自起**（⛔ 不违反"按需"语义） | 重启前**没有**实例 ⇒ 重启后仍为 0 | 空跑一次 `restart dshs` ⇒ scope = 0 |
| **E6** | 内存/启动压力可控 | 接管过程 47 可用内存不跌穿阈值；无 OOM kill | `free` 采样 ＋ `journalctl -u dshs \| grep -c 'oom'` = 0 |
| **E7** | 零回归 | `npm test` **176/175/0/1**、`--scene all --table` **12P/0S/0F**、`overlay-probe --table` **16P/0F/0S** | 三件套跑同值 |

---

## §2 只读前置（执行前**必须**先核实的 4 条）

| # | 要核实什么 | 命令 | 期望 |
|---|---|---|---|
| **P1** | 实例 scope 与 uid 的对应 | `systemctl list-units 'dsh-*.scope' --plain` ＋ 对照 `users` 表 | 确认 `dsh-<uid>-<id>.scope` 里 **`<uid>` = 用户 uid**（档案 30 口径），⛔ 别与"用户 id"混 |
| **P2** | scope 的 `--port` 参数**重启后是否可读回** | `cat /proc/<pid>/cmdline` 或 `systemctl show -p MainPID` 后读 `/proc` | ⚠️ **这是可恢复性的关键**：拿不到端口 ⇒ 没法接管（要另想办法） |
| **P3** | 47 上当前实例数（T0 现场） | `systemctl list-units 'dsh-*.scope'` | 序㉓ 实测 47 = **0**、106 = **1**（⚠️ 实例在 **106** 上）⇒ 本单验收要**主动先起实例** |
| **P4** | 是否有"实例账本"可持久化 | 查 `RemoteSpawner` / `LeasedSpawner` 落库情况 | 若既无 DB 记录也无 /proc 可读 ⇒ **必须先补一步"实例账本"**（见 §4 S1 前置） |

---

## §3 范围

### 3.1 在册文件集（⚠️ **超出必须先停下报告** — R7）

| 面 | 文件 | 说明 |
|---|---|---|
| 改动 | `src/supervisor/orchestrator.ts` | ①② 启动流程：清空 → 接管；新增 `rehydrate()` |
| 改动 | `参数表_覆盖网络_20260917.md` | 新增 `REHYDRATE_*` 键 |
| 改动 | `scripts/overlay-probe.cjs` | 新增观测项（重启后 scope 数 = 重启前） |
| 可能新增 | `test/orchestrator-rehydrate.test.mjs` | 单测（⛔ 不改 `package.json` test 列表的结构） |

⛔ **不在本单范围**：改 bwrap 参数（🔴 **47 是 bubblewrap 0.4.0**，`--perms` 属 0.5+ ⇒ 会起不来）、改 `cleanStaleScopes(uid)` 的"spawn 前清同 uid"语义、动 `RELAY_FAILOVER_*` / `HB_SEC` / burst。

### 3.2 三条硬约束（**违反即事故**）

1. 🔴 **`cleanStaleScopes(uid)`（spawn 前清同 uid）⛔ 不许删** —— 它是档案 30 的修法本体，删了就回到"双实例共 profile"。
2. 🔴 **`cleanAllStaleScopes()` 只能改成"接管"，⛔ 不能改成"什么都不做"** —— 因为内存 map 为空时，**孤儿会失控**（这正是档案 30 的原始故障）。
3. 🔴 **接管必须"认原实例"** —— ⛔ 不许"重启后重新 spawn 一遍"（那会**换端口、换 scope 名**，且瞬间 N 个一起起 = 启动风暴）。

---

## §4 步骤 S0–S6

| 步 | 做什么 | 验证（一次可执行） | 回滚 |
|---|---|---|---|
| **S0** | 只读前置 `P1–P4`（**零改动**） | 拿到"scope 名 ↔ uid ↔ 端口"三者的可读性结论 | 无（只读） |
| **S1** | **（可能需要）实例账本**：把"在线实例"持久化（⚠️ 归属判定：跟着用户走 ⇒ **放实例 home**；本机运维用 ⇒ **Worker 本地库**；⛔ 只有 Manager 能写归属/租约） | 重启后能列出"重启前在跑的实例"清单（含 uid / 端口） | 删账本文件 |
| **S2** | **接管取代清空**：启动扫描 → 回填 map（⛔ 不 stop、⛔ 不 spawn） | `E1`：`restart dshs` 后 scope 数**不变** | 还原 `cleanAllStaleScopes()` 调用 |
| **S3** | **节流**：`REHYDRATE_CONCURRENCY` / `REHYDRATE_STAGGER_MS` | `E2`：4 实例 ⇒ 日志时间差 ≥ 阈值、⛔ 无同秒多条 | 阈值调回 0 ⇒ 回 S2 行为 |
| **S4** | **单实例保证复验**（⛔ 不回归档案 30） | `E4`：同 uid 恒 1 个 scope；`E5`：无实例时不自起 | 同 S2 |
| **S5** | 观测 ＋ 探针新项 | 探针出一项 PASS/FAIL（⛔ 阈值不许是脚本魔数） | 还原探针 |
| **S6** | 真机验收（`E1`–`E6`）＋ 零回归（`E7`）＋ 收口 | `E6`：内存不跌穿、无 OOM；三件套同值 | 产物回滚点 |

---

## §5 真机验收怎么造条件的（⚠️ 关键）

⚠️ **不能只靠"等用户访问"**（本线已因"无 reconciler ⇒ 不自回"卡过一次）。验收必须：

1. **先主动起 2–4 个实例**（用 R4 临时 session 走真实 `enter`，或用本机多实例）⇒ 记录 scope 名 / uid / 端口；
2. `systemctl restart dshs`；
3. **立刻**（≤ 5 s）与 **+60 s** 两个时刻各取一次 `list-units 'dsh-*.scope'`；
4. 断言 `E1`（数不变）／`E2`（逐条时间差）／`E3`（端口不变、⛔ 无新 scope）／`E4`（同 uid = 1）。

⚠️ **已知副作用**：`restart dshs` **会收掉用户实例 scope**（本线既有实测）⇒ 本单要**故意利用**这个副作用做 E1/E5 的对照（重启前有实例 → 应被接管；重启前无实例 → 应保持 0）。

---

## §6 回滚（两层）

1. **代码级**：还原 `orchestrator.ts` 的启动流程为原 `cleanAllStaleScopes()` 调用 → `tsc` → scp `lib/` → `restart dshs` ⇒ 回到"统一清掉防孤儿"（档案 30 行为）。
2. **产物级**：scp 回滚点 `/opt/dsh/backups/seq25-<ts>/lib/supervisor/orchestrator.js`。
   🔴 ⛔ **回滚路径里不许出现 `RELAY_FAILOVER_COOLDOWN_MS=0`**。

---

## §7 回报格式（执行会话**必须**回填）

```markdown
### 8.x 序 ㉕ 执行棒回报（YYYY-MM-DD HH:MM–HH:MM）

#### ① S0–S6 逐条（命令 + 原文输出 + 判定）

#### ② 主判据 E1：重启后实例数不变
- 重启前 scope = ? ｜ +5 s = ? ｜ +60 s = ? ｜ 端口是否全同 = ?

#### ③ 先红后绿（原文级）
- （先跑"仍清空"的旧行为 ⇒ 哪条断言红；改成接管 ⇒ 绿）

#### ④ 零回归三件套（均带 `--table`）

#### ⑤ 边界自证
⛔ 未改生产值 / ⛔ 未改 bwrap 参数 / ⛔ 未删 `cleanStaleScopes(uid)` / 🔴 `COOLDOWN_MS=0` = ? / ⛔ 未 commit·未 push

#### ⑥ 指纹
参数表 = ?（前值 `42238175d84319ada99afa56d583f9db`）｜orchestrator.ts md5 = ?
```

---

## §8 回头条件（**一出现必须回头**）

1. `P2` 拿不到 scope 的端口 ⇒ **停下报告**（"接管"不可行，需先出"实例账本"方案）。
2. 接管导致**双实例共 profile**（档案 30 故障复现）⇒ 立刻回滚 ＋ 报告。
3. 需要**超出 §3.1 文件集** ⇒ 停下报告（R7）。
4. 要**改 bwrap 参数 / 改配额 / 动生产值** ⇒ 停下报告。
5. `E2` 跑不出节流（同秒多条）⇒ 停下报告，⛔ 不许放宽判据。
6. 零回归三件套任一退化 ⇒ 停下报告。
7. 🔴 ⛔ **不许把 `RELAY_FAILOVER_COOLDOWN_MS=0` 写进任何回滚 / 演练 / 夹具路径**。

---

## §9 未验证项

| # | 项 | 状态 |
|---|---|---|
| 1 | 重启后能否从 OS 层读回实例端口 | ⚠️ 待 `P2` 取证 |
| 2 | 是否需要独立"实例账本" | ⚠️ 待 `P4` 取证 |
| 3 | 接管 4 个实例的内存与启动耗时 | ⚠️ 待 S6 实测 |

---

## §10 指纹与状态

| 项 | 值 |
|---|---|
| 本单 §7 之前正文前缀指纹 | **`d9d48121e68faa00e1da17ad8fea36ad`**（口径 = `sed '/^## §7 /,$d' 交接单_实例逐步拉起_20260917.md \| md5sum`） |
| 参数表指纹（立单时） | **`42238175d84319ada99afa56d583f9db`** |
| 代码仓 HEAD（立单时） | `04776af` |
| 本单全文件 md5（立单时） | `2c53a018c2d9bfc2c422d0758413a485`（161 行） |
| 本单状态 | **待执行** ⇒ 交**序 ㉕ 执行棒** |