Agent 沙箱接入生产实践：选型、持久化与执行协议踩坑指南

1. 从"能跑"到"敢上生产"：Agent 沙箱这道坎到底卡在哪

如果你正在做 AI Agent 相关的开发，大概率经历过这样一个阶段：本地写个 demo，让 Agent 调用几个工具、跑几段代码，效果挺惊艳，于是信心满满准备往生产环境推。结果一上生产就发现，事情完全不是那么回事——代码执行环境怎么隔离？执行到一半断了怎么办？多个用户同时跑会不会互相污染？一个恶意 prompt 注入让 Agent 执行了危险操作谁来兜底？

这些问题的核心，都指向同一个组件：Agent 沙箱。说白了，沙箱就是给 Agent 的代码执行能力套上一个"安全笼子"，让它能干活但闯不了祸。听起来简单，但真正接入生产时，选型、持久化、执行协议这三块，每一块都能让你掉一层皮。

我自己在做 Agent 平台的过程中，前后换过三套沙箱方案，踩过的坑从"容器逃逸风险"到"执行结果丢失"再到"协议不兼容导致工具调用超时"，基本把能踩的都踩了一遍。这篇就把花椒（我们内部对这套 Agent 执行框架的代号）在沙箱接入生产过程中的完整实践梳理出来，包括选型时对比了哪些方案、为什么最终选了 CubeSandbox 这条路、持久化怎么设计才不会丢状态、执行协议怎么定才能兼顾安全和效率。

内容适合两类人看：一是正在做 Agent 开发、准备把 demo 推向生产的工程师；二是负责 Agent 平台架构、需要做技术选型的技术负责人。如果你还在"本地跑通就行"的阶段，这篇也能帮你提前建立生产视角，少走弯路。

先说一个反直觉的结论：Agent 沙箱最难的不是隔离技术本身，而是"隔离"和"可用"之间的平衡。隔离做得太狠，Agent 执行效率暴跌、工具调用频繁超时；隔离做得太松，安全风险直接拉满。生产环境的沙箱方案，本质上是在这两者之间找那个动态平衡点。

2. 沙箱选型的四轮淘汰：为什么最后留下的是 CubeSandbox

2.1 第一轮：进程级隔离为什么直接被否

最开始我们想得很简单，Agent 执行代码嘛，起个 subprocess 加个超时限制不就完了？本地 demo 就是这么干的，跑得也挺好。但一上生产就发现问题了：进程级隔离根本没有文件系统隔离，Agent 执行的代码可以直接读写宿主机文件；也没有网络隔离，一段恶意代码就能扫描内网；更别说资源限制了，一个死循环就能把 CPU 吃满。

进程级隔离唯一能做的就是超时 kill，但 kill 之前造成的破坏已经发生了。这一轮淘汰得很干脆，生产环境的 Agent 沙箱，隔离级别至少要到容器级，这是底线。

2.2 第二轮：Docker 原生方案的三个致命伤

容器级隔离，第一反应肯定是 Docker。我们搭了一套基于 Docker 原生 API 的沙箱，每个 Agent 执行任务起一个容器，执行完销毁。跑了一段时间，三个问题暴露得很明显。

第一个是冷启动太慢。Docker 容器从创建到可执行，即使镜像已经拉好，平均也要 1-2 秒。Agent 场景下，一次对话可能触发多次代码执行，每次都等 1-2 秒，用户体验直接崩了。我们试过预热容器池，但池子大小很难定——小了不够用，大了资源浪费。

第二个是状态管理缺失。Docker 原生方案里，容器销毁后执行状态就没了。Agent 执行到一半需要人工确认、或者需要分步执行时，状态就丢了。我们试过把状态存到外部 Redis，但容器和状态之间的同步又成了新问题。

第三个是多租户隔离不彻底。Docker 默认的网络和文件系统隔离，在共享宿主机的情况下，仍然存在侧信道攻击的风险。对于面向多用户的 Agent 平台，这个风险不能接受。

2.3 第三轮：gVisor 和 Firecracker 的取舍

