Queue mode 활성화

Queue mode 활성화 (Enable queue mode)

n8n은 필요에 따라 여러 모드로 실행할 수 있어요. 그중 queue 모드가 가장 좋은 확장성을 제공합니다. 워크로드가 많아질 때 worker를 여러 개 붙여 병렬로 처리하는 구조라, 트래픽 증가에 유연하게 대응할 수 있습니다.

출처: 공식문서 - Enable queue mode

💡 바이너리 데이터 저장: n8n은 파일시스템의 바이너리 데이터 저장과 함께 queue 모드를 지원하지 않습니다. queue 모드에서 워크플로가 바이너리 데이터를 영속화해야 한다면 S3 외부 저장을 사용할 수 있어요.

작동 방식

queue 모드에서는 여러 n8n 인스턴스를 구성하는데, 하나의 메인 인스턴스가 워크플로 정보(예: 트리거)를 받고 worker 인스턴스가 실행을 수행합니다.

각 worker는 독립적인 Node.js 인스턴스로 main 모드에서 실행되지만, 높은 IOPS(초당 입출력 연산) 덕분에 여러 워크플로 실행을 동시에 처리할 수 있습니다.

worker 인스턴스를 사용하고 queue 모드로 실행하면 워크로드를 처리하기 위해 n8n을 위로 확장(worker 추가)하거나 아래로 축소(worker 제거)할 수 있습니다.

처리 흐름은 이렇습니다:

1. 메인 n8n 인스턴스가 타이머와 웹훅 호출을 처리하며 워크플로 실행을 생성합니다(실행은 하지 않음).
2. 실행 ID를 메시지 브로커인 Redis에 전달합니다. Redis는 대기 중인 실행 큐를 유지하고 다음으로 사용 가능한 worker가 이를 가져갈 수 있게 합니다.
3. worker 풀에 있는 worker가 Redis에서 메시지를 가져갑니다.
4. worker는 실행 ID로 데이터베이스에서 워크플로 정보를 가져옵니다.
5. 워크플로 실행 완료 후 worker는:
   • 결과를 데이터베이스에 씁니다.
   • 실행이 끝났다고 Redis에 게시합니다.
6. Redis가 메인 인스턴스에 알립니다.

worker 구성

worker는 실제 작업을 수행하는 n8n 인스턴스입니다. 메인 n8n 프로세스에서 실행할 워크플로 정보를 받아 워크플로를 실행하고, 각 실행이 끝나면 상태를 업데이트합니다.

💡 프로세스별 이벤트 로그 파일: worker가 writable 파일시스템을 공유한다면 각 worker 프로세스에 고유한 이벤트 로그 경로를 주세요. 자세한 내용은 Per-process event log files 문서를 참고하세요.

암호화 키 설정

n8n은 첫 시작 시 암호화 키를 자동으로 생성합니다. 원한다면 환경 변수로 커스텀 키를 직접 제공할 수도 있어요.

메인 n8n 인스턴스의 암호화 키는 모든 worker와 webhook processor 노드와 공유되어야 합니다. 그래야 worker 노드들이 데이터베이스에 저장된 크레덴셜에 접근할 수 있습니다.

각 worker 노드의 암호화 키를 설정 파일이나 해당 환경 변수로 설정하세요.

export N8N_ENCRYPTION_KEY=<main_instance_encryption_key>

실행 모드 설정

💡 데이터베이스 고려사항: n8n이 지원하는 PostgreSQL 버전은 Supported PostgreSQL versions을 참고하세요. SQLite 데이터베이스에서 실행 모드를 queue로 설정해 운영하는 것은 권장하지 않습니다.

메인 인스턴스와 모든 worker에서 EXECUTIONS_MODE 환경 변수를 queue로 설정하세요.

export EXECUTIONS_MODE=queue

또는 설정 파일에서 executions.mode를 queue로 설정할 수 있습니다.

Redis 시작

💡 별도 머신에서 Redis 실행: Redis를 별도 머신에서 실행해도 되며, n8n 인스턴스가 접근 가능하도록만 하면 됩니다.

Docker 컨테이너에서 Redis를 실행하려면:

