큐 모드
필요에 따라 n8n을 다양한 모드로 실행할 수 있습니다. n8n은 파일시스템에 바이너리 데이터를 저장하는 큐 모드를 지원하지 않습니다. 큐 모드로 실행할 때는 여러 n8n 인스턴스를 설정하며, 하나의 메인 인스턴스가 워크플로 정보(예: 트리거)를 받고 워커 인스턴스가 실행을 수행합니다.
필요에 따라 n8n을 다양한 모드로 실행할 수 있습니다. 큐 모드는 최고의 확장성을 제공합니다.
n8n은 파일시스템에 바이너리 데이터를 저장하는 큐 모드를 지원하지 않습니다. 워크플로가 큐 모드에서 바이너리 데이터를 유지해야 하는 경우 S3 외부 스토리지를 사용할 수 있습니다.
작동 방식#
큐 모드로 실행할 때는 여러 n8n 인스턴스를 설정하며, 하나의 메인 인스턴스가 워크플로 정보(예: 트리거)를 받고 워커 인스턴스가 실행을 수행합니다.
각 워커는 자체 Node.js 인스턴스이며 main 모드로 실행되지만 높은 IOPS(초당 입출력 작업 수) 덕분에 여러 워크플로 실행을 동시에 처리할 수 있습니다.
워커 인스턴스를 사용하고 큐 모드로 실행함으로써 워크로드를 처리하기 위해 필요에 따라 n8n을 확장(워커 추가) 및 축소(워커 제거)할 수 있습니다.
프로세스 흐름은 다음과 같습니다:
- 메인 n8n 인스턴스가 타이머와 웹훅 호출을 처리하여 워크플로 실행을 생성합니다(실행하지는 않음).
- 실행 ID를 메시지 브로커인 Redis에 전달하며, Redis는 대기 중인 실행의 큐를 유지하고 다음 사용 가능한 워커가 이를 가져갈 수 있도록 합니다.
- 풀의 워커가 Redis에서 메시지를 가져옵니다.
- 워커는 실행 ID를 사용하여 데이터베이스에서 워크플로 정보를 가져옵니다.
- 워크플로 실행을 완료한 후 워커는:
- 결과를 데이터베이스에 씁니다.
- Redis에 실행이 완료되었다고 게시합니다.
- Redis가 메인 인스턴스에 알립니다.
워커 구성#
워커는 실제 작업을 수행하는 n8n 인스턴스입니다. 메인 n8n 프로세스로부터 실행해야 할 워크플로에 대한 정보를 받아 워크플로를 실행하고 각 실행이 완료된 후 상태를 업데이트합니다.
워커가 쓰기 가능한 파일시스템을 공유하는 경우 각 워커 프로세스에 고유한 이벤트 로그 경로를 지정하세요. 자세한 내용은 프로세스별 이벤트 로그 파일을 참조하세요.
암호화 키 설정#
n8n은 처음 시작할 때 자동으로 암호화 키를 생성합니다. 원하는 경우 환경 변수를 사용하여 사용자 정의 키를 제공할 수도 있습니다.
메인 n8n 인스턴스의 암호화 키는 모든 워커 및 웹훅 프로세서 노드와 공유되어야 하며, 이를 통해 이러한 워커 노드가 데이터베이스에 저장된 자격 증명에 액세스할 수 있습니다.
각 워커 노드의 암호화 키를 구성 파일에서 또는 해당 환경 변수를 설정하여 지정합니다:
export N8N_ENCRYPTION_KEY=<main_instance_encryption_key>
실행 모드 설정#
n8n은 Postgres 13+ 사용을 권장합니다. 실행 모드를 queue로 설정하고 SQLite 데이터베이스와 함께 n8n을 실행하는 것은 권장되지 않습니다.
다음 명령을 사용하여 메인 인스턴스 및 모든 워커에서 환경 변수 EXECUTIONS_MODE를 queue로 설정합니다.
export EXECUTIONS_MODE=queue
또는 구성 파일에서 executions.mode를 queue로 설정할 수 있습니다.
Redis 시작#
Redis를 별도 머신에서 실행할 수 있으며, n8n 인스턴스에서 액세스할 수 있는지만 확인하면 됩니다.
Docker 컨테이너에서 Redis를 실행하려면 아래 지침을 따르세요:
다음 명령을 실행하여 Redis 인스턴스를 시작합니다:
docker run --name some-redis -p 6379:6379 -d redis
기본적으로 Redis는 포트 6379의 localhost에서 비밀번호 없이 실행됩니다. 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를 사용할 수 없을 때 종료하기 전에 n8n이 대기해야 하는 시간을 알려줍니다. 기본값은 10000(ms)입니다. |
queue.bull.gracefulShutdownTimeout:30 |
N8N_GRACEFUL_SHUTDOWN_TIMEOUT |
워커가 프로세스를 종료하기 전에 작업 실행을 완료하기 위한 정상 종료 타임아웃입니다. 기본값은 30초입니다. |
이제 n8n 인스턴스를 시작하면 Redis 인스턴스에 연결됩니다.
워커 시작#
n8n이 워크플로를 실행하도록 하려면 워커 프로세스를 시작해야 합니다. 별도 머신에서 워커를 호스팅하려면 해당 머신에 n8n을 설치하고 Redis 인스턴스와 n8n 데이터베이스에 연결되어 있는지 확인하세요.
루트 디렉터리에서 다음 명령을 실행하여 워커 프로세스를 시작합니다:
./packages/cli/bin/n8n worker
Docker를 사용하는 경우 다음 명령을 사용하세요:
docker run --name n8n-queue -p 5679:5678 docker.n8n.io/n8nio/n8n worker
여러 워커 프로세스를 설정할 수 있습니다. 모든 워커 프로세스가 Redis와 n8n 데이터베이스에 액세스할 수 있는지 확인하세요.
워커 서버#
각 워커 프로세스는 선택적 엔드포인트를 노출하는 서버를 실행합니다:
/healthz:QUEUE_HEALTH_CHECK_ACTIVE환경 변수를 활성화한 경우 워커가 작동 중인지 여부를 반환합니다/healthz/readiness:QUEUE_HEALTH_CHECK_ACTIVE환경 변수를 활성화한 경우 워커의 DB 및 Redis 연결이 준비되었는지 여부를 반환합니다- 자격 증명 덮어쓰기 엔드포인트
/metrics
N8N_ENDPOINT_HEALTH 환경 변수를 사용하여 헬스 체크 엔드포인트 경로를 커스터마이징할 수 있습니다.
실행 중인 워커 보기#
- 셀프 호스팅 Enterprise 플랜에서 사용 가능합니다.
- Cloud Enterprise에서 이 기능에 액세스하려면 n8n에 문의하세요.
Settings > Workers를 선택하여 n8n에서 실행 중인 워커와 성능 메트릭을 볼 수 있습니다.
큐로 n8n 실행#
큐로 n8n을 실행할 때 모든 프로덕션 워크플로 실행은 워커 프로세스에서 처리됩니다. 웹훅의 경우 HTTP 요청은 메인/웹훅 프로세스에서 수신되지만 실제 워크플로 실행은 워커로 전달되며, 이로 인해 약간의 오버헤드와 지연이 추가될 수 있습니다.
Redis는 메시지 브로커 역할을 하고 데이터베이스는 데이터를 유지하므로 둘 다에 대한 액세스가 필요합니다. SQLite로 이 설정으로 분산 시스템을 실행하는 것은 지원되지 않습니다.
한 데이터베이스에서 다른 데이터베이스로 데이터를 마이그레이션하려면 Export 및 Import 명령을 사용할 수 있습니다. 이러한 명령을 사용하는 방법은 n8n용 CLI 명령 문서를 참조하세요.
웹훅 프로세서#
웹훅 프로세스는 Redis에 의존하며 EXECUTIONS_MODE 환경 변수도 설정해야 합니다. 웹훅 프로세서 노드를 설정하려면 위의 워커 구성 섹션을 따르세요.
웹훅 프로세서는 n8n의 또 다른 확장 레이어입니다. 웹훅 프로세서 구성은 선택 사항이며, 수신되는 웹훅 요청을 확장할 수 있습니다.
이 방법을 사용하면 n8n이 엄청나게 많은 병렬 요청을 처리할 수 있습니다. 웹훅 프로세스와 워커를 추가하기만 하면 됩니다. 웹훅 프로세스는 동일한 포트(기본값: 5678)에서 요청을 수신합니다. 이러한 프로세스를 컨테이너 또는 별도 머신에서 실행하고 로드 밸런싱 시스템을 사용하여 요청을 적절히 라우팅하세요.
n8n은 메인 프로세스를 로드 밸런서 풀에 추가하는 것을 권장하지 않습니다. 메인 프로세스를 풀에 추가하면 요청을 받고 과도한 부하를 받을 수 있습니다. 이로 인해 n8n UI를 편집, 보기 및 상호작용하는 데 성능이 저하됩니다.
루트 디렉터리에서 다음 명령을 실행하여 웹훅 프로세서를 시작할 수 있습니다:
./packages/cli/bin/n8n webhook
Docker를 사용하는 경우 다음 명령을 사용하세요:
docker run --name n8n-queue -p 5679:5678 -e "EXECUTIONS_MODE=queue" docker.n8n.io/n8nio/n8n webhook
웹훅 URL 구성#
웹훅 URL을 구성하려면 메인 n8n 인스턴스를 실행하는 머신에서 다음 명령을 실행하세요:
export WEBHOOK_URL=https://your-webhook-url.com
구성 파일에서 이 값을 설정할 수도 있습니다.
로드 밸런서 구성#
여러 웹훅 프로세스를 사용할 때는 요청을 라우팅하기 위한 로드 밸런서가 필요합니다. n8n 인스턴스와 웹훅에 동일한 도메인 이름을 사용하는 경우 다음과 같이 요청을 라우팅하도록 로드 밸런서를 설정할 수 있습니다:
- 웹훅 트리거를 웹훅 서버 풀로 리디렉션합니다. 고려할 경로:
/webhook/*: Webhook 트리거 노드 엔드포인트/webhook-waiting/*: "전송 후 대기" 작업을 수행하는 노드(예: Slack 노드)에서 사용하는 Human-in-the-loop 웹훅 엔드포인트
- 다른 모든 경로(n8n 내부 API, 편집기용 정적 파일 등)는 메인 프로세스로 라우팅되어야 합니다
참고: 수동 워크플로 실행을 위한 기본 URL은 /webhook-test/*입니다. 이러한 URL이 메인 프로세스로 라우팅되는지 확인하세요.
구성 파일 endpoints.webhook에서 또는 N8N_ENDPOINT_WEBHOOK 환경 변수를 사용하여 이 경로를 변경할 수 있습니다. 이를 변경하는 경우 로드 밸런서도 그에 따라 업데이트하세요.
메인 프로세스에서 웹훅 처리 비활성화 (선택 사항)#
워크플로를 실행할 웹훅 프로세서가 있습니다. 메인 프로세스에서 웹훅 처리를 비활성화할 수 있습니다. 이렇게 하면 모든 웹훅 실행이 웹훅 프로세서에서 실행됩니다. 구성 파일에서 endpoints.disableProductionWebhooksOnMainProcess를 true로 설정하면 n8n이 메인 프로세스에서 웹훅 요청을 처리하지 않습니다.
또는 다음 명령을 사용할 수 있습니다:
export N8N_DISABLE_PRODUCTION_MAIN_PROCESS=true
메인 프로세스에서 웹훅 프로세스를 비활성화할 때는 메인 프로세스를 실행하고 로드 밸런서의 웹훅 풀에 추가하지 마세요.
워커 동시성 구성#
concurrency 플래그를 사용하여 워커가 병렬로 실행할 수 있는 작업 수를 정의할 수 있습니다. 기본값은 10입니다. 변경하려면:
n8n worker --concurrency=5
동시성 및 확장 권장사항#
n8n은 워커 인스턴스의 동시성을 5 이상으로 설정하는 것을 권장합니다. 많은 수의 워커와 함께 낮은 동시성 값을 설정하면 데이터베이스의 연결 풀이 고갈되어 처리 지연 및 실패가 발생할 수 있습니다.
멀티 메인 설정#
- 셀프 호스팅 Enterprise 플랜에서 사용 가능합니다.
큐 모드에서 고가용성을 위해 둘 이상의 main 프로세스를 실행할 수 있습니다.
싱글 모드 설정에서 main 프로세스는 두 가지 작업 세트를 수행합니다:
- 일반 작업: API 실행, UI 제공, 웹훅 수신 등
- 한 번만 실행 작업: 비HTTP 트리거(타이머, 폴러, RabbitMQ 및 IMAP과 같은 영구 연결) 실행, 실행 및 바이너리 데이터 정리 등
멀티 메인 설정에는 두 종류의 main 프로세스가 있습니다:
- 팔로워: 일반 작업 실행
- 리더: 일반 작업과 한 번만 실행 작업 모두 실행
리더 지정#
멀티 메인 설정에서 모든 메인 인스턴스는 사용자에게 투명하게 리더십 프로세스를 처리합니다. 현재 리더가 사용 불가능해지는 경우(예: 충돌하거나 이벤트 루프가 너무 바빠짐) 다른 팔로워가 인계받을 수 있습니다. 이전 리더가 다시 응답하게 되면 팔로워가 됩니다.
멀티 메인 설정 구성#
멀티 메인 설정으로 n8n을 배포하려면 다음을 확인하세요:
- 모든
main프로세스가 큐 모드로 실행되고 Postgres 및 Redis에 연결되어 있음 - 모든
main및worker프로세스가 동일한 버전의 n8n을 실행 중임 - 모든
main프로세스가 환경 변수N8N_MULTI_MAIN_SETUP_ENABLED를true로 설정함 - 모든
main프로세스가 세션 지속성(스티키 세션)이 활성화된 로드 밸런서 뒤에서 실행됨
필요한 경우 리더 키 옵션을 조정할 수 있습니다:
| 구성 파일 사용 | 환경 변수 사용 | 설명 |
|---|---|---|
multiMainSetup.ttl:10 |
N8N_MULTI_MAIN_SETUP_KEY_TTL=10 |
멀티 메인 설정에서 리더 키의 TTL(Time to Live, 초 단위)입니다. |
multiMainSetup.interval:3 |
N8N_MULTI_MAIN_SETUP_CHECK_INTERVAL=3 |
멀티 메인 설정에서 리더 확인 간격(초 단위)입니다. |