为了提升隔离级别，我们调研了 gVisor 和 Firecracker 两个方案。gVisor 通过用户态内核拦截系统调用，隔离性很好，但性能损耗明显，尤其是文件 IO 密集型的代码执行，性能下降 30% 以上。Firecracker 是轻量级虚拟机方案，启动快、隔离强，但它的设计初衷是 serverless 场景，对 Agent 这种需要频繁交互、状态保持的场景，适配成本很高。

这两个方案不是不好，而是和 Agent 场景的匹配度不够。Agent 沙箱的核心诉求是：启动快、状态可持久、协议可扩展、多租户安全。gVisor 和 Firecracker 各自解决了其中一部分，但都需要大量二次开发才能满足全部。

2.4 第四轮：CubeSandbox 为什么成了最终答案

CubeSandbox 是我们最终选定的方案。它本质上是一个面向 Agent 场景优化的沙箱运行时，核心特点有几个：毫秒级启动（基于预加载和快照恢复）、原生状态持久化接口（执行状态可以序列化到外部存储）、可扩展的执行协议（支持自定义工具调用协议）、多租户隔离（每个租户独立命名空间）。

选它的核心理由，不是它某一项能力最强，而是它在 Agent 场景的完整度最高。我们对比过一个表格，把四个方案在六个维度上打分：

提示：选型时不要只看单项指标。Agent 沙箱是一个系统工程，启动速度、隔离强度、状态管理、协议扩展这四者缺一不可。任何一项短板，都会在生产环境被放大。

这里补充一个实操心得：CubeSandbox 的毫秒级启动，靠的是快照预热机制。简单说，就是提前把沙箱环境初始化好，打一个快照，后续每次执行都从快照恢复，而不是从头创建。这个机制在配置时有个关键参数——快照池大小。我们一开始设了 10，结果高并发时不够用，后来根据峰值 QPS 动态调整到 50，才稳定下来。这个值怎么定？我的经验是：快照池大小 = 峰值并发数 × 1.5，留 50% 余量应对突发。

3. 持久化设计：Agent 执行状态到底该怎么存

3.1 为什么"执行完就销毁"在生产环境行不通

本地 demo 时，Agent 执行代码就是"执行-返回结果-销毁"，简单直接。但生产环境里，这个模式有三个场景直接失效。

第一个场景是长任务分步执行。Agent 执行一个数据分析任务，可能需要先跑数据清洗、再跑特征工程、最后跑模型训练，每一步之间需要保持环境状态。如果每步都销毁重建，中间产物就丢了。

第二个场景是人工介入确认。Agent 执行到敏感操作时，需要暂停等待人工确认。这个暂停可能持续几分钟甚至几小时，期间沙箱状态必须保持。

第三个场景是执行失败重试。Agent 执行失败后，需要从失败点重试，而不是从头再来。这要求失败前的状态可恢复。

这三个场景，本质上都要求沙箱具备状态持久化能力。CubeSandbox 原生提供了状态序列化接口，可以把沙箱的完整状态（文件系统、内存、执行上下文）序列化到外部存储，需要时再恢复。

3.2 状态序列化的粒度选择：全量还是增量

持久化设计第一个要决策的，是序列化粒度。全量序列化就是把整个沙箱状态打包存储，恢复时完整还原。增量序列化只存变化部分，恢复时基于基础快照叠加增量。

我们一开始用的是全量，简单可靠，但很快发现存储成本太高。一个中等复杂度的 Agent 执行环境，全量状态大概 200-500MB，高频执行场景下，存储很快就爆了。后来改成基础快照 + 增量的模式：基础快照是预热的干净环境，增量只记录执行过程中的文件变更和内存变更。

这个模式的关键在于增量合并策略。增量不能无限叠加，否则恢复时合并开销越来越大。我们的做法是：每 10 次增量后做一次全量合并，生成新的基础快照。这个阈值怎么定？取决于你的执行频率和存储成本容忍度。执行频率高、存储成本敏感，阈值可以设小一点；反之可以设大。

3.3 存储后端选型：Redis 还是对象存储

状态存哪里，是第二个决策点。我们对比了 Redis 和对象存储两个方案。

