任务运行器#
任务运行器是一种以安全高效方式执行任务的通用机制，用于在代码节点中执行用户提供的JavaScript和Python代码。
测试版说明
原生Python任务运行器及n8nio/runners镜像功能目前处于测试阶段。在该功能稳定前，必须使用N8N_NATIVE_PYTHON_RUNNER=true环境变量来启用Python运行器。
本文档将说明任务运行器的工作原理及配置方法。
工作原理#
任务运行器功能包含以下组件：一个或多个任务运行器、任务代理器及任务请求器。
运行器执行任务后将结果返回给任务请求器。任务代理器负责协调运行器与请求器之间的通信。
n8n实例（主实例和工作实例）充当代理器角色，而代码节点则作为任务请求器。
任务运行器模式#
任务运行器支持两种运行模式：内部模式与外部模式。
内部模式#
在内部模式下，n8n实例以子进程形式启动任务运行器。n8n进程会监控并管理任务运行器的生命周期。任务运行器进程与n8n共享相同的uid和gid。不推荐在生产环境中使用此模式。
外部模式#
在外部模式下，由启动器应用按需启动任务运行器并管理其生命周期。通常这意味着在n8n旁部署一个边车容器，运行包含启动器、JS任务运行器和Python任务运行器的n8nio/runners镜像。该边车容器独立于n8n实例。
使用队列模式时，每个工作实例都需要配备独立的边车容器来运行任务运行器。
此外，若未启用将手动执行任务卸载至工作实例的功能（即未在配置中设置OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true），主实例将负责运行手动执行任务，因此也需要独立的边车容器。请注意，不建议在生产环境中关闭任务卸载功能。
配置外部模式#
在外部模式下，您需要在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:
在外部模式下配置 n8n 容器#
以下是运行在外部模式的 n8n 容器可设置的主要环境变量：
| 环境变量 | 说明 |
|---|---|
N8N_RUNNERS_ENABLED=true | 启用任务执行器。 |
N8N_RUNNERS_MODE=external | 在外部模式下使用任务执行器。 |
N8N_RUNNERS_AUTH_TOKEN=<随机安全共享密钥> | 任务执行器用于连接代理的共享密钥。 |
N8N_RUNNERS_BROKER_LISTEN_ADDRESS=0.0.0.0 | 默认情况下任务代理仅监听本地主机。使用多容器（例如 Docker Compose）时需允许外部连接。 |
完整环境变量列表请参阅任务执行器环境变量。
在外部模式下配置执行器容器#
以下是运行在外部模式的执行器容器可设置的主要环境变量：
| 环境变量 | 说明 |
|---|---|
N8N_RUNNERS_AUTH_TOKEN=<随机安全共享密钥> | 任务执行器用于连接代理的共享密钥。 |
N8N_RUNNERS_TASK_BROKER_URI=localhost:5679 | n8n 实例中任务代理服务器的地址。 |
N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT=15 | 关闭任务执行器进程前等待无活动状态的秒数。当有新任务需要执行时，启动器将自动重新启动执行器。设置为 0 可禁用自动关闭功能。 |
完整环境变量列表请参阅任务执行器环境变量。
在外部模式下配置执行器容器中的启动器#
启动器将从执行器容器环境中读取环境变量，并按照默认启动器配置文件（位于容器内的 /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
你还必须将任何第一方或第三方包加入白名单，以便代码节点使用。通过编辑配置文件 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：允许的 Node 内置模块的逗号分隔列表。NODE_FUNCTION_ALLOW_EXTERNAL：允许的 JS 包的逗号分隔列表。N8N_RUNNERS_STDLIB_ALLOW：允许的 Python 标准库包的逗号分隔列表。N8N_RUNNERS_EXTERNAL_ALLOW：允许的 Python 包的逗号分隔列表。
多个运行器和运行器健康检查服务器的端口#
When a single runner is configured, the "health-check-server-port" field found in the n8n-task-runners.json configuration file is optional and defaults to 5681. When multiple runners are configured, this is required and must be unique per runner. Refer to the launcher’s config file documentation for the full list of options and examples.
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