docker run --name some-redis -p 6379:6379  -d redis

기본적으로 Redis는 localhost의 포트 6379에서 비밀번호 없이 실행됩니다. Redis 구성에 따라 메인 n8n 프로세스에 다음을 설정해 n8n이 Redis와 상호작용하게 합니다.

설정 파일 사용	환경 변수 사용	설명
queue.bull.redis.host:localhost	QUEUE_BULL_REDIS_HOST=localhost	기본적으로 Redis는 localhost에서 실행됩니다.
queue.bull.redis.port:6379	QUEUE_BULL_REDIS_PORT=6379	기본 포트는 6379입니다. Redis가 다른 포트면 이 값을 설정하세요.

다음 선택적 설정도 할 수 있습니다.

설정 파일 사용	환경 변수 사용	설명
queue.bull.redis.username:USERNAME	QUEUE_BULL_REDIS_USERNAME	기본적으로 Redis는 사용자 이름을 요구하지 않습니다. 특정 사용자를 쓰면 설정하세요.
queue.bull.redis.password:PASSWORD	QUEUE_BULL_REDIS_PASSWORD	기본적으로 Redis는 비밀번호를 요구하지 않습니다. 비밀번호를 쓰면 설정하세요.
queue.bull.redis.db:0	QUEUE_BULL_REDIS_DB	기본값은 0입니다. 이 값을 바꾸면 설정을 업데이트하세요.
queue.bull.redis.timeoutThreshold:10000ms	QUEUE_BULL_REDIS_TIMEOUT_THRESHOLD	Redis를 사용할 수 없을 때 종료하기 전 대기 시간. 기본값은 10000(ms)입니다.
queue.bull.gracefulShutdownTimeout:30	N8N_GRACEFUL_SHUTDOWN_TIMEOUT	worker가 프로세스 종료 전에 작업을 마칠 수 있는 graceful shutdown 타임아웃. 기본값은 30초입니다.

이제 n8n 인스턴스를 시작하면 Redis 인스턴스에 연결됩니다.

worker 시작

n8n이 워크플로를 실행하려면 worker 프로세스를 시작해야 합니다. worker를 별도 머신에 호스팅하려면 그 머신에 n8n을 설치하고 Redis 인스턴스와 n8n 데이터베이스에 연결되도록 하세요.

루트 디렉터리에서 다음 명령으로 worker 프로세스를 시작합니다.

./packages/cli/bin/n8n worker

Docker를 사용한다면:

docker run --name n8n-queue -p 5679:5678 n8nio/n8n worker

여러 worker 프로세스를 설정할 수 있습니다. 모든 worker 프로세스가 Redis와 n8n 데이터베이스에 접근할 수 있는지 확인하세요.

worker 서버

각 worker 프로세스는 선택적 엔드포인트를 노출하는 서버를 실행합니다.

• /healthz: QUEUE_HEALTH_CHECK_ACTIVE 환경 변수를 켜면 worker가 살아 있는지 반환합니다.
• /healthz/readiness: QUEUE_HEALTH_CHECK_ACTIVE 환경 변수를 켜면 worker의 DB와 Redis 연결이 준비됐는지 반환합니다.
• 크레덴셜 오버라이트 엔드포인트
• /metrics

💡 헬스체크 엔드포인트 커스터마이징: 헬스체크 엔드포인트 경로는 N8N_ENDPOINT_HEALTH 환경 변수로 커스터마이징할 수 있습니다.

실행 중인 worker 보기

💡 기능 가용성: 실행 중인 worker 보기는 셀프호스팅: Enterprise에서 사용 가능합니다. n8n Cloud Enterprise에서는 n8n에 문의해 활성화하세요.

n8n에서 Settings > Workers를 선택해 실행 중인 worker와 성능 메트릭을 볼 수 있습니다.

큐와 함께 n8n 실행

큐와 함께 n8n을 실행하면 모든 프로덕션 워크플로 실행이 worker 프로세스에 의해 처리됩니다. 웹훅의 경우 HTTP 요청은 메인/webhook 프로세스가 받지만 실제 워크플로 실행은 worker에 넘겨져 약간의 오버헤드와 지연이 발생할 수 있습니다.