Redis 的优点是读写快、支持复杂数据结构，适合存储执行上下文这类需要频繁读写的小状态。缺点是内存成本高，大状态存不下。对象存储的优点是容量大、成本低，适合存储文件系统快照这类大状态。缺点是读写延迟高，不适合频繁访问。

最终我们采用的是分层存储：执行上下文（变量、调用栈、工具状态）存 Redis，文件系统快照存对象存储。恢复时，先从 Redis 加载上下文，再从对象存储加载文件系统，两者合并还原。

这里有个坑要提醒：Redis 持久化配置不当会导致状态丢失。我们早期用 Redis 存执行上下文，没开 AOF 持久化，结果一次 Redis 重启，所有进行中的 Agent 任务状态全丢了。后来改成 AOF + RDB 双持久化，并且把 Redis 部署成主从架构，才解决这个问题。

注意：如果你的 Agent 平台对状态可靠性要求高，Redis 必须开启 AOF 持久化，并且配置合理的 fsync 策略。everysec 是性能和可靠性的平衡点，不要用 no。

3.4 状态恢复的一致性保障

持久化最难的不是存，而是恢复时的一致性。我们遇到过几次恢复后状态不一致的问题：文件系统恢复了，但 Redis 里的上下文没恢复；或者上下文恢复了，但工具调用的连接状态丢了。

解决这个问题的核心思路是两阶段恢复 + 校验。第一阶段先恢复基础快照，第二阶段叠加增量，最后做一次一致性校验——校验文件系统关键路径的哈希值、校验 Redis 上下文的版本号、校验工具连接的健康状态。任何一项校验失败，就回退到上一个可用状态。

这个校验机制增加了一点恢复时间，但换来的是状态可靠性的大幅提升。生产环境里，状态不一致的代价远高于恢复慢几百毫秒。

4. 执行协议设计：Agent 和沙箱之间怎么对话

4.1 为什么不能用简单的 HTTP 请求-响应

Agent 和沙箱之间的通信，最直觉的方案是 HTTP 请求-响应：Agent 发一个执行请求，沙箱执行完返回结果。但 Agent 场景下，这个模式有几个硬伤。

第一个硬伤是流式输出。Agent 执行代码时，可能需要实时输出日志、实时返回中间结果。HTTP 请求-响应是阻塞式的，做不到流式。

第二个硬伤是双向通信。Agent 执行过程中，可能需要向沙箱发送额外指令（比如"暂停"、"注入变量"），沙箱也可能主动向 Agent 推送事件（比如"执行超时预警"）。HTTP 的单向请求模式做不到。

第三个硬伤是长连接管理。Agent 执行长任务时，HTTP 连接容易超时断开，需要复杂的重连机制。

所以，Agent 沙箱的执行协议，必须是双向流式协议。我们最终选的是基于 WebSocket 的自定义协议，在 WebSocket 之上定义了一套消息格式。

4.2 协议消息的四种类型

我们的执行协议定义了四种消息类型：

• Execute：Agent 向沙箱发送执行指令，包含代码、参数、超时配置。
• Event：沙箱向 Agent 推送执行事件，包括 stdout、stderr、中间结果、状态变更。
• Control：双向控制指令，Agent 可以发 pause/resume/cancel，沙箱可以发 timeout_warning/resource_warning。
• Result：沙箱执行完成后返回最终结果，包含退出码、返回值、资源消耗统计。

这四种消息类型覆盖了 Agent 执行的全生命周期。消息格式用 JSON，字段设计上有个关键点：每条消息必须带 sequence number。这是为了保证消息顺序，尤其是在网络抖动导致消息乱序时，接收方可以根据 sequence number 重排。

4.3 超时和资源限制的协议层实现

超时和资源限制，是执行协议里最容易出问题的部分。我们踩过的坑是：超时只在沙箱侧做，Agent 侧没有感知，结果沙箱超时 kill 了执行，Agent 还在傻等。

正确的做法是超时和资源限制在协议层双向同步。Agent 发送 Execute 消息时，带上超时配置和资源限制；沙箱执行过程中，定期向 Agent 推送资源消耗 Event；接近超时或资源上限时，沙箱发送 timeout_warning 或 resource_warning；真正超限时，沙箱执行 kill 并返回 Result，Result 里明确标注超限原因。

