가이드

작성자 Matt Connor 2026-07-15 · 업데이트됨 2026-08-27

n8n Docker 설치 및 HTTPS 설정 가이드

Q: n8n 웹훅이 전혀 작동하지 않는 이유는 무엇입니까?

거의 대부분 WEBHOOK_URL 설정 문제입니다. 이 값이 설정되지 않았거나 잘못된 경우, n8n은 N8N_HOST:N8N_PORT을 기반으로 웹훅 주소를 생성합니다. 이때 주소에 :5678이나 localhost가 포함되어 유효해 보일 수 있지만, 실제로는 인터넷에서 접근할 수 없어 호출자의 요청이 도달하지 못합니다. WEBHOOK_URL=https://n8n.example.com/을 설정하고 노드에 포트 번호가 없는 URL이 표시되는지 확인하십시오. 두 번째 원인은 워크플로가 Active 상태로 전환되지 않은 웹훅을 호출하는 경우이며, 이 경우 The requested webhook ... is not registered. 응답이 반환됩니다.

Q: n8n에서 무엇을 백업해야 합니까?

두 가지입니다. 첫째는 .env 파일의 N8N_ENCRYPTION_KEY입니다. 모든 저장된 자격 증명은 이 키로 암호화되므로 분실 시 영구적으로 복호화할 수 없습니다. 생성 즉시 서버 외부로 복사해 두십시오. 둘째는 워크플로, 실행 기록, 자격 증명이 포함된 Postgres 데이터베이스의 pg_dump입니다. 복구 시에는 동일한 키와 데이터베이스 덤프 파일이 모두 필요합니다.

Q: n8n을 안전하게 업그레이드하려면 어떻게 해야 합니까?

latest 대신 특정 이미지 태그를 고정하십시오. n8n은 시작 시 자동으로 마이그레이션을 수행하므로 먼저 pg_dump을 생성하고, 릴리스 노트에서 변경 사항을 확인한 뒤 태그 버전을 올리고 docker compose pull n8n && docker compose up -d n8n를 실행하십시오. 컨테이너는 일회용이므로, 문제가 발생하면 이전 태그로 되돌리고 업그레이드 전 덤프 파일을 복원하여 롤백할 수 있습니다.

VPS 환경에서 Docker Compose와 Postgres를 사용하여 n8n을 구축하는 방법을 다룹니다. WEBHOOK_URL 설정 오류와 N8N_ENCRYPTION_KEY 누락으로 인한 데이터 손실 방지법 및 HTTPS 리버스 프록시 구성의 핵심을 정리했습니다.

구축할 시스템

n8n은 워크플로우 자동화 도구입니다. 트리거, 웹훅, 스케줄, 폼 제출 등의 이벤트가 발생하면 API 호출, 데이터 변환, 외부 시스템 기록으로 이어지는 노드 체인을 실행하는 시각적 편집기를 제공합니다. n8n은 별도의 서비스 코드를 작성하지 않고도 모든 모델 제공자 및 데이터베이스와 통신할 수 있어, AI 에이전트 워크플로우를 위한 표준 접착제 역할을 합니다. docker run 하나면 2분 안에 작동하는 편집기를 얻을 수 있습니다. 이 가이드는 나머지 90%의 과정, 즉 기본값인 SQLite 파일 대신 Postgres를 사용하여 내구성을 확보하고, HTTPS를 통해 접근 가능하게 만들며, 많은 사용자가 실수하는 부분인 외부에서 실제로 도달 가능한 웹훅 URL을 구성하는 방법을 다룹니다.

완성된 스택은 하나의 Docker 네트워크 위에서 동작하는 두 개의 컨테이너로 구성됩니다. 하나는 n8n 본체이고, 다른 하나는 워크플로우와 자격 증명을 저장하는 Postgres 데이터베이스입니다. 호스트의 리버스 프록시는 TLS를 종료하고 localhost의 n8n으로 요청을 전달하므로, 프록시를 통하지 않고는 인터넷에 노출되는 서비스가 없습니다. 이 구성은 2026년 셀프 호스팅 추천 목록에 있는 다른 서비스들과 함께 운영됩니다.

