필요에 따라 n8n을 다양한 모드로 실행할 수 있습니다. 큐 모드는 최고의 확장성을 제공합니다.

작동 방식#

큐 모드로 실행할 때는 여러 n8n 인스턴스를 설정하며, 하나의 메인 인스턴스가 워크플로 정보(예: 트리거)를 수신하고 워커 인스턴스가 실행을 수행합니다.

각 워커는 자체 Node.js 인스턴스로, main 모드로 실행되지만 높은 IOPS(초당 입출력 작업 수) 덕분에 여러 워크플로 실행을 동시에 처리할 수 있습니다.

워커 인스턴스를 사용하고 큐 모드로 실행하면 워크로드를 처리하기 위해 필요에 따라 워커를 추가하여 확장하거나(scale up) 워커를 제거하여 축소(scale down)할 수 있습니다.

처리 흐름은 다음과 같습니다.

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

워커 구성#

워커는 실제 작업을 수행하는 n8n 인스턴스입니다. 메인 n8n 프로세스로부터 실행해야 할 워크플로에 대한 정보를 수신하고, 워크플로를 실행하며, 각 실행이 완료된 후 상태를 업데이트합니다.

암호화 키 설정#

n8n은 최초 시작 시 암호화 키를 자동으로 생성합니다. 원한다면 환경 변수를 사용해 직접 사용자 지정 키를 제공할 수도 있습니다.

워커 노드가 데이터베이스에 저장된 자격 증명에 접근할 수 있도록, 메인 n8n 인스턴스의 암호화 키를 모든 워커 및 웹훅 프로세서 노드와 공유해야 합니다.

구성 파일에서 각 워커 노드의 암호화 키를 설정하거나, 해당 환경 변수를 설정하세요.

export N8N_ENCRYPTION_KEY=<main_instance_encryption_key>

실행 모드 설정#

다음 명령을 사용하여 메인 인스턴스와 모든 워커에서 환경 변수 EXECUTIONS_MODE를 queue로 설정하세요.

export EXECUTIONS_MODE=queue

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

Redis 시작#

Docker 컨테이너에서 Redis를 실행하려면 아래 지침을 따르세요.

다음 명령을 실행하여 Redis 인스턴스를 시작합니다.

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

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

다음과 같은 선택적 구성도 설정할 수 있습니다.

이제 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

실행 중인 워커 보기#

Settings > Workers를 선택하면 n8n에서 실행 중인 워커와 그 성능 지표를 확인할 수 있습니다.

큐를 사용하여 n8n 실행하기#

큐를 사용하여 n8n을 실행하면 모든 프로덕션 워크플로 실행이 워커 프로세스에 의해 처리됩니다. 웹훅의 경우 HTTP 요청은 메인/웹훅 프로세스가 수신하지만, 실제 워크플로 실행은 워커에게 전달되며 이로 인해 약간의 오버헤드와 지연 시간이 발생할 수 있습니다.

Redis는 메시지 브로커 역할을 하고, 데이터베이스는 데이터를 유지하므로 두 곳 모두에 대한 접근이 필요합니다. 이 설정으로 SQLite 상에서 분산 시스템을 실행하는 것은 지원되지 않습니다.

웹훅 프로세서#

웹훅 프로세서는 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-waiting/*: "전송 후 대기(send and wait)" 작업을 수행하는 노드(예: 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 이상으로 설정할 것을 권장합니다. 워커 수가 많은데 동시성 값을 낮게 설정하면 데이터베이스의 커넥션 풀이 고갈되어 처리 지연이나 실패로 이어질 수 있습니다.

멀티 메인 설정#

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

싱글 메인 설정에서는 main 프로세스가 두 가지 종류의 작업을 수행합니다.

• 일반 작업(regular tasks): API 실행, UI 제공, 웹훅 수신 대기 등
• 최대 1회 실행 작업(at-most-once tasks): 비-HTTP 트리거(타이머, 폴러, RabbitMQ 및 IMAP와 같은 지속 연결) 실행, 실행 기록 및 바이너리 데이터 정리 등

멀티 메인 설정에서는 두 종류의 main 프로세스가 존재합니다.

• 팔로워(followers): 일반 작업을 실행합니다.
• 리더(leader): 일반 작업과 최대 1회 실행 작업을 모두 실행합니다.

리더 지정#

멀티 메인 설정에서는 모든 메인 인스턴스가 사용자에게 드러나지 않게 리더십 프로세스를 처리합니다. 현재 리더를 사용할 수 없게 되는 경우(예: 충돌했거나 이벤트 루프가 너무 바빠진 경우), 다른 팔로워가 리더 역할을 넘겨받을 수 있습니다. 이전 리더가 다시 응답 가능한 상태가 되면 팔로워가 됩니다.

멀티 메인 설정 구성하기#

멀티 메인 설정으로 n8n을 배포하려면 다음을 확인하세요.

• 모든 main 프로세스가 큐 모드로 실행 중이며 Postgres 및 Redis에 연결되어 있는지
• 모든 main 및 worker 프로세스가 동일한 버전의 n8n을 실행하고 있는지
• 모든 main 프로세스에서 환경 변수 N8N_MULTI_MAIN_SETUP_ENABLED를 true로 설정했는지
• 모든 main 프로세스가 세션 지속성(스티키 세션)이 활성화된 로드 밸런서 뒤에서 실행되고 있는지

필요한 경우 리더 키 옵션을 조정할 수 있습니다.