Activepieces Worker 即沙箱架构解读单 Worker 单任务、按副本横向扩容的执行模型【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces导读本篇围绕 Activepieces 决策记录ADR000001-worker-is-the-sandbox-one-job-per-worker-scale-by-replicas.md 展开剖析其核心架构决策Worker 进程与执行沙箱合二为一一个 Worker 只并发处理一个任务concurrency 1并行能力完全靠增加 Worker 副本replicas横向扩展。阅读本文后你将理解该模型如何替代Worker 管理沙箱池的旧方案、为什么自托管只需要多开几个 Worker即可扩容以及围绕引擎内存上限、V8 堆参数、镜像体积等关键工程细节踩过的坑与修复方式并能在 worker.ts 等源码中找到一一对应的实现证据。一、决策背景从池化沙箱到Worker 即沙箱1.1 决策内容ADR 000001 给出了一条非常直接的主线Worker 和沙箱坍缩为同一个单元。一个 Worker 轮询一个任务并发度为 1、完成解析后在其进程内的 boxnode 子进程 isolated-vm中运行 engine。不存在独立的沙箱容器、不存在/execute跳转、不存在 Docker socket、不存在沙箱池。并行是横向的N 个 Worker 副本每个副本上限 0.5 CPU / 1 GB 内存。翻译成部署语言就是自托管 Activepieces 时扩容 增加 Worker 容器副本数而不是像某些自动化平台那样维护一个沙箱资源池并做复杂的调度。1.2 被取代的旧探索LOCAL_POOL / GCP_CLOUD_RUN决策记录明确说明该模型取代了一次短暂存在的LOCAL_POOL / GCP_CLOUD_RUN 探索——即Worker 作为池管理器的架构它通过 HTTP 与远端沙箱通信依赖 Docker socket 和一个远程 HTTP 边界。这一旧模型有两个突出负担Docker socket 依赖Worker 需要挂载并操作 Docker socket 来创建/销毁沙箱容器这是当时模型里最大的安全风险面远程传输边界Worker 与沙箱之间多了一条/execute的 HTTP 跳转需要额外维护协议信封、供给器provisioner等大量胶水代码。ADR 的结论是放弃这条路线回到一个受限容器就是一个执行单元的朴素模型。1.3 为什么这样做四点收益决策记录给出了四个核心理由均可作为理解架构的切入点去掉 Docker socket消除了旧模型最大的安全风险Worker 不再具备 Docker 守护进程的操作能力OOM 影响面收敛每个受限容器只跑一个任务一次内存溢出OOM只杀死一个 Worker不会牵连其他任务同时彻底杜绝了复用进程内槽位可能导致的共享堆累积shared-heap ratchet问题——即多个任务共用同一个进程导致内存水位不断抬高单条执行路径不存在池管理器 ↔ 沙箱的接缝seam、没有远程传输、没有供给器、没有需要同步维护的 HTTP 信封代码量大幅减少沿用既有的扩容方式自托管本就是加 Worker的模型该决策让扩容语义与既有运维习惯完全一致。二、架构核心Worker 内部的执行链路要真正理解Worker 即沙箱需要结合 packages/server/worker/src/lib/worker.ts 的轮询与执行主循环来看。2.1 轮询循环与并发控制Worker 启动后通过 Socket.IO 与 API 服务建立长连接随后进入pollAndExecute循环向 API 轮询领取任务apiClient.poll(machineInfo)、执行、上报结果apiClient.completeJob期间每 30 秒调用apiClient.extendLock延长任务锁避免任务被 BullMQ 判为 stalledworker.ts。并发度由环境变量AP_WORKER_CONCURRENCY控制默认值为5该默认值注册在 configs.ts 的默认配置表中以保持旧行为。源码中的注释明确标注了两个相邻 ADR 的分工worker.tsADR 000001本文目标是一个 box 一个 Workerconcurrency 1用副本扩缩容ADR 000002过渡模式在正式收敛前仍支持AP_WORKER_CONCURRENCYN通过运行 N 个进程内 box各自带 workerIndex 路由兼容多并发。也就是说当前代码里每 Worker 单任务是目标形态AP_WORKER_CONCURRENCY1是过渡兼容形态。源码特别提醒当 N1 时一次 OOM 会同时带走 N 个在途任务因此运维必须按 N 倍大小配置容器。2.2 引擎如何在进程内运行无论哪种模式引擎都通过createSandboxRuntime创建运行时box 内执行路径由 packages/server/sandbox/src/lib/create-sandbox-for-job.ts 负责它根据执行模式EXECUTION_MODE选择进程工厂——沙箱隔离模式走isolateProcess非沙箱/仅代码沙箱模式走simpleProcess即child_process.fork并统一解析内存上限SANDBOX_MEMORY_LIMIT、设置--max-old-space-size等引擎启动参数create-sandbox-for-job.ts。“Worker 即沙箱”体现在engine 子进程不是跑在远端或另一个容器里而是由当前 Worker 进程直接 fork 出来simpleProcess使用child_process.fork见 fork.ts即使是 isolate 沙箱模式也只是在 Worker 进程内用 isolate 工具包再包一层仍然没有独立的沙箱容器。2.3 网络与结果上报由于引擎在 Worker 进程内它访问 API 走的是 Worker 自己的应用地址与 API 同机部署时走集群内地址独立部署的 Worker 则走公共 URLensurePublicApiUrl见 worker.ts。执行结果通过completeJob回传异常路径统一映射为EngineResponseStatus.INTERNAL_ERROR。三、后果与约束吞吐量 副本数ADR 的 Consequences 部分直接给出了该模型的定价吞吐量 副本数量Throughput replica count。这意味着单个 Worker 的能力是固定上限的决策记录给出的参考资源为0.5 CPU / 1 GB每个副本提升整体吞吐的手段只有水平扩容不存在给单个 Worker 加并发的纵向优化空间那是 ADR 000002 的过渡模式才做的事因此Worker 镜像必须自带完整的执行工具链engine isolated-vm bun esbuild以保证每个副本开箱即跑。3.1 镜像体积的约束与对策执行工具链全部打进镜像会显著增大体积决策记录指出两条控制手段esbuild 单文件打包engine 以 esbuild 打成单文件 bundle避免把整个依赖树原样塞进镜像懒加载 chat agent与聊天/Agent 相关的重模块按需加载不进入启动路径。这两点与AP_PREWARM_CACHE_ON_STARTUP默认 false见 configs.ts配合使用需要时可在启动时预热并编译所有已启用的 flow但预热的内存/CPU 尖峰随 flow 数量增长小规格 Worker 在大实例上可能因此 OOM因此默认关闭、按需开启worker.ts。3.2 暂不回归 Cloud Run 远程主机ADR 明确现阶段不设 Cloud Run 目标。原因很直接——重新引入远程主机就等于重新引入 HTTP 边界恰好是 1.2 节被淘汰的东西。这保证了执行路径始终只有一条。3.3 POC 状态说明决策记录最后坦承该方案当时的状态是POC仅通过 docker-compose 验证尚未固化为生产级镜像。这是重要的上下文——它说明该 ADR 描述的是架构方向与已验证的可行性而镜像加固属于后续工程任务。四、两个关键工程陷阱Gotchas的源码级验证ADR 的最后一部分记录了执行过程中踩到的两个真实 bug这是全篇信息密度最高的部分且都能在当前仓库源码中找到修复痕迹。4.1 陷阱一除--max-old-space-size外没有任何东西限制引擎内存决策记录指出isolate 本身不施加内存限制调用时既没传--mem也没传--cg-mem因此--max-old-space-size是唯一的内存边界。更严重的旧 bug 是isolate.ts曾把resourceLimits直接丢弃只解构了sandboxId, mounts, env导致两种 isolate 模式下引擎都运行在V8 默认堆上SANDBOX_MEMORY_LIMIT变成了死配置同时丢掉了--expose-gc使引擎在worker-socket.ts中每 60 秒一次的强制 GC 循环静默失效global.gc未定义时该循环是 no-op。故障现象链引擎内存涨破容器 → 内核 OOM killer SIGKILLisolate 只上报SG: Caught fatal signal 9→ 运行以SANDBOX_INTERNAL_ERROR收尾并触发 on-call 分页而不是预期的MEMORY_LIMIT_EXCEEDED——错误语义被彻底掩盖。修复抽出一个共享的engineNodeArgs()同时被fork.ts和isolate.ts使用。当前实现位于 packages/server/sandbox/src/lib/sandbox/node-args.ts三个参数缺一不可参数作用--no-node-snapshot只要加载 isolated-vm 就必须带对应 isolated-vm#424 问题isolate 路径也不例外——因为SANDBOX_CODE_AND_PROCESS会在 isolate 沙箱内部再跑 isolated-vm 执行代码步骤--expose-gc让引擎周期性的强制 GC 真正生效避免内存水位失控--max-old-space-size${memoryLimitMb}唯一的引擎内存硬边界直接来自解析后的沙箱内存限制isolate.ts在构造命令时显式把这三个参数传给沙箱内的process.execPathisolate.tsfork.ts则通过execArgv注入fork.ts两条路径行为完全一致——这正是共享 helper修复的初衷。4.2 陷阱二内存预留必须放在预算被推导的地方而不是被应用的地方--max-old-space-size必须低于容器内存上限因为 V8 的 old space 只是 RSS 的一部分——new space、外部缓冲区、每个 128 MB 的 isolated-vm 堆、原生分配以及 Worker 进程本身都要算进 RSS。但预留reserve不能在 node-args 辅助函数里做一刀切百分比原因很微妙在默认AP_WORKER_CONCURRENCY5下SANDBOX_MEMORY_LIMIT是运维手动配置的数值默认 1024 MB与容器实际大小无关此时给它再砍掉 25% 只会白白剥夺本来就没问题的自托管用户的工作内存而 concurrency-1 的路径本 ADR 的目标形态里内存预算从memory.max推导此时 100% 被证明不可用预留才真正必要。因此决策记录给出的落点是预留逻辑存在于sandbox-config.ts的primeFullContainerMemory()即 concurrency-1 的路径它是唯一100% 不可用被证明的地方而显式配置的SANDBOX_MEMORY_LIMIT则被精确遵守honored exactly不做任何缩减。这一点也呼应了 configs.ts 中把AP_WORKER_CONCURRENCY、AP_REUSE_SANDBOX、AP_CACHE_BASE_PATH等作为 Worker 系统属性的设计——这些环境变量决定了内存预算的推导方式进而决定预留逻辑是否参与。4.3 第三个强制项--no-node-snapshot决策记录特别强调--no-node-snapshot是强制性的只要 isolated-vm 被加载就必须带对应 isolated-vm#424 问题。注意它同时覆盖 isolate 路径因为SANDBOX_CODE_AND_PROCESS模式会在 isolate 沙箱内部再用 isolated-vm 执行代码步骤所以 isolate 命令构造里同样通过engineNodeArgs()带上了该参数isolate.ts。源码注释中标注了IMPORTANT DO NOT REMOVE THIS ARGUMENT提醒后人不要误删。五、横向扩容的运维要点总结综合 ADR 与源码实现自托管部署Worker 即沙箱模型时需要注意以下要点扩容方式增加 Worker 副本replicas参考单副本资源为 0.5 CPU / 1 GB吞吐量与副本数线性相关并发模式目标形态是AP_WORKER_CONCURRENCY1一个 box 一个任务若显式设AP_WORKER_CONCURRENCYN默认 5属于 ADR 000002 的过渡兼容模式容器需按 N 倍内存配置且 OOM 会波及全部 N 个在途任务内存边界引擎内存只由--max-old-space-size约束engineNodeArgs()统一注入该值必须低于容器上限显式设置的SANDBOX_MEMORY_LIMIT会被精确执行而 concurrency-1 路径的预留逻辑位于sandbox-config.ts的primeFullContainerMemory()镜像构成Worker 镜像必须自带 engine isolated-vm bun esbuild通过 esbuild 单文件 bundle 与懒加载 chat agent 控制体积安全面该模型移除了 Docker socket 依赖Worker 不再触碰 Docker 守护进程攻击面显著收敛状态认知该 ADR 记录的是经 docker-compose 验证的 POC 架构方向生产镜像加固是后续独立工程。六、延伸阅读决策记录原文000001-worker-is-the-sandbox-one-job-per-worker-scale-by-replicas.md同系列相关决策000002-transitional-multi-box-concurrency-honor-ap-worker-concurrency.mdWorker 轮询与执行主循环worker.ts引擎启动参数统一入口node-args.ts沙箱进程工厂fork / isolatefork.ts、isolate.ts沙箱创建与内存解析create-sandbox-for-job.tsWorker 系统属性与默认值configs.ts【免费下载链接】activepiecesAI Agents MCPs AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows AI Agents • MCPs for AI Agents项目地址: https://gitcode.com/GitHub_Trending/ac/activepieces创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考