做 AI 应用的同学应该都有类似经历你的 Agent 要跑 Python 代码但代码是模型现场生成的也可能是用户上传的本地不敢跑、线上裸奔更危险最后选了 E2B 沙箱来兜底。E2B 这类沙箱环境用起来确实顺手很多前沿 AI 产品在做代码生成与执行时都会用它做隔离层。但用久了你会发现沙箱不是一台怎么折腾都不会坏的虚拟机——一旦失控命令迟迟不返回、磁盘被打满、上下文悄悄失联整个 Agent 链路直接卡死这时候别说业务保住了日志里连个像样的报错都没有。这篇文章就是我把生产环境里踩过的 E2B 沙箱失控坑以及完整的排查与治理方案整理成一份可以直接抄的实战笔记。适合已经接入或者准备接入 E2B 的 AI 应用开发者和平台工程师尤其是正在被“沙箱里跑着跑着就没了响应”折磨的同学。1. 先弄明白E2B 沙箱到底在替你扛什么1.1 一个 AI 应用的代码执行困境先还原一个典型场景。你的 AI 应用可能在做类似这样的事用户上传一份 CSVLLM 分析后生成一段 Python 代码你的服务端要把这段代码跑起来拿到结果再喂给模型继续生成报告。问题来了这段代码不是预先写好的而是模型现场生成的本身就有语法错误、逻辑错误甚至恶意行为的可能。用户上传的数据也可能是精心构造的攻击样本。如果你直接在业务服务器上exec这段代码等于把整条服务链路的安全命脉交到了一个不可信输入手里——轻则内存被打满重则服务器被拿下。传统的做法是自己维护一个代码执行环境开一台隔离 VM装好 Python 和依赖把代码传进去跑。听起来不复杂但真正做起来全是琐碎活VM 启动要几十秒、环境镜像要自己维护、并发时要排队、资源回收不及时还会堆积一堆僵尸机器。E2B 本质上就是把这件事做成了托管服务——你通过 SDK 在云端启动一个轻量沙箱在沙箱里执行代码、读写文件、运行服务一切都和操作一台 Linux 机器一样但不用自己去维护底层的隔离设施。1.2 E2B 的方案微虚拟机而不是进程容器E2B 的底层是 Firecracker 这类微虚拟机技术。和 Docker 容器最大的区别在于容器和宿主机共享一个内核你的代码、依赖、系统调用都经过这个共享内核兜着微虚拟机则拥有独立的内核、独立的内存、独立的磁盘视图相当于给每个 Agent 任务发了一整台微型“物理机”。这个设计在安全模型上很关键。容器适合“应用内隔离”比如把 Web 服务和数据库分开但对于“执行不可信代码”这种高危场景容器还不足以让人放心。微虚拟机把逃逸攻击面大幅收窄就算沙箱里面的代码把自己玩炸了也炸不到宿主机和别的沙箱。可以用一个生活化的类比容器像几个人合租一套房共用承重墙和下水道一个人半夜蹦迪全楼都能感觉到微虚拟机像每人一栋独栋别墅墙壁是实心的邻居装修再吵你在自己屋子里该干嘛干嘛。独栋的缺点是坏了得自己修没人帮你扛着。这恰恰引出了本篇文章的主题——沙箱失控。隔离环境保护的是外部系统不受沙箱影响但如果沙箱内部的进程疯了、资源满了、状态坏了你的 Agent 依然会被卡死在外面。2. 沙箱失控的三种典型表现我见过的 E2B 沙箱失控基本跑不出下面这三种形态。提前认识它们遇到的时候就不会一脸懵。2.1 命令卡死执行到一半就没人回话最经典的表现你的 Agent 调用sbx.commands.run(python train.py)请求发出去了然后就没有然后了。十秒、三十秒、一分钟回调始终不触发。SDK 层可能已经抛了TimeoutExpired但你以为“超时了就完事了”——并没有沙箱里那个进程还在跑。它可能进入了死循环、在等待一个锁、或者卡在一个永远不返回的网络请求上。这种“命令卡死但沙箱活着”的状态最坑人。连接是通的控制台显示沙箱运行中但里面已经乱成一锅粥。更麻烦的是新任务如果复用了这个沙箱会跟着一起卡住因为资源都被旧进程霸占着。我在实际中见过一个案例某个 Agent 服务突然大批量超时控制台上看沙箱 CPU 使用率飙到 90% 以上却没有任何活跃任务在跑——就是前面的任务进程没被杀干净在后台疯狂空转。2.2 资源被吃光内存、磁盘、CPU 谁先爆谁说了算E2B 的沙箱本身有资源配额但配额上限和“你想让它在什么阈值内优雅运行”是两回事。我遇到过最离谱的一次是一个数据处理脚本把 20GB 垃圾数据写进了/tmp直接把沙箱的虚拟磁盘写满。磁盘满之后文件系统进入一种半死不活的状态执行命令还能勉强返回但任何涉及文件读写的操作都开始报错或者长时间卡住。内存也是一个重灾区。沙箱内跑 Python 脚本时如果某个list没有上限地append内存很快就会被吃光。内存耗尽后沙箱不会立刻死掉而是变得极其迟钝连files.list这种轻量操作都要几十秒才响应。CPU 则是最隐蔽的进程跑满了 CPU但沙箱在控制台上看起来完全正常只有你仔细看监控才发现 CPU 曲线已经是平的一条直线。2.3 上下文与连接互相失联E2B 沙箱是有生命周期的不是永远挂在云端等你。默认情况下如果你的服务端和沙箱的 SDK 连接断开沙箱会按照既定策略被回收即使你想保留也需要显式开启持久化并设置好断开容忍时间。这里有一个非常经典的坑你的 Agent 在一个长任务流程里创建了沙箱中间服务重启了或者网络闪断了几分钟SDK 连接断了沙箱被回收了。等流程恢复后你想重新连回那个沙箱继续跑发现找不回来了。如果这个沙箱里存着重要的中间结果或者状态数据就跟你一起消失了。更隐蔽的是多上下文的失联。如果你在同一个沙箱实例里创建了多个执行上下文Context它们共享沙箱的资源但又各自维护状态。某个上下文崩溃或者进入死循环拖累的却是整个沙箱上所有任务的执行效率而你从外面看只能看到“沙箱变慢了”很难定位到底是哪个上下文在搞事。3. 实战一次失控现场的完整排查过程说了这么多理论不如完整复盘一次真实的失控现场。这个案例我印象很深因为它表面上看起来“什么都没有发生”但生产环境已经被堵死了。3.1 问题复盘从一次“什么都没做”的清任务开始某团队跑了一个数据分析 Agent 服务。某天上午线上突然开始大量告警——所有任务都卡在“等待代码执行结果”这个阶段新任务不断排进队列但一个都出不来。第一反应是检查服务日志结果日志里没有任何异常堆栈只有一条条 SDK 超时记录。这反而说明问题不在应用层而在下层有人怀疑是 E2B API 挂了有人怀疑是网络问题。排查了半天最后打开 E2B 控制台一看沙箱列表里躺着一批仍在“运行中”的沙箱其中一台的 CPU 使用率一直在 90% 以上。可诡异的是那个沙箱对应的任务早就应该在半小时前结束了。这个场景是不是很熟悉任务不该跑了但沙箱里还在疯狂运转。控制台显示“运行中”其实内部已经失控。表面上你什么都没做但它自己停不下来。3.2 用日志反推失控链路排查的第一件事是确认 SDK 连接本身是不是好的。我在本地用同一套 API Key 连了一下沙箱from e2b import Sandbox sbx Sandbox() # 先确认连接是否正常、沙箱是否活着 print(sbx.files.list(/tmp))如果这行代码能正常返回说明 SDK 到沙箱的链路是通的问题不在网络而在沙箱内部。接下来是看一眼沙箱里面到底在跑什么东西# 拿回控制权随便执行一条命令看看回不回应 result sbx.commands.run(ps aux --sort-%cpu | head -20, action_timeout5) print(result.stdout)执行结果返回了一长串进程列表排在最前面的那个进程就是罪魁祸首CPU 使用率 100%命令行显示它还在跑一个已经过期很久的数据处理脚本。到这一步失控链路已经清楚了某个任务的执行体没有被正确终止在沙箱里面空转了半个多小时吃光了 CPU导致同一沙箱上后面所有新任务的执行都得不到资源全部排队超时。再说为什么“死循环的进程”没有被杀掉。根本原因是创建任务时没有设置任何超时保护和任务终止机制。SDK 提供的action_timeout默认行为只覆盖了“等待命令返回”的阶段一旦超时客户端会放弃等待但沙箱里的进程本身并没有被自动终止。如果你没有在异常处理逻辑里显式去 kill 那个上下文它就永远留在那里直到沙箱被销毁。3.3 定位根因三个致命遗漏复盘整条链路最后定位到三个被所有人忽略的点第一个所有执行动作都没有显式设置action_timeout也没有在超时后做进程清理。开发时本地网络好、进程快感觉不到问题一到生产环境某个任务稍微慢一点超时连接一断进程就成了漏网之鱼。第二个沙箱里的执行上下文没有主动管理。任务执行完没有kill上下文的逻辑任务异常了也没有兜底清理。多个任务复用同一个沙箱上下文之间互相干扰一个任务污染了沙箱状态后续所有任务都得跟着遭殃。第三个沙箱本身没有生命周期守卫。服务端进程崩溃后已经创建出来的沙箱没有人负责回收。那次事故里积压的僵尸沙箱占了小一半资源变相把其他正常沙箱的可用资源挤小了。这三个问题单独看都是小事合在一起就是事故。排查的结论也印证了一件事E2B 给你的只是一台干净好用的微型虚拟机但把虚拟机管成什么样完全取决于你自己的工程能力。4. 破解沙箱失控的四个核心操作找到根因之后问题就变成了怎么修。下面这四件事是我认为治理 E2B 沙箱失控必须做到位的核心操作每一项都有代码可以直接抄。4.1 给每个执行动作加上超时保险丝E2B 的 SDK 允许你在创建沙箱和运行命令时都指定超时时间。你要做的不只是把这个参数填上更重要的是理解它的边界from e2b import Sandbox # 创建沙箱时给出默认超时 sbx Sandbox(action_timeout10) # 单次执行覆盖超时设置防止个别长任务卡死 result sbx.commands.run(python train.py, action_timeout30)这里容易有个误解你设置了 30 秒超时SDK 在 30 秒后抛了超时异常你就以为“任务是超时了已经被系统清理了”。实际上 E2B 侧的执行进程大概率还活着。action_timeout只是客户端侧的等待上限服务端并不会因为客户端不等了就自动杀掉进程。所以正确的做法是把“超时抛异常”当成一个触发信号异常处理逻辑里紧接着去查杀沙箱里的上下文而不是直接放弃。类似这样from e2b import Sandbox sbx Sandbox() try: result sbx.commands.run(python train.py, action_timeout10) except TimeoutError: # 超时后必须主动清理沙箱内的执行上下文 for ctx in sbx.contexts.list(): ctx.kill() # 然后根据业务决定是重试还是标记失败 raise我特别强调一点超时不是用来“等”的是用来“杀”的。这也是我认为 E2B 沙箱治理中最重要的一个观念转变。4.2 带上资源限制别让沙箱变成无底洞E2B 第二层防线是资源配额。在创建沙箱模板的时候你应该明确 CPU、内存、磁盘的上限。不要觉得“反正有配额跑满也没关系”——这个想法在隔离环境里同样危险因为一个沙箱吃满自己的配额后会变得完全不可用你的 Agent 任务照样执行不下去。除了平台侧配额更实用的一招是在沙箱内部给具体进程套上resource限制import resource import os def limit_resources(): # 把单进程可用内存限制到 512MB memory_limit 512 * 1024 * 1024 resource.setrlimit(resource.RLIMIT_AS, (memory_limit, memory_limit)) # 打开文件数限制 file_limit 256 resource.setrlimit(resource.RLIMIT_NOFILE, (file_limit, file_limit)) # 在沙箱内执行任务前先调用这个函数做兜底 sbx.commands.run(python -c import resource; ..., action_timeout10)这招相当于给失控进程上了一道“防火墙”即使某个脚本的while True在疯狂申请内存到 512MB 就会被系统直接拒绝进程崩溃退出而不是把整个沙箱拖垮。同理磁盘可以做一个定期检查任务监控/tmp和/home目录的占用超过阈值就清理或者告警。4.3 用 SDK 主动管理上下文生命周期E2B 沙箱内部可以创建多个上下文每个上下文代表一次独立的执行环境。默认情况下如果你用sbx.commands.run()直接跑命令SDK 会返回一个结果对象但上下文会一直留在沙箱里直到沙箱销毁。生产环境我建议的模型是每个任务一个独立上下文任务结束立刻杀掉上下文不让它多活一秒钟。具体做法是用后台模式把控制权拿回来然后主动查杀from e2b import Sandbox sbx Sandbox() # 后台运行长任务拿到上下文ID ctx sbx.commands.run(python long_task.py, backgroundTrue) # 业务判断超时或失败后按ID精确清理 for c in sbx.contexts.list(): if c.id ctx.id: c.kill() # 或者干脆粗暴一点清理当前沙箱所有残留上下文 for c in sbx.contexts.list(): c.kill()用backgroundTrue的好处是长任务不会一直占住 SDK 的连接你可以同时执行其他操作比如监控进度、发起另一个任务或者决定要不要终止这个任务。如果你只用前台模式一个卡死的命令就会把你的整个 Agent 流程锁死因为后续代码根本不会继续执行。上下文生命周期管理这件事如果你们用的是同一个沙箱跑多个任务还要考虑并发冲突的问题。最稳妥的做法是“一个任务就开一个全新沙箱”用完就销毁不让状态在任务之间交叉污染。4.4 持久化与非持久化沙箱的职责拆分E2B 沙箱的默认生命周期是服务端连接断开后自动关闭。如果你需要沙箱在客户端断开后继续存活必须显式开启持久化并设置disconnect_timeoutfrom e2b import Sandbox # 需要长期保存状态的沙箱持久化并设置断线保留时间 sbx Sandbox(persistTrue, disconnect_timeout3600) # 等待持久化生效避免进程退出后沙箱依然被回收 sbx.wait_for_persistence()这里的wait_for_persistence()很关键。某些情况下沙箱创建成功不等于持久化完成如果你不等它确认就继续跑业务进程一旦退出了沙箱可能还是会按默认策略被回收。什么样的场景应该用持久化沙箱答案是需要保留安装的依赖、下载的数据、产生的中间结果并且下一次任务还要继续用这个环境的场景。比如一个数据清洗 Agent先下载数据、装好依赖然后等人工确认后再跑下一步——这个时候沙箱必须持久化否则两步之间网络闪断一下前面准备的依赖和文件就全没了。反过来说临时执行一次代码、跑完就走、结果同步到对象存储的任务完全不需要持久化。每次新建沙箱、用完销毁是最省心的方案。有些团队为了省启动时间会复用沙箱结果省下来的时间全花在排查上下文冲突上了得不偿失。5. 常见问题速查与排查技巧我把实际踩过的坑整理成一张速查表遇到问题先对号入座能省下很多排查时间。现象可能原因排查思路解决建议命令迟迟不返回、无响应进程死循环、等待锁、网络请求挂起执行ps aux看进程状态设置action_timeout并准备 kill 上下文操作报错但连接正常沙箱磁盘满、文件权限异常sbx.files.list(/)看目录可用性清理磁盘 / 检查写入路径沙箱内内存被打满单进程资源无上限free -h看内存剩余沙箱内设置resource限制新任务全部超时旧任务残留进程抢占资源控制台看沙箱 CPU 曲线清理上下文必要时重建沙箱服务重启后找不到沙箱未开启持久化或超时过短查看 SDK 日志中的沙箱 ID配置persistTruedisconnect_timeout并行任务互相干扰多任务复用同一沙箱/上下文查看上下文列表一个任务一个沙箱用完销毁5.1 沙箱启动慢或假死沙箱启动本身一般不会超过两三秒如果明显变慢大概率是宿主机资源紧张或者你请求的模板规格超过了当前可用资源。这时候不要反复创建新沙箱更不要盲目调大模板配额先检查控制台上是不是堆了一大堆“运行中”的僵尸沙箱。把这些清理掉再看启动时间是否恢复正常。5.2 文件上传失败和挂载丢失E2B 的沙箱每次新建都是全新环境不会自动带上你本地的文件。写入之前必须确认目标路径的父目录是存在的from e2b import Sandbox sbx Sandbox() content open(./report.csv, rb).read() # 先创建目录再写入避免路径不存在的报错 sbx.files.write(/home/user/data/report.csv, content)如果写入失败优先排查磁盘剩余空间。我见过一个场景是某脚本反复写文件又不清理磁盘悄悄满了结果所有新增写入都失败而读取还能正常返回导致排查时一度以为只是“权限问题”。5.3 会话超时的坑关于断线后的保留时间核心是理解三个参数的搭配persist控制沙箱是否在断线后继续存活disconnect_timeout控制断线后最多保留多久wait_for_persistence控制创建时是否等到持久化完成。只开persist不给disconnect_timeout沙箱可能被无限保留白白占着资源。只给超时不开持久化那超时时间再长也没用沙箱照样当断线就回收。生产环境建议根据任务的最大耗时来设置比如任务最长跑 20 分钟就设 40 分钟留一倍余量既不会过早回收也不会无限占用。6. 我的经验总结与实践建议复盘这几次 E2B 沙箱失控的经历我最大的体会是E2B 本身是一个很好用的工具但它只解决“给你一台干净的隔离环境”这件事不解决“这台机器在你业务里的生命周期管理”这件事。你把一台虚拟机交给一个粗心的 Agent 去用又不给它任何护栏失控是必然的只是时间问题。现在我接手相关的沙箱治理项目时会先检查三条底线你可以对照自己的项目看一下第一条所有执行动作必须有超时而且超时后的第一动作必须是清理不是记日志。第二条沙箱的创建和销毁必须是代码里的确定性逻辑放在try/finally里不管任务成功还是异常沙箱最终都会被回收。第三条把“状态”搬出沙箱。中间结果落到对象存储配置依赖固化到模板让沙箱本身永远是廉价、可再生的。这样就算某个沙箱彻底失控销毁重建的成本也几乎为零。最后再分享一个小技巧我习惯在沙箱模板里预装一个healthcheck.sh脚本用来快速探测沙箱是否“活着”。检测方法很简单输出当前时间和可用的磁盘空间再跑几行内存统计。一旦感觉到沙箱不对劲先执行这个脚本三秒钟就能判断是“假死”还是“真卡死”比打开控制台翻曲线省事得多。
