[提案] v1 调度面架构演进：意图 MySQL 化 · 调度面多活无状态 · Agent 上报制 · 控制面合并

状态：已提交（openFuyao/SandboxSched Issue #4，评审中）
标签建议：proposal / enhancement
影响范围：internal/sandboxsched-controller、internal/sandboxsched-scheduler、cmd/sandboxsched-{controller,scheduler}、charts/sandboxsched、internal/sandboxwatcher（一处适配）

一、背景与动机

v1 现架构存在四个结构性限制（均附代码锚点）：

1. 意图经 CR 异步落盘，存在"接受但未持久化"窗口
沙箱创建走 FastPath：先 agent create 成功、Sandbox CR 异步补写（sandbox_controller.go:594-614）。崩窗期意图仅存进程内存；controller/scheduler 重启恢复全靠 CR 全量重建（RebuildRouter controller.go:142-174、restoreSSG ssg_controller.go:354）。

2. controller 单实例 + 内存权威态
--leader-elect=false（main.go:49），chart replicaCount=1；内存 Router 三张 map 是权威状态（round-robin 决策、sandboxInfos），实例故障即调度面不可用；重启恢复依赖全量 CR List 回放。

3. scheduler 是静态分片而非多活
StatefulSet×3 按 SSG label 静态绑定（API 层过滤，ssg_watcher.go:61-63），实例故障需重新分片才能恢复容量；InMemoryRegistry（registry.go:28-52）承载全量 reservation/slot/心跳，进程内权威态。

4. 观测面轮询
scheduler 2s Loop 对全部 agent 并发 GetStatus 刷新心跳（60s 过期，loop.go:124-163、registry.go:706），与 Create 请求争抢同一 agent HTTP server（高水位 50 退避，loop.go:53-54 注释明示）——agent 侧被动挨扫，观测开销随沙箱规模线性增长。

二、目标架构

sandboxsched 调度面（多活 Deployment ×N，合并替代 controller + scheduler 两组件）
├─ 入向：gRPC SDK（SandboxProviderService 契约不变，:9091）+ 内部 HTTP（原 :9090 面）
├─ 意图：Sandbox → MySQL manifest（双腿并发同步落盘，CAS 状态机）
│        —— agent 派发与意图落盘双腿并发：双腿成功才返回 201，补偿语义消灭
│           "接受但未落盘"窗口
├─ 观测：agent 5s 上报心跳 → 任意实例接收 → Redis（2s 全量轮询退役，按需拉取兜底）
├─ 容量：Redis 原子预约账 + MySQL CAS 持久门（多实例并发创建不超卖）
├─ 周期任务：过期 GC/孤儿清扫协调/SSG 调和 → K8s Lease 选主（仅周期任务选主，请求面真多活）
└─ 保留不动：SG/SSG CR（容量/模板声明）、watcher DS、agent 执行路径、/api/v1/schedagent 协议

三、四点改动（现状锚点 → 设计方案）

1. 意图存储：CR → MySQL（同步双腿落盘）

• 现状：CR 唯一读写者 = scheduler 侧 SandboxController（CR worker 有序队列/restore/list）；controller 侧三处 CR 索引与重建；gRPC 面四个 CR 读点（List/Get/SetLabel/convert，sandbox_provider.go:325-424）；finalizer 门控删除
• 方案：CR 读写面整体替换为 MySQL 存储层；manifest 表以单事务写入完整意图 JSON（结构见数据模型）；派发采用双腿并发 + 补偿设计——agent 派发与意图落盘同时进行，双腿成功才对外成功，任一腿失败触发补偿（agent 回滚删除或意图行转孤儿由清扫任务收敛）；finalizer 机制随 CR 退役（删除走账本状态机推进）；SandboxWatcher informer 退役（事件源三路替代：FastPath 直调 / leader 周期扫描 / 心跳与 gRPC RPC 转移）；提供 SandboxSpec→意图 JSON 的映射层（逐字段转换，含 resources 量纲换算与 expireTime→TTL）

2. scheduler 多活无状态（+Redis）

• 现状：InMemoryRegistry 全内存权威；SSG label 静态分片；实例故障需重新分片
• 方案：registry 消解——心跳/视图/沙箱投影 → Redis（任意实例 LB 可收可读）；容量预约 = Redis SET 原子账（SADD+SCARD 校验）+ MySQL CAS 持久门，调和对账任务修复 drift；Deployment ×N 替代 StatefulSet 分片；请求面天然多活（MySQL CAS 并发安全），仅周期任务选主

