Activepieces Worker 内存泄漏诊断实战从 OOM 定位到 V8 堆快照与 Retainer Path 归因【免费下载链接】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 自托管场景中最常见也最隐蔽的一类问题worker 容器内存随 Pod 存活时间增长、worker 自行重启、或容器长期贴近内存上限运行。你将掌握一套完整的诊断流水线——先在 cgroup 层面确认是否真的被 OOM 杀死并定位是哪个进程再区分 JS 堆泄漏与原生内存增长然后在不把敏感快照带出宿主机的前提下就地抓取 V8 堆快照、在容器外解析直方图最后沿 retainer path保留路径一路走回持有内存的那行代码。整套方法源自仓库内的排障技能文档 .agents/skills/profile-worker-memory/SKILL.md并结合 workers.md 记录的真实生产事故与 cache-state.ts 等源码实现进行交叉印证。0. 排障前提先理解 Activepieces 的 worker 形态在动手之前先确认你面对的是哪种部署形态因为 SKILL.md 中的部分命令依赖它。0.1 Worker 即沙箱进程模型Activepieces 的 worker 是独立的 Node 进程负责从应用侧拉取任务并执行 flow/trigger。关键点在于worker 本身就是沙箱——它通过activepieces/sandbox的createSandboxRuntime在进程内 fork 引擎不存在独立的沙箱池。目标部署模型是一盒一 workerconcurrency 1横向扩展靠小规格副本这样一个 OOM 只杀死一个任务而不是共享池中的一片任务见 workers.md。这也解释了为什么要单独诊断 workerworker 进程与其 fork 出的引擎子进程共处同一个 cgroup 内它们的--max-old-space-size上限在同一容器里叠加诊断时必须把两者区分开详见第 1 节和第 3 节。0.2 监督单元的版本差异PM2 时代 vs 容器即监督单元SKILL.md 多处提到pm2 list、pm2 jlist这对应的是容器内用 pm2 托管 worker的历史形态。而当前仓库主分支已经移除了 pm2docker-entrypoint.sh用普通node --enable-source-maps直接启动 bootstrap 脚本WORKER模式让单个 node 进程充当 PID 1WORKER_AND_APP模式同时跑两个进程任一退出都会杀死另一个并以非零码退出交由编排器重建整个容器见 docker-entrypoint.sh 与 workers.md 的 Gotchas。两种形态下OOM 但容器看起来正常的表现完全不同PM2 形态OOM 杀死的是 pm2 的子进程pm2 每约 4 分钟静默重启它容器始终保持Updocker stats看起来一切正常——这正是 SKILL.md 说的容器从不离开 Up的陷阱容器监督形态OOM 直接杀死 PID 1容器死亡并被编排器重建RestartCount会如实增长。本文完整保留 SKILL.md 的原始排查步骤含 pm2 命令适用于存量 PM2 部署并在各处标注当前主分支形态下的等价做法。两种形态下docker inspect的OOMKilled标志、dmesg的 cgroup OOM 记录、以及整套快照分析流程都是通用的。0.3 核心记忆点cache-state 是纯磁盘缓存诊断本文主角泄漏第 5 节前先记住 worker 缓存的底层设计cache-state.ts实现的是一个刻意不在内存中保留任何数据的磁盘缓存——每次getOrSetCache都从cache.json重新读取见 cache-state.ts。这一点是理解什么才是泄漏的基准线磁盘缓存本身不是内存问题内存问题只会来自那些绕过了这一设计、把数据留在模块级对象里的代码路径。1. 第一步确认它真的被 OOM 杀死并找到死的是谁1.1 不要被docker ps骗了PM2 形态下worker 子进程被 OOM 杀死后 pm2 会把它重启回来容器从不离开Updocker ps与docker stats看起来都平静如水。真正的信号藏在下面三条命令里docker inspect container --format {{.State.OOMKilled}}|{{.RestartCount}} docker exec container pm2 list # ↺ 列是崩溃计数 dmesg -T | grep -aiE Memory cgroup out of memory|Killed process判读规则OOMKilledtrue出现在一个正在运行的容器上意味着 cgroup OOM-killer 杀死了某个子进程而 PID 1 幸存下来——这正是 PM2 形态的典型特征。workers.md记录的一次真实事故中全舰队 448 个容器有 445 个带State.OOMKilledtrue同时docker stats全部正常dmesg是最终裁决它给出的进程名会被截断为 15 个字符。node /usr/src/a是worker其入口为packages/server/worker/dist/src/bootstrap.js而引擎运行路径是/usr/local/bin/node。把这个认反了你会对着错误的进程做全套快照分析。1.2 主分支形态的等价判读在移除 pm2 的当前形态下把第 2 条换成检查编排器如 Helm 的 deployment rollout / statefulset中该容器的重启次数与最后退出原因dmesg的 cgroup OOM 记录与OOMKilled标志依然成立。workers.md还给出了一条补充口径当 worker 的NODE_OPTIONS--max-old-space-size与引擎子进程的--max-old-space-size来自SANDBOX_MEMORY_LIMIT默认 1048576 KB 1024 MB在同一容器内叠加时V8 可能永远感觉不到压力直到内核在更低的 RSS 水位把它杀死——这类容量不匹配的 OOM 与泄漏无关排障时不要先入为主详见第 5.4 节。2. 第二步JS 堆还是原生内存快照前先做决定堆快照只能看到 V8 堆内部如果泄漏在堆外native 侧快照会给你看一个空无一物的结果。所以动手抓快照之前先用两条命令区分docker exec c pm2 jlist # pm2_env.axm_monitor[Used Heap Size] docker exec c cat /proc/pid/smaps_rollup对比Used Heap Size与RssRSS 在涨、堆也跟着涨→ JS 堆泄漏继续抓快照RSS 在涨、堆保持平坦→ 原生内存增长isolated-vm、Buffer、native addon堆快照对你毫无帮助应该转向分析smaps_rollup中各映射段的增长。worker 的基线经验值约为堆大小 约 100 MB 固定开销workers.md的实测off-heap 保持约 100 MB 平坦。换句话说如果 RSS 增长但堆没动多出来的那部分几乎可以断定在原生侧。在选目标之前先对宿主机上所有容器采样一遍优先快照堆最大的那个——它最接近泄漏现场命中率最高。3. 第三步就地抓取快照快照永远不离开宿主机3.1 先抬高 cgroup快照后必须还原序列化堆是一个会临时分配大量内存的操作一个 1 GiB 的容器会在快照序列化中途被 OOM 杀死。因此在抓取前先把 cgroup 内存上限抬高结束后必须还原并验证docker update --memory 6g --memory-swap 6g container # ... 抓快照 ... docker update --memory 1g --memory-swap 1g container docker inspect container --format {{.HostConfig.Memory}} # 确认已还原一个必须知道的限制cgroup 可以抬高--max-old-space-size抬不了。如果进程的 V8 上限本来就小于堆的实际大小序列化中途照样会被 V8 自己掐死。workers.md的实测口径是堆约 950 MB 时全量快照会杀死进程可以靠抬 cgroup 缓解但无法改变--max-old-space-size抓取目标应选在 RSS 约 430–600 MB 区间的 worker太低没有代表性太高则序列化过程本身就会杀人。3.2 两个能省一个小时的机制陷阱陷阱一引擎进程被改名为sandbox-nanoid。直接按/usr/local/bin/node匹配会找到代码步骤的子进程——它大约只有 45 MB拥有自己独立的模块注册表require.cache只有 1 条跟 pieces 毫无关系。要匹配引擎必须读/proc/pid/cmdline找sandbox-*。镜像里没有ps直接遍历/proc。陷阱二Node 的全局WebSocket连不上 V8 inspector。握手会被接受然后 socket 带着一个光秃秃的错误死掉。要用镜像里自带的ws库find /usr/src/app/node_modules -type d -name ws -path *node_modules/ws连接参数必须带{ perMessageDeflate: false, maxPayload: 0 }。3.3 用 CDP 驱动快照向目标进程发送SIGUSR1打开 inspector然后通过127.0.0.1:9229驱动 Chrome DevTools Protocolprocess.kill(pid, SIGUSR1) // 打开 inspector // GET /json/list - webSocketDebuggerUrl然后在 socket 上依次 // HeapProfiler.enable // HeapProfiler.collectGarbage - 先回收你才能看到存活对象而非垃圾 // HeapProfiler.takeHeapSnapshot // 把 HeapProfiler.addHeapSnapshotChunk 事件流式写入文件collectGarbage这一步是承重的不做它直方图里全是可回收的垃圾真正的 retainers 会被埋在下面。3.4 只需要身份时根本不用抓快照如果问题只是哪些模块驻留在内存里而不是谁 retain 了这个对象一次Runtime.evaluate就能用几 KB 的代价回答且不可能触发 OOM// returnByValue: true, includeCommandLineAPI: true const cache process.mainModule.constructor._cache const keys Object.keys(cache) // → totalModules、匹配 activepieces/shared 与 pieces-framework 的数量、 // 不同的 activepieces/piece-* 包数量、以及 process.memoryUsage()要拿到正确的时机窗口在某个 flow 正持有 sandbox 时对着sandbox-id的 pid 执行。为了制造这个窗口探针 flow 要以一个会 sleep 的 CODE 步骤结尾——注意不能用delaypiece 步骤超过 10 秒的 delay 会创建 waitpoint 并暂停运行、释放 sandbox等你赶到时目标进程已经没了。workers.md记录了这套轻量探测的真实战绩用Runtime.evaluate对比加载过的引擎2615 个模块 / 9 份驻留 shared / 517 MB GC 后堆 / 668 MB RSS与全新引擎8 个模块 / 46 MB / 183 MB RSS直接证明了require.cache是引擎内存的 step function——内存随这个引擎服务过多少个不同的 piece 包增长空闲时间不增加任何东西。4. 第四步把快照拿到 worker 进程外解析永远不要在被约束的容器内解析快照——解析本身的内存开销会让它再次 OOM。用docker cp把快照拷出来放进一个用同一镜像启动的一次性 fat 容器里解析docker run --rm --memory 10g -v /tmp:/data --entrypoint node image \ --max-old-space-size8192 /data/parse.js /data/heap.heapsnapshot快照格式是扁平的类型化数组由snapshot.meta描述布局读node_fields得到步长stride然后遍历nodes按strings[name]分组累加self_size。这一张直方图通常就能直接说出泄漏的名字谁占了多少字节但它回答不了谁持有它。5. 第五步走 retainer path——这才是答案直方图告诉你什么被 retain只有 retainer path 告诉你谁持有它而那才是你要改的那行代码。构造方法把firstEdge建成每个节点edge_count的前缀和从节点 0 出发做 BFS为每个节点记录父节点从罪魁节点沿父指针一路回溯到根打印边名——路径上的属性名就是源码里的变量名。5.1 真实案例2026-08 的 worker 泄漏workers.md与 SKILL.md 记录的是同一桩事故。那次泄漏最后两步边就是完整诊断Object property:/usr/src/app/cache/v13/bundles/flowVersionId - Object property:flowVersionId - string {\flowVersion\:… [90 MB]一个模块级对象以缓存路径为 key持有整个 flow bundle 清单flowVersion pieces 全部编译代码且从不驱逐。代码位置是packages/server/sandbox/src/lib/cache/flow/flow-bundle-store.ts所在的缓存树——泄漏根因正是cache-state.ts之外那份无界内存缓存。5.2 从源码看懂这次泄漏的规模模型flow-bundle-store.ts的tryFetch把flowVersionId同时用作目录路径与cache.json的 key见 flow-bundle-store.ts而flow-cache.ts同样把flowVersionId放进路径。问题在于当这些路径同时被某个无界内存对象索引时基数就变成了这个 worker 碰过的每个 flow 版本一条每条的值都是完整的序列化 manifest作为原始字符串保留且每次读取还要重新JSON.parse。实测数据0.87.0 修复前一个 worker retain 了545 个 manifest 170 MB / 约 330 MB 堆单条字符串最大90 MB宿主机的共享缓存持有 19,293 个 bundle 目录 / 1.6 GB按 UTF-16 计约 3 GB共享 worker 因为从所有项目拉任务会遍历全部症状就是内存与 Pod 存活时间相关off-heap 保持约 100 MB 平坦——RSS 涨、堆也涨这是 JS 堆泄漏不是 native。规模估算规则判断租户 X 会不会撞上按字节数算不要按 flow 数算。语料极度偏斜——bundle 中位数 6 KB、均值 77 KB、p99 1.2 MB、最大 47 MB95.5% 的 bundle 小于 64 KB 但只占 10.5% 的字节而 59 个超过 4 MB 的 bundle0.3%占了 55.8%。因此 1,000 个中位 flow 约 11 MB无足轻重十个重度 code flow 就是约 400 MB。建模公式堆 ≈ 120 MB 基线 Σ(每个被执行过的不同 flow 版本的 manifest 字节数) × 1.0–1.9×1.9 是 V8 双字节字符串的情形实测 47.1 MB 磁盘 → 90.3 MB 堆。注意单位是 flow版本——重新发布会产生版本更换翻倍消耗。5.3 修复方向与当前源码形态当前主分支的cache-state.ts已经是磁盘是唯一缓存的设计getOrSetCache每次读盘、memoryLock.runExclusive只锁并发写见 cache-state.ts。workers.md明确告诫不要再把 memo 加回去——实测典型 bundle 的cache.json只有 39 KB、读取耗时 0.26 ms相对以秒计的 flow 运行可以忽略唯一不免费的是多 MB 级 bundle47 MB → 约 220 ms但flowBundleStore.tryFetch本来就通过cacheMiss谓词每次JSON.parse两次memo 也省不下主导成本。如果要在旧版本上做应急处理方向是确保缓存 key 由内容派生、值可被任意进程校验并把谁在内存里持有路径键作为排查重点。5.4 附带警告别把容量问题误判成泄漏workers.md用 0.88.0 修复版的生产数据给出一个重要提醒修好 bundle 泄漏并没有降低 kill 率——484 个容器从 0.87.0 的约 1,450 次重启/时到修复版 0.88.0 仍稳定在约 1,620–1,700 次/时。采样的堆均值保持 128 MB、最大 316 MB内核仍在约 1.01 GB anon-rss 处击杀。这是每次运行的快速尖峰而非累积的特征泄漏会抬高采样均值这里没有。真正的嫌疑是容量过签worker 的--max-old-space-size768 MB 引擎的--max-old-space-size默认 1024 MB pm2/isolate 约 90 MB ≈ 1.9 GB 的许可堆塞在一个 1 GiB 的容器里。此外flowBundleStore.publish在一次 RPC await 中同时持有三份完整编译代码实测 702 MB 堆对 768 MB 上限也属于每次运行的尖峰。因此验证修复要用浸泡一段时间后对比重启速率永远不要看刚重启的舰队——刚重启的舰队看起来总是健康的。6. 发布结论前先脱敏快照不离开机器但它的输出以微型形式携带同样的数据构造函数直方图和 retainer path 里全是真实的flowVersionId被 retain 的字符串预览可能暴露 flow 名称、步骤配置和时间戳。在把它们放进 PR 描述、issue、Slack 消息或文档之前一律替换成占位符如flow-version-a。本仓库的 PR 是公开的——在快照环节守住了底线然后把原始直方图贴进公开 PR就前功尽弃了。7. 收尾清理收尾清单删除快照文件它又大又敏感删除辅助脚本确认每一条被你动过的 cgroup 限制都恢复到原始值第 3.1 节的docker update是对称操作漏还原会让生产 worker 长期顶着 6g 上限运行。附仓库内可继续深挖的路径排障技能文档本体.agents/skills/profile-worker-memory/SKILL.mdWorker 运行时知识库含全部 Gotchas 与事故记录workers.md纯磁盘缓存实现泄漏的对照基准cache-state.tsFlow bundle 存取实现2026-08 泄漏的现场flow-bundle-store.ts沙箱复用判定REUSE_SANDBOX与执行模式的交互sandbox-manager.ts容器启动脚本PM2 移除后的监督形态docker-entrypoint.sh【免费下载链接】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），仅供参考