1. Sandcastle 是什么先聊清楚“沙箱编排”这个概念先说我自己的背景。这几年我一直做在线代码执行和自动化评测相关的系统天天跟沙箱打交道。所以当我看到 Matt Pocock 这套用 TypeScript 写的 Sandcastle 框架时第一反应是“终于有人把这一层抽象成框架了”。在正式开始之前得先搞清楚概念上的一个关键区别沙箱和沙箱编排是两层完全不同的事。单个沙箱解决的是“一段不可信代码能不能在我的机器上安全跑起来”的问题。比如你做了一个在线运行 TypeScript 的功能总不能让用户代码直接在你的 Node.js 主进程里跑——一个死循环、一次原型链污染、一次内存暴涨整个服务就没了。所以你需要一个隔离层让不可信代码跑在受限环境中进程级隔离也好、vm 模块也好、iframe 也好本质上都是“圈一块地你别出来”。但现实场景里的需求往往比这个复杂得多。你面对的通常不是一段代码而是几十上百段代码来自不同的用户有各自的优先级、超时要求、资源上限还要支持多种运行环境——浏览器端可能是 iframe Web Worker服务端可能是独立进程或容器。如果每个调用方都自己造轮子去创建、复用、销毁、超时回收沙箱代码很快就会变成一团乱麻而且不同模块之间的资源使用互相不可见搞不好就出现“A 模块开了 50 个沙箱不回收B 模块一个都开不了”的尴尬局面。Sandcastle 的核心思路就是把“沙箱实例”当成一种有生命周期的资源来统一管理再在上层提供一个编排调度层。你提交一个执行任务框架负责分配沙箱、执行代码、回收资源、返回结果。调用方不需要关心沙箱是怎么启动的、跑在哪个进程或哪个 Worker 里、运行完之后有没有被清理干净。这和线程池、数据库连接池的设计哲学完全一致——资源是稀缺的管理必须集中状态必须可控。这篇文章我会从实际使用角度拆解这套方案的设计思路、核心实现、以及我在把类似能力落地到真实项目时踩过的一些坑。适合谁看不管你是做在线判题系统、Web IDE、低代码平台的自定义脚本还是做 AI 代码生成之后的安全执行环境下面这些内容应该都能给你一些参考。2. 为什么需要“编排”而不是单个沙箱2.1 从“隔离”到“资源池化”很多人觉得“只要每个任务都丢进一个沙箱就安全了”。这个想法的漏洞在于它忽略了资源的有限性。沙箱不是免费的每一个沙箱实例都要占用内存、文件描述符、CPU 时间片启动还有成本。创建一个 iframe 很容易但创建几百个 iframe 你的浏览器就会卡死在 Node 里 fork 一个进程很容易但 fork 几百个进程你的服务器直接 OOM。所以当你从“跑一次代码”升级到“跑很多次代码、并且要稳定地跑”的时候问题就变了。你得把沙箱当成资源来池化预创建一批沙箱放在池子里任务来了就从池子里取用完放回去不够用了再动态扩容空闲了再逐步收缩。这就是编排层存在的第一个理由——它让沙箱的供给和任务的消费之间始终维持一个平衡。2.2 编排层要解决的四大问题按我的实践总结一个沙箱编排框架本质上要回答四个问题第一个是调度也就是任务进来之后分给哪个沙箱执行按照什么优先级、什么策略来分第二个是生命周期沙箱什么时候创建、什么时候销毁、任务执行完要不要立刻重置状态第三个是隔离边界任务和宿主之间通过什么协议通信能传什么数据、不能传什么数据第四个是失败处理沙箱挂掉了怎么办、超时了怎么办、任务执行到一半崩溃了怎么让调用方感知。很多自研方案只覆盖了前两个问题。比如有人在代码里写了一个简单的沙箱管理器createSandbox、runTask、destroySandbox 三个函数看起来像模像样但一遇到任务执行到一半崩溃、或者两个任务并发共用同一个沙箱导致状态污染就直接歇菜。Sandcastle 把这四个问题都放进了框架层面调用方只需要面向任务编程而不是面向沙箱编程。2.3 和“每次新建沙箱然后用完就丢”的粗暴方案比有同学会说我每次任务都新建一个沙箱用完直接销毁不就不存在“编排”问题了吗这种方案在小流量下确实能跑但有几个很现实的成本第一是启动开销如果你用容器或独立进程做沙箱每次任务都要承担一次完整的启动时间这个时间可能比任务本身还长第二是资源碎片化频繁创建销毁会导致内存碎片和句柄泄漏跑一晚上之后系统越来越慢第三是不可控的峰值没有池化和限流流量一冲上来沙箱数量跟着暴涨宿主先被打死。编排层做的事情不是“聪明地创建沙箱”而是“让创建和销毁变得可预期”。它给系统加了一个缓冲层——流量再大池子里的沙箱数量是可控的任务再多队列里的等待是有序的。这对生产系统来说比“看起来很高的上限”重要得多。3. 核心架构Sandcastle 风格的分层设计3.1 沙箱实例的生命周期管理先说生命周期。按我理解的 Sandcastle 的设计思路一个沙箱实例大致经历这么几个状态空闲、忙碌、重置、销毁。空闲状态表示沙箱已经初始化好、但没有在执行任务可以随时被分配忙碌状态表示正在跑代码重置状态是任务执行完之后框架把沙箱里残留的全局变量、定时器、事件监听器全部清掉恢复到初始状态销毁则是资源回收可能因为长期空闲、也可能因为沙箱本身已不可信。这看起来简单但真正做好很难。我见过很多自研方案死在“重置”这一步——跑完一次代码之后不清状态第二个任务进来直接复用结果第一个任务里定义的全局变量污染了第二个任务的运行结果。更隐蔽的是定时器和事件监听器泄漏比如第一个任务里 setInterval 没清沙箱虽然“空闲”了但后台定时器还在跑CPU 白白被吃掉。生命周期管理的核心原则是一个沙箱从忙碌变回空闲必须是“全新”的空闲而不是“残留”的空闲。用什么手段达到这个状态取决于沙箱的隔离等级。如果是浏览器 iframe最简单粗暴的方案是直接重建 iframe 的 contentWindow或者 reload 一下如果是 Node 的 vm 模块可以用 vm.createContext 重新创建一个新的 context 对象把旧的丢弃。宁可重置成本高一点也不要抱着侥幸心理去复用脏状态。3.2 通信协议与数据交换编排层和沙箱之间必须有通信机制否则任务怎么传进去、运行结果怎么传出来Sandcastle 在这块的设计很有参考价值它把通信通道抽象成标准的请求-响应模型而不是让调用方直接操作底层通道。在浏览器场景里通信通道通常是 postMessage在 Node 场景里可以是 child_process 的 IPC也可以是 worker_threads 的 MessagePort。无论底层是什么协议层的设计都差不多调用方向沙箱发送一个任务描述包含代码、输入参数、超时时间沙箱执行完回传一个执行结果对象包含返回值、日志、错误信息、运行时统计。通信协议要解决的一个关键问题是序列化边界——传进去的对象必须可序列化函数、类实例、原型链这种东西在沙箱边界上都是传不过去的传到一半要么报错要么变成空对象调用方还很难排查。另一个容易被忽略的点是输出截断。用户代码可能往 console.log 里扔几兆字符串如果不截断这些数据全都要跨通信通道传回来然后塞进你的内存里。所以编排层在协议层面就要做输出限制——多少字节以内直接传超过之后截断并加个标记。这个限制必须在协议层做放到应用层往往就晚了。3.3 资源配额与调度策略调度策略决定了系统的公平性和吞吐量。Sandcastle 这类框架通常会提供两种调度模式简单队列和优先级队列。简单队列就是先进先出任务按提交顺序执行适合所有任务地位平等的场景优先级队列则是每个任务带一个优先级字段高优先级的任务可以插队适合生产环境里“普通任务让路给紧急任务”的情况。资源配额的粒度也需要想清楚。我自己的实践是至少分三层时间配额单个任务最长执行多久超时直接 kill内存配额沙箱能申请到多少内存超出就报错退出并发配额同一个沙箱实例同时最多服务多少个任务。第三条很多人会忽略但它在浏览器 iframe 场景特别重要——一个 iframe 同时只能跑一个主线程任务你要是把两个任务同时丢给同一个 iframe它们会互相卡死产生完全不可预期的结果。4. 实操从零搭一个 Sandcastle 风格的沙箱编排器4.1 环境与代码骨架聊完理论上点实操。我假设的场景是用 Node.js通过 worker_threads 做沙箱隔离外层实现一个任务队列来编排。选择 worker_threads 而不是 child_process 或者 vm 模块理由有三个一来 worker_threads 共享进程内存空间启动开销比子进程小得多二来它有标准的 MessageChannel通信协议写起来顺手三来它和主进程天然隔离了全局作用域比 vm 模块这种“用代码模拟隔离”的方案靠谱得多——vm 模块逃逸漏洞历史上出过不少能用进程级隔离就不用语言级隔离。先看骨架代码。定义一个沙箱工厂负责创建 Worker 并且绑定通信逻辑// sandbox-factory.ts import { Worker } from node:worker_threads; import { EventEmitter } from node:events; export interface SandboxTask { id: string; code: string; args: unknown[]; timeoutMs: number; } export interface SandboxResult { id: string; ok: boolean; data?: unknown; error?: string; logs: string[]; durationMs: number; } export interface SandboxInstance { worker: Worker; busy: boolean; lastUsedAt: number; } export function createSandboxInstance(): SandboxInstance { const worker new Worker(./sandbox-worker.js, { workerData: { sandboxId: crypto.randomUUID() }, }); return { worker, busy: false, lastUsedAt: Date.now(), }; }这里有个细节每个沙箱实例在创建时就绑定了一个全局唯一的 worker后续所有任务调度都以这个实例为单位。不要让一个 worker 同时执行两个任务虽然在技术上 MessageChannel 可以区分消息但两个任务共享 worker 里的全局状态风险非常大。把“一个沙箱同时只跑一个任务”当作铁律比花力气去做并发隔离要省心得多。4.2 实现任务队列、超时与回收接下来是编排器本体。我在实际项目中经常用这样一套组合一个可用沙箱池、一个等待队列、一组超时定时器。核心逻辑是——任务来了先去池子里拿一个空闲沙箱池子空了就等任务完成后再继续或者扩容创建新沙箱。任务执行期间设置一个超时定时器超时就把 worker terminate 掉然后重新创建。// orchestrator.ts import { EventEmitter } from node:events; import { createSandboxInstance, SandboxInstance, SandboxResult, SandboxTask } from ./sandbox-factory; export class SandboxOrchestrator extends EventEmitter { private pool: SandboxInstance[] []; private taskQueue: SandboxTask[] []; private activeTasks new Mapstring, { timer: NodeJS.Timeout }(); constructor(private maxPoolSize 10) { super(); } async submit(task: SandboxTask): PromiseSandboxResult { const instance this.acquireSandbox(); const result await this.runWithTimeout(instance, task); this.releaseSandbox(instance, task.id); return result; } private acquireSandbox(): SandboxInstance { let instance this.pool.find((s) !s.busy); if (!instance) { if (this.pool.length this.maxPoolSize) { instance createSandboxInstance(); this.pool.push(instance); } else { // 等待有空闲沙箱回收后再分配实际项目中应配合事件通知 return this.waitForAvailable(); } } instance.busy true; instance.lastUsedAt Date.now(); return instance; } private runWithTimeout(instance: SandboxInstance, task: SandboxTask): PromiseSandboxResult { return new Promise((resolve, reject) { const timer setTimeout(() { // 超时直接杀掉 worker宁可重建也不要留下僵尸沙箱 instance.worker.terminate(); const fresh createSandboxInstance(); const idx this.pool.indexOf(instance); this.pool[idx] fresh; reject(new Error(task ${task.id} timed out after ${task.timeoutMs}ms)); }, task.timeoutMs); instance.worker.once(message, (msg: SandboxResult) { clearTimeout(timer); resolve(msg); }); instance.worker.postMessage({ code: task.code, args: task.args }); }); } private releaseSandbox(instance: SandboxInstance, taskId: string) { // 这里很重要释放之前重设状态防止脏数据影响下一个任务 instance.busy false; instance.lastUsedAt Date.now(); this.emit(available); } }这段代码省掉了 waitForAvailable 的具体实现真实项目里可以加一个条件变量或者 Promise 队列。我在实际项目中踩过的一个坑是拿到空闲沙箱之后忘了把 busy 置回 false导致这个沙箱永远“忙碌”池子最终被占满所有新任务都进入等待状态系统表现为“没有任何报错但任务全部卡住”。这类状态标识错误非常难排查因为日志和监控看到的基本都是正常的只有跑一段时间才能发现吞吐量骤降。超时处理上也有个细节值得说超时之后杀掉旧 worker、立刻创建新 worker 补位这个动作背后有个潜台词——沙箱一旦超时就不能再相信它了。超时可能是死循环也可能是资源泄漏导致的运行缓慢不管是哪种这个沙箱的内部状态都不可靠了继续复用风险太大。所以我的经验是超时之后直接报废宁可多花一次启动成本也不要拿稳定性赌。4.3 在浏览器与 Node 场景中的落地差异如果你不是做服务器端而是想在浏览器里跑这个框架比如你做了一个网页版的代码编辑器希望用户点一下“运行”在页面上直接跑 JS那么核心逻辑一致但沙箱的实现载体要从 worker_threads 换成 iframe Web Worker 的组合。浏览器端的主线程是金贵的所有计算必须放到 Web Worker 或者 iframe 的独立线程里避免阻塞页面渲染。我的常用组合是外层用 iframe 做执行容器通过 sandbox 属性禁用弹窗、导航、表单提交等能力iframe 内部再起一个 Web Worker 跑纯计算这样即使代码写得很烂也只会卡住 Worker不会卡住 iframe 的渲染线程。浏览器端的资源限制比服务端严苛得多。你不能真正意义上限制一个 Worker 的内存只能通过 performance API 和多次采样来估算。实际操作中我一般会在任务运行时周期性发送一个“心跳”消息主线程根据心跳间隔判断任务是死循环了还是正常运行——心跳间隔突然变长就说明事件循环被阻塞了。这个方案虽然不是精确测量但在浏览器场景里是最实用的判断手段。4.4 任务定义与结果契约不管底层是 Worker 还是 iframe任务和结果的协议建议固化成一个版本化接口不要用自由格式的对象。版本化接口的意思是说协议里带一个 version 字段后续升级解析逻辑的时候可以通过版本判断走新逻辑还是老逻辑。// protocol.ts export const SANDBOX_PROTOCOL_VERSION 1.0.0; export interface SandboxRequest { version: string; requestId: string; action: run | inspect | reset; payload: { script: string; input?: Recordstring, unknown; options?: { maxLogSize?: number; env?: Recordstring, string; }; }; } export interface SandboxResponse { version: string; requestId: string; ok: boolean; result?: unknown; error?: { name: string; message: string; stack?: string; }; logs: string[]; stats: { startedAt: number; finishedAt: number; memoryUsage: number; }; }我特别想强调 stats 里的 memoryUsage这个字段很多人不重视。它记录的是执行完任务后沙箱的实时内存如果连续多个任务执行后内存使用是递增的基本可以判定沙箱里有泄漏。在自研沙箱系统的运营中这个字段是排查问题的第一线索。5. 踩坑实录与排查技巧5.1 为什么会漏杀 Worker 导致句柄耗尽我遇到最典型的问题是任务执行到一半、报错之后对应的 Worker 没有被 terminate。原因是代码只监听了 message 事件没有监听 error 事件——任务里抛了个异步异常Worker 直接就挂了主线程这边完全不知道等下一个任务来的时候又把消息发给了这个已经死掉的 Worker。postMessage 在给死掉的 Worker 发送时会抛一个异常但如果你没做错误处理这个异常会直接让主线程炸掉。排查技巧所有 task 提交的地方统一包一个 try/catch并且沙箱 Worker 上同时挂 error 和 exit 监听器。一旦 exit池子里对应的实例立刻移除下次任务来了重新创建。不要试图“救活”一个已经退出的 WorkerJavaScript 的 Worker 生命周期是不可逆的。5.2 沙箱逃逸的边界问题沙箱逃逸是个绕不开的话题。用语言级方案做沙箱比如 vm 模块时逃逸风险是真实存在的。边界需要从根上讲清楚凡是能访问 Node.js 原生 API 的代码理论上都有办法绕过限制。所以如果你要执行的是完全不可信的代码我建议直接上进程级隔离方案如果只是限制团队成员或者低风险用户语言级隔离在成本和安全性上是个可接受的平衡。我自己的安全冗余习惯是进程级隔离做主体语言级限制做纵深防御。也就是说即使代码跑在单独的 Worker 进程里我依然会在代码运行前用语法分析的方式拦截明显的危险操作——比如 require、process.binding、globalThis 上的可疑属性访问。拦截规则不用太复杂能挡住 80% 的明显攻击就够了剩下的交给进程隔离兜底。5.3 调度饿死与公平性另一个很隐蔽的问题是调度饿死。当大量高优先级任务持续涌入时低优先级任务可能永远排不上形成“饿死”。我之前在线上系统里遇到过一个定时任务每个月跑一次数据清理因为优先级设得低被一天几万条的业务任务一直挤在队列末尾等了一个多小时都没执行。解决方案不复杂给等待队列加一个“等待时间老化因子”。任务在队列里待得越久它的有效优先级越高。具体实现就是在排序函数里把 waitingTime 乘一个权重加进优先级计算里让低优先级任务也有机会被调度。这个细节容易忽略但生产环境早晚会碰到。5.4 通信封包过大导致的内存爆炸最后一个值得说的坑是跨沙箱传输大对象。如果你让用户代码的返回值可以是一个任意对象那这个对象可能非常大。沙箱执行完把所有返回值都序列化通过通信通道传回主线程一次性塞进内存服务瞬间被打满。解决办法是给返回值做硬限制超限就直接截断或者报错。我在实际项目中给返回值上限设为 100KB日志上限 50KB超过上限的一律截断并在结果里标记 truncated: true。宁可让用户埋怨“输出被截断了”也不能让一个不小心循环拼接字符串的任务把整个宿主进程的内存打爆。6. 个人体会与后续扩展最后聊一些我的主观感受。沙箱编排这个领域难的不是写代码而是做取舍。每往上叠一层安全措施都要付出性能或复杂度的代价每做一个抽象都要防止把底层细节泄漏给调用方。Matt Pocock 这套框架给我最大的启发是它把“沙箱”和“编排”拆成了两个可以独立演进的模块。底层沙箱实现可以替换——今天用 Worker明天换 Docker都不会影响上层 API上层调度策略也可以单独调整——从简单队列换成优先级队列、从单机池化变成多机调度都只是替换一个实现类的事。如果你看完这篇文章想自己动手做一版我的建议是从最小闭环开始先做一个沙箱能跑任务紧接着就写任务队列和超时回收然后再考虑池化和优先级。顺序不能乱因为超时回收是沙箱系统的保命功能没有它后面的所有优化都是空中楼阁。最后再分享一个经验千万不要一上来就追求“高并发沙箱编排”。先跑通一个沙箱、再跑通一百个、再跑通一百万个每跑大一个量级你会对资源的理解深入一层。这种理解是看多少文档都换不来的也是这套框架真正想让人掌握的东西。