作者花椒直播基础架构部负责人·王成龙花椒直播CTO·封冰清编者按 大部分团队接入 Agent 沙箱时思考顺序是我们需要隔离所以上沙箱。花椒团队的顺序是先把 Agent 平台设计成一层可配置的执行环境抽象沙箱只是这个抽象层里的选项由每个 Agent 根据自己的隔离需求决定要不要用。这篇实践记录的是这套思考是如何落地的包括从组织级的隔离决策到贡献 Go SDK、定位并修复一个 host-mount 场景下的快照恢复 bug再到在 CubeSandbox 之上重新定义了一套终端协议。◆一、沙箱是执行环境的一个选项◆花椒直播是花房集团旗下的产品。我们企业 Agent 平台最早在花椒直播业务侧完成从 0 到 1 的落地验证后续基于这套沉淀的底层能力为花房集团中台搭建了一套独立部署的实例。◆ 花椒 Agent 主要服务花椒直播内部的设计、产品、技术、运营、客服、审核等部门应用中心目前上线了 25 个入口包括 DMG 业务助手、ChatBI、内容运营助手、设计助手、产品助手、H5 页面生成助手、客服部门助手、审核数据分析助手、经营数智平台和电销平台等此外还有一个独立的 C 端产品。◆ 花房 Agent 服务花房集团中台已经在经济系统、数据、行政、法务、GR政府关系5 个部门落地包括 BI 数据助手、行政部助手、法务工作台和 GR 工作台等应用。两套部署基于同一套 Agent Runtime分别服务花椒直播的业务部门和花房集团的中台部门合计已经落地约 30 个不同的 Agent 应用。花椒的实践完成了平台和业务应用从 0 到 1 的验证花房的实践则进一步验证了同一套底层能力可以跨组织独立部署和复用。图1: 花椒 Agent 、花房Agent 平台截图搭建 Agent 平台时我们先确定了一条边界平台内部不放任何业务相关的代码。所有 Agent 的能力都通过后台配置生成。这样一套架构可以完全复用给任意场景的 Agent而不用适配每个新业务而重新开发、重新“造轮子”。这就好比Agent 平台相当于操作系统而Agent 则是跑在操作系统上的应用Skills 相当于各类开发框架和 SDK。这套架构中最关键的一层抽象叫执行环境——大模型要执行命令时具体在哪执行就是执行环境要回答的问题。一个 Agent 可以配置一个或多个执行环境也支持个人私有执行环境的动态注册和移除。执行环境的操作系统可以是 Windows、Linux 或 macOS部署形态可以是裸金属、普通云服务器也可以是 Kubernetes。每种执行环境都会启动一个守护进程负责和 Agent 平台通信。CubeSandbox 是我们接进执行环境服务的一种沙盒方案目前暂时只部署在普通云服务器上后续还会扩展到K8s场景。但不管执行环境本身是什么性质都可以在其上选择用沙盒。什么场景才要上沙箱我们没有定统一规则而是按 Agent 的定位来判断。判断的核心只有一个这台执行环境上的资源需不需要在多个用户之间物理隔离。如果 Agent 管理的是一台专属机器工作内容只有单一主体在消费用不用沙箱没有区别同一台执行环境一旦要服务多个用户每个人的工作状态必须彼此独立我们一般就会选择沙箱。换句话说隔离决策不在平台层统一而是随 Agent 的定位落到具体执行环境上。在 Agent 之间我们按资源要不要物理隔开的标准决定要不要用沙箱在组织之间我们把同一个标准用在了更高的层级例如花椒 Agent 和花房 Agent 采用了两套完全独立的实例部署平台服务、账号权限、业务数据、应用资产、执行环境和 CubeSandbox 实例分别管理不共享控制面。因为我们现阶段更看重不同组织之间清晰、可审计的安全边界这个优先级高于共享控制面能带来的资源复用效率。◆二、Cube Sandbox的选型与落地◆选型之前我们用的是最原始的方案单服务器目录隔离。其间遇到了一系列问题缺乏隔离能力用户 A 理论上可以通过 Agent 操作到用户 B 的文件。我们评估过其他几类方案逐一被否Docker 启动慢、隔离不彻底、性能低传统虚拟机成本高资源分配也不灵活。MicroVM级的方案层面我们调研、测试对比了启动速度后发现 CubeSandbox 最快特性和性能也符合预期尤其是强隔离这一条经过实验确认能满足需求就应用了下来。选型确定之后遇到的第一个实际问题是用户数据放在哪。沙盒本身是可回收的但用户的工作状态必须跨沙盒保留下来。我们最初的做法是挂载外部磁盘用户数据需要持久化不能因为云服务器故障就丢失所以放在一块数据盘上而不是系统盘。后来考虑高可用性我们发现普通数据盘做不到同时挂载到多台云服务器于是升级成 NFS 方案——用户的持久化数据全部写到 NFS 目录云服务器故障时立即启动新机器挂载同一个 NFS 继续服务损失的只是运行中的进程。这套方案接进 CubeSandbox 靠的是 host-mount 机制部署在云服务器上的执行环境守护进程把不同目录映射到沙盒内部沙盒内部无法做权限逃逸守护进程只关注最小粒度的会话一个会话对应一个沙盒。落地过程中我们遇到的不只是怎么把 CubeSandbox 用起来的应用层问题还有几次必须直接动 CubeSandbox 本身代码的情况。我们从 CubeSandbox 第一个发布版本起就在用当时官方还没有 Go SDK我们自己写了一版对齐 Python SDK 的能力提交到了官方仓库PR #254 Add Go SDK一次性提交生命周期管理、命令执行、文件读取、proxy transport 等完整能力共 15 个文件、新增 3288 行代码。合并当天官方代码审查发现Sandbox.Close()会意外关闭多个沙箱共享的 HTTP 连接池我们随即提交PR #322修复。另一次更深的问题出现在休眠唤醒场景。挂载了磁盘的沙盒在休眠和唤醒时存在 bug我们定位到根因是CubeSandbox 给 host-mount 场景打快照时没有为 virtio-fs 准备好迁移所需的元数据根 inode 因此丢失了迁移状态恢复时报错 InvalidVirtioFsState。我们随后又提交了PR #341和PR #354进行修复和后续加固但PR #354测试之后自己关掉了原因是测完之后不确定这个改动是否完美。我们目前的做法是直接销毁沙盒再重建绕开还没解决的部分。图2: 花房集团Agent 平台管理界面目前CubeSandbox 已经在我们生产环境运行了 3 个多月。支撑了花椒和花房两个实例的大约 30 个 Agent 应用日均 token 消耗约 8300 万。◆三、agentd在 CubeSandbox 之上重新定义一套终端协议◆为了丰富对外提供的能力的需求我们在Cube Sandbox之上加了一层自研的终端协议——agentd用来和 Agent 平台的执行环境服务对接与 Cube 模版里自带的envd 并存分工。它在制作沙盒模版时会默认启动。3.1 agentd的定位与自研背景envd 本身不缺执行命令、文件读写或 PTY 这些基础能力CubeSandbox 官方文档把它定义为 Sandbox 的原生数据面模板探针、初始化以及 SDK 的command/fileAPI 都依赖它命令、文件、文件系统和 PTY 相关的请求都路由到 envd 的 49983 端口。但我们研发的agentd不是对envd的简单补缺而是平台为exec_command/ write_stdin 定义并掌握语义的专用终端会话数据面。之所以开发agentd原因有三层第一我们需要一套自己定义、能够长期独立演进的终端协议而不是把 runtime 的会话模型直接绑定在 Cube 或 E2B 的外部 API 语义上第二我们需要一个能直接验证挂载后的技能和工件是否真的在 Sandbox 内可见的接口StatFiles并且需要一套自己可控的 bearer-token 认证边界第三早期实现时我们遇到过一个具体的缺陷——Cube API 没有把创建 Sandbox 时设置的环境变量传递到 CubeMaster导致我们原计划给每个 Sandbox 注入一个随机 AGENTD_TOKEN 的方案无法成立后来改成模板和 Worker 共享一个固定 token。更准确的说法是agentd 补的是我们自己需要的契约、可控性和故障语义不是在补 envd 缺失的通用执行能力。维度envdagentd端口4998349984所属CubeSandbox 原生组件本仓库模板内的服务Cube 模板/初始化必需不承担Cube 原生 SDK 命令/文件 API使用不使用本平台 exec_command / write_stdin当前不走它当前唯一执行数据面生命周期操作不负责不负责Sandbox 创建/暂停/恢复/销毁Cube API / Cube SDK 负责二者都不是该层同左3.2 agentd 的运行机制作为模板主命令启动PID 为 1监听 0.0.0.0:49984它提供的是一组很窄的 HTTP API◆ GET/healthz存活、版本、活跃会话数◆ POST /v1/sessions启动 shell 命令◆ GET /v1/sessions/{id}从指定 chunk 游标开始长轮询输出◆ POST/v1/sessions/{id}/stdin写标准输入◆ POST/v1/sessions/{id}/resize调整 PTY◆ DELETE /v1/sessions/{id}关闭会话◆ 文件读取、批量 stat、从 URL 拉取并写入文件。3.3 一次命令执行的关键路径◆ 外层 Worker 根据 thread 找到或创建专属的 Sandbox准备好 workspace、上传文件、技能和持久目录挂载◆ Worker 通过 CubeProxy 拼出 http(s)://49984-sandbox-id.domain 这个地址访问 agentd而不是调用 Cube SDK 原生的 command API◆ agentd 为这次执行创建独立进程组TTY 命令走 PTY非 TTY 命令分别捕获 stdout 和 stderr输出写进一个带单调chunk_id、有容量上限的内存 ring buffer外层 Worker 用游标轮询增量不会重复上报同一段输出◆ 短命令直接返回终态长命令返回session_idWorker 把它映射成我们自己的write_stdin会话在后台持续轮询、上报输出和退出结果◆timeout_ms会取消进程会话结束后保留短暂 TTL 再回收只有 CubeSandbox 断连或 agentd 持续不健康时Worker 才会把这个会话判定为session_lost。这套机制真正解决的问题不是能不能跑 shell 命令而是把我们自己需要的一整套终端语义固定下来——PTY、标准输入、chunk 游标、输出截断、明确的timeout/exit状态、会话丢失判定以及这些状态和平台自身持久化任务状态之间的一致映射。图3: CubeSandbox路径中agentd的运行方式envd 和 agentd 目前是并存分工的关系envd 跑在 49983 端口是 CubeSandbox 的原生组件Cube 模板初始化必需Cube 原生 SDK 的命令和文件 API 走它agentd 跑在 49984 端口是我们模板里自带的服务不承担模板初始化也不使用 Cube 原生 SDK是我们当前唯一的执行数据面。两者都不负责沙盒的创建、暂停、恢复、销毁这类生命周期操作这部分始终由 Cube API 和 SDK 负责。部署脚本会把两个端口同时暴露写进模板状态envd_port49983、agentd_port49984。agentd 是模板里的主命令但这不等于它接管了 Cube 的基础设施职责——Cube 仍然需要原生的 envd 来完成模板就绪和初始化我们只是在一个已经创建、且网络可达的 Sandbox 上把自己的终端和文件协议直接代理到 agentd 上。用我们自己的话来说agentd 抹平的是执行环境类型——不管底层是 CubeSandbox 还是别的沙盒方案业务侧对接的都是同一套 agentd 协议不需要感知底下具体跑的是什么。◆四、一次资源认知的纠偏◆资源分配上我们走过一段完整的认知纠偏。最初对沙箱的理解不足以为资源是按实际用量动态分配的不知道还有预分配资源这层机制所以没有对沙箱做任何规格配置。内存不够之后云服务器先触发了监控告警我们紧急扩容了云服务器。当时没有细究这次内存不足具体是 OOM、卡死还是变慢先把问题压下去事后才回头看了一下 CubeSandbox 的默认配置发现这套默认值本身还算合理就没再调整。基于这次经历我们现在的资源规划分成了两层测试环境用一台小规格云服务器线上环境用一台中高规格服务器同时做了沙箱的闲置回收机制结合云服务器自身的监控告警去动态调整服务器规格。我们给其他在使用沙箱的团队一个参考建议是明确沙盒的定位把它当成一个高性能、强隔离的虚拟机去用而不要预设它会像某种弹性资源池那样按实际使用自动伸缩。◆写在最后◆回过头看这套实践里最值得记录的是我们的两层思考◆ 一层是执行环境是可配置的沙箱只是其中一个选项这层思考把隔离决策下放到了每个 Agent 自己身上◆ 另一层是CubeSandbox 提供的原生协议不必是我们唯一依赖的协议agentd 的存在证明了我们愿意在 CubeSandbox 的原生数据面之上再补一层自己完全掌控的终端语义。这两层思考共同指向同一个结论——沙箱是被我们反复验证、按需选用的一个组件不是被默认套用的标配。感谢花椒直播王成龙、封冰清老师对以上内容的贡献。Cube 实战笔记专栏介绍本系列旨在记录真实团队和项目在 Cube Sandbox 上的工程实践——架构选型、部署落地、踩坑复盘每一篇都来自一线上手经验。既有跑通的方案也有走过的弯路给正在评估和使用 Cube 的人一份可参照的路径。如果你也在 Cube 上实践、探索或有对于问题的解决方案欢迎投稿或与我们联系让经验被更多用户看见。
