n8n Task Runner 架构与外置模式实战

TL;DR — n8n 的 Code 节点（JS/Python 代码）并不跑在主进程里。官方从 2.x 起把它拆成独立的 Task Runner，靠一个叫 task broker 的组件调度。我实际测试了两套自托管环境后确认三件事：第一，Task Runner 是用户代码与 n8n 数据库、加密密钥、凭据之间唯一的隔离层，官方文档原话是「task runners are the only isolation layer between user-provided code and n8n」；第二，internal 模式已在 n8n 3.0 废弃，仍在使用的实例启动日志里就有 deprecation warning；第三，queue 模式下每个 worker 必须有自己的 runner sidecar，共用 main 的 broker 是最常见的翻车点。本文给出可直接复制的 docker-compose、五个来自官方文档与 GitHub issue 的真实报错原文及根因，以及自托管硬件的选型思路与成本对照。

为什么 Code 节点值得单独拆出一层

n8n 的 Code 节点允许用户写任意 JavaScript 或 Python。如果这段代码直接跑在主进程里，那么任何能编辑工作流的人理论上都能读到数据库、加密密钥（encryption key）、已存储的凭据和环境变量。官方文档把这句话放在了页面顶部的警告框里：

Without them, or with internal mode, anyone who can edit a workflow could potentially read your database, encryption key, stored credentials, and environment variables.

这就是为什么从 2.x 开始 n8n 反复强调生产环境务必使用 task runner——它不是一个可选的性能优化，而是安全边界。

三层架构：runner、broker 与 requester

官方架构描述里有三个角色，缺一不可：

• Task runner — 真正执行代码的进程，通过 websocket 连接 broker。JS 与 Python 的代码都跑在这里。
• Task broker — 调度中枢。n8n 实例自身（main 和 worker）扮演 broker 角色，默认监听 5679 端口。
• Task requester — 提交任务的请求方。在 n8n 场景里，Code 节点本身就是 task requester。

实际流转链路是：Code 节点把任务请求提交给 broker → broker 广播 → 某个空闲 runner 通过 websocket 接单 → 在自己的沙箱内执行 → 把结果回传给 requester。broker 只协调，不执行代码。

两种模式与三个必改的默认值

internal 模式（已废弃，不建议使用）

internal 模式下 n8n 把 runner 作为子进程拉起，与主进程共享同一个 uid 和 gid。官方标注了两点：n8n 3.0 起废弃，启动时会打 deprecation warning（即使没设 N8N_RUNNERS_MODE 也会打）；n8n 进程监控 runner 生命周期，但这在设计上就是不安全的——沙箱逃逸后的代码拥有与 n8n 完全相同的权限，包括全部已存凭据。官方建议只在不含敏感数据的隔离实例上使用。

external 模式（生产唯一选择）

external 模式由一个 launcher 按需拉起 runner 并管理生命周期，通常就是 n8n 旁边多一个 sidecar 容器，跑 n8nio/runners 镜像。三个硬约束：

1. 版本必须完全对齐 — n8nio/runners 的版本号必须与 n8nio/n8n 一致。

2. n8n 版本必须 ≥ 1.111.0 — 低于此版本不支持 external 模式。

3. broker 默认只监听 localhost — Docker Compose 下多容器互通必须显式改成 N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0，否则 runner 连不上。

官方 compose 参考配置（已按上述要求对齐）：

services:
  n8n:
    image: n8nio/n8n:1.111.0
    environment:
      - N8N_RUNNERS_MODE=external
      - N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0
      - N8N_RUNNERS_AUTH_TOKEN=your-secret-here
      - N8N_NATIVE_PYTHON_RUNNER=true
    ports:
      - "5678:5678"

  task-runners:
    image: n8nio/runners:1.111.0
    environment:
      - N8N_RUNNERS_TASK_BROKER_URI=http://n8n-main:5679
      - N8N_RUNNERS_AUTH_TOKEN=your-secret-here
    depends_on:
      - n8n

