1. AI Agent Sandbox 到底在隔离什么做 AI Agent 的人最开心的时刻往往是第一次看到 Agent 自己调用工具、自己循环推理完成一个多步任务。但开心之后你大概率会撞上一堵墙Agent 跑起来了它该在什么环境里跑这个问题如果只是“给个容器随便跑”后面有的是硬仗要打。我最近把自己的 Agent 平台重构了一遍把 Sandbox 从临时方案升级成一套有明确边界的执行环境核心就是标题里那几件事Hosted vs Self-hosted 怎么选、文件怎么隔离、Secret 怎么注入、网络怎么控制、持久化怎么做。这篇把完整的设计过程和踩坑记录写下来给正在做 AI Agent 部署的同学一个参考。1.1 沙箱的本质是“受控执行”Agent 和普通 API 服务有个本质区别它有自主性。它会根据当前状态做决定可能去执行一段代码、可能去调一个外部工具、可能反复重试同一个请求。这种自主性正是 Agent 的价值但也是风险来源。Sandbox 要做的不是限制 Agent 的能力而是给这种自主性划一条边界让它在边界内自由发挥边界外一律默认拒绝。我习惯把沙箱的职责拆成四个隔离维度文件隔离、网络隔离、进程隔离、资源隔离。文件隔离管“它能碰哪些数据”网络隔离管“它能访问哪些地址”进程隔离管“它能不能影响宿主机和其他任务”资源隔离管“它最多消耗多少 CPU 和内存”。这四件事做不到位Agent 跑得再漂亮也是裸奔。很多教程只教你 Docker 跑起来但没告诉你容器默认共享内核、默认有网络出口、默认以 root 身份运行这些默认行为在 Agent 场景里每一个都是坑。1.2 先定义“威胁模型”设计沙箱之前不要急着选技术。先回答一个问题你最担心 Agent 干出什么坏事我见过不少团队把这道题想得太大最后用上了全套微 VM但实际上他们的 Agent 只跑自己生成的代码威胁面很小。也见过完全反过来的Agent 要处理用户上传的文档、要访问企业内网数据库结果沙箱只是简单docker run然后天天担心数据泄露。我的经验是列出三种典型风险。第一种是恶意输入用户故意让 Agent 读取服务器文件或者往内网发请求这种属于攻击型风险。第二种是失控行为Agent 死循环、占满内存、把磁盘写爆这种属于资源型风险。第三种是数据泄露Agent 把敏感文件读出来后通过日志或网络发出去这种属于数据型风险。针对这三种风险再去选隔离方案你的架构才不会过度设计也不会该堵的地方没堵。1.3 最小权限原则要落到每个维度最小权限是老话但在 Agent 沙箱里特别容易被忽略。很多实现直接把宿主的.env、挂载目录、甚至是docker.sock一股脑传给容器Agent 一跑能看的东西比你自己还多。docker.sock尤其致命容器拿到它基本等于拿到宿主机 root所谓隔离直接变成笑话。我现在的原则是默认拒绝一切按需逐步开放。需要读写文件才挂一个临时目录需要联网才走白名单代理需要访问数据库才注入一个短期凭证。每项能力都应该有一个明确的“负责人”这是整个沙箱设计的核心思路也直接决定了后面文件、Secret、网络这些模块的具体做法。你在设计阶段多花一点时间做减法后面运维阶段能少掉一大半头发。2. Hosted vs Self-hosted两条路怎么选沙箱的部署模式是第一道分叉路。Hosted 和 Self-hosted 没有绝对的好坏但选错了成本差距很大。这一章我把两个方向的真实体验和参数对比整理一下最后聊一下我自己怎么选。2.1 Hosted 沙箱省心但也要留后路Hosted 模式指的是把沙箱运行在云厂商或第三方服务商提供的环境里比较典型的像 E2B、Firecracker 微 VM 云服务、各类 Serverless Agent 运行时。优点很直接不用自己维护隔离层启动速度快多语言运行时开箱即用弹性伸缩也由平台处理。并发高的时候你只管加容器平台会自动帮你调度这对“ai agent 怎么扛并发”这个问题来说几乎是无脑解。但 Hosted 不是没有代价。最让我在意的是数据主权用户的代码、Agent 的中间状态、读取过的文件都会经过第三方环境。如果你的业务涉及企业内部数据合规这一关可能就过不去。另外Hosted 沙箱的网络延迟和按秒计费在高频调用场景下会变成一个不小的成本项。我建议 Hosted 更适合做产品原型、个人玩具项目、或者对数据合规不敏感的公开场景。如果决定用 Hosted记得把平台的导出能力和 API 兼容性提前摸清楚别等数据进去了才发现被绑定死。2.2 Self-hosted 沙箱可控但运维是硬仗Self-hosted 是自己搭沙箱运行环境常用技术栈包括 Docker 容器、gVisor、Firecracker、NSJAIL甚至纯 systemd 加 seccomp。它最大的好处是可以完全掌控边界文件系统怎么挂、网络怎么通、Secret 怎么注入全都可以按业务定制。数据不出域离线环境也能跑长期来看成本也相对可控。代价是运维压力全部落到自己身上。Docker 容器本身并不等于安全沙箱容器逃逸虽然不常见但一旦发生就是大事gVisor 这类用户态内核隔离更强但性能有所损耗每次安全更新你都得自己跟进。我的经验是如果你的团队已经有 DevOps 能力并且对数据敏感度较高Self-hosted 是值得投入的方向如果只有两三个后端还是先 Hosted 上线更现实。技术栈选定后不要频繁换隔离层的改造牵一发动全身。2.3 一张表把两者放在一起看对比维度Hosted 沙箱Self-hosted 沙箱隔离强度平台负责通常较强取决于技术栈和配置可强可弱启动速度毫秒到秒级有预热池容器或微 VM优化后可以做到亚秒级数据主权数据经过第三方环境数据完全在自己手里运维成本低平台兜底高需自己处理补丁、监控、逃逸防护长期成本按秒计费高频场景较贵固定机器成本高并发时更划算定制能力受平台 API 限制完全可定制离线支持困难天然支持上手难度低注册即用高需要自己搭整套链路这张表不是让你按总分选方案而是帮你看清自己的约束条件。数据合规、成本结构、团队能力这三个变量几乎决定了最终答案。我自己见过一个 20 人团队因为不想维护容器环境选了 Hosted结果最核心的客户要求数据不出内网最后花了两个月重新迁到 Self-hosted得不偿失。2.4 我的选型逻辑与并发考量很多同学问我“ai agent 怎么扛并发”这个问题的答案很大程度取决于沙箱类型。Hosted 沙箱天然带弹性并发高时自动扩容你不用太操心Self-hosted 沙箱就得自己做容器池预先启动 N 个容器任务来了直接复用不然每次冷启动都能把延迟拉到几秒。我现在的平台是混合策略默认 Self-hosted 跑核心任务遇到流量毛刺再借助托管服务削峰。这样既兼顾数据主权又不用把峰值容量一直买着。具体到选型我给自己定了几条硬规则客户数据要落库的一律 Self-hosted纯公开数据、对延迟敏感的原型直接 Hosted团队没有专职安全人员时优先 Hosted 而非硬上 Self-hosted。这条规则可能不适用所有人但至少能避免最差的情况——方案做到一半发现运维扛不住。3. 文件系统沙箱里的文件到底怎么管文件是 Agent 和外界交互的主要媒介。用户上传文档、Agent 生成报告、代码执行写临时文件全都绕不开文件系统。这一章我重点讲沙箱内目录怎么划分、怎么挂载、怎么防爆盘以及文件传入传出的正确姿势。3.1 临时文件与持久文件分开处理沙箱里的文件要分成两类。一类是临时文件比如 Agent 生成的中间代码、爬下来的临时网页、需要现场编译的产物这类文件随任务结束删除就行我建议直接挂到内存盘 tmpfs不仅速度快而且容器一停就彻底消失不会留下残留。另一类是持久文件比如用户上传的文档、Agent 长期记忆、向量化后的知识库这类文件不应该放在沙箱容器内部而应该放在外部存储比如对象存储或数据库Agent 需要时再拉进来。这个划分想清楚后文件管理的复杂度会下降一大截。最怕的是把所有文件都塞进容器容器重建时要么全没要么必须跟着容器走又重又脆弱。把沙箱当无状态执行环境所有需要留存的数据都外置这是整个文件设计的基石。3.2 一个不算复杂但实用的目录方案在 Self-hosted 沙箱里我用的 Docker 启动参数大致是下面这样docker run -d --name agent-sandbox \ --network none \ --read-only \ --tmpfs /tmp:rw,noexec,nosuid,size256m \ -v /data/agent-bucket:/workspace/input:ro \ -v /data/agent-output:/workspace/output:rw \ -v /data/agent-scratch:/workspace/scratch:rw \ --memory 1g --cpus 1 \ my-agent-image:latest关键点有几个。第一根文件系统设为只读Agent 镜像里本来就不该有可变文件只读能防止它偷偷改自己。第二/tmp用 tmpfs临时数据写内存进程结束即消失noexec防止在临时目录里执行下载来的二进制。第三输入目录只读挂载输出目录独立挂载任务完成后外部去 output 目录拿结果把上传和下载彻底分离。第四/workspace/scratch是给需要编译或执行代码的场景留的工作目录它挂在真实磁盘上可以做配额。这里有一个很容易被忽略的问题输出目录虽然是 rw但如果不做配额Agent 可能写满宿主磁盘。Docker 层面可以用--storage-opt size512m限制容器写入量或者把 scratch 和 output 各自独立配额。血泪教训配额一定要做不然一个失控 Agent 能把整块磁盘干爆拖垮同一台机器上的所有任务。3.3 文件传入传出的正确姿势Agent 任务往往需要读用户提供的文件比如文档分析、图片处理。我的做法是提供一个文件桶接口任务启动前先让用户上传到对象存储然后沙箱启动时把对应文件软链或复制到/workspace/input。任务跑完Agent 生成的任何附件统一放到/workspace/output由外部程序定期回收并落盘到对象存储。这样设计的好处是沙箱完全无状态。容器随时可以被杀掉、重建、迁移数据始终在外部稳定性大大提升。还有一个小细节文件传到沙箱后建议立刻做类型校验和大小限制别让 Agent 处理一个 10GB 的“文档”那不是任务是事故。对象存储层加前缀和生命周期策略临时文件三天自动清理也能省不少存储费。4. Secret 管理密钥进沙箱的正确姿势Secret 管理是 Agent 沙箱设计里最容易被低估的一块。很多团队把 API Key 往环境变量里一塞就上线直到泄露那天才意识到问题。这一章我讲清楚为什么环境变量方案不可靠以及更安全的注入方式。4.1 环境变量方案为什么不可靠初学者最常见的做法是把 API Key、数据库密码写进环境变量然后容器里直接os.environ读取。这个做法的风险不是环境变量本身而是环境变量的传递链条太长。Agent 执行子进程、打印调试日志、调用外部工具时都可能把这些变量带出去更隐蔽的是Agent 循环推理中如果通过工具读系统信息这些 Key 会进入 LLM 的上下文等于你主动把密钥交给了第三方模型。我见过不止一个案例日志里整页整页地打印环境变量Key 全暴露了。还有一个实际问题环境变量对沙箱内所有进程可见容器里任何一个子进程崩溃时打印 environment密钥就跟着进了错误上报系统。所以能不用环境变量直接注入密钥就不要用。Agent 的自主性决定了它不可信不可信的东西就按不可信的方式对待。4.2 推荐的注入方式是“短期凭证 白名单权限”我给自己的沙箱定了三条规矩密钥不进 LLM 上下文密钥不落到长期日志密钥只在任务需要的窗口期内有效。具体实现上我倾向用短期凭证而不是长期密钥。比如访问数据库就通过 STS 签一个有效期 15 分钟的临时凭证注入容器访问对象存储就生成一个带限定前缀的临时 AK。这样就算沙箱被攻破攻击者拿到的也是一个马上过期的凭证而不是一把万能钥匙。如果实在要访问带长期密钥的外部服务也不要直接塞给 Agent而是由一个内部代理持有Agent 需要访问外部服务时通过代理发起请求由代理在外层注入鉴权头。这样 Agent 和应用服务之间彻底隔离密钥全程不出代理进程。这个模式很像网关服务但关键点在于 Agent 永远拿不到原始密钥它只知道“我能通过代理调这个接口”。4.3 Docker 场景下怎么传 SecretDocker 自带 secret 机制可以在容器启动时把密钥挂载成只读文件进程内读取后再从内存中删除引用。我实际用的是编排层注入services: sandbox: image: my-agent-image:latest secrets: - db_password environment: - TASK_ID${TASK_ID} tmpfs: - /run secrets: db_password: file: ./secrets/db_password.txt注意一个细节容器内/run/run/secrets/db_password文件默认权限是 0444意味着同容器内所有进程都能读。如果你的沙箱是多租户的要确保一个容器只跑一个 Agent 任务这是 Secret 和任务粒度必须一致的前提。另外代码里读完 Secret 后应该立刻shred或删除对应文件尽量减少密钥暴露窗口。4.4 密钥轮换与审计Secret 设计得再好没有轮换和审计也是白搭。我在每次任务结束后强制刷新短期凭证长期密钥每 90 天轮换一次。审计日志里只记录“哪个任务在什么时间访问了哪个服务”绝不记录具体密钥内容。调试时如果需要复现宁可重新签发一次密钥也不去解开日志里的旧记录。还有一点值得提醒不要把 Secret 入库。有些平台会把任务定义和 Secret 一起存进数据库一旦数据库泄露所有密钥一起完蛋。正确做法是 Secret 单独走密钥管理服务任务定义只引用密钥 ID读取密钥的操作统一走短期凭证或代理层。5. 网络隔离给 Agent 一个受控的互联网入口网络是 Agent 沙箱里最难做又最不能不做的一环。Agent 一旦有了自主调用工具的能力它就可能主动向外发起请求。不控制好网络所有文件隔离和 Secret 管理都可能白做。5.1 默认断网按需开闸大多数 Agent 任务根本不需要访问外网。比如数据分析、内部知识库问答、生成代码并测试这些任务需要的资源要么在本地要么在 Agent 框架内部。所以我给沙箱的默认网络策略是--network none完全断网。只有当任务声明确实需要访问外部 API、搜索结果等才单独开设网络通道。这个“默认拒绝”的思路非常关键。你一旦默认给网后面做白名单、做流量审计的成本会高很多而且 Agent 已经能随意出网了你再限制就属于亡羊补牢。任务声明要网络的时候我一般要求带上理由和域名列表这样每个网络通道都有据可查。5.2 白名单出口代理怎么搭当任务需要外网时我不会直接把公网口开给容器而是给容器一个 HTTP 代理地址所有外部请求统一走代理。代理层做两级控制域名白名单和协议限制。只有匹配白名单的域名才被放行其他连接一律 403协议通常只放 HTTPSHTTP 明文尽量拒绝防止数据裸奔。实现上可以用 squid 加外部 ACL也可以用 mitmproxy 做 HTTPS 敏感行为审计还可以在容器内在 iptables 里把 FORWARD 和 OUTPUT 链的默认策略设为 DROP只放行到代理容器的流量。简单起见我一开始用 Docker 自定义桥接网络给沙箱容器只暴露一个代理 IP然后在代理容器上用 nftables 控制出网。实际效果是Agent 偶尔会请求一些无关域名比如遥测、更新检查白名单机制直接把这些流量挡在外面既不污染任务也减少了外部数据泄露面。如果你用 Kubernetes可以给沙箱 Pod 配egress策略原理一样。5.3 防 SSRF这是内外网边界最容易翻车的地方SSRF服务端请求伪造在 Agent 场景里太容易被触发了。Agent 如果拿到一个公网工具用户诱导它访问http://169.254.169.254或内网地址那就等于让 Agent 变成了一个跳板去探测你的内部网络。更麻烦的是Agent 是自动化的它可能在一个循环中尝试多个 IP 段扫描速度比你手工测试快得多。我的做法是出口代理上直接拦截所有私有网段和保留 IP 段包括10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、169.254.0.0/16还有 IPv6 的fe80::/10。代理层靠 URL 解析后的真实 IP 做判断别只检查字符串里的 IP防止用 DNS rebinding 绕过。容器内再叠加 iptables 规则即使代理失效容器也连不上内网。SSRF 防护做得好不好直接决定你的沙箱是不是别人内网的免费跳板。5.4 沙箱与沙箱之间的隔离多任务并发时沙箱之间也要隔离。Docker 自定义网络中每个容器有自己的 IP但默认同一网络内容器可以互访。我会再起一个 overlay 网络并设置 network policy 只允许沙箱访问外部网关沙箱与沙箱之间默认隔离。如果你用 Kubernetes直接上 NetworkPolicy 更方便规则写清楚哪个 Pod 能访问哪个 Pod避免 Agent 之间互相探测。我遇到过的一个真实案例两个 Agent 同时跑在默认 bridge 网络一个 Agent 的工具列表里有“读取环境变量”的能力另一个 Agent 的任务里有敏感数据结果前者通过容器网络探测到了后者的端口并尝试读取数据。虽然不是严重事故但彻底让我下决心在所有沙箱网络之间加了硬隔离。Agent 之间的信任应该为零。6. 持久化沙箱没了数据还在Agent 沙箱的临时性和业务数据的持久性是一对天然矛盾。沙箱容器随时会被杀掉、重建、迁移但用户数据和 Agent 记忆不能丢。这一章讲清楚哪些数据该持久化、持久化放哪里、以及 Redis、对象存储、向量库在其中的分工。6.1 先分清“沙箱状态”和“业务数据”很多人在持久化这里纠结其实是把两类数据混在一起了。一类是沙箱的运行状态比如正在执行的临时文件、环境变量、当前工作目录这类数据不需要持久化应该随容器销毁而消失。另一类是业务数据比如用户上传的文档、Agent 的记忆向量、对话记录、任务结果这类数据必须持久化而且要放在沙箱之外。我个人强烈建议把沙箱当作完全无状态的执行环境来设计。任何要留存的数据一开始就写入外部存储绝不要依赖容器内磁盘。这样一来容器随时可以杀了重建水平扩展也变得很容易。很多 Agent 平台跑不稳就是因为在沙箱内部堆了状态容器一重建就什么都不剩只能靠环境变量硬塞回去最后状态乱成一团。6.2 持久化该落在哪一层业务数据落到哪里取决于类型。文件类我用对象存储MinIO 或者 S3 兼容桶按任务 ID 分目录简单可靠。结构化数据我用 PostgreSQL 或 MySQL重点记录任务状态、运行日志、结果摘要。Agent 的记忆和向量索引我用向量数据库任务结束后按会话 ID 写入下次对话再按相似度召回。顺便说下 Redis。很多团队用 Redis 做 Agent 的任务队列和短期状态缓存这没问题但别把它当持久化主存储。Redis 的 AOF 和 RDB 本质上是把内存状态定期或增量写到本地磁盘RDB 是定期快照恢复快但可能丢窗口期数据AOF 是记录每条写指令的日志数据不丢但要重放。如果你的 Agent 依赖 Redis 里存了不可丢失的数据要么彻底用外部数据库要么必须配置好持久化策略和备份。把 Redis 当缓存用把数据库当存储用这个边界要划清。6.3 Agent 记忆怎么持久化才不丢Agent 记忆是 AI Agent 场景里特别有代表性的持久化需求。我的做法是对话消息落库到 PostgreSQL关键事实和摘要抽出来做成向量写入向量库。每次任务结束后框架把本轮新增的内容单独存一个长 key指向会话 ID 和任务 ID方便追溯。这样 Agent 下次启动时只加载当前会话的记忆而不是把所有历史都塞进上下文既省 token 又保留连续性。有个坑不要把 Agent 记忆直接存到沙箱里的向量库目录。因为沙箱是临时环境容器一删所有记忆全没。我见过有人把 Chroma 装在容器里跑一升级容器用户历史全清空那种事故特别伤信任。记忆存储应该和沙箱彻底解耦就算是本地开发环境也应至少放在独立的数据卷里而不是容器内路径。6.4 快照到底要不要做快照是一个双刃剑。它能让你随时恢复到 Agent 出错前的状态适合调试和审计但快照会消耗大量磁盘恢复也慢不适合高频任务。我的建议是默认不做全量快照只对出错任务做“证据留存”比如把输入文件、输出文件、日志留档保存 30 天。真要快照可以只给特定的高危任务或需要可复现性的任务开启用 overlay 文件系统做差异快照而不是整容器打包。另外提醒一句持久化和备份是两件事。就算你把数据写到了外部存储也要定期检查对象存储版本控制和数据库备份策略。沙箱里的数据丢失概率不高但外部存储崩了、误删了同样致命。备份这件事不复杂但必须形成习惯至少做到“每天一全量、每小时一增量”的节奏。7. 落地案例基于 FastAPI LangGraph 的 Agent 沙箱实践前面讲了大量设计原则这一章落到代码和流程上。我挑一个目前在用的组合——FastAPI 做 API 层、LangGraph 做编排层、Docker 做执行沙箱——分享落地方式和关键实现细节。7.1 整体架构与服务分层如果你要用 FastAPI LangChain LangGraph 搭一套带沙箱的 Agent 服务我建议分层拆成四块API 层用 FastAPI 接收请求编排层用 LangGraph 定义 Agent 的状态机和工具调用逻辑执行层负责把代码或命令放进沙箱存储层使用 PostgreSQL、Redis、对象存储和向量库。沙箱不要嵌入 LangGraph 的主进程而是独立成一个部署单元通过 docker SDK 或 HTTP 接口调用。这样分层的原因很实际LangGraph 节点如果直接执行用户代码一旦代码崩溃、死循环、写坏内存整个编排进程就陪葬了。把执行放到沙箱容器里最坏的情况就是杀掉一个容器Agent 主流程还能继续处理其他任务。这也是“ai agent 主流架构”里大家越来越倾向的做法——编排和执行分离。7.2 使用 docker-py 创建最小沙箱下面这段代码是我项目里的简化版体现的是文件、网络、Secret 三个模块怎么组合import docker client docker.from_env() def create_sandbox(task_id: str, secret_file: str): return client.containers.run( imagemy-agent-image:latest, namefsandbox-{task_id}, usernobody, read_onlyTrue, networksandbox-net, tmpfs{/tmp: rw,noexec,nosuid,size256m}, volumes{ /data/bucket/input: {bind: /workspace/input, mode: ro}, /data/bucket/output: {bind: /workspace/output, mode: rw}, /data/bucket/scratch: {bind: /workspace/scratch, mode: rw}, }, secrets[secret_file], mem_limit1g, nano_cpus1_000_000_000, detachTrue, removeTrue, )注意几个点usernobody避免以 root 身份运行networksandbox-net而不是默认 bridge方便统一做出口代理removeTrue确保容器退出即删除不会堆积孤儿容器。第一次跑脚本之前记得先创建 sandbox-net 网络并把代理容器也接到这个网络上沙箱容器才能通过代理出网。如果你的沙箱需要访问 GPU 做模型推理Docker 的gpus参数要单独配置但这会引入新的隔离问题建议 GPU 任务走独立的高权限沙箱别和普通任务混用。7.3 任务生命周期状态机一个完整的沙箱任务大致是这样的流程API 接收请求后生成 task_id写入 PostgreSQL状态为 pending编排层从消息队列拉取任务调用容器创建沙箱状态变为 runningAgent 在沙箱内执行工具、读文件、调模型结束后把产物写进/workspace/output执行层回收容器读取 output 目录把结果写入对象存储和 PostgreSQL状态变为 completed。如果容器执行超时或异常退出状态变为 failed外层可以基于日志做重试策略。这里最值得花心思的是超时机制。Agent 场景和传统 API 不一样一个任务可能跑几十秒甚至几分钟。我一般设置两层超时业务层超时 5 分钟容器层超时 7 分钟超过时间直接 kill 容器回滚任务状态。避免因为一个 Agent 死循环把整个并发池占满。重试策略也要谨慎不是所有任务都适合无脑重试有些 Agent 任务是有副作用的重试可能导致重复发邮件、重复扣款这类任务失败后应该进入人工审核队列。7.4 并发场景的几个关键参数前面提到“ai agent 怎么扛并发”落到实处就是这几个参数容器池大小、并发上限、请求排队超时、回收频率。我建议先压测你的机器看单个沙箱从启动到退出的完整周期占多少资源然后按机器的 CPU 和内存算最大并发。一般来说1 个容器配置 1 核 1G8 核 32G 的机器跑 6~8 个并发任务比较稳再多就会触发内存抖动。容器池化是 Self-hosted 并发优化的重点。不要每个任务都冷启动一个新容器而是预先启动若干容器待命任务分配时从池里取任务结束归还或重置。重置容器要用快照/镜像回滚确保上一个任务的痕迹清干净。还有一层是 API 层的限流FastAPI 可以基于 Redis 做滑动窗口限流单用户并发太高的请求直接排队或拒绝防止一个用户的任务把全平台的容器池占满。8. 常见问题与排查技巧实录最后分享一些我真实踩过的坑和排查方法。这些东西不在官方文档里但实操中几乎都会遇到。8.1 一张表对照常见症状和解决办法症状可能原因解决办法Agent 能跑代码但拿不到上传文件输入目录挂载路径不一致检查 volume 绑定确认容器内实际路径任务报网络超时出口代理未启动或白名单没加域名检查代理容器状态在 ACL 里临时放行日志里出现完整 API KeySecret 通过环境变量注入且被打印改用短期凭证禁止在日志中输出环境变量容器目录被写满未配置磁盘配额加 storage-opt 或 tmpfs 限制输出目录独立配额一个 Agent 拖垮整台机器并发池无上限设置并发上限和容器级资源 limit沙箱访问不到内网数据库网络策略默认拒绝内网显式放行特定数据库 IP 和端口不走公网代理Agent 任务偶发失败容器冷启动超时提前预热容器池减少创建开销这张表我从项目上线维护到现在一直在更新每次遇到新问题就补一行。排查手册沉淀下来之后新同学接手也能快速上手不用每个坑都重新踩一遍。8.2 我自己踩过的几个坑第一个坑是日志泄露。最初我把容器的 stdout 直接流式打到应用日志Agent 一旦把环境变量或密钥打到 stdout就会永久记录在日志系统里。后来我加了日志脱敏用正则匹配常见 key 的格式直接打码才敢放心收集。第二个坑是时区问题。沙箱容器默认 UTCAgent 如果做时间相关任务结果会莫名差 8 小时。我在镜像里预设了TZAsia/Shanghai或者把业务逻辑里的时间统一用 UTC 存储、展示时再转换避免在容器里改时区引发混乱。第三个坑是孤儿容器。任务超时被 kill 后如果没有removeTrue容器会一直停留在 Exited 状态时间长了堆一堆僵尸。我用定时任务清理所有 Exited 且创建时间超过 1 天的容器并在创建时统一加上removeTrue和标签方便批量管理。还有一个容易被忽略的细节是容器名冲突并发任务生成 task_id 时如果碰撞容器创建会直接失败我在 task_id 后面加了毫秒级时间戳彻底解决这个问题。8.3 排查思路从外到内先网络后文件当 Agent 行为异常时我的排查顺序是固定的先看 API 层有没有收到回调确认任务是不是压根没开始执行再看编排层日志确认 LangGraph 节点在哪一步卡住然后看沙箱容器日志确认代码执行输出最后才进到沙箱内部复现问题。不要一上来就 bash 进容器这会破坏现场。先保留日志和 output 目录必要时做快照。如果是网络问题我会先在代理容器上tcpdump看有没有请求流量然后检查白名单。如果是文件问题先确认 volume 挂载是否正常用docker inspect看 Mounts 字段再确认权限位。这套顺序能省掉大量弯路。排查结束之后不管是哪个环节出问题都要回到设计原则上去想是不是我给 Agent 的权限又给多了是不是某个边界又没守住。沙箱的安全和稳定不是上线那一刻达成的而是在一次次排查和收紧中慢慢磨出来的。写到这里我对“AI Agent Sandbox 怎么设计”这个问题能讲的都讲了。最后说点个人的真实感受沙箱设计没有银弹Hosted 和 Self-hosted 各有各的账文件和 Secret 管理本质是给 Agent 立规矩网络隔离是在自由和风险之间找平衡持久化则是让 Agent 从玩具变成服务的底气。我做过的最值得的一件事就是把沙箱当作一个独立产品而不是附属功能来设计——它有自己的边界模型、自己的运维手册、自己的监控指标。每当你觉得 Agent 又开始乱来先把沙箱边界收紧一层往往比不停调 prompt 管用得多。愿你的 Agent 在笼子里飞得又稳又远。