这样 Agent 侧就能实时感知执行状态，做出相应处理——比如超时预警时，Agent 可以决定是否延长超时；资源预警时，Agent 可以决定是否降低执行复杂度。

4.4 协议安全：防注入和防重放

执行协议本身也是攻击面。我们考虑了两个安全风险：协议注入和协议重放。

协议注入是指攻击者构造恶意消息，注入到 Agent 和沙箱的通信中。防护措施是消息签名：每条消息带一个基于共享密钥的 HMAC 签名，接收方验签后才处理。

协议重放是指攻击者截获合法消息，重复发送。防护措施是sequence number + 时间戳：接收方维护一个已处理 sequence number 的窗口，窗口外的消息直接丢弃；同时校验时间戳，超过时间窗口的消息也丢弃。

这两个措施增加了一点协议开销，但对于生产环境的 Agent 平台，安全开销是必须付的。

5. 花椒沙箱接入生产的完整踩坑链路

5.1 第一个坑：快照恢复后的文件权限错乱

这个坑我们排查了整整两天。现象是：Agent 执行代码时，偶尔报"Permission denied"，但同样的代码在本地跑没问题。排查过程是这样的：

第一步，确认不是代码问题——同样的代码，在沙箱里手动执行正常，只有通过 Agent 调用时才报错。第二步，确认不是并发问题——单用户单任务也复现。第三步，对比正常和异常时的沙箱状态，发现异常时文件权限是 000，正常时是 644。

根因定位：快照恢复时，文件权限没有正确还原。CubeSandbox 的快照机制默认不保存文件权限元数据，恢复时用了默认权限。解决方案是在快照配置里开启权限元数据保存，恢复时显式还原权限。

这个坑的教训是：快照恢复不是简单的文件拷贝，元数据（权限、所有者、时间戳）必须一并处理。后来我们在快照配置里加了一个检查清单，每次恢复后校验关键元数据。

5.2 第二个坑：Redis 连接池耗尽导致状态写入失败

现象是：高并发时，Agent 执行状态写入 Redis 失败，导致任务状态丢失。排查发现，Redis 连接池大小设的是 20，但峰值并发时，同时需要写入状态的连接超过 20，新连接请求被阻塞，最终超时失败。

解决方案有两步：一是把连接池大小调到 100，二是引入状态写入队列——状态先写入本地队列，由后台线程异步写入 Redis，避免阻塞主执行流程。

这里有个经验值：Redis 连接池大小 = 峰值并发数 × 2。因为每个任务可能同时需要读和写两个连接。另外，异步写入队列要设置合理的批量大小和刷新间隔，太小则频繁网络往返，太大则状态丢失风险高。我们最终设的是批量 50 条、间隔 100ms。

5.3 第三个坑：WebSocket 心跳配置不当导致长任务断连

现象是：Agent 执行超过 5 分钟的任务时，WebSocket 连接断开，任务中断。排查发现，WebSocket 心跳间隔设的是 30 秒，但服务端和客户端的心跳超时阈值不一致——服务端设的是 60 秒，客户端设的是 90 秒。结果服务端先判定连接超时，主动断开。

解决方案是统一心跳配置：心跳间隔 15 秒，服务端超时阈值 45 秒，客户端超时阈值 45 秒。同时增加断线重连 + 状态恢复机制：连接断开后，客户端自动重连，重连时带上最后收到的 sequence number，服务端从该 sequence number 之后的消息开始重发。

这个坑的教训是：WebSocket 的心跳配置，服务端和客户端必须严格一致。任何一侧的阈值偏大或偏小，都会导致误判断连。

5.4 第四个坑：沙箱资源限制过严导致正常任务被 kill

现象是：一些计算密集型的 Agent 任务，执行到一半被 kill，报"Resource limit exceeded"。排查发现，沙箱默认的 CPU 限制是 1 核，内存限制是 512MB。但我们的 Agent 任务里，有些数据分析任务需要 2 核 CPU 和 2GB 内存。