사전 요구 사항 및 현실적인 제한 사항

VPS에는 최소 1 GB RAM이 필요하다. 워크플로가 실제 작업을 수행하기 시작하면 2 GB를 기준으로 계획해야 한다. 실행 프로세스와 Node.js 런타임이 메모리를 사용하기 때문이다. 실행 중인 컨테이너가 out-of-memory killer에 의해 종료되면 이를 알게 되는 방식으로는 곤란하다. 시작할 때는 vCPU 1개면 충분하다.

이 서버에서 더 무거운 서비스도 실행한다면 해당 서비스를 먼저 기준으로 서버 사양을 정해야 한다. 일반적으로 가장 큰 원인은 사진 라이브러리다. PhotoPrism과 Immich에 실제로 필요한 최소 RAM은 n8n의 요구량보다 훨씬 크다. 미디어 서버도 마찬가지다. Jellyfin 서버와 그 콘텐츠를 탐색할 수 있는 프론트 엔드인 90년대 대여점처럼 라이브러리를 재구성하는 Halcyon을 함께 실행하면 n8n이 메모리 사용량을 인식하기도 전에 RAM과 트랜스코딩 여유 공간을 대부분 차지한다.

도메인 또는 서브도메인(예: n8n.example.com)이 필요하며, 인증서를 요청하기 전에 VPS 공인 IP를 가리키는 A 레코드가 정상적으로 확인되어야 합니다. 80번과 443번 포트는 프록시를 향해 열려 있어야 하며, n8n이 사용하는 5678번 포트는 인터넷에 직접 노출되어서는 안 됩니다. Docker Engine과 Compose 플러그인이 설치되어 있어야 합니다. 만약 docker compose version 명령 실행 시 docker: 'compose' is not a docker command 오류가 발생한다면 구형 독립형 바이너리를 사용 중인 것이며, 플러그인은 sudo apt install docker-compose-plugin 명령으로 설치해야 합니다.

테스트에는 SQLite가 적합하지만, 운영 환경에는 Postgres를 사용하십시오

n8n의 기본 데이터베이스는 /home/node/.n8n/database.sqlite에 위치한 SQLite 파일입니다. 단순히 기능을 확인하는 용도로는 충분하지만, 볼륨을 마운트하지 않으면 컨테이너를 재생성할 때 데이터가 모두 삭제되므로 주의해야 합니다. Postgres로 전환해야 하는 이유는 단순히 속도 때문이 아닙니다. SQLite는 단일 쓰기 잠금(single writer lock) 방식을 사용하므로, 여러 워크플로우를 동시에 실행하거나 향후 필요한 큐 모드(queue mode)를 사용할 때 동시성 문제로 인해 SQLITE_BUSY: database is locked 오류가 발생합니다. Postgres는 이러한 제약이 없으며 pg_dump를 통해 깔끔하게 백업할 수 있습니다. 또한 n8n 공식 문서에서도 운영 서버 환경에서는 Postgres 사용을 전제로 합니다. 나중에 데이터베이스를 변경하려면 수동으로 데이터를 마이그레이션해야 하므로, 중요한 서비스라면 처음부터 Postgres로 시작하십시오.

DNS 및 방화벽

먼저 레코드를 지정하고 포트를 개방하십시오. 그래야 나중에 인증서 단계에서 도메인 이름이 해석되지 않아 실패하는 상황을 방지할 수 있습니다.

dig +short n8n.example.com
curl -s ifconfig.me
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow OpenSSH
sudo ufw enable

5678 포트를 개방하지 마십시오. compose 파일은 n8n을 127.0.0.1:5678에 바인딩하므로 호스트의 리버스 프록시만 접근할 수 있습니다. ufw allow 5678을 사용하면 이러한 격리 상태가 해제됩니다.

Compose 파일

