AI/Technical

n8n 사용법: Docker Compose 셀프호스팅 템플릿과 운영 체크리스트

Royzero 2026. 1. 6. 10:58
반응형

TL;DR

  • n8n을 "실서비스처럼" 셀프호스팅하려면 최소한 영속 데이터(Workflow/Execution/Credential), 웹훅 URL 정합성, 암호화 키 관리, 로그/메트릭/정리(Pruning) 까지는 세팅해야 합니다.
  • 소규모는 공식 Docker Compose(트래픽+TLS) 구성이 빠르고, 확장/내구성을 원하면 Postgres + (선택) Redis 큐 모드로 가는 게 정석입니다.ㅊ
  • 운영에서 자주 터지는 이슈는 "리버스 프록시 뒤에서 Webhook URL이 꼬임", "N8N_ENCRYPTION_KEY 분실", "Execution 데이터 폭증"입니다. 이 글은 그 3가지를 먼저 막는 템플릿과 체크리스트를 제공합니다.

본문

1) 운영 관점에서 n8n 셀프호스팅을 ‘설계’하는 법

n8n은 기본적으로 SQLite를 사용해 워크플로/실행 이력/자격증명 등을 저장하고, 셀프호스팅에서는 PostgreSQL로 전환할 수 있습니다.
또한 n8n은 v1.0에서 MySQL/MariaDB 지원을 deprecate(중단 예정/비권장) 처리했으므로, 새로 설계한다면 Postgres 전제를 추천합니다.

운영 설계를 단순화하려면, 아래 4가지만 먼저 “결정”하면 됩니다.

결정 항목 선택지 실무 권장
DB SQLite / Postgres 운영은 Postgres
실행 방식 기본 / Queue mode 트래픽·병렬 필요 시 Queue
리버스 프록시/TLS Traefik / Nginx / LB 한 가지로 표준화
데이터 정리(Pruning) 기본값 / 튜닝 반드시 튜닝

Why it matters: 셀프호스팅에서 장애는 대부분 “기능”이 아니라 “운영 기본기(영속성/보안/관측)”에서 발생합니다. 처음부터 이 4가지를 고정하면, 이후 워크플로 개발이 훨씬 편해집니다.

2) 템플릿 #1: 가장 빠른 운영형(공식 Docker Compose + TLS)

n8n 공식 문서는 Linux 서버에서 Docker Compose로 실행하는 절차를 제공하며, 예시로 n8n + Traefik(인증서/TLS/라우팅) 2개 컨테이너 구성을 안내합니다.
또한 공식 예시는 n8n 데이터(예: SQLite DB 파일, encryption key)가 볼륨에 저장됨을 명시합니다.

포인트: "작게 시작하되, HTTPS/TLS·영속 볼륨"까지는 깔고 들어가자.

2-1) 공식 흐름에서 꼭 챙길 값(.env 핵심)

공식 Compose 가이드는 .env에 도메인/서브도메인/타임존/인증서 이메일 등을 두는 예시를 제공합니다.

실무에서 추가로 자주 쓰는(혹은 반드시 고정해야 하는) 값은 아래입니다.

# n8n Base URL 정합성(리버스 프록시 뒤에서 특히 중요)
N8N_PROTOCOL=https
N8N_HOST=n8n.example.com
N8N_PORT=5678

# 외부 웹훅 URL(외부 시스템이 콜백할 주소를 강제)
WEBHOOK_URL=https://n8n.example.com/

N8N_HOST / N8N_PORT / N8N_PROTOCOL 및 WEBHOOK_URL은 n8n의 배포/엔드포인트 설정 변수로 문서화되어 있습니다.

Why it matters: 리버스 프록시 뒤에서 URL이 꼬이면, Slack/Stripe/GitHub 같은 서비스의 웹훅 콜백이 실패하거나, 에디터 UI가 잘못된 URL을 만들어냅니다. 운영에서 제일 흔한 “셀프호스팅 함정”입니다.

