n8n 中文文档

设置任务运行器

任务运行器是一种以安全且高性能的方式执行任务的通用机制。它们用于在代码节点中执行用户提供的 JavaScript 和 Python 代码。

本文档介绍任务运行器的工作原理以及如何配置它们。

警告

在生产环境中始终使用任务运行器

任务运行器是用户提供的代码与 n8n 之间的唯一隔离层。如果没有它们,或者使用内部模式,任何可以编辑工作流的人都可能读取您的数据库、加密密钥、存储的凭据和环境变量。

在生产环境中,以及在保存敏感数据的任何实例上,请使用外部模式,并遵循强化任务运行器中的措施。为节省托管成本而跳过外部模式,只适合仅保存可信数据或模拟数据的隔离实例。

工作原理

任务运行器功能由以下组件组成:一个或多个任务运行器、任务代理和任务请求者。

任务运行器概述

任务运行器通过 websocket 连接到任务代理。任务请求者向代理提交任务请求,可用的任务运行器会接收并执行该请求。

任务运行器执行任务并将结果提交给任务请求者。任务代理负责协调运行器与请求者之间的通信。

n8n 实例(主实例和工作实例)充当代理。本例中的 Code 节点是任务请求者。

任务运行器模式

您可以在两种模式下使用任务运行器:内部和外部。

内部模式

在内部模式下,n8n 实例将任务运行器作为子进程启动,这在设计上是不安全的。n8n 进程监视并管理任务运行器的生命周期。任务运行器进程与 n8n 共享相同的 uid 和 gid。

警告

功能可用性

内部模式自 n8n 3.0 起弃用,并将在未来版本中移除。以内部模式运行时,n8n 会在启动时记录弃用警告;未设置 N8N_RUNNERS_MODE 时也会如此。请迁移到外部模式,以获得更安全的隔离和扩展能力。

不建议在生产环境中使用内部模式。由于运行器以与 n8n 相同的用户身份在同一主机上运行,逃逸运行器沙箱的代码会获得与 n8n 相同的访问权限,包括访问存储的凭据(请参阅本页顶部的警告)。仅在不保存敏感数据的隔离实例上使用内部模式。

外部模式

在外部模式下,启动器应用程序按需启动任务运行器并管理其生命周期。通常,这意味着在 n8n 旁边添加一个运行 n8nio/runners 镜像的 sidecar 容器,其中包含启动器、JS 任务运行器和 Python 任务运行器。该 sidecar 容器独立于 n8n 实例。启动器会公开一个健康检查端点,用于监控任务运行器进程。

任务运行器部署为 sidecar 容器

使用队列模式时,每个 worker 都需要有自己的任务运行器 sidecar 容器。

此外,如果 OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=false,主实例将运行手动执行,也需要自己的任务运行器 sidecar 容器。请注意,不建议在生产环境中运行禁用卸载的 n8n。

设置外部模式

在外部模式下,您将 n8nio/runners 镜像作为 n8n 旁边的 sidecar 容器运行。下面的 Docker Compose 配置可供参考。请记住,n8nio/runners 镜像版本必须与 n8nio/n8n 镜像版本匹配,并且 n8n 版本必须 >=1.111.0。

services:
  n8n:
    image: n8nio/n8n:1.111.0
    container_name: n8n-main
    environment:
      - N8N_RUNNERS_ENABLED=true
      - 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"
    volumes:
      - n8n_data:/home/node/.n8n
    # etc.

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

volumes:
  n8n_data:

配置分为三层:n8n 容器、runners 容器以及 runners 容器内的启动器。

在外部模式下配置 n8n 容器

以下是您可以在以外部模式运行的 n8n 容器上设置的主要环境变量:

警告

功能可用性

从 n8n 2.0 开始,N8N_RUNNERS_ENABLED 已弃用,您不再需要设置它。n8n 1.x 仍支持此变量,必须将其设置为 true 才能启用任务运行器。在 1.x 中禁用任务运行器会让 Code 节点脚本在主 n8n 进程内运行,完全没有隔离。不要在保存敏感凭据或数据的实例上这样做。