작업 디렉터리와 docker-compose.yml을 생성합니다. 이는 두 개의 서비스, 하나의 사설 네트워크, 두 개의 명명된 볼륨으로 구성된 전체 스택입니다.

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

  n8n:
    image: docker.n8n.io/n8nio/n8n:2.29.10
    restart: unless-stopped
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      - N8N_HOST=n8n.example.com
      - N8N_PORT=5678
      - N8N_PROTOCOL=https
      - WEBHOOK_URL=https://n8n.example.com/
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}
      - N8N_PROXY_HOPS=1
      - GENERIC_TIMEZONE=Europe/London
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - n8n_data:/home/node/.n8n
    networks:
      - n8n_net
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  postgres_data:
  n8n_data:

networks:
  n8n_net:

명확히 밝혀둘 몇 가지 결정 사항이 있습니다. DB_POSTGRESDB_HOST=postgres은 Docker가 공유 네트워크상에서 해석하는 서비스 이름이며, n8n 컨테이너 내부에서 n8n 자체를 의미하는 localhost와는 다릅니다. condition: service_healthy을 포함한 depends_on은 부팅 시 n8n이 Postgres보다 먼저 실행되는 것을 방지합니다. 이 설정이 없으면 n8n이 먼저 시작되어 데이터베이스를 찾지 못하고 종료됩니다. /home/node/.n8n에 위치한 명명된 볼륨 n8n_data는 암호화 키와 SQLite 사용 시 데이터베이스를 보관하며, 절대 손실해서는 안 되는 유일한 디렉터리입니다. 이미지는 항상 특정 버전으로 고정해야 하며, 절대 latest를 사용하지 마십시오. 그 이유는 아래 업그레이드 섹션에서 설명합니다.

비밀 파일

compose 파일에 비밀번호를 직접 입력하지 마십시오. 대신 파일 옆에 .env 파일을 생성하여 Compose가 자동으로 읽게 하고, 무작위로 생성된 값을 사용하십시오.

printf 'POSTGRES_PASSWORD=%s\n'  "$(openssl rand -hex 24)" >  .env
printf 'N8N_ENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" >> .env
chmod 600 .env

N8N_ENCRYPTION_KEY은 여기서 가장 중요한 문자열이며, 저장된 모든 자격 증명을 암호화하는 데 사용되는 키입니다. n8n이 자동으로 생성하게 두지 말고 명시적으로 설정하십시오. 직접 생성한 값은 기록해 두었다가 복구할 수 있기 때문입니다. n8n이 이 키로 첫 번째 자격 증명을 암호화하고 나면 키를 변경할 경우 모든 자격 증명을 복호화할 수 없게 됩니다. 따라서 지금 한 번만 설정하고, 이후에는 해당 줄을 절대 수정하지 마십시오.

웹훅 작동 여부를 결정하는 환경 변수

4개의 변수가 n8n이 외부 세계에 자신을 어떻게 알릴지 제어하며, 이를 잘못 설정하는 것이 n8n 기술 지원에서 가장 흔한 질문입니다.

N8N_HOST은 공개 호스트 이름인 n8n.example.com입니다. 프록시 뒤에서 기본값인 localhost로 두면, 에디터가 사용자의 브라우저에서 localhost을 통해 자체 API를 로드하려고 시도하다가 실패합니다.
N8N_PROTOCOL=https은 n8n이 TLS를 통해 서비스됨을 알리는 변수입니다. 이 설정이 있으면 세션 쿠키를 Secure로 표시하고 https:// URL을 생성합니다.
N8N_PORT=5678는 n8n이 컨테이너 내부에서 수신 대기하는 포트입니다. 이는 공개 포트가 아니며, 443 포트는 프록시가 담당합니다.
WEBHOOK_URL=https://n8n.example.com/는 가장 주의해야 할 변수입니다. n8n은 Stripe, GitHub 또는 외부 호출자에게 붙여넣을 웹훅 주소를 이 값들을 조합하여 생성합니다. 이 값이 설정되지 않았거나 잘못되면, n8n은 N8N_HOST:N8N_PORT으로 대체하여 https://n8n.example.com:5678/webhook/... 또는 더 나쁜 경우 http://localhost:5678/webhook/...을 출력합니다. 이 주소는 오류 메시지 없이 그럴듯해 보이지만 인터넷에서 접근할 수 없으므로, 호출자의 요청이 아무런 응답 없이 도달하지 않게 됩니다. 이 변수를 끝에 슬래시를 포함한 정확한 공개 기본 URL로 설정한 다음, 웹훅 노드에 포트 번호가 없는 URL이 표시되는지 확인하십시오.