3) 템플릿 #2: Postgres + (선택) Redis Queue mode 운영 템플릿

3-1) Postgres로 바꿔야 하는 이유(팩트 기반)

  • n8n은 기본 SQLite에서 Postgres로 전환 가능하고, Postgres 사용 시 필요한 환경 변수를 문서로 제공합니다.
  • DB 환경 변수 페이지는 v1.0 기준으로 MySQL/MariaDB 지원 deprecate를 명시합니다.

3-2) Postgres 환경 변수 최소 세트

n8n 문서의 Postgres 설정 변수는 아래처럼 정리됩니다.

DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=postgres
DB_POSTGRESDB_PORT=5432
DB_POSTGRESDB_DATABASE=n8n
DB_POSTGRESDB_USER=n8n
DB_POSTGRESDB_PASSWORD=change-me
DB_POSTGRESDB_SCHEMA=public

Why it matters: 워크플로가 늘수록 실행 이력/로그/바이너리 데이터(첨부)까지 DB 성장이 빨라집니다. SQLite로 시작하면 “용량/성능/백업”에서 곧 한계가 옵니다.

4) Queue mode(확장형 실행) 설계 포인트

Queue mode 관련 환경 변수는 n8n 문서에 별도로 정리되어 있으며, Redis 연결 정보(호스트/포트/비밀번호 등)와 실행 방식(예: EXECUTIONS_MODE = queue일 때 클러스터 설정 동작)이 문서화되어 있습니다.

예시(.env):

# 실행 모드
EXECUTIONS_MODE=queue

# Redis (Bull queue) 연결
QUEUE_BULL_REDIS_HOST=redis
QUEUE_BULL_REDIS_PORT=6379
QUEUE_BULL_REDIS_PASSWORD=change-me

참고: Queue mode에서의 워커/메인 분리 실행 방식은 n8n "Configuring queue mode" 문서에서 다룹니다(구성 철학/스케일링 관점).

Why it matters: 트래픽이 커지면 "한 컨테이너가 웹 UI + 실행까지 다 처리"하는 구조는 병목이 됩니다. Queue mode는 실행을 분리해 수평 확장을 가능하게 하는 방향입니다.

5) 실무용 Docker Compose 예시(운영 템플릿)

아래 compose는 Postgres + Redis + n8n의 최소 운영형 예시입니다. (공식 문서에 나온 환경 변수 정의를 기반으로 작성한 예시이며, 실제 운영에서는 네트워크/보안 정책에 맞게 수정하세요.)

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: n8n
      POSTGRES_USER: n8n
      POSTGRES_PASSWORD: change-me
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7
    command: ["redis-server", "--requirepass", "change-me"]
    volumes:
      - redis_data:/data

  n8n:
    image: docker.n8n.io/n8nio/n8n
    ports:
      - "5678:5678"
    environment:
      # Base URL / Webhook
      - N8N_PROTOCOL=https
      - N8N_HOST=n8n.example.com
      - N8N_PORT=5678
      - WEBHOOK_URL=https://n8n.example.com/

      # Encryption key (반드시 고정)
      - N8N_ENCRYPTION_KEY=replace-with-32+chars-secret

      # Database (Postgres)
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=change-me

      # Queue mode + Redis
      - EXECUTIONS_MODE=queue
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
      - QUEUE_BULL_REDIS_PASSWORD=change-me

      # Execution pruning (기본 활성화지만, 운영에서는 정책을 명시)
      - EXECUTIONS_DATA_PRUNE=true
      - EXECUTIONS_DATA_MAX_AGE=336
      - EXECUTIONS_DATA_PRUNE_MAX_COUNT=10000

      # Metrics (Prometheus)
      - N8N_METRICS=true
      - N8N_METRICS_INCLUDE_QUEUE_METRICS=true

      # Queue mode에서는 filesystem 바이너리 모드를 지원하지 않음 → database 권장
      - N8N_DEFAULT_BINARY_DATA_MODE=database

    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      - postgres
      - redis

