태스크 러너는 태스크를 안전하고 효율적으로 실행하기 위한 범용 메커니즘입니다. Code 노드에서 사용자가 제공한 JavaScript 및 Python 코드를 실행하는 데 사용됩니다.

이 문서에서는 태스크 러너의 작동 방식과 구성 방법을 설명합니다.

작동 방식#

태스크 러너 기능은 하나 이상의 태스크 러너, 태스크 브로커, 태스크 요청자로 구성됩니다.

태스크 러너는 웹소켓 연결을 사용하여 태스크 브로커에 연결합니다. 태스크 요청자는 브로커에 태스크 요청을 제출하고, 사용 가능한 태스크 러너가 이를 가져와 실행합니다.

러너는 태스크를 실행하고 결과를 태스크 요청자에게 제출합니다. 태스크 브로커는 러너와 요청자 간의 통신을 조율합니다.

n8n 인스턴스(메인 및 워커)가 브로커 역할을 합니다. 이 경우 Code 노드가 태스크 요청자입니다.

태스크 러너 모드#

태스크 러너는 내부 및 외부의 두 가지 모드로 사용할 수 있습니다.

내부 모드#

내부 모드에서는 n8n 인스턴스가 태스크 러너를 자식 프로세스로 실행합니다. n8n 프로세스가 태스크 러너의 라이프사이클을 모니터링하고 관리합니다. 태스크 러너 프로세스는 n8n과 동일한 uid 및 gid를 공유합니다. 프로덕션에서는 권장하지 않습니다.

외부 모드#

외부 모드에서는 런처 애플리케이션이 필요에 따라 태스크 러너를 실행하고 라이프사이클을 관리합니다. 일반적으로 n8n 옆에 런처, JS 태스크 러너 및 Python 태스크 러너가 포함된 n8nio/runners 이미지를 실행하는 사이드카 컨테이너를 추가하는 것을 의미합니다. 이 사이드카 컨테이너는 n8n 인스턴스와 독립적입니다.

큐 모드를 사용할 때는 각 워커마다 태스크 러너를 위한 자체 사이드카 컨테이너가 필요합니다.

또한 OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=false인 경우, 메인 인스턴스가 수동 실행을 처리하므로 태스크 러너를 위한 자체 사이드카 컨테이너도 필요합니다. 오프로드를 비활성화한 상태로 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:

구성에는 n8n 컨테이너, 러너 컨테이너, 러너 컨테이너 내부의 런처의 세 가지 레이어가 있습니다.

외부 모드에서 n8n 컨테이너 구성#

외부 모드에서 실행 중인 n8n 컨테이너에 설정할 수 있는 주요 환경 변수는 다음과 같습니다.

전체 환경 변수 목록은 태스크 러너 환경 변수를 참조하세요.

외부 모드에서 러너 컨테이너 구성#

외부 모드에서 실행 중인 러너 컨테이너에 설정할 수 있는 주요 환경 변수는 다음과 같습니다.

전체 환경 변수 목록은 태스크 러너 환경 변수를 참조하세요.

외부 모드에서 러너 컨테이너 내 런처 구성#

런처는 러너 컨테이너 환경에서 환경 변수를 읽고 다음 작업을 수행합니다.

• 런처 자체 환경의 환경 변수를 모든 러너에 전달(allowed-env)
• 특정 러너에 특정 환경 변수 설정(env-overrides)

전달 및 설정할 환경 변수는 러너 이미지에 포함된 런처 구성 파일에 정의됩니다. 이 구성 파일은 컨테이너의 /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",         // <-- 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 패키지의 쉼표로 구분된 목록입니다.

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