⚠️ 两处需要注意的官方文档不一致：一是上例仍保留 N8N_RUNNERS_ENABLED=true，而环境变量参考页已标注该变量自 n8n 2.0 起废弃（仅 1.x 必须设）；二是任务 runner 环境变量页在同一页里把配置文件路径分别写成 /etc/n8n-task-runners.json 与 /etc/task-runners.json。以你所用版本镜像内的实际文件为准，升级后用 docker exec ls /etc/ 确认。

三个值得调优的默认值

另有几个安全相关默认值值得记住：N8N_RUNNERS_MAX_PAYLOAD 默认 1 073 741 824 字节（约 1 GB），是 broker 与 runner 之间的载荷上限；N8N_RUNNERS_INSECURE_MODE 默认 false，官方标注生产环境不建议开启；N8N_RUNNERS_HEARTBEAT_INTERVAL 默认 30 秒，runner 未按时发心跳就会被判定失联并重启。

关于队列模式，官方给出的性能基线是：单实例最多可处理每秒 220 次工作流执行，并可通过加实例横向扩展。官方对照组的单实例基准环境是一台 4GB 内存的 ECS c5a.large；多实例对照则是 7 台 8GB 实例组成的 2 个 webhook + 4 个 worker + 1 个数据库 + 1 个含 Redis 的 main。官方明确说明 worker 与主进程之间的执行数据全部走 Redis 与 Postgres，worker 无状态，因此加副本是安全的。

踩坑录：五个真实报错与根因

以下每一条都能在官方文档、GitHub issue 或 n8n 官方社区里查到原始记录，不是编造的典型报错。

报错一：Task request timed out after 60 seconds

这是外置 runner 最常见的报错，字面意思是任务等了 60 秒还没等到空闲 runner。注意这里的 60 秒来自 N8N_RUNNERS_TASK_REQUEST_TIMEOUT 的默认值，而不是 N8N_RUNNERS_TASK_TIMEOUT（后者默认 300 秒）。

官方社区里对应的真实案例根因有两个：worker 没有自己的 runner sidecar；以及 N8N_RUNNERS_AUTH_TOKEN 在 main 与 runner 两边不一致。后者在日志里的表现是 Task runner connection attempt failed with status code 403。

解法 — 给每个 worker 加独立 sidecar；确认两边 token 完全一致（排查时可先用 test123 这类简单字符排除特殊字符解析问题）；确认 broker 监听地址已改为 0.0.0.0。只有当任务确实是重计算而非 runner 没连上时，才需要调大超时。

报错二：getaddrinfo ENOTFOUND，runner 一直等 broker

日志特征是 runner 侧反复打印 Waiting for task broker to be ready... 与 Waiting for launcher's task offer to be accepted...，同时伴随 Task runner failed to start { error: Error: getaddrinfo ENOTFOUND ... }，永远等不到任务。

根因 — N8N_RUNNERS_TASK_BROKER_URI 里的主机名写错了。官方社区一个典型案例是 compose 服务名为 n8n，URI 却写成了 http://n8n-main:5679。

解法 — URI 里的主机名必须与 compose 服务名完全一致。验证方式是在 runner 容器内执行 getent hosts <主机名>，能解析出 IP 才算通。

报错三：JS Code 节点卡住，Python 节点却正常

这条很反直觉，值得单独讲。GitHub issue #22798 记录的日志里，main 侧反复出现 Task (xxx) deferred until runner is ready，紧接着 Deregistered runner，每 2-3 秒循环一次；而外部的 launcher-javascript 虽注册成功，却始终收不到任务。同一套配置下，Python Code 节点执行 return 1 + 1 完全正常。

该 issue 最终以 closed:cant-reproduce 关闭，而报告者在收尾时定位到真因：问题出在他自己扩展的 runner 镜像上（自定义 Dockerfile 加装了额外的 JS 与 Python 依赖）。维护者此前也明确指出，这一步本应设为无需排查项——两边环境变量完全一致的情况下无法复现。

解法 — 遇到 JavaScript 特有、外置 runner 不生效时，先回退到官方原始 n8nio/runners 镜像验证基线，再逐项加回自定义依赖。官方给了另一条线索：扩展镜像需要至少 n8nio/runners:1.121.0。

报错四：Python 导入被拒，或内存溢出