3. Agent 上报制

• 现状：agent 纯被动 HTTP server（不轮询）；2s Loop 全量 GetStatus 拉取是观测瓶颈与争抢源
• 方案：agent 侧新增周期上报组件（5s+jitter+指数退避，断连自愈）POST → 调度面 Service（LB 到任意实例）→ 心跳接收端点 → Redis；env SCHEDULER_REPORT_URL 由 SSG controller constructPod 注入（SSG CR schema 不动）；按需 GetStatus 兜底保留

4. 控制面合并 + 选主

• 现状：controller/scheduler 两进程经 5 个 HTTP RPC 协作（SchedulerClient）；Router.Resolve 内存 round-robin；gRPC 入向面独立部署
• 方案：两进程合并为单组件——5 RPC 内联为进程内调用；Router.Resolve 内联进调度流水线（Redis 视图+SSG informer cache）；gRPC server 迁入；周期任务统一收敛到选主 Runner 执行——K8s Lease 协调，同一周期任务全局单实例运行；请求面多活不选主（MySQL CAS 已并发安全）

四、数据模型

MySQL（新增两张核心表，DDL 随实施给出）

快照台账不在本次范围：v1 的 Snapshot RPC 经 templatemanager（E2B Template Manager）编排，快照目录在 E2B 侧——维持现状（"其他保持不动"），不引入 sandbox_snapshots/snapshot_artifacts 表；如未来需要一方快照台账，作为独立增强另行提案。

state 词汇映射（CAS 状态机为准，v1 phase 为 last_phase 投影）：

Redis（新增，key 设计经操作清单逐条推演——心跳/预约/Resolve/清扫/对账五操作全覆盖，统一 prefix 隔离）

设计取舍说明（相对初稿的操作推演修订）：

• 活性机制合一：ZSET score 替代独立 seen 键——心跳一条 ZADD 完成成员登记+活性刷新，清扫一条 ZREMRANGEBYSCORE 批量清过期（无 SET/seen 失配窗口）
• 删除沙箱 phase 投影（ssg:{ssgKey}:sandboxes:{agentID}）：phase 权威在 MySQL，低频读直查即可——对账面从双向 diff 缩为单向（容量账 vs manifest）；若实测 Resolve 热路径需要投影，登记为演进位
• allocated 字段删除：容量账 SCARD 即 allocated，避免双写漂移

权威边界：

• MySQL = 意图与分配状态机唯一权威（CAS 并发安全）
• Redis = 易变观测 + 原子计数（可重建，调和任务 diff MySQL 修复 drift）
• K8s CR = SG/SSG 声明；K8s Lease = 周期任务选主
• 路由真相 = MySQL manifest.agent_pod（Redis 只放观测投影）

Agent↔Scheduler 连接拓扑：agent env 注入调度面 Service DNS（非实例地址）——推送 LB 到任意健康实例，写共享 Redis，实例故障自动摘除转移；下行派发由任意实例查 MySQL manifest.agent_pod 直连 agent pod（pod 网络全可达）。两方向均无实例绑定。

五、兼容性承诺

• gRPC SDK（SandboxProviderService）契约与响应形状零变化——SDK 用户无感
• agent 侧 /api/v1/schedagent 协议、沙箱执行路径（runtime/manager）零修改（仅新增上报 env 注入）
• SG/SSG CR 定义与语义零变化（容量/模板继续走 CR）
• watcher DS 保留，仅孤儿判定的"CR 缺失"检查改查 MySQL（正确性依赖的唯一必要适配）
• 面向全新部署形态，不做存量 Sandbox CR 迁移（已上线版本不在范围内）

六、部署改动（charts/sandboxsched）

七、分阶段实施

八、验证标准

• 全程 TDD；全量单测 + -race 绿；行为零变化（SDK 响应/SG·SSG CR 语义/agent 协议逐字回归）
• kind 真跑取证：全生命周期（create/delete/pause/resume/snapshot）/ 多实例 LB（双实例并发创建容量不超卖实证）/ kill 实例（心跳与请求自动转移）/ kill leader（周期任务漂移接续）/ gRPC SDK 兼容回归
• codecheck 门禁绿

九、风险与对策