Skip to content

任务运行器#

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

测试版

原生 Python 的任务运行器支持和 n8nio/runners 镜像处于测试版。在此功能稳定之前，您必须使用 N8N_NATIVE_PYTHON_RUNNER=true 环境变量来启用 Python 运行器。

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

工作原理#

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

任务运行器概述

任务运行器使用 websocket 连接连接到任务代理。任务请求者向代理提交任务请求，可用的任务运行器可以接收并执行。

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

n8n 实例（主实例和工作实例）充当代理。在这种情况下，代码节点是任务请求者。

任务运行器模式#

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

内部模式#

在内部模式下，n8n 实例将任务运行器作为子进程启动。n8n 进程监控和管理任务运行器的生命周期。任务运行器进程与 n8n 共享相同的 uid 和 gid。不建议在生产环境中使用。

外部模式#

在外部模式下，启动器应用程序按需启动任务运行器并管理其生命周期。通常，这意味着在 n8n 旁边添加一个边车容器，运行包含启动器、JS 任务运行器和 Python 任务运行器的 n8nio/runners 镜像。此边车容器独立于 n8n 实例。

任务运行器部署为边车容器

使用队列模式时，每个 n8n 容器（主容器和工作容器）都需要有自己的边车任务运行器容器。

设置外部模式#

在外部模式下，您在 n8n 旁边运行 n8nio/runners 镜像作为边车容器。下面您将找到一个 docker compose 作为参考。请记住，n8nio/runners 镜像版本必须与 n8nio/n8n 镜像版本匹配，并且 n8n 版本必须 >=1.111.0。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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 容器#

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

环境变量 描述
N8N_RUNNERS_ENABLED=true 启用任务运行器。
N8N_RUNNERS_MODE=external 在外部模式下使用任务运行器。
N8N_RUNNERS_AUTH_TOKEN=<random secure shared secret> 任务运行器用于连接到代理的共享密钥。
N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0 默认情况下，任务代理只监听 localhost。使用多个容器时（例如，使用 Docker Compose），它需要能够接受外部连接。

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

在外部模式下配置运行器容器#

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

环境变量 描述
N8N_RUNNERS_AUTH_TOKEN=<random secure shared secret> 任务运行器用于连接到代理的共享密钥。
N8N_RUNNERS_TASK_BROKER_URI=localhost:5679 n8n 实例内任务代理服务器的地址。
N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT=15 关闭任务运行器进程之前等待的非活动秒数。当有新任务要执行时，启动器将自动重新启动运行器。设置为 0 以禁用自动关闭。

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

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

启动器将从运行器容器环境中读取环境变量，并将环境变量传递给每个运行器，如默认启动器配置文件中定义的那样，该文件位于容器中的 /etc/task-runners.json。要自定义启动器配置文件，请挂载到此路径。

有关启动器配置文件的更多信息，请参阅此处。

添加额外依赖项#

您可以自定义 n8nio/runners 镜像。为此，您可以在 n8n 存储库的此目录中找到运行器 Dockerfile。下面引用的清单也在此目录中。

要使其他包在代码节点中可用，您可以在构建时将额外的包烘焙到自定义运行器镜像中：

  • JavaScript: edit docker/images/runners/package.json (package.json manifest used to install runtime-only deps into the JS runner)
  • Python (Native): edit docker/images/runners/extras.txt (requirements.txt-style list installed into the Python runner venv)

重要：为了安全起见，任何外部库都必须明确允许用于代码节点。更新 n8n-task-runners.json 以将您添加的内容加入允许列表。

1) JavaScript 包#

编辑运行时额外清单 docker/images/runners/package.json：

1
2
3
4
5
6
7
8
{
  "name": "task-runner-runtime-extras",
  "description": "Runtime-only deps for the JS task-runner image, installed at image build.",
  "private": true,
  "dependencies": {
    "moment": "2.30.1"
  }
}

在 "dependencies" 下添加您想要的任何包（固定版本以确保可重现性），例如：

1
2
3
4
"dependencies": {
  "moment": "2.30.1",
  "uuid": "9.0.0"
}

2) Python 包#

编辑需求文件 docker/images/runners/extras.txt：

1
2
3
4
# Runtime-only extras for the Python task runner (installed at image build)
numpy==2.3.2
# add more, one per line, e.g.:
# pandas==2.2.2

固定版本（例如，==2.3.2）以确保确定性构建。

3) 为代码节点允许列表包#

打开 docker/images/runners/n8n-task-runners.json 并将您的包添加到环境覆盖中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
{
  "task-runners": [
    {
      "runner-type": "javascript",
      "env-overrides": {
        "NODE_FUNCTION_ALLOW_BUILTIN": "crypto",
        "NODE_FUNCTION_ALLOW_EXTERNAL": "moment,uuid",   // <-- add JS packages here
      }
    },
    {
      "runner-type": "python",
      "env-overrides": {
        "PYTHONPATH": "/opt/runners/task-runner-python",
        "N8N_RUNNERS_STDLIB_ALLOW": "json",
        "N8N_RUNNERS_EXTERNAL_ALLOW": "numpy,pandas"     // <-- add Python packages here
      }
    }
  ]
}
  • NODE_FUNCTION_ALLOW_BUILTIN：允许的 node 内置模块的逗号分隔列表。
  • NODE_FUNCTION_ALLOW_EXTERNAL：允许的 JS 包的逗号分隔列表。
  • N8N_RUNNERS_STDLIB_ALLOW：允许的 Python 标准库包的逗号分隔列表。
  • N8N_RUNNERS_EXTERNAL_ALLOW：允许的 Python 包的逗号分隔列表。

4) 构建您的自定义镜像#

例如，从 n8n 存储库根目录：

1
2
3
4
docker buildx build \
  -f docker/images/runners/Dockerfile \
  -t n8nio/runners:custom \
  .

5) 运行它#

例如：

1
2
3
4
5
6
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