企业官网建设流程全解析

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 一张表把两者放在一起看

这张表不是让你按总分选方案，而是帮你看清自己的约束条件。数据合规、成本结构、团队能力这三个变量几乎决定了最终答案。我自己见过一个 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,size=256m \ -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 size=512m限制容器写入量，或者把 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 场景下怎么传 Secret

Docker 自带 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；协议通常只放 HTTPS，HTTP 明文尽量拒绝，防止数据裸奔。

实现上可以用 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( image="my-agent-image:latest", name=f"sandbox-{task_id}", user="nobody", read_only=True, network="sandbox-net", tmpfs={"/tmp": "rw,noexec,nosuid,size=256m"}, 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_limit="1g", nano_cpus=1_000_000_000, detach=True, remove=True, )

注意几个点：user="nobody"避免以 root 身份运行；network="sandbox-net"而不是默认 bridge，方便统一做出口代理；remove=True确保容器退出即删除，不会堆积孤儿容器。第一次跑脚本之前，记得先创建 sandbox-net 网络，并把代理容器也接到这个网络上，沙箱容器才能通过代理出网。如果你的沙箱需要访问 GPU 做模型推理，Docker 的gpus参数要单独配置，但这会引入新的隔离问题，建议 GPU 任务走独立的高权限沙箱，别和普通任务混用。

7.3 任务生命周期状态机

一个完整的沙箱任务大致是这样的流程：API 接收请求后生成 task_id，写入 PostgreSQL，状态为 pending；编排层从消息队列拉取任务，调用容器创建沙箱，状态变为 running；Agent 在沙箱内执行工具、读文件、调模型，结束后把产物写进/workspace/output；执行层回收容器，读取 output 目录，把结果写入对象存储和 PostgreSQL，状态变为 completed。如果容器执行超时或异常退出，状态变为 failed，外层可以基于日志做重试策略。

这里最值得花心思的是超时机制。Agent 场景和传统 API 不一样，一个任务可能跑几十秒甚至几分钟。我一般设置两层超时：业务层超时 5 分钟，容器层超时 7 分钟，超过时间直接 kill 容器，回滚任务状态。避免因为一个 Agent 死循环把整个并发池占满。重试策略也要谨慎，不是所有任务都适合无脑重试，有些 Agent 任务是有副作用的，重试可能导致重复发邮件、重复扣款，这类任务失败后应该进入人工审核队列。

7.4 并发场景的几个关键参数

前面提到“ai agent 怎么扛并发”，落到实处就是这几个参数：容器池大小、并发上限、请求排队超时、回收频率。我建议先压测你的机器，看单个沙箱从启动到退出的完整周期占多少资源，然后按机器的 CPU 和内存算最大并发。一般来说，1 个容器配置 1 核 1G，8 核 32G 的机器跑 6~8 个并发任务比较稳，再多就会触发内存抖动。

容器池化是 Self-hosted 并发优化的重点。不要每个任务都冷启动一个新容器，而是预先启动若干容器待命，任务分配时从池里取，任务结束归还或重置。重置容器要用快照/镜像回滚，确保上一个任务的痕迹清干净。还有一层是 API 层的限流，FastAPI 可以基于 Redis 做滑动窗口限流，单用户并发太高的请求直接排队或拒绝，防止一个用户的任务把全平台的容器池占满。

8. 常见问题与排查技巧实录

最后分享一些我真实踩过的坑和排查方法。这些东西不在官方文档里，但实操中几乎都会遇到。

8.1 一张表对照常见症状和解决办法

这张表我从项目上线维护到现在一直在更新，每次遇到新问题就补一行。排查手册沉淀下来之后，新同学接手也能快速上手，不用每个坑都重新踩一遍。

8.2 我自己踩过的几个坑

第一个坑是日志泄露。最初我把容器的 stdout 直接流式打到应用日志，Agent 一旦把环境变量或密钥打到 stdout，就会永久记录在日志系统里。后来我加了日志脱敏，用正则匹配常见 key 的格式直接打码，才敢放心收集。第二个坑是时区问题。沙箱容器默认 UTC，Agent 如果做时间相关任务，结果会莫名差 8 小时。我在镜像里预设了TZ=Asia/Shanghai，或者把业务逻辑里的时间统一用 UTC 存储、展示时再转换，避免在容器里改时区引发混乱。

第三个坑是孤儿容器。任务超时被 kill 后，如果没有remove=True，容器会一直停留在 Exited 状态，时间长了堆一堆僵尸。我用定时任务清理所有 Exited 且创建时间超过 1 天的容器，并在创建时统一加上remove=True和标签，方便批量管理。还有一个容易被忽略的细节是容器名冲突，并发任务生成 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 在笼子里飞得又稳又远。