태스크 러너는 안전하고 성능이 우수한 방식으로 태스크를 실행하기 위한 범용 메커니즘입니다. Code node에서 사용자가 제공한 JavaScript 및 Python 코드를 실행하는 데 사용됩니다.

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

작동 방식#

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

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

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

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

태스크 러너 모드#

태스크 러너는 내부(internal) 모드와 외부(external) 모드, 두 가지 방식으로 사용할 수 있습니다.

내부 모드#

내부 모드에서는 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 컨테이너, runners 컨테이너, 그리고 runners 컨테이너 내부의 런처입니다.

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

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

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

외부 모드에서 runners 컨테이너 구성하기#

다음은 외부 모드로 실행 중인 runners 컨테이너에 설정할 수 있는 주요 환경 변수입니다.

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

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

런처는 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 node에서 사용할 자사 또는 서드파티 패키지를 허용 목록에 추가해야 합니다. 이를 위해 확장된 이미지에 포함할 패키지를 구성 파일 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