Redis가 메시지 브로커 역할을 하고 데이터베이스가 데이터를 영속화하므로 둘 다에 대한 접근이 필요합니다. 이 분산 시스템 구성은 SQLite로는 지원되지 않습니다.

💡 데이터 마이그레이션: 한 데이터베이스에서 다른 데이터베이스로 데이터를 옮기려면 Export와 Import 명령을 사용할 수 있습니다. 사용법은 n8n CLI 명령 문서를 참고하세요.

Webhook processor

💡 유의: webhook 프로세스는 Redis에 의존하며 EXECUTIONS_MODE 환경 변수도 설정해야 합니다. 위의 worker 구성 섹션에 따라 webhook processor 노드를 설정하세요.

Webhook processor는 n8n의 또 다른 확장 계층입니다. 설정은 선택 사항이며, 들어오는 웹훅 요청을 확장할 수 있게 해 줍니다.

이 방법으로 n8n은 방대한 양의 병렬 요청을 처리할 수 있습니다. webhook 프로세스와 worker를 필요한 만큼 추가하기만 하면 됩니다. webhook 프로세스는 같은 포트(기본값: 5678)에서 요청을 듣습니다. 이 프로세스들을 컨테이너나 별도 머신에서 실행하고, 로드 밸런싱 시스템으로 요청을 라우팅하세요.

n8n은 메인 프로세스를 로드 밸런서 풀에 추가하는 것을 권장하지 않습니다. 메인 프로세스를 풀에 추가하면 요청을 받고 과부하가 걸릴 수 있습니다. 이는 n8n UI 편집, 보기, 상호작용 성능 저하로 이어집니다.

루트 디렉터리에서 다음 명령으로 webhook processor를 시작합니다.

./packages/cli/bin/n8n webhook

Docker를 사용한다면:

docker run --name n8n-queue -p 5679:5678 -e "EXECUTIONS_MODE=queue" n8nio/n8n webhook

웹훅 URL 구성

메인 n8n 인스턴스를 실행하는 머신에서 다음 명령으로 웹훅 URL을 구성하세요.

export WEBHOOK_URL=https://your-webhook-url.com

이 값은 설정 파일에서도 설정할 수 있습니다.

로드 밸런서 구성

여러 webhook 프로세스를 사용할 때 요청을 라우팅할 로드 밸런서가 필요합니다. n8n 인스턴스와 웹훅에 같은 도메인 이름을 사용한다면 로드 밸런서를 다음과 같이 설정할 수 있습니다.