解决方案是资源限制分级：定义三档资源配置——轻量档（1 核/512MB）、标准档（2 核/2GB）、重量档（4 核/8GB）。Agent 发送 Execute 消息时，根据任务类型指定资源档位。同时增加资源预警：执行过程中，如果资源消耗达到档位的 80%，沙箱推送 resource_warning，Agent 可以选择升级档位或优化任务。

这里有个实操建议：资源档位的划分，要基于实际任务的资源消耗分布来定。我们统计了一周的任务资源消耗，发现 70% 的任务在轻量档就够，20% 需要标准档，10% 需要重量档。按这个分布定档位，资源利用率最高。

6. 生产环境沙箱的监控与告警该怎么搭

6.1 必须监控的五个核心指标

沙箱接入生产后，监控是保障稳定性的关键。我们最终确定了五个核心指标：

• 沙箱启动耗时：P50、P95、P99 三个分位。P99 超过 500ms 就要告警。
• 执行成功率：成功执行数 / 总执行数。低于 99% 就要排查。
• 状态持久化成功率：状态写入成功数 / 总写入数。低于 99.9% 就要告警。
• 协议消息延迟：消息从发送到接收的耗时。P95 超过 100ms 就要关注。
• 资源超限率：资源超限被 kill 的任务数 / 总任务数。超过 1% 就要调整资源档位。

这五个指标覆盖了沙箱的启动、执行、持久化、通信、资源五个维度。任何一个维度出问题，都能从对应指标上看出来。

6.2 告警分级与响应策略

告警不能一刀切，我们分了三级：

• P0 告警：执行成功率低于 95%，或状态持久化成功率低于 99%。响应策略：立即人工介入，5 分钟内响应。
• P1 告警：启动耗时 P99 超过 1 秒，或协议消息延迟 P95 超过 500ms。响应策略：30 分钟内排查，2 小时内给出方案。
• P2 告警：资源超限率超过 5%，或单个租户执行失败率异常升高。响应策略：当天排查，次日给出优化方案。

分级的好处是避免告警疲劳。如果所有告警都是 P0，运维人员很快就会麻木，真正严重的告警反而被忽略。

6.3 日志采集与问题回溯

沙箱的日志分三类：执行日志（Agent 执行的 stdout/stderr）、协议日志（消息收发记录）、系统日志（沙箱自身的运行日志）。三类日志分开采集、分开存储。

问题回溯时，关键是关联查询。我们给每个执行任务分配一个全局 trace_id，执行日志、协议日志、系统日志都带上这个 trace_id。排查问题时，用 trace_id 一次性拉出所有相关日志，快速定位。

这里有个经验：协议日志要记录消息的完整内容，但敏感信息要脱敏。我们早期协议日志记录了完整消息，结果日志里出现了用户代码里的密钥。后来加了脱敏规则，对特定字段做掩码处理。

7. 一些关于 Agent 沙箱接入生产的个人体会

做 Agent 沙箱接入生产的这段时间，我最大的体会是：沙箱不是一个独立组件，而是和 Agent 框架、存储系统、监控体系深度耦合的系统工程。选型时只看沙箱本身的指标是不够的，必须考虑它和现有系统的集成成本。

另一个体会是：持久化和执行协议，是沙箱接入生产的两大难点，但也是最容易被低估的部分。很多团队在选型时只关注隔离强度和启动速度，忽略了状态管理和协议设计，结果上线后才发现问题。我的建议是，选型阶段就把持久化和协议作为硬性评估项，不满足的直接淘汰。

最后分享一个实用技巧：沙箱接入生产前，一定要做混沌测试。我们上线前模拟了 Redis 宕机、WebSocket 断连、快照恢复失败、资源超限等场景，验证了系统的容错能力。这个测试帮我们提前发现了三个潜在问题，避免了上线后的故障。混沌测试的场景设计，可以参考"依赖组件故障 + 网络异常 + 资源异常"三个维度来组合。

如果你也在做 Agent 沙箱接入生产，欢迎交流踩坑经验。这个领域还在快速演进，很多最佳实践还在形成中，多交流能少走很多弯路。