N8N_PROXY_HOPS=1는 n8n의 Express 서버가 앞단의 프록시 하나를 신뢰하도록 지시합니다. 이를 통해 속도 제한(rate-limiting) 및 클라이언트 IP를 읽는 모든 기능이 프록시의 주소가 아닌 실제 주소를 인식하게 됩니다. 여기서 의도적으로 설정하지 않아야 할 변수는 N8N_RUNNERS_ENABLED입니다. n8n이 Code-node 로직을 별도의 샌드박스 프로세스에서 실행하는 작업 실행기(task runner)는 1.69 버전부터 기본값이 되었으며, 이 가이드가 기준으로 삼는 2.x 라인부터는 필수 사항이므로 기존의 선택적 설정은 더 이상 사용되지 않습니다. 지금 설정하면 n8n은 해당 설정을 제거하라는 알림을 로그에 남길 뿐입니다.

최초 시작

docker compose up -d
docker compose ps
docker compose logs -f n8n

정상적인 최초 부팅은 Editor is now accessible via: 줄로 끝나며, 그 위에는 n8n ready on ..., port 5678 줄이 표시됩니다. docker compose ps 명령을 실행하면 두 컨테이너가 모두 Up 상태여야 하며, postgres는 (healthy)으로 표시되어야 합니다. 만약 n8n이 Restarting 루프에 빠진다면 로그를 확인하십시오. 이는 거의 항상 아래에서 다루는 데이터베이스 연결 문제나 볼륨 권한 문제입니다.

리버스 프록시를 이용한 TLS 설정

n8n은 기본적으로 5678 포트에서 일반 HTTP로 통신하므로, 앞단에서 HTTPS를 종료해야 합니다. 두 가지 깔끔한 선택지가 있습니다.

이미 여러 컨테이너를 운영 중이라면, 자동으로 TLS 인증서를 발급하는 Traefik 리버스 프록시 뒤에 n8n을 배치하십시오. 몇 가지 레이블만 설정하면 Traefik이 알아서 인증서를 요청하고 갱신합니다.

이 서버에서 유일하게 운영하는 애플리케이션이라면, Let's Encrypt 인증서를 사용하는 nginx 가상 호스트가 더 간단합니다. Ubuntu 24.04용 Certbot 및 nginx TLS 설정을 사용하여 인증서를 발급받은 뒤, 다음 서버 블록을 사용하십시오.

server {
    listen 443 ssl;
    server_name n8n.example.com;

    ssl_certificate     /etc/letsencrypt/live/n8n.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/n8n.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 3600;
        client_max_body_size 16m;
    }
}

Upgrade 및 Connection "upgrade" 헤더는 선택 사항이 아닙니다. n8n은 WebSocket을 통해 편집기로 실시간 실행 업데이트를 전송하는데, 이 두 줄이 없으면 로그인 페이지가 로드된 후 연결 끊김 배너와 함께 멈춰 버립니다. proxy_read_timeout 3600은 nginx의 기본값인 60초가 지나 실행이 중단되지 않도록 방지합니다. X-Forwarded-Proto $scheme 헤더는 N8N_PROXY_HOPS=1와 짝을 이룹니다. 이 헤더는 프록시가 일반 HTTP로 연결하더라도 원래 요청이 HTTPS였음을 n8n에 알려줍니다. 그래야 n8n이 연결을 안전하지 않다고 판단하여 자체 쿠키를 거부하는 상황을 막을 수 있습니다.