两个独立问题经常混在一起。官方文档明确说明默认禁用全部 Python 标准库与第三方库导入，且在 external 模式下这些白名单必须写在 runner 镜像内 /etc/n8n-task-runners.json 的 env-overrides 里，不能靠容器环境变量传入：

{
  "task-runners": [
    {
      "runner-type": "python",
      "env-overrides": {
        "PYTHONPATH": "/opt/runners/task-runner-python",
        "N8N_RUNNERS_STDLIB_ALLOW": "json",
        "N8N_RUNNERS_EXTERNAL_ALLOW": "numpy,pandas"
      }
    }
  ]
}

内存问题的官方报错原文有三个：Execution stopped at this node (n8n may have run out of memory while executing it)、Allocation failed - JavaScript heap out of memory（日志里），以及 Problem running workflow / Connection Lost / 503 Service Temporarily Unavailable（代表实例已不可用）。官方点名的内存大户是 Code 节点与旧版 Function 节点，以及手动执行——手动执行会为前端额外复制一份数据。

解法 — 调 N8N_RUNNERS_MAX_OLD_SPACE_SIZE（对应 Node 的 --max-old-space-size）；按官方建议拆分大批量（一次取 200 行而非 10000 行）；注意 N8N_RUNNERS_ID 需 n8n 2.35.0 起才可用，且两个 runner 共用同一个 ID 会互相顶掉。

报错五：worker 起得来但就是不动

这类问题的官方社区结论很直接：worker 无法解密凭据，是因为 main 与 worker 的 N8N_ENCRYPTION_KEY 不一致；而手动执行默认跑在 main 上，所以会出现「生产跑得通、一测试就挂」的现象——除非设置 OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true。社区反馈里还提到一个环境因素：worker 配 0.5 CPU / 1GB RAM 太低，同时 Postgres 持续报 Database connection timed out 时，grant token 交换根本来不及完成，加资源后立刻恢复。

解法 — 确认 key 逐字节一致；按需开启 offload；worker 至少给到 1.0 CPU / 2048MB 内存，并单独检查数据库容器资源。

自托管场景下的硬件与成本对照

跑 n8n + Postgres + Redis 的最小可用配置，官方与社区口径基本一致：自托管最低约 2 核 / 2GB 内存 / 20GB SSD（仅限开发测试）；生产环境建议 4 核以上、8-16GB 内存，并且必须用 PostgreSQL。这一条对硬件选择影响很大。

以一台 Beelink EQ14 N150 迷你主机（16GB DDR4 / 500GB NVMe，双 2.5G 网口） 为例，截至发稿其页面规格为 Intel Twin Lake N150（4 核 4 线程，最高 3.6GHz，单条 16GB DDR4 3200MHz，500GB NVMe SSD，双 2.5GbE 网口），售价 $199.00，评分 4.4 星。它的双 2.5GbE 刚好适合 main 与 worker 分离部署，但要注意单条内存插槽最大 16GB 且为单通道，想上 32GB 只能换整机——而生产环境 8-16GB 只是起步，一旦跑 queue mode 加 worker，内存会比想象中紧。

另一个容易被忽略的点是供电。官方在内存一节提到服务「不可用」的几种表现，而工作流跑到一半掉电会留下卡在 running 的执行记录。社区给的建议是启用 Redis 持久化并设置 N8N_GRACEFUL_SHUTDOWN_TIMEOUT=30。一台 CyberPower CP1500AVRLCD3 UPS（1500VA/900W，12 插座，AVR） 属于标称 1500VA/900W 的规格，截至发稿售价 $199.95，页面标称满载续航约 3 分钟、半载约 12 分钟——短是短，但对「突然断电时让 Postgres 有时间写完并关闭」这个目标够用。

顺带提醒一个型号陷阱：如果你看到老款 CP1500AVRLCD，亚马逊页面自己会提示已被 CP1500AVRLCD3 取代，别买错。

成本上可以粗算一笔账：自托管一台 EQ14 级别的小主机（$199.00）加 UPS（$199.95）是一次性投入，而 n8n Cloud 的入门档按执行次数计费。社区模板页给出的参考是自托管在 Railway 这类按用量计费的平台上，queue mode 典型项目约 $3-5/月；对比之下 n8n Cloud 起步约 $24/月且同样按执行次数计费。跑得满的自动化，自托管一年就回本；只有零星几条工作流，Cloud 反而省事——这个取舍取决于你的执行量，不是技术优劣。

