Opensandbox on 潘达窝

OpenSandbox 源码走读（五·收官）：踩坑合集——3s 轮询、execd 限制与风险清单

Sun, 06 Sep 2026 20:11:17 +0800

OpenSandbox 源码走读（五·收官）：踩坑合集——3s 轮询、execd 限制与风险清单

系列最后一篇，不讲架构，专讲坑。调研和使用 OpenSandbox 过程中踩过、或者差点踩到的坑，按"现象 → 定位 → 根因 → 对策"整理成独立小节，可以直接当 checklist 用。

3s 轮询：任务调度的来龙去脉

这是我在这套代码里最重要的一个发现：批量任务型 sandbox 的整个调度闭环，是被一个写死的 3s 周期推着走的。

先看代码，kubernetes/internal/controller/batchsandbox_controller.go：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


func (r *BatchSandboxReconciler) reconcileTasks(
 ctx context.Context,
 batchSbx *sandboxv1alpha1.BatchSandbox,
 pods []*corev1.Pod,
) (*taskScheduleResult, error) {
 ...
 // Because tasks are in-memory and there is no event mechanism, periodic reconciliation is required.
 DurationStore.Push(types.NamespacedName{Namespace: batchSbx.Namespace, Name: batchSbx.Name}.String(), 3*time.Second)
 ...
}

注释说得很直白：task 是控制器进程内的纯内存对象，没有任何事件机制，所以只能周期性 reconcile。每 3 秒一轮，干三件事：

1
2
3
4


每 3s 一轮 Schedule():
 1. refreshFreePods() 重建空闲 pod 列表（一个 pod 同时只跑一个 task）
 2. collectTaskStatus() 并发 GET http://<podIP>:5758/getTasks 拉任务状态
 3. scheduleTaskNodes() 分配空闲 pod + POST /setTasks 下发任务 / 释放资源

现象：稳态下没有任何业务变化，控制器依然高频 reconcile。粗算一下，1000 个任务型 sandbox 就是稳态 333 reconcile/s，规模化后 CPU 和 API server 压力线性上涨。

根因：为什么不用事件驱动？我专门推演过改成 push 模式的可行性，结论是当前设计下很难：

约束	说明
归属路由	taskScheduler 在控制器内存里，pod 内的 task-executor 根本不知道该上报给哪个实例（leader 还会切换）
可靠性	上报会丢（控制器重启/网络抖动），需要 ack/重试/补偿；轮询天然幂等
调度动作仍需驱动	新任务下发、释放、删除回收都靠周期性 reconcile 推进状态机，状态上报替代不了

也就是说 pull 不是偷懒，是"task 状态存在 pod 内 HTTP 服务里 + 调度器在内存里"这个结构下的必然选择。3s 是"可感知粒度"的妥协——HTTP 默认超时也是 3s（kubernetes/internal/scheduler/default_scheduler.go 里 defaultTimeout = 3 * time.Second）。

但真正的坑在放大效应。第一处，状态收集是无界全并发，kubernetes/internal/scheduler/status_collector.go：

1
2
3
4
5


func (s *defaultTaskStatusCollector) Collect(ctx context.Context, ipList []string) map[string]*api.Task {
 semaphore := make(chan struct{}, len(ipList)) // ← 容量 = pod 数，等于没有限流
 ...
 s.logger.Info("Collect task status", "result", utils.DumpJSON(ret)) // ← 每轮把全部任务状态序列化打 Info 日志
}

第二处，Pod 事件无过滤，batchsandbox_controller.go 的 Owns(&corev1.Pod{}) 没挂任何 predicate——任意 Pod 状态波动都触发整池 reconcile。第三处，RequeueAfter 走 AddAfter，绕过了 workqueue 的指数退避限流（限流只保护返回 error 的路径）。

对策：

这个 3s 目前改不了，只能缓解：调大 --concurrency=batchsandbox，把状态收集日志降到 Debug；
自己写集成时，任务型 sandbox 的规模要做预估算，别等 reconcile 延迟失控才发现；
如果要改事件驱动，可行路径是 task-executor 在任务终态写回 CR status，控制器 watch 触发 + 低频兜底轮询防丢——但代价正是现在这套设计刻意规避的 API server 写放大。

说实话我一开始以为这是个能顺手修掉的"缺陷"，读完整个调度链才发现它是结构性的：内存态调度器 + pod 内 HTTP 状态源，这两个决定摆在那，轮询就是唯一自洽的方案。要根治得动数据流，不是改个时间常数的事。

execd 目录列表：六个限制一次说清

插件场景（通过 execd 读沙箱内文件系统）最容易在这里翻车，尤其是大目录。

接口是 execd 的 POST /directories/list，契约在 specs/execd-api.yaml，实现全在 components/execd/pkg/web/controller/filesystem.go。六个限制，逐个对应代码：

1. depth 默认 1，depth=0 返回空数组

1
2
3
4
5
6
7
8
9


depth := 1
if rawDepth := c.ctx.Query("depth"); rawDepth != "" {
 parsedDepth, err := strconv.Atoi(rawDepth)
 if err != nil || parsedDepth < 0 {
 c.RespondError(http.StatusBadRequest, ...) // ← 负数/非数字直接 400
 return
 }
 depth = parsedDepth
}

1
2
3
4
5
6
7


func listDirectoryEntries(root string, maxDepth int) ([]model.FileInfo, error) {
 entries := make([]model.FileInfo, 0, 16)
 if maxDepth == 0 {
 return entries, nil // ← depth=0 不是"不限深度"，是空数组
 }
 ...
}

第一眼看 depth=0 很容易理解成"不限制"，实际是返回空。想递归列全树只能一层层调。

2. 符号链接不穿透。root 是 symlink 直接拒绝：

1
2
3
4
5
6
7
8
9


// Use Lstat so a symlink passed as the root is detected and rejected
// rather than silently followed
info, err := os.Lstat(path)
...
if info.Mode()&os.ModeSymlink != 0 {
 c.RespondError(http.StatusBadRequest,
 fmt.Sprintf("path is a symbolic link, refusing to traverse: %s", path))
 return
}

遍历过程中的 symlink 只作为条目列出，不递归展开。/workspace 这类 symlink 路径会直接 400，要传真实路径。

3. 必须是目录：传文件路径 400，路径不存在 404。

4. 没有路径白名单：ExpandAbsPath 会展开 ~ 等，execd 以 root 跑在沙箱内，整个容器文件系统都能列（安全边界只剩容器本身的挂载视图）。

5. 没有数量/大小上限：listDirectoryEntries 递归无任何截断。列 /usr、node_modules 这种目录会返回巨大 JSON，撑爆响应体或客户端内存——这是实际影响最大的一个坑。

6. 只返回元数据：FileInfo（path/name/size/mode/is_dir/modified），不含内容，看内容要再调 read 接口。

对策：列目录前先用 depth=1 探一下规模，再按需深入；定向找文件改用 /files/search（支持 glob，默认 **，同样是 filepath.Walk 全量遍历、无数量上限，适合找文件而不是扫目录）。

第 2 条 symlink 拒绝我觉得设计是对的——Lstat 而不是 Stat，注释里明确写了理由：symlink-as-root 会暴露与调用者请求不同的子树。宁可 400 也不静默穿越，这个取舍值得学。

controller 已知缺陷清单

这一节是我对着源码逐条核过的，每条都标注了代码位置，按"会不会咬人"排序。

Helm 默认资源限额过小（kubernetes/charts/opensandbox-controller/values.yaml）：

1
2
3
4
5
6
7


resources:
 limits:
 cpu: 500m
 memory: 128Mi
 requests:
 cpu: 10m
 memory: 64Mi

控制器是全集群 informer 缓存（数百 MB 量级）+ 每 sandbox 调度器状态 + HTTP 轮询，128Mi 上限在批量创建/回收潮里很容易 OOM。上规模前先调大。

缩容未实现（batchsandbox_controller.go）：

1
2


// TODO var needDeleteIndex []int
// TODO consider supply Pods if Pods is deleted unexpectedly

两行 TODO 挨在一起，覆盖了两个坑：spec.replicas 调小不会删 Pod（只扩不缩）；Pool 模式下分配的 Pod 被外部删掉后，alloc-status 注解里的 Pod 名残留，supplement = replicas - len(allocated) 恒为 0，沙箱永久不可用。节点驱逐、OOM Kill 这种规模化最常见的场景正好命中后者。

恢复失败直接退出进程（kubernetes/internal/controller/allocator.go）：

1
2


// ... is terminated via os.Exit(1) because the allocator cannot operate with an ...
os.Exit(1)

首次 Schedule() 时 Recover 失败（全集群无选择器 List）→ 直接 os.Exit(1) → CrashLoop，且每次重启重试全量 List。RBAC 权限错误、API server 抖动都会触发，恢复逻辑没有降级路径。

pause 只支持单副本（batchsandbox_pause_resume.go）：

1

const supportedPauseReplicas int32 = 1

多副本请求 pause 会 ACK 回原 phase + PauseFailed(UnsupportedReplicas)。和"缩容未实现"组合成死锁：想 pause 多副本 → 得先缩到 1 → 缩不了。

每 pod 串行执行（kubernetes/internal/task-executor/manager/task_manager.go）：

1

maxConcurrentTasks = 1

一个 pod 同时只能跑一个任务，第二个直接报错。并发度完全由 spec.replicas 决定，任务排队只能靠扩容。

分配状态真相源是注解，整表覆盖写。每次分配把 pod 数组 JSON 整表 MergePatch 写 alloc-status 注解，并发分配时以最后一次写入为准，丢更新风险靠"先内存后注解、失败回滚"兜底。绕过内存 store 直接改注解会丢状态——注解是内部契约，别碰。

任务下发走裸 HTTP。调度器对 pod 内 5758 端口直连，无认证无鉴权，安全边界完全依赖 NetworkPolicy。部署时必须配。

这份清单里我最警惕的是缩容那条 TODO——它意味着"多副本"这个看起来很常规的能力，实际是半成品：不能缩、pause 不了、Pod 挂了不补。容量规划只能按只增不减来做。

风险清单：上游 open issues 里躲不掉的坑

调研时我们实际用不到 pause/resume，本来以为禁掉就能绕开一批问题。对着全部 open issues 逐个过完的结论是：绝大多数规模化风险和 pause/resume 无关，禁用也躲不掉。

P0 级，Pool 模式的复合缺陷（截至调研均无修复 PR）：

Issue	现象	要点
#1423	Pod 创建/删除风暴	每分钟创建 ~2250 / 删除 ~2290 个 pool Pod，约一半创建请求失败；重启控制器无效，~15 分钟复发
#954	分配的 Pod 被删后永不重绑	上面缩容 TODO 那条的上游 issue 化，沙箱永久不可用
#1433	`poolRef` 可变更导致 in-use Pod 被杀	CRD 无 `x-kubernetes-validations` 也无 admission webhook，运行中改 poolRef 触发破坏链且状态假报

#1423 有个特别阴的细节：缩容按 CreationTimestamp 升序删 idle Pod，“最旧空闲"在长启动时间下等于"刚启动完的”——正好把可服务的 buffer 删掉，留下 Pending，风暴自我维持。

「挂了自动拉起」不存在。上游明确 resume 只恢复有意的 Paused 状态，Terminated/Failed 不自动重启；重建 = 新 sandbox ID + 内存和未持久化状态全丢。这是集成设计的前提性结论：业务关键状态必须外置，“自动拉起 + 保 ID + 保状态"在当前上游语义下不可实现。