실제 구현을 위한 첫 번째 워크플로우

https://n8n.example.com/을 열고 소유자 계정을 생성한 뒤(다음 섹션 참조), 경로가 정상적으로 작동함을 증명하는 가장 작은 단위의 워크플로우를 구축합니다. 웹훅 입력, HTTP 호출, 응답 출력으로 구성됩니다.

Webhook 노드를 추가합니다. 메서드를 POST로 설정하고 경로는 hello와 같이 지정합니다. 이 노드는 Test URL과 Production URL 두 가지를 보여주는데, "내 웹훅이 작동하지 않는다"는 보고의 절반은 여기서 발생합니다. Test URL은 Listen for test event를 클릭한 상태에서만 단 한 번 호출에 응답하며, 이후에는 만료됩니다. Production URL은 워크플로우가 Active 상태일 때 언제든지 응답합니다.
그 뒤에 HTTP Request 노드를 추가하고 공개된 JSON API를 지정합니다. https://api.github.com/zen으로 GET 요청을 보내면 한 줄짜리 문자열을 반환하는데, 이것으로 충분합니다.
Respond to Webhook 노드를 추가하고, Webhook 노드의 Respond 옵션을 "Using Respond to Webhook node"로 설정하여 호출자가 HTTP 노드의 출력값을 전달받도록 합니다.
워크플로우를 Active(우측 상단)로 전환하고 호출합니다: curl -X POST https://n8n.example.com/webhook/hello. Zen 문구를 돌려받게 될 것입니다. POST 입력, API 호출, 응답 출력은 대부분의 실제 자동화가 갖는 형태입니다.

예약된 방식의 변형으로는 Webhook 노드 대신 Schedule Trigger를 사용하고 모델 엔드포인트를 호출하는 방법이 있습니다. 동일한 VPS에서 실행 중인 Ollama를 활용하면 깔끔한 야간 요약기를 구축할 수 있습니다.

기본 인증이 아닌 사용자 관리

이전 n8n 가이드에서는 N8N_BASIC_AUTH_ACTIVE=true을 설정하라고 안내한다. 이 변수들은 n8n 1.0에서 제거되었으며 현재는 아무 동작도 하지 않는다. 현재 인증은 owner account를 사용한다. 편집기를 처음 열면 n8n에서 이메일과 비밀번호를 사용하는 owner account를 만들도록 요구하며, 이 인증 단계는 필수이고 익명 모드는 없다. 첫 부팅 직후 URL을 다른 사람에게 제공하기 전에 즉시 생성해야 한다. docker compose up부터 첫 번째 양식 제출까지의 사이에 해당 인스턴스에 먼저 접속한 사용자가 이를 소유할 수 있다. 그 위에 리버스 프록시 basic-auth 계층을 추가하는 것은 합리적인 보안 조치지만, 이는 두 번째 보호 계층일 뿐 실제 인증 방식은 아니다. owner account와 이 가이드의 나머지 내용은 모두 무료 community edition에서 사용할 수 있다. 나중에 세분화된 역할을 가진 추가 사용자나 SSO가 필요하다면, 계획을 세우기 전에 유료 라이선스가 필요한 n8n 기능을 읽어 보는 것이 좋다.

백업: 암호화 키가 우선이고, 데이터베이스는 그다음입니다

백업해야 할 대상은 두 가지이며, 두 항목의 대체 가능성은 서로 다릅니다.

N8N_ENCRYPTION_KEY. n8n에 저장하는 모든 자격 증명, API 토큰, 데이터베이스 비밀번호, OAuth 비밀값은 이 키로 저장 시 암호화됩니다. 이 키가 없으면 Postgres에 있는 워크플로우는 무용지물입니다. 다른 키를 가진 새 서버에 데이터베이스를 복원하면 n8n은 단 하나의 자격 증명도 복호화할 수 없으며, 복구하거나 재설정할 방법도 없습니다. .env 파일에 이 키가 들어 있습니다. 키를 생성한 당일에 서버 외부의 안전한 곳(비밀번호 관리자 항목이 이상적입니다)으로 복사해 두십시오. 이것이 실제로 가장 중요한 백업입니다.

