任务运行器#

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

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

工作原理#

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

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

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

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

任务运行器模式#

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

内部模式#

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

外部模式#

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

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

此外，如果您没有启用将手动执行卸载到工作实例（如果您在配置中没有设置 OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true），那么您的主实例将运行手动执行，也需要自己的任务运行器边车容器。请注意，不建议在生产环境中禁用卸载功能运行 n8n。

设置外部模式#

在外部模式下，您在 n8n 旁边运行 n8nio/runners 镜像作为边车容器。下面您将找到一个 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:

There are three layers of configuration: the n8n container, the runners container, and the launcher inside the runners container. 配置有三层：n8n 容器、运行器容器和运行器容器内的启动器。

Configuring n8n container in external mode 在外部模式下配置 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>`	The shared secret the task runner uses to connect to the broker. 任务运行器用于连接到代理的共享密钥。
`N8N_RUNNERS_TASK_BROKER_URI=localhost:5679`	The address of the task broker server within the n8n instance. n8n 实例内任务代理服务器的地址。
`N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT=15`	Number of seconds of inactivity to wait before shutting down the task runner process. The launcher will automatically start the runner again when there are new tasks to execute. Set to `0` to disable automatic shutdown. 在关闭任务运行器进程之前等待的非活动秒数。当有新任务要执行时，启动器将自动再次启动运行器。设置为 `0` 以禁用自动关闭。

For full list of environment variables see task runner environment variables. 有关环境变量的完整列表，请参阅任务运行器环境变量。

Configuring launcher in runners container in external mode 在外部模式下配置运行器容器中的启动器#

The launcher reads environment variables from runners container environment, and performs the following actions: 启动器从运行器容器环境中读取环境变量，并执行以下操作：

Passing environment variables from the launcher's own environment to all runners (allowed-env) 将环境变量从启动器自己的环境传递给所有运行器（allowed-env）
Setting specific environment variables on specific runners (env-overrides) 在特定运行器上设置特定环境变量（env-overrides）

Which environment variables to pass and to set are defined in the launcher config file included in the runners image. This config file is located in the container at /etc/task-runners.json. To learn more about the launcher config file, refer to the Config file documentation. 要传递和设置哪些环境变量在运行器镜像中包含的启动器配置文件中定义。此配置文件位于容器中的 /etc/task-runners.json。要了解有关启动器配置文件的更多信息，请参阅配置文件文档。

The default launcher configuration file is locked down, but you can edit this file, for example, to allowlist first- or third-party modules. To customize the launcher configuration file, mount to this path: 默认启动器配置文件已锁定，但你可以编辑此文件，例如，将第一方或第三方模块加入允许列表。要自定义启动器配置文件，请挂载到此路径：

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

Adding extra dependencies 添加额外依赖#

1. Extend the `n8nio/runners` image 扩展 `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

你还必须将任何第一方或第三方包加入允许列表，以供代码节点使用。通过编辑配置文件 n8n-task-runners.json 将包含在扩展镜像中的包添加进来。

{
  "task-runners": [
    {
      "runner-type": "javascript",
      "env-overrides": {
        "NODE_FUNCTION_ALLOW_BUILTIN": "crypto",         // <-- 在此处将 Node.js 内置模块加入允许列表
        "NODE_FUNCTION_ALLOW_EXTERNAL": "moment,uuid",   // <-- 在此处将第三方 JS 包加入允许列表
      }
    },
    {
      "runner-type": "python",
      "env-overrides": {
        "PYTHONPATH": "/opt/runners/task-runner-python",
        "N8N_RUNNERS_STDLIB_ALLOW": "json",              // <-- 在此处将 Python 标准库包加入允许列表
        "N8N_RUNNERS_EXTERNAL_ALLOW": "numpy,pandas"     // <-- 在此处将第三方 Python 包加入允许列表
      }
    }
  ]
}

NODE_FUNCTION_ALLOW_BUILTIN: comma-separated list of allowed node builtin modules. NODE_FUNCTION_ALLOW_BUILTIN：允许的 Node.js 内置模块的逗号分隔列表。
NODE_FUNCTION_ALLOW_EXTERNAL: comma-separated list of allowed JS packages. NODE_FUNCTION_ALLOW_EXTERNAL：允许的 JS 包的逗号分隔列表。
N8N_RUNNERS_STDLIB_ALLOW: comma-separated list of allowed Python standard library packages. N8N_RUNNERS_STDLIB_ALLOW：允许的 Python 标准库包的逗号分隔列表。
N8N_RUNNERS_EXTERNAL_ALLOW: comma-separated list of allowed Python packages. N8N_RUNNERS_EXTERNAL_ALLOW：允许的 Python 包的逗号分隔列表。

2. Build your custom image 构建自定义镜像#

例如，从 n8n 仓库根目录：

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

3. Run the image 运行镜像#

例如：

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