快照作为替代方案也有坑：带 egress sidecar（即启用 network_policy）的沙箱无法 snapshot（#1382，commit Job 对多平台 manifest 单平台化 push 失败）——几乎所有有网络隔离的真实工作负载都中招；快照删除不清理 registry 镜像（#1179），存储泄漏。

运维侧三个必知：

#1386：server 运行约 1 周后 httpx 连接池耗尽（当时并发只有 1-5 也复现），长期运行建议监控连接池并周期性重启；
#1408：server 只导出一个指标，还是 SDK 客户端上报的——不用 SDK 的部署一个指标都没有，约 40 种失败模式零计数，故障在指标层完全不可见；
#1409：egress 的 memory/cpu 指标实际读的是节点 /proc，却按 sandbox_id 打标签，N 个沙箱 = N 条相同的节点级假序列，监控基数爆炸。

对策压缩成五条：不假设任何自动恢复；Pool 模式先验证 #954/#1433 修复是否合入、CR 创建后禁止改 poolRef、小 pool 固定容量；批量释放别用 SDK 串行 releaseAllIdle（500 个空闲沙箱 ≈ 480s，自实现 50 并发可压到 ~150s）；快照方案避开 network_policy 并自行清理镜像；server 自建指标。

proxy 链路的业务事实

我们的业务里所有沙箱流量都走 server proxy，这一节是把 proxy 的行为事实单独拎出来，集成时逐条对过。

连接拓扑：

1
2
3
4
5
6
7


业务 / SDK（use_server_proxy=True）
 │ create / delete / renew-expiration（lifecycle API，直连 server）
 │ exec / 文件 / 健康检查（execd API，经 proxy 转发）
 ▼
OpenSandbox Server
 ├── proxy（/sandboxes/{id}/proxy/{port}/）──► 沙箱 execd（默认 44772）
 └── renew_intent consumer（proxy 访问触发自动续约）

每次 proxy 转发前依次执行（server/opensandbox_server/api/proxy.py）：解析沙箱内部端点 → secure-access token 校验（启用时缺头 401/403）→ 提交自动续约信号（非阻塞）→ 转发。

自动续约的生效条件，四个必须同时满足：服务端 [renew_intent] enabled = true；沙箱创建时 opt-in（extensions["access.renew.extend.seconds"] = 300~86400）；沙箱 Running；有过期时间。语义是 new_expires_at = max(now + extend.seconds, current_expires_at)，单调不减、幂等。

容易踩的边界：

端口必须已暴露：proxy 只对创建沙箱时暴露的端口生效，execd 的 44772 没暴露就是 404/502；
runtime-id 门禁：pod 被重建后旧 id 返回 409 RUNTIME_REPLACED，调用方要按响应里的 runtime_id 切换，这个 409 实际是"环境已重置"的信号；
伪永久沙箱不续约：创建不传 timeout 则 expiresAt=null，永不自动终止，自动续约机制完全跳过；反过来过期了的沙箱想用 renew-expiration 补时间也是 409——TTL 是单向的；
HTTP 的 Upgrade: websocket 会 400，WebSocket 走 proxy 的独立路由；
敏感 header 不转发：authorization/cookie 会被剥掉。

我们的选型结论：池化会话走伪永久 + 上层主动删除，不 opt-in 续约，业务 delete 时由中间层 postStop 兜底回写状态；需要"空闲回收"兜底时才改 TTL + opt-in，让活跃会话经 proxy 自动续命。两条路径都不需要 Redis（proxy-only 模式本地冷却就够）。

proxy 这个设计我比较欣赏的是续约信号的放置位置：挂在每次转发的必经路径上、非阻塞提交，活跃会话自然续命，不活跃自然过期——业务侧完全无感。缺点是多副本部署时可能重复续约（好在幂等，无害）。

结

把全系列五篇的坑浓缩成一张最终 checklist：

1
2
3
4
5
6
7
8
9


[ ] 任务型 sandbox 规模预估算过 3s 轮询的 reconcile 压力了吗
[ ] 列大目录前先 depth=1 探了吗；symlink 路径换成真实路径了吗
[ ] Helm 限额（128Mi/500m）按实际规模调过了吗
[ ] 接受"缩容未实现、Pod 挂了不补"了吗（容量只增不减）
[ ] 业务关键状态外置了吗（自动拉起不存在，重建 = 新 ID + 丢状态）
[ ] Pool 模式验证过 #954/#1433 修复了吗；poolRef 锁死了吗
[ ] NetworkPolicy 配了吗（task 下发是裸 HTTP）
[ ] server 自建指标了吗（自监控约等于零）
[ ] 长期运行的 server 有 httpx 连接池监控吗

五篇走读到这收官。从 controller 的 reconcile 闭环、lease 生命周期与续约、池化的模板/注入/S3 会话同步、出口网络的策略与池化出口，最后落到这篇的坑清单——我对 OpenSandbox 的整体判断没变过：架构思路（池化 + 内存态调度 + 注解契约）足够轻快，但工程完备度和它宣传的生产可用之间还有明显距离，规模化路径上的每一个坑几乎都指向同一个根源：内存态 + 无事件机制 + 无界结构。用它，就得按它的真实边界来设计，而不是按文档承诺来设计。

OpenSandbox 源码走读（四）：出口网络——NetworkPolicy、Egress Sidecar 与池化出口

Sun, 06 Sep 2026 20:10:55 +0800

OpenSandbox 源码走读（四）：出口网络——NetworkPolicy、Egress Sidecar 与池化出口

沙箱平台最尴尬的问题之一：用户在沙箱里跑的代码是不可信的，但它偏偏需要出网——调 LLM API、拉 GitHub、装 pip 包。这一篇讲 OpenSandbox 怎么管住这条出口：先拆 egress sidecar 的内部实现，再对比 K8s 原生 NetworkPolicy 为什么不行，最后是我结合自己 Higress 背景想聊的池化出口 + 网关分层方案。

egress sidecar：共享 netns 的透明拦截器

egress 是按需挂载的 Go sidecar（components/egress/），和沙箱应用容器共享网络命名空间。它的定位很克制：只做 L3/L4 + DNS 层的出口管控，L7 明确不做。

先看它什么时候会被挂进 Pod。server/opensandbox_server/services/k8s/egress_helper.py：

1
2
3


def apply_egress_to_spec(..., network_policy, egress_image, ...):
 if not network_policy or not egress_image:
 return # 两个条件缺一个，egress 根本不会出现

也就是：请求带了 network_policy，且 server 配了 [egress] image，才有 sidecar。不传策略的沙箱出站完全不受限——这是个容易误解的默认行为，管控是 opt-in 的。

安全模型的核心在同一个文件里：

1
2
3
4
5
6


def build_security_context_for_sandbox_container(has_network_policy, ...):
 if not has_network_policy:
 ...
 return {
 "capabilities": {"drop": ["NET_ADMIN"]},
 }

启用网络策略时，server 会把沙箱容器的 NET_ADMIN 摘掉，只有 egress sidecar 保留——沙箱里跑的恶意代码没法自己改 iptables 绕过拦截。这一手比任何规则配置都重要，规则再严，用户能改规则就全白搭。

启动流程在 components/egress/main.go，顺序即依赖：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


initialRules, _, err := policy.LoadInitialPolicyDetailed(...)
if err != nil {
 log.Fatalf("failed to load initial egress policy: %v", err) // fail-closed
}
alwaysDeny, alwaysAllow, err := policy.LoadAlwaysRuleFiles()
...
proxy.Start(ctx) // DNS 代理先起，127.0.0.1:15353
...
if err := iptables.SetupRedirect(15353, exemptDst); err != nil {
 log.Fatalf("failed to install iptables redirect: %v", err)
}
setupNft(...) // dns+nft 模式下加载 nftables 链
...
policySrv, err := startPolicyServer(...) // HTTP API :18080
mitm, err := startMitmproxyTransparentIfEnabled() // 可选，实验特性

值得注意的失败模式：全链路 fail-closed。初始策略解析失败、iptables 装不上、nft 加载失败，一律 log.Fatalf 退出，靠 supervisor 重启——宁可沙箱不可用，不带病放行。早期 OSEP 里"没有 CAP_NET_ADMIN 时降级继续运行"的设计已经废弃了，现在 /healthz 不就绪的 Pod 根本不会被分配流量。

熟悉我的老读者知道我写过 Higress 的 failover 逻辑，所以看到 egress 的 DNS 上游处理时有点亲切感：NXDOMAIN/NOERROR 不重试（这是权威答案），其他 rcode 才 failover 到下一个上游。语义是对的。

两层拦截：DNS 代理 + nftables 动态放行

egress 的核心思路是把"域名白名单"这个 L7 概念拆成两层落地：DNS 层管域名，IP 层管连接。策略模型本身只有 action + target 两个字段。

策略解析在 components/egress/pkg/policy/policy.go：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


