Queue Mode로 n8n 수평 확장하기

📖 이론10분

🛠️ 실습15분

🎯 미션5분

"확장성은 처음부터 설계하는 것이 아니라, 필요할 때 추가하는 것이다."

— 마틴 파울러 (Martin Fowler, 소프트웨어 설계 전문가)

🎯 오늘의 학습 목표

Queue Mode 아키텍처의 구조와 동작 원리를 설명할 수 있다.
Redis + Worker 구조의 docker-compose.yml을 작성할 수 있다.
Queue Mode 전환 후 정상 동작을 확인할 수 있다.

Queue Mode 아키텍처

text

[사용자 브라우저]
       ↓
[n8n Main 서버]  ← 워크플로우 편집, 사용자 관리, 스케줄링
       ↓ 작업을 큐에 넣음
  [Redis 큐]    ← 대기 중인 작업 목록 저장 (초고속)
    ↓       ↓
[Worker 1] [Worker 2]  ← 실제 워크플로우 실행

언제 Queue Mode가 필요한가?

동시에 10개 이상의 워크플로우가 실행될 때, 워크플로우 실행 지연이 지속적으로 2~3초 이상일 때, CPU 사용률이 80% 이상으로 자주 올라갈 때 Queue Mode를 고려하세요.

Queue Mode docker-compose.yml

yaml

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
      interval: 5s
      timeout: 5s
      retries: 10

  redis:
    image: redis:7-alpine
    restart: unless-stopped
    command: redis-server --appendonly yes
    volumes:
      - ./data/redis:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 5

  n8n-main:
    image: n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=${POSTGRES_DB}
      - DB_POSTGRESDB_USER=${POSTGRES_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
      - N8N_HOST=${N8N_HOST}
      - N8N_PORT=${N8N_PORT}
      - N8N_PROTOCOL=${N8N_PROTOCOL}
      - WEBHOOK_URL=${WEBHOOK_URL}
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_RUNNERS_ENABLED=true
    volumes:
      - ./data/n8n:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  n8n-worker-1:
    image: n8nio/n8n:latest
    restart: unless-stopped
    command: ["n8n", "worker", "--concurrency=5"]
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=${POSTGRES_DB}
      - DB_POSTGRESDB_USER=${POSTGRES_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_RUNNERS_ENABLED=true
    volumes:
      - ./data/n8n:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

  n8n-worker-2:
    image: n8nio/n8n:latest
    restart: unless-stopped
    command: ["n8n", "worker", "--concurrency=5"]
    environment:
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=${POSTGRES_DB}
      - DB_POSTGRESDB_USER=${POSTGRES_USER}
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
      - GENERIC_TIMEZONE=${GENERIC_TIMEZONE}
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_RUNNERS_ENABLED=true
    volumes:
      - ./data/n8n:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy

재시작 및 상태 확인

bash

docker compose down
docker compose up -d
docker compose ps

Queue 상태 모니터링

bash

# 대기 중인 작업 수 확인
docker compose exec redis redis-cli llen bull:jobs:wait

# 실행 중인 작업 수 확인
docker compose exec redis redis-cli llen bull:jobs:active

💡 워커 수를 늘리려면 n8n-worker-3, n8n-worker-4 블록을 동일한 방식으로 추가하면 됩니다.

🛠️ DAY 21 실습

Step 1docker-compose.yml Queue Mode로 교체

기존 docker-compose.yml 백업: cp docker-compose.yml docker-compose.yml.bak
위의 Queue Mode 설정으로 docker-compose.yml 교체
data/redis 디렉토리 생성: mkdir -p ~/n8n/data/redis

Step 2컨테이너 재시작 및 확인

docker compose down 후 docker compose up -d 실행
docker compose ps 로 5개 컨테이너 모두 running 확인
docker compose logs n8n-main --tail=20 으로 오류 없는지 확인

Step 3Queue Mode 동작 테스트

n8n에서 여러 워크플로우를 동시에 수동 실행
redis-cli llen bull:jobs:active 로 분산 처리 확인
Executions 탭에서 Worker가 처리한 결과 확인

🚀 DAY 21 미션

Queue Mode로 전환하여 n8n-main, n8n-worker-1, n8n-worker-2, redis, postgres 5개 컨테이너가 모두 정상 동작하는 환경을 완성하세요.

☑️ 미션 체크리스트

docker-compose.yml Queue Mode로 교체 완료
5개 컨테이너 모두 running 상태 확인
워크플로우 동시 실행 테스트 완료
Queue 모니터링 명령어 동작 확인

💡 힌트: Queue Mode 전환 후 기존 워크플로우가 Published 상태인지 반드시 확인하세요. Draft 상태는 실행되지 않습니다.

🎯 성공 기준: docker compose ps 결과에서 5개 컨테이너가 모두 running (healthy) 또는 running 상태