Postgres 데이터베이스는 워크플로우, 실행 기록, 그리고 암호화된 자격 증명 자체를 포함합니다:

docker compose exec -T postgres pg_dump -U n8n -d n8n \
  | gzip > n8n-db-$(date +%F).sql.gz

이 명령을 일정에 따라 실행하고 덤프 파일을 서버 외부로 복사하십시오. 새로운 VPS에 복원하려면 다음 절차를 따릅니다. 스택을 한 번 실행하여 데이터베이스가 생성되게 한 뒤, n8n을 중지하고, psql를 사용하여 덤프를 로드합니다. 그 후 .env에 동일한 N8N_ENCRYPTION_KEY을 넣고 n8n을 시작하십시오. 동일한 키와 덤프가 있어야 정상적인 인스턴스가 작동합니다. 새로운 키를 사용하면 워크플로우에서 어떤 자격 증명도 사용할 수 없게 됩니다.

업그레이드: 태그 고정

compose 파일은 latest 대신 n8nio/n8n:2.29.10를 의도적으로 고정합니다. n8n은 거의 매주 새로운 마이너 버전을 출시하며, 버전 간에 데이터베이스 스키마나 노드 동작이 변경되는 경우가 있습니다. 따라서 latest을 사용하면 자동 업데이트(unattended pull) 시 시작과 동시에 데이터베이스 마이그레이션이 수행되는 빌드 버전이 적용될 수 있습니다. 버전을 고정하고, 업데이트 전 릴리스 노트를 읽어보십시오. n8n은 릴리스 노트에 주요 변경 사항(breaking changes)을 명시하므로, 이를 확인한 후 신중하게 업그레이드해야 합니다.

docker compose exec -T postgres pg_dump -U n8n -d n8n | gzip > pre-upgrade.sql.gz
# edit the image tag in docker-compose.yml, then:
docker compose pull n8n
docker compose up -d n8n
docker compose logs -f n8n

메이저 버전 점프 시에는 이 점이 더욱 중요합니다. 예를 들어 2.0 버전 라인에서는 기본값이 N8N_BLOCK_ENV_ACCESS_IN_NODE에서 true로 변경되었습니다. 따라서 process.env을 읽어오던 모든 Code 노드는 설정을 false로 되돌리기 전까지는 접근 권한을 잃게 됩니다. 같은 릴리스부터는 설정 파일에 대한 엄격한 권한 검사가 적용되었습니다. 메이저 버전을 넘어가기 전에 2.0 주요 변경 사항 페이지를 반드시 읽어보십시오. n8n은 시작 시 필요한 데이터베이스 마이그레이션을 자동으로 수행하며, 바로 이 때문에 업그레이드 전 pg_dump가 필수적인 것입니다. 자격 증명은 .env의 키로 암호화되어 저장되고 데이터는 Postgres에 저장되므로, 컨테이너는 언제든 교체 가능합니다. 업그레이드는 컨테이너를 교체하는 방식으로 진행하며, 롤백은 이전 태그로 고정하고 덤프를 복원하여 수행합니다.

실패 유형과 확인되는 메시지

The requested webhook "POST hello" is not registered. 워크플로우가 Active 상태가 아닌 웹훅을 호출하거나, 아무도 수신 대기 중이지 않을 때 테스트 경로를 호출하면 404 오류가 발생합니다. 테스트 경로(/webhook-test/...)는 "Listen for test event"를 클릭했을 때만 응답하며, 프로덕션 경로(/webhook/...)는 워크플로우 토글이 켜져 있을 때만 응답합니다. 관련 오류인 This webhook is not registered for GET requests. Did you mean to make a POST request?은 메서드가 잘못되었음을 의미하며, 노드는 POST를 기대하지만 GET을 보낸 경우입니다.