volumes:
  postgres_data:
  redis_data:
  n8n_data:
  • n8n의 기본 포트(예: 5678)와 실행 예시는 Docker 문서 예제에서도 반복적으로 등장합니다.
  • N8N_DEFAULT_BINARY_DATA_MODE는 바이너리 데이터(파일)를 메모리 대신 저장하는 전략과 연결되고, Queue mode에서는 filesystem을 지원하지 않는다고 문서에 명시되어 있습니다.
  • 실행 데이터(Execution data) 정리는 n8n이 기본적으로 pruning을 활성화하며, 기본값(예: 14일/1만 건 기준)을 문서로 제공합니다.
  • Prometheus 메트릭은 기본 비활성이며, 환경 변수로 활성화하는 방식이 문서화되어 있습니다.

Why it matters: 이 템플릿이 막아주는 운영 사고는 세 가지입니다. (1) 암호화 키 유실로 인한 Credential 복호화 불가, (2) 실행 이력 폭증으로 DB 디스크 고갈, (3) 웹훅 URL 꼬임으로 외부 연동 실패. 전부 "초기 세팅"에서 예방 가능합니다.

6) N8N_ENCRYPTION_KEY: 운영에서 ‘절대’ 잃어버리면 안 되는 값

n8n은 자격증명(Credentials)을 암호화하며, 설치 시 생성되는 키가 ~/.n8n에 저장될 수 있고(볼륨/디렉터리 마운트), 운영에서는 사용자 지정 키를 고정하는 방식을 문서로 제공합니다.

# 예시: 사용자 지정 키를 고정
N8N_ENCRYPTION_KEY=replace-with-strong-secret

Why it matters: 컨테이너를 재배포하거나 볼륨을 교체할 때 키가 바뀌면, 저장된 Credential이 “있는데도 못 여는” 상태가 됩니다. 운영 사고로 직결됩니다.

7) 실행 데이터(Execution data) 저장/정리 정책

n8n은 실행 데이터가 쌓이면 DB가 커져 스토리지가 부족해질 수 있으며, 불필요한 저장을 줄이고 pruning을 활성화하라고 권장합니다.
또한 문서에 따르면 pruning은 기본 활성화이며, 기본 조건(예: 완료 후 336시간/총 10,000건 초과 시)을 기준으로 정리합니다.

운영에서 자주 쓰는 정책 예시:

# 성공 실행은 저장하지 않고, 에러만 남기는 식으로 튜닝 가능
EXECUTIONS_DATA_SAVE_ON_ERROR=all
EXECUTIONS_DATA_SAVE_ON_SUCCESS=none
EXECUTIONS_DATA_SAVE_ON_PROGRESS=false
EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS=false

위 변수는 "Execution data" 문서에서 예시로 안내합니다.

Why it matters: 실행 데이터는 “쌓이는 속도”가 워크플로 성공 여부와 무관하게 빨라질 수 있습니다(스케줄링/폴링/웹훅 트래픽). 정리 정책 없이는 디스크 고갈이 시간문제입니다.

8) 관측: Prometheus Metrics와 큐 메트릭

n8n은 Prometheus 메트릭을 환경 변수로 활성화할 수 있고, 큐 관련 메트릭 포함 여부도 별도 옵션으로 제공합니다.

N8N_METRICS=true
N8N_METRICS_INCLUDE_QUEUE_METRICS=true

간단 확인:

curl -s http://localhost:5678/metrics | head

Why it matters: "잘 되고 있는지"는 로그만으로는 부족합니다. 큐 길이/처리량/실패율이 보이면, 워커 증설 같은 대응이 빨라집니다.

9) 백업/복구: 워크플로·크레덴셜을 ‘파일’로도 뽑아두기

n8n은 CLI를 통해 워크플로/크레덴셜/사용자 등을 export/import하는 명령을 제공합니다.
운영에서는 DB 백업과 별개로, 최소한 워크플로는 주기적으로 파일 export를 권장합니다.