• 웹훅 트리거를 webhook 서버 풀로 리다이렉트합니다. 고려할 경로:
  • /webhook/*: Webhook trigger 노드 엔드포인트
  • /webhook-waiting/*: "send and wait" 작업을 수행하는 노드(예: Slack 노드)가 사용하는 human-in-the-loop 웹훅 엔드포인트.
• 다른 모든 경로(n8n 내부 API, 편집기용 정적 파일 등)는 메인 프로세스로 라우팅합니다.

참고: 수동 워크플로 실행의 기본 URL은 /webhook-test/*입니다. 이 URL이 메인 프로세스로 라우팅되도록 하세요.

설정 파일의 endpoints.webhook 또는 N8N_ENDPOINT_WEBHOOK 환경 변수로 이 경로를 바꿀 수 있습니다. 바꾸면 로드 밸런서도 함께 업데이트하세요.

메인 프로세스의 웹훅 처리 비활성화 (선택)

웹훅 실행을 webhook processor에서 수행하도록 하고 싶다면 메인 프로세스에서 웹훅 처리를 비활성화할 수 있습니다. 설정 파일에서 endpoints.disableProductionWebhooksOnMainProcess를 true로 설정하면 n8n이 메인 프로세스에서 웹훅 요청을 처리하지 않습니다.

또는 다음 명령을 사용할 수 있습니다.

export N8N_DISABLE_PRODUCTION_MAIN_PROCESS=true

메인 프로세스에서 웹훅 처리를 비활성화했다면 메인 프로세스를 실행하되 로드 밸런서의 웹훅 풀에는 추가하지 마세요.

큰 웹훅 응답

queue 모드에서 worker가 실행을 수행하지만, 웹훅 요청을 보낸 클라이언트는 메인 또는 webhook 인스턴스에 연결된 채로 남아 있습니다. Respond to Webhook 노드의 응답은 큐 메시지 안에서 worker로부터 그 인스턴스로 다시 전달되므로, 메시지가 전송 중일 때 Redis가 전체 응답을 보관합니다.

N8N_WEBHOOK_RESPONSE_RELAY_SIZE_MAX는 그 메시지가 얼마나 클 수 있는지(MiB) 설정합니다. 기본값은 64입니다. Redis는 전송 중인 응답의 사본 여러 개를 보관하므로, 전송 중인 각 응답마다 Redis 메모리에 이 값의 약 1.5배를 예산으로 잡으세요. 오프로드하지 않으면 한도를 넘는 응답은 노드가 실패합니다.

MCP Trigger 워크플로가 worker에서 반환하는 도구 결과에도 같은 한도가 적용됩니다. 도구 결과는 오프로드할 수 없으므로, 크기가 너무 큰 것은 그 한도를 명시한 도구 오류로 MCP 클라이언트에 도달합니다.

큰 응답 본문을 저장소로 오프로드

💡 n8n 2.34.0부터 사용 가능

worker에 N8N_WEBHOOK_RESPONSE_RELAY_OFFLOAD_ENABLED=true를 설정하면 노드를 실패시키는 대신 한도를 넘는 응답 본문을 바이너리 데이터 저장에 저장합니다. 그러면 큐 메시지는 참조만 나르고, 메인 인스턴스는 저장소에서 본문을 클라이언트로 스트리밍하며, 응답을 전달한 뒤 저장된 본문을 삭제합니다.

오프로딩에는 모든 인스턴스가 읽을 수 있는 저장소가 필요합니다. default를 제외한 모든 모드가 저장하므로 N8N_DEFAULT_BINARY_DATA_MODE를 filesystem, database, s3, azure 중 하나로 설정하세요.

export N8N_WEBHOOK_RESPONSE_RELAY_SIZE_MAX=64
export N8N_WEBHOOK_RESPONSE_RELAY_OFFLOAD_ENABLED=true
export N8N_DEFAULT_BINARY_DATA_MODE=s3

n8n은 큰 응답에 s3나 azure를 권장합니다. 둘 다 본문을 스트리밍하므로 메인 인스턴스는 한 번에 한 청크만 보관합니다. 설정 방법은 외부 저장을 참고하세요. database 모드에서는 메인 인스턴스가 보내기 전에 전체 본문을 메모리에 로드하고, 응답이 기본 데이터베이스를 통과합니다. filesystem 모드에서는 모든 인스턴스가 같은 디스크를 마운트해야 하는데 n8n은 이를 권장하지 않습니다. default 모드는 바이너리 데이터를 메모리에 유지하므로 메인 인스턴스가 읽을 것이 없고, 한도를 넘는 응답은 여전히 노드가 실패합니다.

n8n은 응답 본문만 오프로드합니다. 응답의 나머지(헤더와 상태 코드)는 같은 한도로 측정하므로, 헤더만으로 한도를 넘는 응답은 어느 쪽이든 실패합니다.

업그레이드 중 오프로딩 켜기

오프로드된 본문을 읽는 것은 n8n 2.34.0 이상을 실행하는 메인 인스턴스뿐입니다. 이전 버전은 응답 본문 대신 저장소 참조를 클라이언트에 반환합니다. 먼저 모든 메인과 webhook 인스턴스를 업그레이드한 다음, worker에 N8N_WEBHOOK_RESPONSE_RELAY_OFFLOAD_ENABLED를 설정하세요. 변수가 설정되지 않은 worker는 모든 응답을 인라인으로 보내고 한도를 넘는 것은 실패시킵니다.

큰 웹훅 응답 문제 해결

오류	원인	해결책
The response is too large to be sent back from the worker, N8N_WEBHOOK_RESPONSE_RELAY_OFFLOAD_ENABLED 언급	worker에서 오프로딩이 꺼져 있습니다.	worker에 변수를 설정하거나 N8N_WEBHOOK_RESPONSE_RELAY_SIZE_MAX를 올리세요.
The response is too large to be sent back from the worker, N8N_DEFAULT_BINARY_DATA_MODE 언급	바이너리 데이터 저장이 데이터를 메모리에 보관해 오프로드할 곳이 없습니다.	N8N_DEFAULT_BINARY_DATA_MODE를 filesystem, database, s3, azure 중 하나로 설정하세요.
The response is too large for the binary-data store to hold	database 모드가 자체 크기 한도 때문에 본문을 거부했습니다.	N8N_BINARY_DATA_DATABASE_MAX_FILE_SIZE를 데이터베이스 컬럼이 담는 1 GB까지 올리거나, 자체 한도가 없는 filesystem, s3, azure로 전환하세요.
The stored webhook response body could not be read	메인 인스턴스가 worker가 쓴 저장소를 읽을 수 없습니다.	모든 인스턴스를 같은 저장소로 지정하세요. filesystem 모드에서는 모든 인스턴스가 같은 디스크를 마운트해야 하는데 n8n은 이를 권장하지 않습니다.

worker 동시성 구성

worker가 병렬로 실행할 수 있는 작업 수를 concurrency 플래그로 정의할 수 있습니다. 기본값은 10입니다. 바꾸려면:

n8n worker --concurrency=5

동시성과 스케일링 권장사항

n8n은 worker 인스턴스의 동시성을 5 이상으로 설정할 것을 권장합니다. worker 수가 많은데 낮은 동시성 값을 설정하면 데이터베이스의 연결 풀을 고갈시켜 처리 지연과 실패를 초래할 수 있습니다.

Multi-main 설정

💡 기능 가용성: Multi-main 설정은 셀프호스팅: Enterprise에서 사용 가능하며 n8n Cloud에서는 사용할 수 없습니다.

queue 모드에서 고가용성을 위해 main 프로세스를 둘 이상 실행할 수 있습니다.

단일 모드 설정에서 main 프로세스는 두 가지 작업 세트를 수행합니다.

• 일반 작업(regular tasks) — API 실행, UI 제공, 웹훅 수신 등
• at-most-once 작업 — HTTP가 아닌 트리거(타이머, 폴러, RabbitMQ·IMAP 같은 영속 연결) 실행, 실행/바이너리 데이터 정리 등

multi-main 설정에는 두 종류의 main 프로세스가 있습니다.

• follower — 일반 작업만 실행
• leader — 일반 작업과 at-most-once 작업을 모두 실행

Leader 지정

multi-main 설정에서 모든 main 인스턴스는 리더십 프로세스를 사용자에게 투명하게 처리합니다. 현재 leader를 사용할 수 없게 되면(예: 크래시하거나 이벤트 루프가 과부하) 다른 follower가 인계받습니다. 이전 leader가 다시 응답하면 follower가 됩니다.

Multi-main 설정 구성

multi-main 설정으로 n8n을 배포하려면 다음을 보장하세요.

• 모든 main 프로세스가 queue 모드로 실행되고 Postgres와 Redis에 연결됩니다.
• 모든 main과 worker 프로세스가 같은 n8n 버전을 실행합니다.
• 모든 main 프로세스가 N8N_MULTI_MAIN_SETUP_ENABLED 환경 변수를 true로 설정했습니다.
• 모든 main 프로세스가 세션 영속성(sticky sessions)이 활성화된 로드 밸런서 뒤에서 실행됩니다.

필요하면 leader 키 옵션을 조정할 수 있습니다.

설정 파일 사용	환경 변수 사용	설명
multiMainSetup.ttl:10	N8N_MULTI_MAIN_SETUP_KEY_TTL=10	multi-main 설정에서 leader 키의 TTL(초).
multiMainSetup.interval:3	N8N_MULTI_MAIN_SETUP_CHECK_INTERVAL=3	multi-main 설정에서 leader 체크 간격(초).

더 알아보기 (Learn more)

• n8n 스케일링 개요
• n8n 명령줄 사용
• 외부 저장 (바이너리/실행 데이터)