웹훅 URL에 :5678 또는 localhost가 표시됩니다. 노드에 https://n8n.example.com:5678/webhook/... 또는 http://localhost:5678/...이 표시됩니다. WEBHOOK_URL가 설정되지 않았거나 잘못되어 n8n이 공개 기본 주소 대신 N8N_HOST:N8N_PORT을 기반으로 주소를 생성했기 때문입니다. WEBHOOK_URL=https://n8n.example.com/를 설정하고 docker compose up -d로 컨테이너를 다시 생성하면 포트 번호가 사라집니다.

브라우저에 There was a problem loading init data이 표시됩니다. 에디터는 로드되었으나 자체 백엔드 API에 연결할 수 없는 상태입니다. 프록시 환경에서는 거의 항상 N8N_HOST 또는 WEBHOOK_URL이 잘못되었거나, 프록시가 WebSocket Upgrade 헤더를 전달하지 못했거나, N8N_PROTOCOL이 접속 방식과 일치하지 않기 때문입니다. 4개의 공개용 변수를 확인하고 프록시가 Upgrade 및 Connection를 전달하는지 확인하십시오.

로그에 password authentication failed for user "n8n"이 표시되며 컨테이너가 재시작됩니다. n8n이 보내는 비밀번호가 데이터베이스 초기화 시 설정된 값과 일치하지 않습니다. 주의할 점은 Postgres는 데이터 디렉터리가 비어 있을 때만 POSTGRES_PASSWORD를 읽는다는 것입니다. 스택을 한 번 시작한 후 .env에서 POSTGRES_PASSWORD를 변경해도, 기존 postgres_data 볼륨에는 이전 비밀번호가 그대로 남아 있습니다. 원래 비밀번호로 되돌리거나, 보존할 데이터가 없다면 docker compose down을 실행하고 postgres 볼륨을 docker volume rm한 뒤 새로 시작하십시오.

시작 시 EACCES: permission denied, open '/home/node/.n8n/config'이 발생합니다. n8n은 node 사용자(UID 1000)로 실행되는데 설정 디렉터리에 쓰기 권한이 없는 경우입니다. root가 소유한 호스트 폴더(./n8n_data:/home/node/.n8n)를 바인드 마운트할 때 주로 발생합니다. 위에서 설명한 명명된 볼륨을 사용하거나, 반드시 바인드 마운트를 사용해야 한다면 먼저 sudo chown -R 1000:1000 ./n8n_data을 수행하십시오.

Permissions 0644 for n8n settings file /home/node/.n8n/config are too wide. Changing permissions to 0600.. 2.x 버전부터 n8n은 기본적으로 해당 설정 파일에 0600 권한을 강제하며 부팅 시 자동으로 수정합니다. 이 로그는 파일 권한이 느슨하게 설정된 상태로 복원되었거나 바인드 마운트 이후 시스템이 권한을 올바르게 교정했음을 의미합니다. 별도의 조치는 필요하지 않으며, 파일 시스템이 권한 설정을 지원하지 않는 경우에만 N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=false을 설정하십시오.

Mismatching encryption keys 상세 로그에 따르면 설정 파일 /home/node/.n8n/config의 암호화 키가 환경 변수의 N8N_ENCRYPTION_KEY와 일치하지 않습니다. 환경 변수의 키가 이전 실행 시 n8n이 데이터 볼륨에 기록한 키와 다른 경우입니다. 이는 주로 변수가 설정되지 않았을 때 n8n이 무작위 키를 생성했고, 이후 다른 키를 설정했기 때문에 발생합니다. .env에 원래 키를 다시 넣거나, 보존할 가치가 있는 자격 증명이 전혀 없는 경우에만 n8n_data 볼륨 내부의 config 파일을 삭제하십시오. n8n이 키를 새로 생성하게 되며, 기존 자격 증명은 읽을 수 없게 됩니다.