func normalizePolicy(p *NetworkPolicy) error {
 ...
 if ip, err := netip.ParseAddr(r.Target); err == nil {
 r.targetKind = targetIP // 纯 IP
 r.ip = ip
 continue
 }
 if prefix, err := netip.ParsePrefix(r.Target); err == nil {
 r.targetKind = targetCIDR // CIDR
 r.prefix = prefix
 continue
 }
 // 否则按域名处理

specs/egress-api.yaml 里那句 “IP/CIDR not yet supported in the egress MVP” 是过时注释，实现早就支持了。另外 ParsePolicy 对空策略的处理是 "" / null / {} → DefaultDenyPolicy()——空策略即 deny-all，不会手滑变成全放行。

Layer 1：DNS 代理。iptables 把所有 53 端口流量重定向到本机代理（pkg/iptables/redirect.go）：

1
2
3
4


{"iptables", "-t", "nat", op, "OUTPUT", "-p", "udp", "--dport", "53",
 "-m", "mark", "--mark", constants.MarkHex, "-j", "RETURN"}, // ← 防自递归
{"iptables", "-t", "nat", op, "OUTPUT", "-p", "udp", "--dport", "53",
 "-j", "REDIRECT", "--to-port", targetPort},

代理自己向上游发的查询打上 mark 先 RETURN 跳过，否则会无限套娃。上游地址必须是字面 IP，hostname 会再次命中重定向。IPv4/IPv6 双栈都装，nft 后端装不上 iptables 时还有一套原生 nft redirect 回退（opensandbox_dns_redirect 表）。

被拒域名在 pkg/dnsproxy/proxy.go 的处理：

1
2
3
4
5
6
7
8


if currentPolicy != nil && currentPolicy.Evaluate(domain) == policy.ActionDeny {
 telemetry.RecordDNSDenied()
 p.publishBlocked(domain)
 resp := new(dns.Msg)
 resp.SetRcode(r, dns.RcodeNameError) // 被拒 = NXDOMAIN
 _ = w.WriteMsg(resp)
 return
}

Layer 2：nftables（dns+nft 模式）。pkg/nftables/manager.go 的 buildRuleset 生成的链结构：

1
2
3
4
5
6
7
8
9


ct state established,related accept # 存量连接放行，策略变更不掐断
meta mark <MarkHex> accept # 代理自身流量
oifname "lo" accept # 回环
ip daddr 127.0.0.1 udp/tcp dport 15353 accept
tcp/udp dport 853 drop # DoT 默认阻断，防 DNS 绕过
ip daddr @deny_v4/v6 drop # 静态 deny 集
ip daddr @dyn_allow_v4/v6 accept # 动态 allow 集（DNS 解析产物）
ip daddr @allow_v4/v6 accept # 静态 allow 集
drop # defaultAction: deny 兜底

动态集的 TTL 设计在 pkg/nftables/dynamic.go：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


const (
 dynSetTimeoutS = 360
 nftTTLSlackSec = 60 // 比 resolver 缓存多活 60s，减少竞态
 minTTLSec = 60
 maxTTLSec = 360 // max DNS TTL (300) + slack
)

func clampTTL(d time.Duration) time.Duration {
 sec := int(d.Seconds()) + nftTTLSlackSec
 sec = min(max(sec, minTTLSec), maxTTLSec)
 return time.Duration(sec) * time.Second
}

放行的域名解析出的 IP 带 TTL 进动态集；连接跟踪器每 30s 扫 /proc 里的活跃 TCP 连接续期（只跟踪 TCP，UDP/QUIC 靠 DNS TTL 自然过期）。还有一个容易忽略的时序细节，proxy.go 的注释写得很明白：

1
2


// maybeNotifyResolved calls onResolved before w.WriteMsg so dynamic nft allows are installed
// before the client receives the answer and may open a connection.

nft 放行在 DNS 响应返回给客户端之前同步完成——否则客户端拿到 A 记录立刻建连，会被还没更新的 nft 规则丢掉，变成玄学超时。

这套设计的弱点也很清楚：IP/CIDR 规则只在 dns+nft 模式生效，纯 dns 模式下 DNS 层直接跳过非域名规则。另外端口维度完全没有——NetworkRule 就没有 port 字段，后面讲 Higress 分层时会回到这个问题。

为什么不用 K8s NetworkPolicy

这是官方 docs/architecture/network-isolation.md 里明确的选择，我在源码层面核了一遍，结论成立：不是 NetworkPolicy 不好，是它的语义模型和沙箱场景不匹配。

维度	K8s NetworkPolicy	egress sidecar
控制点	集群网络层（CNI 数据面）	沙箱 Pod 内部（共享 netns）
控制对象	Pod 集合（namespace + label selector）	单个沙箱（per-sandbox）
域名级控制	原生不支持（需 Cilium `toFQDNs` 扩展）	原生支持 FQDN 白名单
动态调整	静态 YAML，改规则要 apply	运行时 API（`POST/PATCH /policy`）实时生效
平台/用户双层	只有平台级（集群管理员 RBAC）	`deny.always`（平台不可覆盖）+ 用户策略
额外开销	无	每沙箱多一个容器 + `NET_ADMIN` 攻击面
gVisor 兼容	无关（运行时透明）	不兼容（netstack 不实现 iptables nat 表）

三个致命的不匹配：

一，label 不可预测。 沙箱 Pod 的 label 由平台自动注入，不同租户/安全级别的沙箱可能共享同一套 label。NetworkPolicy 靠 label selector 划边界，边界本身不可控，规则写得再细也是空中楼阁。

二，生命周期错位。 沙箱秒级创建销毁，NetworkPolicy 是静态声明。“默认拒绝来自所有其他沙箱的访问"是 per-sandbox 语义，用 Pod 集合语义表达要为每个沙箱单独建规则，且永远覆盖不到下一个创建的沙箱。

三，出站控制天然弱。 NetworkPolicy 的 Ingress 能挡入站，但挡不住沙箱进程主动 curl 另一个沙箱的 Pod IP。要挡出站得 Ingress+Egress 双向配，又绕回前两个问题。而沙箱场景最常用的"允许访问 api.github.com“这种域名规则，原生根本不支持。

再往下挖一层是语义差异。NetworkPolicy 是网络管理员视角——“这个网段允许访问那个网段”；egress 是沙箱视角——“这个沙箱允许访问哪些域名”。多租户场景里用户根本不该知道集群的 Pod/Service CIDR（这本身是敏感信息），egress 让用户只声明域名，CIDR 知识留在平台侧。

一个实际的细节：启用策略时 server 摘掉沙箱容器 NET_ADMIN、只留给 sidecar（前面贴过的 build_security_context_for_sandbox_container），所以沙箱内进程无法绕过。NetworkPolicy 场景下这个前提都不需要，因为策略在集群层，沙箱内根本摸不到。

但 egress 的代价也要列清楚：

缺点	说明
需要 `NET_ADMIN`	只给 sidecar，但镜像/部署复杂度和审计面是实打实增加的
与 gVisor 不兼容	netstack 没有 iptables nat 表，REDIRECT 无效；只能改 Kata 或 CNI 级 FQDN 策略
与透明 mesh 冲突	Istio/Envoy sidecar 同在一个 netns 重写流量，二选一
资源开销	每个受控沙箱多一个容器（内存/CPU/镜像拉取）
只管出站	沙箱间入站隔离仍要靠 `deny.always` 挡 Pod CIDR 间接实现

我的判断：OpenSandbox 选 egress 当主力不是"sidecar 模式先进”，而是沙箱平台的三要素——多租户、动态生命周期、域名级出站白名单——每一个都踩在 NetworkPolicy 的语义盲区上。NetworkPolicy 合理的位置是补充：集群内入站隔离、挡 Pod CIDR，跟 Cilium 这类 CNI 配合做 egress 方案的降级备选（gVisor 场景）。

池化模式：策略必须预置进模板

池化（Pool）是预热沙箱的经典套路——先创建一批 Pod 备着，请求来了直接分配。但这和"创建时注入 sidecar"天然冲突：Pod 已经存在了，生命周期 API 没法往里塞容器。

约束很硬：networkPolicy 与 extensions.poolRef 同时使用会被 server 直接拒绝（HTTP 400）。正确做法是把 egress 容器手动写进 Pool 的 spec.template（完整 corev1.PodTemplateSpec，Schemaless 原样透传）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


- name: egress
 image: opensandbox/egress:v1.1.6
 securityContext:
 capabilities:
 add: ["NET_ADMIN"] # 缺失则 sidecar 启动失败（fail-closed）
 env:
 - name: OPENSANDBOX_EGRESS_MODE
 value: "dns+nft" # IP/CIDR 规则仅此模式生效
 - name: OPENSANDBOX_EGRESS_RULES
 value: '{"defaultAction":"deny","egress":[{"action":"allow","target":"api.github.com"}]}'
 - name: OPENSANDBOX_EGRESS_TOKEN
 value: "<token>" # 不设则 18080 无认证，能连上就能改策略
 readinessProbe:
 httpGet: {path: /healthz, port: 18080}

由此带来几个池化特有的坑：

坑	后果
所有沙箱共享模板策略	每请求独立的 `network_policy` 在 pool 模式不生效，模板级统一管控
`OPENSANDBOX_EGRESS_SANDBOX_ID` 无法注入	egress 审计/deny webhook 的 payload 里 `sandboxId` 为空，无法归因到具体沙箱
模板变更不追溯	已预热的 Pod 继续执行旧策略，要滚动更新 Pool 才生效
运行时 patch 需要预置 token	分配后仍可动态改策略（SDK 走 server 鉴权），但模板必须先带 token

sandbox_id 归因缺失是我认为池化模式目前最实际的短板：一个 Pool 服务多个租户时，deny webhook 只知道"有沙箱撞了黑名单”，不知道是谁。审计闭环断了。

池化出口 + Higress：粗粒度给 sidecar，细粒度给网关

这是我自己方案里最想展开的部分。egress 的能力边界卡在两个地方：没有端口维度、没有 L7。企业内网场景（内部 HTTP API、NodePort 服务）恰好需要这两样。既然集群里已有 Higress 网关，与其改造 egress，不如分层。

先固化平台级基线。/var/egress/rules/deny.always（优先级高于用户策略，每分钟热加载，用户不可覆盖）：

1
2
3
4
5
6
7
8
9


# 平台组件 Service DNS
opensandbox-server.opensandbox.svc.cluster.local
opensandbox-ingress-gateway.opensandbox.svc.cluster.local
# 集群内部 CIDR：平台组件 + 沙箱间互访一刀切
10.244.0.0/16 # Pod CIDR
10.96.0.0/12 # Service CIDR
# 上层业务运行时
10.40.0.0/16
*.admin.corp

用户策略（Pool 模板）只放外部服务和网关：

1
2
3
4
5
6
7
8
9


{
 "defaultAction": "deny",
 "egress": [
 {"action": "allow", "target": "api.openai.com"},
 {"action": "allow", "target": "*.pypi.org"},
 {"action": "allow", "target": "higress-gateway.corp.internal"},
 {"action": "allow", "target": "10.20.0.0/16"}
 ]
}

分层架构：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


沙箱应用容器
 │
 ▼
egress sidecar（dns+nft，defaultAction: deny）
 │ 只放行：外部服务域名 + Higress 网关
 ├──────────────► 外部服务（LLM / GitHub / 包源）——域名直连
 │
 ▼
Higress 网关（L7：路径级 allow/deny、认证、限流）
 │
 ▼
内部服务（HTTP API / NodePort 服务）

分工：

层	职责	粒度
egress	默认拒绝 + 白名单；强制内部流量必须走网关；隔离平台组件/业务运行时	域名 / IP / CIDR
Higress	路径/方法级 allow/deny、认证、限流	HTTP 路由

关键机制是egress 把集群内部 CIDR 全 deny，只放行网关——沙箱想访问内部服务，物理上只有 Higress 一条路。这样 L7 管控点天然收口到网关，Higress 上配路由级策略就够，不用关心流量从哪个沙箱来。这个思路对做网关的人来说很自然：L3/L4 收口是防火墙的活，L7 治理是 API 网关的活，别让一个组件干两层的事。

落地时有三个必须踩准的点：

一，内部 Service 要双重放行。 访问集群内 Service，域名（过 DNS 层）和 ClusterIP CIDR（过 nft 层）必须同时 allow。只放域名会出现最迷惑的现象：nslookup 正常，TCP 连接超时——nft 把包丢了，而且动态放行失败在沙箱内看和策略拒绝不可区分。

二，通配符不匹配裸域。 *.pypi.org 匹配不到 pypi.org 本身（domain_index.go 里 exact map 和 wildcard suffix map 是分开的），要两条都加。

三，NodePort 看场景。 专用节点池就 allow 节点网段（如 10.30.1.0/24）；共享节点无法按端口区分，必须让服务走 Higress（网关以 NodePort 暴露，egress 只放网关节点 IP），或者改 ClusterIP + 网关转发。

验证不能只看策略文本，要实测行为：

1
2
3
4


osb egress get <sandbox-id> -o json # 确认 mode=deny_all, enforcementMode=dns+nft
osb command run <sandbox-id> -o raw -- curl -I https://api.github.com # 放行 → 200
osb command run <sandbox-id> -o raw -- curl -I https://blocked.corp # 阻断 → NXDOMAIN
osb command run <sandbox-id> -o raw -- curl -I http://10.244.0.5 # 阻断 → 超时

注意 nft 链放行 established,related，改策略不掐存量连接——验证必须用新连接，不然测的是旧规则。

如果要在生产用这套组合，我会先补三件事：pool 模式的 sandbox_id 归因（比如 egress 支持分配时注入）、egress.nftables.updates.failed_total 指标的告警（动态放行失败是 fail-closed 静默故障，现象和策略拒绝一模一样）、以及一份按实际集群 CIDR 生成的 deny.always 模板——CIDR 写错要么误放行要么误阻断，且都很难从现象反推。

出口网络这条线到这里基本闭环了：组件内部实现 → 与 K8s 原生方案的取舍 → 池化 + 网关分层。整个 OpenSandbox 源码走读系列的下一篇也是收官篇，会把前面几篇没展开的踩坑合集一次性倒出来。

系列索引：（一）CRD Controller 与 Reconcile 循环 · （二）Sandbox Lease 与生命周期管理 · （三）池化设计；下一篇（收官）：踩坑合集。

OpenSandbox 源码走读（三）：池化设计——Template 更新、分配注入与 S3 会话同步

Sun, 06 Sep 2026 20:10:52 +0800

OpenSandbox 源码走读（三）：池化设计——Template 更新、分配注入与 S3 会话同步

前两篇看了 CRD 模型和创建链路，这篇讲我觉得整套系统里工程含金量最高的部分：池化。AI agent 场景下沙箱创建动辄十几秒，用户等不了——所以要把 pod 提前建好捂热，create 时直接分配。但"复用已运行的 pod"这个约束会连锁引出一堆问题：模板更新了怎么办？用户身份怎么在分配时刻注进去？上一个用户的会话数据怎么保证不串到下一个用户？这篇沿着"模板 → 池 → 分配 → 会话同步"把这条线走完。

为什么要池化

非池化路径下，create 一个沙箱意味着：调度 pod → 拉镜像 → 启动容器 → execd 就绪，整个链路秒级起步、镜像大了奔着分钟去。agent 场景里这是不可接受的——用户发一条消息，agent 要在对话内频繁开沙箱跑代码，没人愿意等十几秒的"白屏"。

池化的思路很朴素：用 Pool CRD 预先按模板创建一批 pod 捂着，业务 create 时带 extensions.poolRef，server 不再建 pod，而是从池里挑一个已运行的分给这个 BatchSandbox：

flowchart LR
A[业务 create poolRef] --> B[server 建 BatchSandbox CR]
B --> C[PoolReconciler 分配预热 pod]
C --> D[taskTemplate 下发到 pod 内 task-executor]
D --> E[返回 create 成功]

pod 建好之后所有动作都发生在"已运行的容器"里，这就是池化一切设计的出发点。

Template 更新：sha256 版本号 + 只换空闲 pod

Pool 的模板版本不是手填的，是控制器对 spec.template 做 sha256 算出来的：

1
2
3
4
5
6
7
8
9


// kubernetes/internal/controller/pool_controller.go
func (r *PoolReconciler) calculateRevision(pool *sandboxv1alpha1.Pool) (string, error) {
 template, err := json.Marshal(pool.Spec.Template)
 if err != nil {
 return "", err
 }
 revision := sha256.Sum256(template)
 return hex.EncodeToString(revision[:8]), nil // ← 取前 8 字节做版本号
}

新创建的 pod 会打上 sandbox.opensandbox.io/pool-revision 标签（createPoolPod 里 pod.Labels[LabelPoolRevision] = updateRevision），这样池子里每个 pod 属于哪个版本一目了然。

更新策略有个关键前提：只处理 idle pod。scheduleSandbox 里 idle 的定义是"Ready 且未被分配"：

1
2
3
4
5
6
7
8


// kubernetes/internal/controller/pool_controller.go
latestAllocation, err := r.Allocator.GetPoolAllocation(ctx, pool)
idlePods := make([]string, 0)
for _, pod := range pods {
 if _, ok := latestAllocation[pod.Name]; !ok { // ← 被分配的不算 idle
 idlePods = append(idlePods, pod.Name)
 }
}

recreateUpdateStrategy.Compute（pool_update.go）的签名直接把这一点写在了参数上：

1
2


Compute(ctx context.Context, updateRevision string,
 pods []*corev1.Pod, idlePods []string) *UpdateResult

替换节奏受 UpdateStrategy.MaxUnavailable（默认 25%）预算控制，空闲 pod 分批删旧建新。GenerationChangedPredicate 保证只有 spec 变更才触发 reconcile，status 抖动不会引发无谓轮询。

只换 idle pod 是对的——已分配的 pod 背后有活着的沙箱，删了就是事故。但它带来一个容易被忽略的推论：如果池子里所有 pod 都被分配了，updatePool 算出 SupplyUpdateRevision = 0，一个新 pod 都不会建，整个池子停留在旧版本，而且没有任何告警。升级模板前得先看一眼分配率。

分配：先到先得，不认版本号

分配算法在 algorithm/packed.go，简单到值得整段贴出来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


// kubernetes/internal/controller/algorithm/packed.go
type PackedSchedule struct{}

func (p *PackedSchedule) Schedule(availablePods []string, allRequest []*SandboxRequest) *AllocAction {
 action := &AllocAction{
 ToAllocate: make(map[string][]string),
 ToRelease: make(map[string][]string),
 PodSupplement: int32(0),
 }
 for _, req := range allRequest {
 // ... 收集 release 请求 ...
 need := req.PodSupplement
 if need <= 0 { continue }
 if int32(len(availablePods)) >= need {
 action.ToAllocate[req.SandboxName] = availablePods[:need] // ← 按列表顺序切
 availablePods = availablePods[need:]
 } else if len(availablePods) > 0 {
 action.ToAllocate[req.SandboxName] = availablePods
 action.PodSupplement += need - int32(len(availablePods)) // 不够就补建
 availablePods = nil
 } else {
 action.PodSupplement += need
 }
 }
 return action
}

availablePods 就是上一节的 idle 列表——注意它不区分 revision，新旧版本的 pod 混在一起先到先得。所以模板刚更新完，只要 idle 池里还剩旧 revision 的 pod，新沙箱就可能分到旧 pod。

分配关系的记录方式也值得注意：pod 上没有任何指向 BatchSandbox 的所有权标记。pod 只有 pool-name 和 pool-revision 两个标签，ownerReference 指向的是 Pool；分配关系单向记在 BatchSandbox 的注解上：

1
2
3
4


// kubernetes/internal/controller/apis.go
AnnoAllocStatusKey = "sandbox.opensandbox.io/alloc-status" // {"pods":["pod-a"]}
AnnoAllocReleaseKey = "sandbox.opensandbox.io/alloc-release" // 待释放
AnnoAllocReleasedKey = "sandbox.opensandbox.io/alloc-released" // 已释放

没有 pod → sandbox 的正向索引，查"这个 pod 属于哪个沙箱"只能反向遍历所有 BatchSandbox 的注解。控制器的 InMemoryAllocationStore 也是从注解 Recover 出来的，没有独立持久化——好处是注解即真相、重启可恢复，坏处是规模化之后反向查询会很疼。

分配时刻注入：taskTemplate 就是现成的通道

池化 pod 是预热的，分配时不能改 pod spec——initContainer、ConfigMap 挂载、env 注入这些"创建时生效"的手段全部失效。分配时刻能做的只有往运行中的容器里执行动作。

server 的做法是把注入打包进 taskTemplate。看 batchsandbox_provider.py 的真实代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# server/opensandbox_server/services/k8s/batchsandbox_provider.py
def _build_task_template(self, entrypoint, env, sandbox_id):
 escaped_entrypoint = ' '.join(shlex.quote(arg) for arg in entrypoint)
 if self.execd_run_as_init:
 user_process_cmd = f"exec /opt/opensandbox/bootstrap.sh {escaped_entrypoint}"
 else:
 user_process_cmd = f"/opt/opensandbox/bootstrap.sh {escaped_entrypoint} &"

 wrapped_command = ["/bin/sh", "-c", user_process_cmd]
 env_list = [{"name": k, "value": v} for k, v in env.items()] if env else []
 env_list.append({"name": "OPENSANDBOX_ID", "value": sandbox_id})
 return {"spec": {"process": {"command": wrapped_command, "env": env_list}}}

有个容易踩的坑藏在 _create_workload_from_pool 里：不传 entrypoint/env 时走快路径，直接不生成 taskTemplate：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


needs_task_template = (
 env
 or entrypoint != DEFAULT_ENTRYPOINT
 or self.execd_run_as_init
)
if needs_task_template:
 spec["taskTemplate"] = self._build_task_template(entrypoint, env, batchsandbox_name)
else:
 # Fast path: the pre-created pool pod keeps running its own warm
 # entrypoint, so no per-allocation env can reach execd.

快路径省一次任务下发，但代价是连 OPENSANDBOX_ID 都注入不了，注释里明说了这条路径上 eBPF 审计无法归属 sandbox_id。

“分配后注入"能成立，靠的是 controller 的 3 秒轮询链路：

1
2
3
4


server 创建 BatchSandbox（含 taskTemplate）
 → BatchSandboxReconciler 每 3s reconcile
 → taskTemplate 生成 task specs 下发到 pod 内 task-executor（:5758）
 → task-executor 先跑 preStart 钩子，再跑主命令

这引出一个关键的时序判断：taskTemplate 是 server 每次分配时生成的，create 请求里的动态参数（user_id、token）在生成那一刻就已知，所以可以直接渲染进命令——命令里 cat > file <<'EOF' 写文件、sh file 调脚本，注入和调用一次完成。执行天然发生在分配后，不需要新开 k8s exec 接口。exec 只在需要"分配后才知道的信息”（pod IP、运行时探测）时才值得引入。

token 这类敏感凭证注入时要小心：taskTemplate 的命令会进日志，user_auth_token 千万别拼进命令行，走 env 注入更稳。而且 Pool 模式下 Secret 挂载必须预挂进模板，分配时加不了——所以分配时刻注入 token 实际只有 env 和文件两条路。

S3 会话同步：固定 postStop + 中间层静默 exec

池化还有个更麻烦的问题：pod 是复用的，用户 A 用完回池，用户 B 分到同一个 pod 时绝不能看到 A 的文件。解法是把会话状态放 S3，按前缀隔离：

1

s3://<bucket>/tenants/<tenantId>/users/<userId>/sessions/<sessionId>/

架构上分三层，各管各的：

层	职责	时机
Pool 模板	共享 emptyDir `/shared-workspace`、task-executor 侧 S3 CLI + 凭证（IRSA）	一次配置
BatchSandbox	固定 postStop（与用户无关，所有沙箱一样）	建 CR 时带上
中间层	按用户渲染并注入 sync 脚本、触发 restore	分配后 exec

固定 postStop 长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


lifecycle:
 postStop:
 execMode: Local  # 在 task-executor 侧执行
 timeoutSeconds: 180
 exec:
 command: ["/bin/sh", "-c"]
 args:
 - |
 set -eu
 HOOK=/shared-workspace/.osb-sync-out.sh
 if [ -x "$HOOK" ]; then "$HOOK"; fi # ← 存在才跑，注入的回写脚本
 find /shared-workspace -mindepth 1 -delete # 清盘防串台

中间层的 create 流程对外仍然是一次普通的 create：

1
2
3
4
5
6
7
8


1. 解析身份 → S3_USER_PREFIX
2. 创建 BatchSandbox（poolRef + 固定 postStop 的 taskTemplate）
3. 等待分配的 pod Ready
4. 内部 pods/exec 到 task-executor 容器：
 a. 写入并 chmod +x /shared-workspace/.osb-sync-out.sh
 b. 后台启动 inbound restore（aws s3 sync ... || true），不等 CLI 结束
5. 标记会话已 prepare
6. 返回 create 成功

delete 时（主动删或 expireTime 到期）走同一条路：删 CR → finalizer → StopTask → postStop 跑 .osb-sync-out.sh 回写 S3 + 清盘 → pod 回池。到期删除也能回写，这是把回写放进 postStop 而不是让业务在 delete 前自己 sync 的核心理由。

为什么脚本要靠 exec 注入、而不是让固定钩子去读用户 env？我查了 task-executor 的实现，Local 钩子的环境是这么构造的：

1
2


// kubernetes/internal/task-executor/runtime/process.go
cmd.Env = os.Environ() // ← 只继承 task-executor 进程自身环境

钩子不继承 task 的 process.env，所以"create 时塞个 S3_USER_PREFIX env、固定 sync 脚本去读"这条路在当前实现下走不通——注入脚本把前缀写进文件，就是在绕这个限制。postStop 钩子在任务终态（成功/失败/超时/删除）时必执行，倒是销毁前持久化产物的可靠挂点。

这套设计里我最欣赏的是"动态与静态分离"：用户相关的东西（S3 前缀、脚本内容）由中间层运行时注入，用户无关的骨架（postStop 逻辑、清盘）固化在 CR 模板里。业务 SDK 全程只看到 create → 使用 → delete，pods/exec、S3 命令、脚本路径全都不出中间层。代价是链路变长了：中间层挂了恢复逻辑、postStop 失败是否阻塞回池、restore 还在跑就回池的竞态，这些都是要靠运维约定兜底的模糊地带。

shardTaskPatches：批量创建时的差异化补丁

最后补一个和 taskTemplate 配套的机制。BatchSandbox 支持一次创建 N 个沙箱，shardTaskPatches[i] 按下标对第 i 个副本的任务做覆盖，实现"批量创建、各跑各的"：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


spec:
 replicas: 3
 taskTemplate:
 spec:
 process:
 command: ["python", "train.py"]
 args: ["--epochs", "10"]
 shardTaskPatches:
 - spec: { process: { args: ["--epochs", "10", "--lr", "1e-3"] } }
 - spec: { process: { args: ["--epochs", "10", "--lr", "1e-4"] } }
 # 副本 2 无 patch → 用默认 taskTemplate

合并逻辑在 task_scheduling_strategy_default.go，就是标准的 strategic merge patch：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


func (s *DefaultTaskSchedulingStrategy) getTaskSpec(idx int) (*api.Task, error) {
 task := &api.Task{Name: fmt.Sprintf("%s-%d", s.Name, idx)}
 if len(s.Spec.ShardTaskPatches) > 0 && idx < len(s.Spec.ShardTaskPatches) {
 taskTemplate := s.Spec.TaskTemplate.DeepCopy() // ← 在深拷贝上合并，不动原模板
 cloneBytes, _ := json.Marshal(taskTemplate)
 patch := s.Spec.ShardTaskPatches[idx]
 modified, err := strategicpatch.StrategicMergePatch(
 cloneBytes, patch.Raw, &sandboxv1alpha1.TaskTemplateSpec{})
 if err != nil {
 return nil, fmt.Errorf("batchsandbox: failed to merge patch raw %s, idx %d, err %w", patch.Raw, idx, err)
 }
 // ...
 task.Process = convertProcessSpec(newTaskTemplate.Spec.Process,
 s.Spec.TaskTemplate.Spec.TimeoutSeconds) // ← timeout 取基础模板
 } else if s.Spec.TaskTemplate != nil && s.Spec.TaskTemplate.Spec.Process != nil {
 task.Process = convertProcessSpec(s.Spec.TaskTemplate.Spec.Process,
 s.Spec.TaskTemplate.Spec.TimeoutSeconds)
 }
 return task, nil
}

几个容易记错的语义：env 数组按 name merge（同名覆盖、异名保留，patch 删不掉模板里的 env）；timeoutSeconds 永远取基础模板，patch 里改了不算数；patch 数量和 replicas 不匹配时静默兜底，多补丁忽略、少补丁用模板，没有告警。注意 server API 并不暴露 shardTaskPatches，只能直接操作 CR；server 的池化分配路径走的是单任务模板（_build_task_template），没有 shard 能力。 RL 训练/评测这类 “high-throughput agentic-RL” 场景是它的主场：配合 taskResourcePolicyWhenCompleted: Release，任务跑完 pod 立刻回池，批量沙箱用完即焚。

把这条链路串起来看，池化设计的精髓是"把不确定性往后推"：模板预热消灭冷启动，revision 机制管住模板演化，taskTemplate 把分配时刻的动态注入变成一次任务下发，postStop + S3 前缀把有状态会话塞进无状态池。每一环都不复杂，但约束传导得很干净——“复用已建 pod"这一条，决定了注入只能走任务下发、清理只能靠钩子、隔离只能靠外部存储。如果要说短板，我觉得是可观测性：快路径注入不了 ID、旧 revision 无告警、postStop 失败只记注解，这些都得自己补监控。

下一篇走读出口网络：沙箱的 egress 代理、token 鉴权和域名白名单是怎么做的。

OpenSandbox 源码走读（二）：Sandbox Lease 与生命周期管理

Sun, 06 Sep 2026 20:10:30 +0800

OpenSandbox 源码走读（二）：Sandbox Lease 与生命周期管理

沙箱这类"按需创建、用完即弃"的资源，最怕的不是创建慢，而是没人回收——客户端崩了、网络断了，服务端还替它养着一个占 CPU 占内存的容器。这次把 OpenSandbox 的 lease（租约）机制翻了一遍：TTL 怎么算、到期谁去杀、续约有几条路、以及"伪永久"模式的清理边界。代码基于 main 分支（2026-08 核对）。

为什么需要 lease：没有它会出什么事故

先想清楚问题。沙箱不是无状态的 HTTP 请求，它是一个持续占用资源的容器/ Pod。调用方（比如一个 Agent 运行时）创建沙箱后，可能：

进程崩溃，永远不会再发"删除"请求；
网络分区，删除请求丢了；
业务 bug，for 循环里创建了 1000 个沙箱然后忘了。

没有租约机制，这些沙箱就变成孤儿——API 层面查得到，但没人对它们负责。Docker 里一个容器几百 MB 内存，K8s 里一个 Pod 还带 sidecar，泄漏速度远超普通连接池。

OpenSandbox 的解法是经典的 lease 模型：创建时必须声明租期（或者明确声明不设租期），到期由服务端单方面回收。入口在创建请求的 timeout 字段（秒，最小 60），服务端换算成绝对时间戳：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# server/opensandbox_server/services/docker/docker_service.py
def _prepare_creation_context(
 self,
 request: CreateSandboxRequest,
) -> tuple[str, datetime, Optional[datetime]]:
 sandbox_id = self.generate_sandbox_id()
 created_at = datetime.now(timezone.utc)
 expires_at = None
 if request.timeout is not None:
 expires_at = calculate_expiration_or_raise(created_at, request.timeout) # ← createdAt + timeout
 return sandbox_id, created_at, expires_at

注意 timeout is None 这个分支——它不是"忘了传"，而是一个正式模式（后面讲）。租期计算和上限校验都在 services/validators.py：

1
2
3
4
5
6
7
8
9


# server/opensandbox_server/services/validators.py
def ensure_timeout_within_limit(timeout_seconds, max_timeout_seconds) -> None:
 if timeout_seconds is None:
 return # ← 伪永久模式，跳过校验
 calculate_expiration_or_raise(datetime.now(timezone.utc), timeout_seconds)
 if max_timeout_seconds is None:
 return # ← 服务端没配上限 = 不限
 if timeout_seconds > max_timeout_seconds:
 raise HTTPException(status_code=400, ...)

max_sandbox_timeout_seconds 是 [server] 配置里的 TTL 上限（config.py，默认 None 不限）。多租户部署建议配一个，否则调用方传个 timeout=999999999 也能过——虽然 calculate_expiration_or_raise 会把 datetime 溢出转成 400，但"合法地租一年"依然拦不住。

lease 存的是绝对时间戳（expiresAt）而不是剩余秒数，这个选择是对的：服务端重启、时钟回拨、续约覆盖，都以一个不可变的时间点为准，不需要维护递减计数器。

到期执行：Docker 定时器 vs K8s 控制器

expiresAt 算出来了，谁来负责到期杀沙箱？Docker 和 K8s 两条运行时走了完全不同的实现路线。

Docker 路线是进程内 Timer。每个沙箱一个 threading.Timer，续约时直接替换旧 timer：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# server/opensandbox_server/services/docker/docker_service.py
def _schedule_expiration(self, sandbox_id, expires_at, *, update_expiration=True, ...) -> None:
 delay = max(0.0, (expires_at - datetime.now(timezone.utc)).total_seconds())
 timer = Timer(delay, self._expire_sandbox, args=(sandbox_id,), kwargs=expire_kwargs or None)
 timer.daemon = True
 with self._expiration_lock:
 # Replace existing timer (if any) so renew operations take effect immediately
 existing = self._expiration_timers.pop(sandbox_id, None)
 if existing:
 existing.cancel()
 if update_expiration:
 self._sandbox_expirations[sandbox_id] = expires_at
 self._expiration_timers[sandbox_id] = timer
 timer.start()

进程内 Timer 有个致命问题：server 重启，内存里的 timer 全丢。所以启动时有一段 restore 逻辑，遍历所有容器 label 重建 timer，已过期的立即补杀：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# docker_service.py（启动恢复，简化）
expires_at = self._get_tracked_expiration(sandbox_id, labels)
if expires_at is None:
 if self._has_manual_cleanup(labels):
 restored += 1
 continue # ← 伪永久沙箱跳过调度
 ...
if expires_at <= now:
 expired_entries.append((sandbox_id, mount_keys)) # 已过期，pass 2 补杀
 continue
self._schedule_expiration(sandbox_id, expires_at)

_get_tracked_expiration 的查找顺序是内存缓存 → 文件元数据存储 → 容器 label，三层兜底保证重启后也能恢复租约。而 _expire_sandbox 的回调里还有个细节我挺喜欢——杀之前再查一次当前租约，续约竞态时放弃删除：

1
2
3
4
5


# docker_service.py
current_expires = self._get_tracked_expiration(sandbox_id, labels)
if current_expires and current_expires > datetime.now(timezone.utc):
 self._schedule_expiration(sandbox_id, current_expires, update_expiration=False)
 logger.info("Sandbox %s was renewed (expires %s); aborting expiration.", ...)

没有这个检查，就会出现"用户刚续约，过期定时器还是把沙箱杀了"的灵异事件。另外定时器触发时如果暂时查不到容器（瞬时报错），会 30 秒后重试而不是放弃——lease 到期是确定性的，只是延迟，不会丢。

K8s 路线完全没有定时器这回事，靠的是控制器 reconcile。expiresAt 写进 BatchSandbox CR 的 spec.expireTime，控制器每次 reconcile 检查：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// kubernetes/internal/controller/batchsandbox_controller.go
if expireAt := batchSbx.Spec.ExpireTime; expireAt != nil {
 now := time.Now()
 if expireAt.Time.Before(now) {
 if batchSbx.DeletionTimestamp == nil {
 log.Info("batch sandbox expired, delete", "expireAt", expireAt)
 if err := r.Delete(ctx, batchSbx); err != nil { ... } // ← 到期直接删 CR
 }
 } else {
 DurationStore.Push(...) // ← 未到期，把差值塞回去驱动下次 requeue
 }
}

两条路线对"到期后是删是留"还有一个共同的开关：shutdown_policy: Delete|Retain（config.py:700）。设成 Retain 时过期只终止不清理，用于调试或事后取证。

Timer（推）vs reconcile（拉）是分布式系统里到期处理的两种基本形态。Timer 精确但要自己处理重启恢复；reconcile 天然幂等、重启免费，但精度受 requeue 间隔限制。OpenSandbox 两种都用了，各自贴合运行时特性，这个选择没毛病。

手动续约：renew-expiration 的三条约束

租约要能续，否则长任务都得把 timeout 估到最大。续约 API 只有一个端点：

1
2


POST /sandboxes/{id}/renew-expiration
{ "expiresAt": "2026-08-19T12:00:00Z" } // 绝对时间，必填

路由是薄壳，直接委托 service 层（api/lifecycle.py:344-384）。真正有意思的是它背后的三条约束：

约束一：只能延长，不能缩短。 spec 里写死 “Must be in the future and after the current expiresAt time”，服务端校验在 validators.py：

1
2
3
4
5
6
7
8


def ensure_future_expiration(expires_at: datetime) -> datetime:
 if expires_at.tzinfo is None:
 normalized = expires_at.replace(tzinfo=timezone.utc) # naive 时间按 UTC 处理
 else:
 normalized = expires_at.astimezone(timezone.utc)
 if normalized <= datetime.now(timezone.utc):
 raise HTTPException(status_code=400, detail={"code": "INVALID_EXPIRATION", ...})
 return normalized

这意味着你不能通过续约来提前回收一个沙箱，也不能给伪永久沙箱"补"一个过期时间——后者直接 409：

1
2
3
4
5
6
7
8
9


# docker_service.py renew_expiration
if self._has_manual_cleanup(labels):
 raise HTTPException(
 status_code=status.HTTP_409_CONFLICT,
 detail={"code": SandboxErrorCodes.INVALID_EXPIRATION,
 "message": f"Sandbox {sandbox_id} does not have automatic expiration enabled."},
 )
if self._get_tracked_expiration(sandbox_id, labels) is None:
 raise HTTPException(status_code=409, ...) # ← label 丢失也拒绝，宁可不续

约束二：lease 状态要三处同步。 Docker 实现里，续约成功要同时改内存 timer、文件元数据、容器 label 三个地方：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# docker_service.py renew_expiration（注释是原文）
# Persist the new timeout in memory; the file-backed override also keeps renewals correct across restarts
self._schedule_expiration(sandbox_id, new_expiration)
try:
 self._metadata_store.set_expiration(sandbox_id, new_expiration)
except OSError as exc:
 logger.warning("Failed to persist expiration override ...") # ← 失败只记日志
labels[SANDBOX_EXPIRES_AT_LABEL] = new_expiration.isoformat()
try:
 with self._docker_operation("update sandbox labels", sandbox_id):
 self._update_container_labels(container, labels)
except (DockerException, TypeError) as exc:
 logger.warning("Failed to refresh labels ...")

三处里任何一处失败都是 warning 而不是报错——好在查找时有 fallback 链兜底，但严格说这不是事务性的。

约束三：K8s 侧要同步 CR 和 label。 kubernetes_service.py 的 renew_expiration 同时更新 BatchSandbox 的 spec.expireTime 和对应 label，保证 reconcile 逻辑和 kubectl 排障看到的值一致。

409 的设计值得玩味：续约不能作用于伪永久沙箱，这是一个用状态机拒绝而不是静默成功的例子。如果这里静默返回 200，调用方会以为沙箱有了租约，实际永远不会过期——比 409 危险得多。

自动续约（OSEP-0009）：访问即续命

手动续约要求调用方自己记得续，OpenSandbox 在 OSEP-0009 里做了访问驱动的自动续约：反向代理观测到流量，就替沙箱续一次命。

用法上就两步：创建沙箱时在 extensions 里 opt-in，之后所有经 server proxy 的调用（exec/文件/健康检查，转发前有 _schedule_proxy_renew 埋点）自动续期；ingress 模式额外开 Redis。但整条链路有一个唯一的坑，先说在前面——服务端开关。[renew_intent] enabled 默认 False，而创建时对 extension 的校验只查值的格式（300~86400 的字符串十进制整数），不查服务端开关。也就是说客户端全做对了、proxy 调用一切正常，server 没开开关就一个字都不续——proxy_renew.py 第 38 行直接短路返回，无日志无报错，沙箱到点照样被杀。排查"自动续约不生效"，第一个要看的不是客户端配置，是 server config 里这个开关。

opt-in 的合法性在创建时校验的只有这个：

1
2
3


# server/opensandbox_server/extensions/validation.py
ACCESS_RENEW_EXTEND_SECONDS_MIN = 300 # 5 分钟
ACCESS_RENEW_EXTEND_SECONDS_MAX = 86400 # 24 小时

1
2
3
4


{
 "extensions": { "access.renew.extend.seconds": "3600" },
 "timeout": 600
}

注意传的是字符串形式的十进制整数，范围 300~86400，非法值创建即 400。每次访问触发的续约量就是 now + extend.seconds。

触发源有两条路：

flowchart LR
A[客户端流量] -->|经 server proxy| B[ProxyRenewCoordinator
api/proxy.py 埋点]
A -->|经 ingress gateway| C[Go 侧 Publisher
components/ingress/pkg/renewintent]
B --> D[RenewIntentConsumer
统一 asyncio 队列]
C -->|Redis List| E[BRPOP feeder]
E --> D
D --> F{AccessRenewController 门控}
F -->|通过| G[renew_expiration]

所有路径最终汇到 integrations/renew_intent/controller.py 的门控，逻辑很收敛：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


def _try_renew_sync(self, sandbox_id: str, *, source: str) -> bool:
 try:
 sandbox = self._sandbox_service.get_sandbox(sandbox_id)
 except HTTPException:
 return False
 if sandbox.status.state.lower() != "running":
 return False # ← 非 Running 不续
 if sandbox.expires_at is None:
 return False # ← 伪永久沙箱不参与自动续约
 extend = self._extension_service.get_access_renew_extend_seconds(sandbox_id)
 if extend is None:
 return False # ← 未 opt-in 不续
 candidate = now + timedelta(seconds=extend)
 new_expires = max(candidate, current) # ← 单调不减，天然幂等
 ...

max(candidate, current) 这个写法保证了重复消费或乱序消费都不会把租约改小，配合每沙箱 asyncio.Lock 串行化，基本堵死了竞态。

坑都在外围。我对照实现把 OSEP 设计稿和代码过了一遍，这几个点值得记：

Redis 启用时 proxy 路径没有冷却。consumer.py 的 _process_work 里，self._redis is not None 时直接续约，完全跳过 min_interval 节流：

1
2
3
4
5
6
7
8


# consumer.py
async with st.lock:
 if self._redis is not None:
 await self._controller.renew_after_gates(work.sandbox_id, source=work.source)
 return # ← 无 min_interval 检查
 now = time.monotonic()
 if st.last_success_monotonic is not None and (now - st.last_success_monotonic) < self._min_interval:
 return

高 QPS 访问同一个沙箱时，续约 API 调用会非常频繁。续约本身幂等所以不出错，纯属浪费。

没有分布式锁。OSEP 设计了 opensandbox:renew:lock:{sandbox_id}，实现只有进程内 asyncio.Lock。多副本部署 proxy 模式会重复续约——反正 max() 单调不减，影响有限；ingress 模式靠 BRPOP 竞争天然去重。
best-effort 语义。intent 无 ack，消费后进程崩了就丢；超过 INTENT_MAX_AGE_SECONDS=300 的 intent 直接丢弃；ingress 发布队列满（容量 8192）直接 drop。自动续约是"尽力而为"，不能当强保证用。
Redis 不可用静默降级。连接失败降级为 proxy-only 模式，只打日志。ingress 场景下自动续约整个失效，但没有任何告警指标——沙箱会悄悄开始过期。
内存上限。proxy 路径每沙箱状态的 LRU 上限是 PROXY_RENEW_MAX_TRACKED_SANDBOXES = 8192（renew_intent/constants.py），超了驱逐（持锁的除外）。规模再大就要靠 Redis 模式了。

还有一个最容易被忽略的：SDK 默认不走 proxy。Python SDK 的 ConnectionConfig.use_server_proxy 默认 False，工具调用（exec/文件操作）直连沙箱 IP:44772 的 execd 端口——这条路径 server 根本观测不到流量，自动续约完全不生效。业务想要"活跃即续命"，必须显式走 proxy 或 ingress。

自动续约有个隐含的哲学转变：TTL 从"调用方声明的租期"变成了"最后一次访问之后的空闲超时"。这更像 HTTP session 而不是传统 lease。但 best-effort 的投递语义意味着它只能做兜底，关键业务还是应该显式管理租约。

伪永久（manual cleanup）： lease 的另一个极端

创建时不传 timeout，expiresAt 就是 None，schema 里的原文是：“When omitted or null, the sandbox will not auto-terminate and must be deleted explicitly”——不自动终止，必须显式删除。

实现上就是打一个 label / 不设字段，然后让所有过期逻辑绕行：

1
2
3
4
5
6
7
8


# server/opensandbox_server/services/k8s/create_helpers.py
expires_at = None
if request.timeout is not None:
 expires_at = calculate_expiration_or_raise(created_at, request.timeout)

labels: Dict[str, str] = {SANDBOX_ID_LABEL: sandbox_id}
if expires_at is None:
 labels[SANDBOX_MANUAL_CLEANUP_LABEL] = "true" # ← 唯一的区别就是一个 label

K8s 侧 spec.expireTime 不设置，控制器的 expire 分支直接跳过；Docker 侧过期扫描器看到 manual-cleanup=true 就 restore 后 continue（前面启动恢复那段代码里已经有了）。清理完全靠上层业务在会话结束时调 DELETE /sandboxes/{id}。

这个模式是为池化场景准备的：TTL 到期误杀正在使用的会话，比多养几个空闲沙箱的代价大得多。但它把回收责任完全推给了调用方，边界条件都得自己兜：

上层忘删 = 永久泄漏。伪永久沙箱没有任何服务端兜底回收，必须业务侧自建清理（比如定期扫描 expiresAt == null 且长时间无访问的沙箱）。而 SDK 自带的 releaseAllIdle 是严格串行的，实测 500 个空闲沙箱要 ~480 秒（上游 issue #1472），批量清理根本指望不上，得自实现并发 kill。
单向门。创建时没传 timeout，事后不能通过 renew-expiration 补上（409）。伪永久是一个创建时就必须做的决定。
Pool 模式下"删除"本身有坑。这是风险清单里最扎心的部分：#954（分配到的 Pod 被外部删除后 alloc-status 注解残留，supplement 恒为 0，沙箱永久不可用）、#1433（poolRef 可变更导致 in-use Pod 被当孤儿回收 + 新池永不分配）、#1423（Pool 控制器六重缺陷复合成自维持的 Pod 创建/删除风暴，实测约一半创建请求失败）。这三个 issue 截至核对都没有修复 PR。
“挂了自动拉起"不存在。上游明确 resume 只恢复有意的 Paused 状态，Terminated/Failed 不自动重启（#1127/#1328，SDK resume 报 409）。重建 = 新 sandbox ID + 内存和未持久化状态全丢。所以伪永久不是"永久可用”，只是"不会因为 TTL 被服务端杀掉"。

伪永久 + 上层主动删除，本质上是把 lease 的责任从服务端转移到了业务侧。服务端甩掉了误杀风险，但换来的是"业务必须自己靠谱"的前提。如果业务侧的清理兜底写得不靠谱，孤儿沙箱问题会以更隐蔽的方式回来——TTL 模式至少有个确定性的最后期限。

config/env 注入链：一句话版

生命周期之外，把配置注入链也简单记一笔（详细展开值得单独一篇）。核心结论：server 侧固定注入的 env 只有一个——K8s 运行时的 EXECD=/opt/opensandbox/execd（services/k8s/provider_common.py 的 _build_main_container），其余全是 API 请求 env 字段透传。sandbox_id 不走 env，走 label opensandbox.io/id；egress/secure-access 的 token 走 annotation。

有一个和生命周期直接相关的注入条件要注意：创建请求里的 env 和 entrypoint 是通过 taskTemplate 生效的，触发条件是 env 非空或 entrypoint 非默认值，都没传就走快路径——env 注不进去。所以"创建时注入用户 token"这类操作必须确认 taskTemplate 真的被触发了，否则沙箱起来了但没有你要的变量，而且不会报错。

egress 是个例外支线：OPENSANDBOX_EGRESS_* 前缀的 key 会被 split_egress_env 拆出来进 sidecar，不在白名单（ALLOWED_EGRESS_ENV_VARS）直接 ValueError，创建失败——这是少数"配置错误会在创建时 fail-loud"的地方。

边界条件自查清单

把这次走读里值得在集成前确认的边界收拢一下：

边界	行为	出处
timeout 传 0 / 负数	创建 400（最小 60）	`validators.py`
timeout 超服务端上限	创建 400	`ensure_timeout_within_limit`
续约时间早于现在	400	`ensure_future_expiration`
续约时间早于当前 expiresAt	spec 禁止（只能延长）	`sandbox-lifecycle.yml`
伪永久沙箱调续约	409	`docker_service.py:1199`
自动续约对伪永久沙箱	静默跳过（门控 return False）	`controller.py:69`
server 未开 renew_intent.enabled	opt-in 照常创建、proxy 照常转发，但续约零次（开关默认 False）	`config.py` / `proxy_renew.py:38`
lease 状态 label 丢失	拒绝续约（409），但过期调度也可能 skip+warning	`docker_service.py` restore 逻辑
Pod 被外部删除（Pool）	沙箱永久不可用，无自愈	#954
TTL 过期自动删除（K8s）	PVC ownerReferences 可能缺失导致泄漏	#1199
server 长期运行	httpx 连接池疑似泄漏，约 1 周耗尽	#1386

最后一条单独说：#1386 不是沙箱的问题，是 server 自己的。续约、状态查询全走 server，server 挂了所有沙箱的 lease 管理瘫痪——Docker 模式下 timer 停摆但容器还在跑，K8s 模式下 reconcile 停摆 expireTime 形同虚设。server 本身是这个 lease 系统的单点，生产部署要按"它会挂"来设计：监控 httpx 连接池、周期性重启、 lease 到期查询别全压在一个实例上。

走读完整体判断：OpenSandbox 的 lease 设计在"单机/中小规模"上是完整的——绝对时间戳、续约单调性、重启恢复、竞态放弃删除，该有的细节都有。但规模化风险集中在 K8s Pool 一侧（#954/#1433/#1423 三个无 PR 的 P0），伪永久模式的回收责任又全压给业务方。如果要上生产，我会选 TTL + 自动续约组合而不是伪永久：让服务端兜底最后期限，业务侧只负责"保活"，这比"保活 + 回收"两个责任都自担要安全。

下一篇预告：沙箱池化设计——Pool CRD、alloc-status 注解协议、预热与分配路径，以及为什么池化模式在当前上游版本要先踩一遍 #1423 的坑再决定开不开。

OpenSandbox 源码走读（一）：CRD Controller 与 Reconcile 循环

Sun, 06 Sep 2026 20:10:26 +0800

OpenSandbox 源码走读（一）：CRD Controller 与 Reconcile 循环

最近在看 OpenSandbox（阿里的沙箱开源项目）的控制面实现。它把"沙箱"建模成 K8s CRD，用一个 controller-runtime 算子驱动整个生命周期。这篇是我对自己 fork 里 kubernetes/ 目录的走读笔记：从 POST /sandboxes 的参数怎么落进 BatchSandbox spec，到 Reconcile 每一步在干什么，再到失败之后靠什么重试。代码都来自本地 clone（controller-runtime v0.21.0）。

全景：三个 CRD，两条回路

算子一共定义了 3 个 CRD（API 组 sandbox.opensandbox.io/v1alpha1），对应 3 个 Reconciler：

CRD	Reconciler	并发默认	干什么
BatchSandbox（`bsbx`）	BatchSandboxReconciler	32	沙箱本体：建 Pod、跑任务、pause/resume
Pool	PoolReconciler	16	预热 Pod 池：分配/回收/滚动更新/驱逐
SandboxSnapshot（`sbxsnap`）	SandboxSnapshotReconciler	1	rootfs 快照提交（pause/resume 的底层依赖）

整个控制面就两条互相咬合的回路：

1
2
3
4


任务回路：BatchSandbox reconcile → TaskScheduler → HTTP 推任务到 pod 内 task-executor(:5758)
 → 轮询任务状态 → 写回 status
分配回路：Pool reconcile → Allocator → 写 alloc-status 注解 + 内存 store
 → 注解变化经 watch 触发对方 reconcile → 闭环

注意第二条回路的关键设计：分配状态的持久化真相源是 BatchSandbox 上的注解，不是 Pool 的 status。Pool 的内存 store 只是个可重建的缓存。这个设计后面还会反复出现——很多"奇怪"的代码都是在为注解契约服务。

create 请求怎么变成 BatchSandbox

业务侧调 POST /sandboxes，server（Python）把它翻译成一个 BatchSandbox CR。池化模式的核心在 server/opensandbox_server/services/k8s/batchsandbox_provider.py 的 _create_workload_from_pool：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


def _create_workload_from_pool(self, batchsandbox_name, namespace, labels, pool_ref, expires_at, entrypoint, env, ...):
 entrypoint = entrypoint or DEFAULT_ENTRYPOINT
 spec = {
 "replicas": 1,
 "poolRef": pool_ref, # ← 池化模式的开关，指向预热池
 }
 if env or entrypoint != DEFAULT_ENTRYPOINT or self.execd_run_as_init: # needs_task_template
 spec["taskTemplate"] = self._build_task_template(entrypoint, env, batchsandbox_name)
 if expires_at is not None:
 spec["expireTime"] = expires_at.isoformat() # ← timeout 参数的归宿
 # 再包一层 apiVersion/kind/metadata，create_custom_object 直接落一个 BatchSandbox CR

几个 create 参数的映射关系值得记一下：

API 参数	落到 CR 的哪里	备注
`extensions.poolRef`	`spec.poolRef`	特殊值 `*` = 让控制器自动选池
`env` / `entrypoint`	`spec.taskTemplate`	非空即触发 taskTemplate 生成
`timeout`	`spec.expireTime`	不传 = 不自动到期，靠手动 delete
`metadata`	`metadata.labels`	用于 `GET /sandboxes?metadata=...` 过滤
`image` / `resourceLimits`	被忽略	池化 pod 预创建，模板锁死在 Pool 上

env 这条最有意思：server 会把 env 包进一个 shell 包装命令（_build_task_template 里 shlex.quote 转义后拼进 /bin/sh -c "/opt/opensandbox/bootstrap.sh <entrypoint> &"），再把 OPENSANDBOX_ID 追加进 env 列表，最终挂到 taskTemplate.spec.process。

这里有个容易踩的坑：不传 env 也不传 entrypoint 时走"快路径"，不生成 taskTemplate——池 pod 继续跑自己的 warm entrypoint，代价是任何分配时的 env 都注入不进去。所以"为什么我的环境变量没生效"十有八九是这个分支判断没过。

最终生成的 CR 大概长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


kind: BatchSandbox # apiVersion: sandbox.opensandbox.io/v1alpha1
spec:
 replicas: 1
 poolRef: my-pool  # 二选一：poolRef（池化）或 template（直建）
 taskTemplate: # 可选；决定要不要走任务调度
 spec:
 process:
 command: ["/bin/sh", "-c", "/opt/opensandbox/bootstrap.sh python /app/main.py &"]
 env: [{name: OSB_USER_ID, value: user-12345}]
 expireTime: "2026-09-06T12:00:00Z" # timeout 的归宿

注意 spec 里 template 和 poolRef 互斥：直建模式自己带 PodTemplateSpec，池化模式只有 poolRef，Pod 的长相完全由 Pool 的模板决定。server 还会把一批参数（volumes、networkPolicy、snapshotId+poolRef 组合等）直接 400 拒掉，因为池化 pod 是预创建的，事后没法改。

BatchSandbox 的 spec/status 长什么样

apis/sandbox/v1alpha1/batchsandbox_types.go，关键字段摘出来：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


type BatchSandboxSpec struct {
 Replicas *int32 // 默认 1
 PoolRef string // 与 Template 互斥
 Template *corev1.PodTemplateSpec
 ShardPatches []runtime.RawExtension // 按 index 给每个 pod 打 strategic merge patch
 ExpireTime *metav1.Time // 到了就删，控制器负责执行
 TaskTemplate *TaskTemplateSpec // 非 nil = 需要 TaskScheduler
 Pause *bool // pause/resume 意图，Server 写、Controller 执行
}

// +kubebuilder:validation:Enum=Pending;Succeed;Pausing;Paused;Resuming;Failed
type BatchSandboxPhase string

phase 一共 6 个：Pending / Succeed 是稳态，Pausing / Paused / Resuming 是暂停链路，Failed 是终态。status 侧除了 replicas/ready 计数，还有一组任务计数和两个特殊字段：

1
2
3
4
5
6
7
8


type BatchSandboxStatus struct {
 ObservedGeneration int64
 Replicas, Allocated, Ready int32
 TaskRunning, TaskSucceed, TaskFailed, TaskPending, TaskUnknown int32
 Phase BatchSandboxPhase
 PauseObservedGeneration int64 // pause/resume 幂等闸门：最近一次 ACK 的 generation
 Conditions []BatchSandboxCondition // Ready/Progressing/Paused/PauseFailed/ResumeFailed/PodFailed
}

PauseObservedGeneration 这个设计我第一次看有点绕：spec.pause 只是个布尔意图，Controller 靠"generation 是否前进 + 我 ACK 到哪个 generation 了"来判断这是不是一次新请求。这是把 K8s 原生的 observedGeneration 惯例复用到了 pause/resume 这条命令通道上，避免了额外的 ACK 子资源。

Reconcile 主循环：一轮到底干了什么

核心在 internal/controller/batchsandbox_controller.go 的 Reconcile，按执行顺序拆开：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


func (r *BatchSandboxReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
 batchSbx := &sandboxv1alpha1.BatchSandbox{}
 if err := r.Get(ctx, client.ObjectKey{...}, batchSbx); err != nil {
 if errors.IsNotFound(err) {
 return ctrl.Result{}, nil // 对象没了，不用管
 }
 return ctrl.Result{}, err // 其他错误 → 交给退避重试
 }

 // 1. ExpireTime：过期就删，没过期把剩余时间记进 requeue 计划
 if expireAt := batchSbx.Spec.ExpireTime; expireAt != nil {
 if expireAt.Time.Before(now) && batchSbx.DeletionTimestamp == nil {
 r.Delete(ctx, batchSbx)
 } else if !expireAt.Time.Before(now) {
 DurationStore.Push(key, expireAt.Time.Sub(now))
 }
 }

 // 2. poolRef="*"：自动选池，List 全 namespace 的 Pool 挑一个 patch 回 spec.poolRef
 if updated, err := r.assignPool(ctx, batchSbx, profileName); updated {
 return ctrl.Result{}, nil // ← spec 变了，generation 前进，等下一轮
 }

 // 3. finalizer：有 taskTemplate 才挂 task-cleanup，防删除时残留任务
 // 4. pause/resume 分发：优先级最高的命令通道
 if result, handled, err := r.dispatchPauseResume(ctx, batchSbx); handled {
 return result, err
 }

 // 5. 列出 pod（两种模式实现完全不同，见下）
 pods, err := r.listPods(ctx, poolStrategy, batchSbx)
 // 池化模式下分配的 pod 消失了 → failClosedOnMissingAllocatedPods：fail-closed 标 Failed

 // 6. 扩容（池化和 Paused 状态跳过；只有扩没有缩）
 if !poolStrategy.IsPooledMode() && batchSbx.Status.Phase != Paused {
 r.scaleBatchSandbox(ctx, batchSbx, batchSbx.Spec.Template, pods)
 }

 // 7. 从 pod 现状推 phase
 runtimeView := buildRuntimeView(batchSbx, pods)

 // 8. 任务调度（taskTemplate != nil 才进），结果写进 status 任务计数
 if taskStrategy.NeedTaskScheduling() && batchSbx.Status.Phase != Paused {
 ts, err := r.reconcileTasks(ctx, batchSbx, pods)
 ...
 }

 // 9. 落盘：endpoints/runtime-id 注解 + status patch
 requeue, persistErrors := r.persistRuntimeView(ctx, batchSbx, runtimeView)

 // 10. requeue：多来源取最短（Pop 返回各处 Push 的最短值，再与 persist 阶段合并）
 requeueAfter := DurationStore.Pop(req.String())
 return reconcile.Result{RequeueAfter: requeueAfter}, gerrors.Join(aggErrors...)
}

第 6 步的 guard 值得细品：池化模式直接跳过 scale——池化 sandbox 没有 template，pod 的生死由 Pool 的分配/回收决定，控制器自己建删只会打架。Paused 跳过是因为暂停后的沙箱 pod 应该保持不存在，等 resume 重写镜像再拉起来。

listPods 在两种模式下的实现完全不同：直建模式按 ownerRefUID 的 field index 一次 List 拿齐；池化模式先解析 alloc-status 和 alloc-released 两个注解做差集，再对剩下的 pod 逐个 Get——代码里就带着 // TODO maybe performance is problem 的原话注释。池化 sandbox 的 replicas 一大，这每轮 R 次深拷贝 Get 的成本就线性往上叠。

状态机：phase 不是存的，是算的

走读里印象最深的设计：phase 没有独立的状态存储，每轮 reconcile 都从 pod 现状重新推导（batchsandbox_status.go 的 buildRuntimeView）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


func buildRuntimeView(batchSbx, pods) runtimeView {
 newStatus := batchSbx.Status.DeepCopy()
 for _, pod := range pods {
 newStatus.Replicas++
 if utils.IsAssigned(pod) {
 newStatus.Allocated++ // 池化模式下"分配了"的 pod
 }
 if podReady(pod) {
 newStatus.Ready++ // Running + Ready 且未在删除
 }
 }
 switch batchSbx.Status.Phase {
 case Pausing, Paused:
 // 生命周期稳态，不动
 case Resuming:
 applyResumingRuntimePhase(newStatus, pods)
 default:
 applySteadyRuntimePhase(batchSbx, newStatus, pods)
 }
}

func applySteadyRuntimePhase(...) {
 if summary, hasFailures := summarizePodFailures(pods); hasFailures {
 // CrashLoopBackOff / ImagePullBackOff / ErrImagePull / CreateContainerConfigError → Failed
 status.Phase = sandboxv1alpha1.BatchSandboxPhaseFailed
 return
 }
 if status.Ready > 0 {
 status.Phase = sandboxv1alpha1.BatchSandboxPhaseSucceed
 return
 }
 status.Phase = sandboxv1alpha1.BatchSandboxPhasePending
}

状态流转画出来：

stateDiagram-v2
[*] --> Pending: 创建
Pending --> Succeed: ready > 0
Pending --> Failed: pod 进入 BackOff 类状态
Succeed --> Failed: pod 故障
Succeed --> Pausing: spec.pause=true 且 generation 前进
Pausing --> Paused: 内部 Snapshot Succeed，删 Pod、去 finalizer
Pausing --> Failed: Snapshot Failed 且 Pod 丢失
Paused --> Resuming: spec.pause=false 且 generation 前进
Resuming --> Succeed: 快照镜像重建的 pod ready
Resuming --> Failed: resume pod 失败

“状态是推导出来的而不是记录下来的”，这是 K8s 控制器的正统做法（level-triggered），好处是任何状态丢失都能自愈。代价是 Failed 这种"终态"必须靠条件分支保护——代码里到处是 if phase != Failed 的短路判断，不然一个 ready pod 的短暂波动就会把 Failed 翻回去。另外 PauseFailed/ResumeFailed 两个 condition 由 mergeLifecycleConditions 单独保护，不被运行时推导覆盖。

扩容：确定性命名 + 期望机制防重复

scaleBatchSandbox 是直建模式下 pod 的唯一出生点，两个细节都值得学：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


func (r *BatchSandboxReconciler) scaleBatchSandbox(ctx, batchSandbox, podTemplateSpec, pods) error {
 // 1. 对现有 pod 做 ObserveScale，然后查期望是否满足
 if satisfied, unsatisfiedDuration, _ := BatchSandboxScaleExpectations.SatisfiedExpectations(key); !satisfied {
 // 上一轮的 Create 还没被 informer 观察到 → 跳过本轮扩容，防重复建 pod
 DurationStore.Push(key, expectations.ExpectationTimeout-unsatisfiedDuration)
 return nil
 }
 // 2. 算缺哪些 index
 var needCreateIndex []int
 // TODO var needDeleteIndex []int ← 缩容压根没实现，只留了个空注释
 for i := 0; i < int(*batchSandbox.Spec.Replicas); i++ {
 if _, ok := indexedPodMap[i]; !ok {
 needCreateIndex = append(needCreateIndex, i)
 }
 }
 for _, idx := range needCreateIndex {
 pod, _ := utils.GetPodFromTemplate(podTemplateSpec, batchSandbox, controllerRef)
 // 3. 按 index 打 shard patch（每个副本可以不一样）
 podBytes, _ := json.Marshal(pod)
 modifiedPodBytes, _ := strategicpatch.StrategicMergePatch(podBytes, batchSandbox.Spec.ShardPatches[idx].Raw, &corev1.Pod{})
 pod.Name = fmt.Sprintf("%s-%d", batchSandbox.Name, idx) // 4. 确定性命名，天然幂等
 BatchSandboxScaleExpectations.ExpectScale(key, expectations.Create, pod.Name)
 r.Create(ctx, pod) // 失败则 ObserveScale 回滚期望 + 记 Warning Event
 }
}

确定性命名 + ScaleExpectations 是一对组合拳：名字确定让"建了又看不见"（informer 滞后）不会变成重复创建，期望机制让这个等待变得显式。但缩容那句 TODO var needDeleteIndex []int 很扎眼——spec.replicas 调小不会删任何 pod，这可是 ReplicaSet 十年前的基本功。想缩副本只能删整个 sandbox，或者走 Pool 模式。

与 K8s 原生机制的耦合点

这个控制器重度依赖 K8s 原生设施，汇总成一张表：

机制	用法
ownerReference + Owns	Pod/Snapshot 挂 BatchSandbox 为 owner，`Owns(Pod)` watch 级联
Finalizer	`task-cleanup`（停任务）/ `pool-allocation`（等 pod 归还池）/ `cleanup`（清 commit Job）
Annotation	alloc-status / alloc-release / alloc-released / endpoints / runtime-id，五条内部契约
Generation	spec 变更自增，配合 observedGeneration / pauseObservedGeneration 做幂等
Subresource status	`Status().Patch` 单独写状态，与 spec 写路径隔离

注解契约里最容易混淆的是池化三件套，语义上有时序：

1
2
3


alloc-status (Pool 写)："这些 pod 分给这个 sandbox 了" —— 已生效
alloc-release (BatchSandbox 写)："我请求释放这些 pod" —— 释放请求
alloc-released (Pool 写)："确认已回收" —— 释放完成

releasePods 的实现就是把释放请求 MergePatch 到 BatchSandbox 的 alloc-release 注解上（batchsandbox_controller.go），然后靠 Pool 侧的 watch 谓词感知这次变化。Pool 侧的 watch 装配（pool_controller.go 的 SetupWithManager）：

1
2
3
4
5
6
7
8


return ctrl.NewControllerManagedBy(mgr).
 For(&sandboxv1alpha1.Pool{}, builder.WithPredicates(predicate.GenerationChangedPredicate{})).
 Owns(&corev1.Pod{}). // ← 无谓词，任何 pod 事件都全量 reconcile
 Watches(&sandboxv1alpha1.BatchSandbox{}, handler.EnqueueRequestsFromMapFunc(findPoolForBatchSandbox),
 builder.WithPredicates(filterBatchSandbox)). // 只放行 release 注解变化/replicas 变化/进入删除
 Watches(&sandboxv1alpha1.BatchSandbox{}, enqueueOldPoolForDetachedBatchSandbox,
 builder.WithPredicates(filterBatchSandboxDetached)). // poolRef 非空→空：通知旧池重新平衡
 Complete(r)

这个谓词设计其实很精细：普通 alloc-status 变化不会惊动 Pool（不然分配回路就是死循环），只有 release/replicas/删除这三类"需要 Pool 动手"的信号才入队。对比之下 For(BatchSandbox) 连谓词都没有——status 更新会自己触发自己的 reconcile，每笔状态变更约等于两次 reconcile。一边抠得极细，一边完全裸奔，观感有点割裂。

失败怎么重试：三层 requeue 机制

控制器里的重试其实分三层。第一层：返回 error，走 controller-runtime 默认指数退避。 任何 return ctrl.Result{}, err 都进 workqueue 的 rate limiter。最省事但也最不可控——网络抖动和业务逻辑失败在这里没有区别。

第二层：RequeueAfter 定时轮询，多来源取最短。 这是最重的一层，配套了一个小工具 DurationStore：

1
2
3
4
5
6


// internal/utils/requeueduration —— 多个来源都往里 Push，取最短值
func (rd *Duration) Update(newDuration time.Duration) {
 if newDuration > 0 && (rd.duration <= 0 || newDuration < rd.duration) {
 rd.duration = newDuration
 }
}

其中 3s 任务轮询是这个设计的命门：

1
2
3
4
5
6


func (r *BatchSandboxReconciler) reconcileTasks(...) (*taskScheduleResult, error) {
 ...
 // Because tasks are in-memory and there is no event mechanism, periodic reconciliation is required.
 DurationStore.Push(key, 3*time.Second) // ← 注释写得明明白白：没事件机制，只能轮询
 ...
}

第三层：RetryOnConflict，只管写冲突。 Pool 控制器把整个 reconcilePool 包在 retry.RetryOnConflict(retry.DefaultBackoff, ...) 里，冲突就整段重跑。

三层里最要命的是第二层的两个特性叠加：任务型 sandbox 不管有没有变化每 3s 必 reconcile 一次，而 RequeueAfter 走 AddAfter 直接入队，完全绕过 rate limiter（默认指数退避只保护返回 error 的路径）。1000 个任务型 sandbox 就是稳态 333 次 reconcile/s，退避机制对它一筹莫展。任务状态纯内存、task-executor 又没有状态上报事件，这个 3s 是代码注释里自己承认的无奈之举。pause/resume 期间还有一堆 1s 轮询在推进中间态，控制器一过载这些中间态就会集体变慢——轮询式状态机的通病。

整体看下来，这个控制器的骨架是很标准的 controller-runtime 姿势，状态推导、finalizer、期望机制都用得中规中矩；真正让我犹豫的是它把注解当 IPC 用（五个注解键、JSON 整表覆盖式写入、跨控制器 watch 级联）和 3s 无条件轮询这两个选择——单机 demo 没问题，规模上去之后这两处就是最先崩的地方。下一篇拆 Pool 的分配/回收/滚动更新，那里能看到注解契约的完整写路径。（下一篇：Lease 与生命周期）