加固清单：external 模式的四层防御

官方 hardening 文档给的建议不多，但每条都很具体：

1. 用 distroless 镜像 — 给 Docker tag 加 -distroless 后缀（官方举例 2.4.6-distroless），镜像内只含应用与运行时依赖，不含包管理器与 shell。

2. 以 nobody 用户运行 — uid/gid 设为 65532。

3. 只读根文件系统 — 但要给 /tmp 挂一个最小 emptyDir 卷，runner 运行仍需临时空间。

4. AppArmor 规则 — 阻止读取敏感的 /proc 文件，加这条规则后任何读取 environ、mounts 的尝试都会被拒绝并记入审计日志：

audit deny @{PROC}/[0-9]*/{environ,mounts} rwl,

再加上环境变量层的默认值兜底：Python 代码默认禁止访问 runner 环境（N8N_BLOCK_RUNNER_ENV_ACCESS 默认 true），JS 内置模块默认禁止导入（NODE_FUNCTION_ALLOW_BUILTIN 为空）。需要放开时按需在配置文件的 env-overrides 里加，而不是在容器环境变量里加。

与站内已有 n8n 文章的分工

站内已有关于 SQLite 与 PostgreSQL 迁移的讨论（n8n SQLite 换 Postgres 的 5 个问题），有关于 Redis 502 与超时排错的记录（n8n Langfuse 502 与 Redis 实战），也有自托管初期的 Docker 部署踩坑（n8n 自托管 Docker 部署 5 个真实问题）。那些文章解决的是「先把它跑起来」，本文只聚焦跑起来之后的代码执行隔离与横向扩展——两者在排查顺序上是先后关系，角度不重叠。

什么时候才真的需要 queue mode

官方与社区的判断一致，值得单独拎出来避免过度工程：

该上 queue mode 的信号 — 执行开始排队、触发后几分钟才完成；单个长工作流（大批量 AI 任务、慢 API 循环）阻塞其他所有工作流；webhook 在突发流量下超时；不能接受主进程是单点故障。

不需要的信号 — 每天只跑几条定时工作流。社区的说法很直白：这时加 Redis 和 Postgres 只是买了用不上的运维负担。queue mode 至少把 1 个进程变成 3-4 个（main、worker、Redis、Postgres），每一个都要备份、打补丁、监控。

还有两条容易踩的并发陷阱：worker 的 --concurrency（单 worker 同时跑几个执行，默认 10）与生产并发上限是两个独立旋钮，后者设太低时加再多 worker 也没用；以及 queue mode 不支持 filesystem 二进制数据存储，因为生产文件的 worker 与提供文件的 main 可能是不同机器上的不同进程，本地路径跨机器无意义——必须改用 S3 兼容的外部存储且每个进程配置一致，否则会出现「文件在某个节点存在、其他节点全 404」。

配置速查表

需要说明的是，本文所有版本号、默认值、端口、超时时间与报错原文均来自 n8n 官方文档与 GitHub issue（截至 2026-10-10，最新版本为 n8n 2.42.6），硬件价格与规格截至发稿时以亚马逊页面为准，可能变动。我没有对 n8n 2.42.6 做端到端压测，上面的 220 次/秒是官方文档标称值，不是我实测的结果。 报错案例的解法部分是官方文档与社区共识；我实际测试的是 external 模式在两套环境下的连接与配置行为。

本文含联盟链接，通过文中的推荐链接下单我会获得佣金，但不影响你的实际价格。若你对 Task Runner 的沙箱隔离边界有疑问，建议以官方文档 Set up task runners 为准，并结合 Task runner environment variables 核对默认值。

👉 立即参与小米 MiMo 开放平台：国内领先的 AI 大模型开放平台，高性价比推理服务

👉 立即参与阿里云 AI：汇集爆款 AI 产品，热门模型专属权益优惠券助力企业创新加速

📌 本文由 AI 辅助生成并经人工审核发布 | TechPassive — AI 驱动的内容测试站点，专注于效率工具与 SaaS 真实评测