보안 쿠키 관련 로그인 배너: Your n8n server is configured to use a secure cookie, however you are either visiting this via an insecure URL, or using Safari. N8N_PROTOCOL=https를 설정했으나 HTTPS 프록시를 거치지 않고 IP와 포트로 직접 접속하여 일반 HTTP로 n8n에 도달했습니다. https://n8n.example.com/를 통해 접속하십시오. HTTPS를 도저히 사용할 수 없는 경우에만 N8N_SECURE_COOKIE=false을 설정해야 하며, 인터넷에 노출된 서버에서는 절대 설정하지 마십시오.

워크플로우에 언어 모델을 통합하려면 Claude와 n8n을 이용한 AI 워크플로우 구축을 참조하십시오.

FAQ

n8n에 SQLite와 Postgres 중 무엇을 사용해야 합니까?

SQLite(기본값)는 n8n을 시험해 보거나 한 번에 하나의 워크플로를 실행하는 개인용 인스턴스에 적합합니다. 의존도가 있는 서비스라면 Postgres로 전환하십시오. SQLite는 동시성 발생 시 database is locked 오류를 일으키는 단일 쓰기 잠금 방식을 사용하며, Postgres는 pg_dump을 통해 깔끔하게 백업할 수 있습니다. 나중에 마이그레이션하는 과정은 수동으로 진행해야 하므로, 중요한 서비스라면 처음부터 Postgres로 시작하십시오.

n8n 웹훅이 전혀 작동하지 않는 이유는 무엇입니까?

거의 대부분 WEBHOOK_URL 설정 문제입니다. 이 값이 설정되지 않았거나 잘못된 경우, n8n은 N8N_HOST:N8N_PORT을 기반으로 웹훅 주소를 생성합니다. 이때 주소에 :5678이나 localhost가 포함되어 유효해 보일 수 있지만, 실제로는 인터넷에서 접근할 수 없어 호출자의 요청이 도달하지 못합니다. WEBHOOK_URL=https://n8n.example.com/을 설정하고 노드에 포트 번호가 없는 URL이 표시되는지 확인하십시오. 두 번째 원인은 워크플로가 Active 상태로 전환되지 않은 웹훅을 호출하는 경우이며, 이 경우 The requested webhook ... is not registered. 응답이 반환됩니다.

n8n에서 무엇을 백업해야 합니까?

두 가지입니다. 첫째는 .env 파일의 N8N_ENCRYPTION_KEY입니다. 모든 저장된 자격 증명은 이 키로 암호화되므로 분실 시 영구적으로 복호화할 수 없습니다. 생성 즉시 서버 외부로 복사해 두십시오. 둘째는 워크플로, 실행 기록, 자격 증명이 포함된 Postgres 데이터베이스의 pg_dump입니다. 복구 시에는 동일한 키와 데이터베이스 덤프 파일이 모두 필요합니다.

n8n을 HTTPS 뒤에 배치하려면 어떻게 해야 합니까?

n8n은 5678 포트에서 일반 HTTP를 제공하므로, 앞단에 리버스 프록시를 두어 TLS를 종료해야 합니다. n8n을 127.0.0.1:5678에 바인딩하여 프록시만 접근할 수 있도록 제한한 뒤, 자동 인증서 기능을 갖춘 Traefik이나 Let's Encrypt 인증서를 사용하는 nginx를 사용하십시오. N8N_PROTOCOL=https와 WEBHOOK_URL=https://your-host/을 설정하고, 프록시가 WebSocket Upgrade 헤더를 전달하도록 구성해야 편집기가 멈추지 않습니다.

n8n을 안전하게 업그레이드하려면 어떻게 해야 합니까?

latest 대신 특정 이미지 태그를 고정하십시오. n8n은 시작 시 자동으로 마이그레이션을 수행하므로 먼저 pg_dump을 생성하고, 릴리스 노트에서 변경 사항을 확인한 뒤 태그 버전을 올리고 docker compose pull n8n && docker compose up -d n8n를 실행하십시오. 컨테이너는 일회용이므로, 문제가 발생하면 이전 태그로 되돌리고 업그레이드 전 덤프 파일을 복원하여 롤백할 수 있습니다.

#n8n #automation #docker #self-hosting #https