# 워크플로 내보내기 예시(환경에 맞게 경로/옵션 조정)
n8n export:workflow --all --output=/backups/workflows.json

# 크레덴셜 내보내기(민감 정보 주의)
n8n export:credentials --all --output=/backups/credentials.json

또한 공식 Docker Compose 가이드는 n8n 데이터가 /home/node/.n8n에 저장되고(볼륨 마운트), 이것이 SQLite DB/키 저장 위치가 될 수 있음을 설명합니다.

Why it matters: "DB만 백업"하면, 복구 시점/권한/설정이 어긋나 복원 시간이 길어질 수 있습니다. 워크플로 export는 가장 빠른 복구 카드입니다.

10) TLS/인증서: HTTP-01은 80 포트를 요구한다(현업 팁)

Let's Encrypt 문서에 따르면 HTTP-01 챌린지는 80 포트에서만 수행될 수 있고, 임의 포트를 허용하지 않는다고 명시합니다.
즉, "인증서 자동 발급"을 HTTP-01로 하려면, 대개 80/443 포트 경로 설계가 필요합니다.

공식 n8n Docker Compose 예시는 Traefik으로 TLS를 처리하며, 예시 구성에서는 "HTTPS로만 접근 가능"하다고 명시합니다.

Why it matters: 인증서 자동화가 막히면 운영이 수동 작업(갱신/만료)으로 변하고, 만료 사고가 곧 장애가 됩니다. 초기에 포트/라우팅을 설계해두는 게 중요합니다.

11) 운영 체크리스트(실무용)

구분 체크 기준
URL/웹훅 WEBHOOK_URL 고정 리버스 프록시/외부 콜백 정상
포트 내부 5678(표준) 프록시가 upstream으로 전달
암호화 키 N8N_ENCRYPTION_KEY 고정/백업 Credential 복구 가능
DB Postgres 전환 MySQL/MariaDB deprecate
큐 모드 Redis 연결 변수 점검 확장/병렬 처리
바이너리 Queue mode면 database filesystem 미지원
정리 execution pruning 정책 명시 기본 14일/1만건 등
관측 Prometheus metrics 활성화 장애 탐지/용량 계획
백업 CLI export + 볼륨/DB 백업 빠른 복구 경로
보안 v1.0 이후 사용자 관리 전제 기본 인증(basic auth)만 믿지 않기

Why it matters: 체크리스트는 “기능”이 아니라 “운영 실패 지점”을 막기 위한 것입니다. 위 10개가 맞으면, 대부분의 셀프호스팅 장애(연동 실패/데이터 손실/용량 고갈/관측 부재)를 크게 줄일 수 있습니다.

결론 (요약 정리)

  • 소규모는 공식 Docker Compose(TLS 포함)로 빠르게 시작하고, 운영 확장 시 Postgres + (선택) Redis Queue mode로 설계를 옮기는 것이 안전합니다.
  • 운영에서 가장 중요한 값은 WEBHOOK_URL, N8N_ENCRYPTION_KEY, Execution pruning 정책입니다.
  • Prometheus 메트릭과 CLI export는 "장애 대응 속도"를 올려주는 즉효 수단입니다.

References

반응형
저작자표시 비영리 변경금지 (새창열림)

'AI > Technical' 카테고리의 다른 글

NVIDIA 그래픽 카드 모델(대표)별 Ollama 추천 모델 표  (13) 2026.01.09
Kubeflow 사용법: 설치부터 Pipelines·Trainer·KServe까지  (2) 2026.01.08
n8n 사용법 실무 가이드: Webhook·스케줄·에러처리 3종 워크플로우  (4) 2026.01.06
n8n 사용법 2편: Webhook·에러처리·큐 모드로 실무 자동화 구축  (6) 2026.01.06
n8n 사용법: 워크플로 자동화 시작부터 운영·확장까지  (1) 2026.01.05

'AI/Technical'의 다른글

  • 현재글n8n 사용법: Docker Compose 셀프호스팅 템플릿과 운영 체크리스트

관련글

티스토리툴바