环境变量 描述
N8N_RUNNERS_ENABLED=true 启用任务运行器。从 n8n 2.0 开始弃用,n8n 1.x 仍支持。
N8N_RUNNERS_MODE=external 在外部模式下使用任务运行器。
N8N_RUNNERS_AUTH_TOKEN=<random secure shared secret> 任务运行器用于连接代理的共享密钥。
N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0 默认情况下,任务代理仅监听 localhost。使用多个容器(例如 Docker Compose)时,它必须能够接受外部连接。

有关环境变量的完整列表,请参阅 任务运行器环境变量。

在外部模式下配置 runners 容器

以下是您可以在以外部模式运行的运行器容器上设置的主要环境变量:

环境变量 说明
N8N_RUNNERS_AUTH_TOKEN=<random secure shared secret> 任务运行器用于连接代理的共享密钥。
N8N_RUNNERS_TASK_BROKER_URI=localhost:5679 n8n 实例内任务代理服务器的地址。
N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT=15 关闭任务运行器进程前等待的不活动秒数。当有新任务要执行时,启动器会自动再次启动运行器。设置为 0 可禁用自动关闭。

有关环境变量的完整列表,请参阅 任务运行器环境变量。

在外部模式下在运行器容器中配置启动器

启动器从 runners 容器环境中读取环境变量,并执行以下操作:

  • 将环境变量从启动器自己的环境传递给所有运行器(allowed-env)
  • 在特定运行器上设置特定环境变量(env-overrides)

要传递和设置的环境变量在 runners 镜像中包含的启动器配置文件中定义。该配置文件位于容器中的 /etc/task-runners.json。有关启动器配置文件的更多信息,请参阅配置文件文档。

默认启动器配置文件已锁定,但您可以编辑它,例如将第一方或第三方模块加入允许列表。要自定义启动器配置文件,请将文件挂载到以下路径:

path/to/n8n-task-runners.json:/etc/n8n-task-runners.json

添加额外的依赖项

1. 扩展 n8nio/runners 镜像

您可以扩展 n8nio/runners 镜像,为运行器添加额外依赖项。至少需要 n8nio/runners:1.121.0 才能执行此操作。

FROM n8nio/runners:1.121.0
USER root
RUN cd /opt/runners/task-runner-javascript && pnpm add moment uuid
RUN cd /opt/runners/task-runner-python && uv pip install numpy pandas
COPY n8n-task-runners.json /etc/n8n-task-runners.json
USER runner

您还必须将任何第一方或第三方包加入允许列表,供 Code 节点使用。编辑配置文件 n8n-task-runners.json,将扩展镜像中的包加入允许列表:

{
  "task-runners": [
    {
      "runner-type": "javascript",
      "env-overrides": {
        "NODE_FUNCTION_ALLOW_BUILTIN": "crypto",         // <-- allowlist Node.js builtin modules here
        "NODE_FUNCTION_ALLOW_EXTERNAL": "moment,uuid",   // <-- allowlist third-party JS packages here
      }
    },
    {
      "runner-type": "python",
      "env-overrides": {
        "PYTHONPATH": "/opt/runners/task-runner-python",
        "N8N_RUNNERS_STDLIB_ALLOW": "json",              // <-- allowlist Python standard library packages here
        "N8N_RUNNERS_EXTERNAL_ALLOW": "numpy,pandas"     // <-- allowlist third-party Python packages here
      }
    }
  ]
}
  • NODE_FUNCTION_ALLOW_BUILTIN:允许的 Node.js 内置模块列表,以逗号分隔。
  • NODE_FUNCTION_ALLOW_EXTERNAL:允许的 JS 包列表,以逗号分隔。
  • N8N_RUNNERS_STDLIB_ALLOW:允许的 Python 标准库包列表,以逗号分隔。
  • N8N_RUNNERS_EXTERNAL_ALLOW:允许的 Python 包列表,以逗号分隔。

2. 构建自定义镜像

例如,从 n8n 存储库根:

docker buildx build \
  -f docker/images/runners/Dockerfile \
  -t n8nio/runners:custom \
  .

3. 运行镜像

例如:

docker run --rm -it \
  -e N8N_RUNNERS_AUTH_TOKEN=test \
  -e N8N_RUNNERS_LAUNCHER_LOG_LEVEL=debug \
  -e N8N_RUNNERS_TASK_BROKER_URI=http://host.docker.internal:5679 \
  -p 5680:5680 \
  n8nio/runners:custom

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。