n8n VPS 오프라인 현상 원인 분석 및 해결 방법
n8n이 오프라인으로 표시되는 4가지 주요 원인을 진단합니다. 웹소켓 연결 오류, 컨테이너 재시작 루프, OOM Killer에 의한 프로세스 강제 종료, 워크플로우 스케줄 중단 문제를 구분하고 해결하는 구체적인 방법을 안내합니다.
n8n이 오프라인 상태가 되는 이유: 4가지 장애와 1가지 증상
"n8n이 계속 오프라인 상태가 됩니다"라는 문장은 서로 다른 4가지 장애를 포괄하며, 각각 다른 해결책이 필요합니다. 컨테이너는 정상적으로 실행 중인데 편집기에 연결 끊김 배너가 표시되는 경우, 컨테이너가 스스로 재시작되는 경우, 커널이 메모리 과다 사용을 이유로 Node.js 프로세스를 강제 종료하는 경우, 혹은 프로세스에는 아무런 문제가 없는데 활성화된 워크플로우가 전혀 실행되지 않는 경우가 있습니다. 잘못된 설정을 변경하면 겪지도 않은 문제를 해결하느라 주말을 허비하게 됩니다.
따라서 설정을 건드리기 전에 어떤 장애가 발생했는지 먼저 파악해야 합니다. n8n은 일반적으로 Docker 컨테이너 내부에서 실행되는 메인 Node.js 프로세스를 가지며, TLS(전송 계층 보안)를 종료하는 리버스 프록시 뒤에서 동작합니다. 코드 노드는 작업 실행 프로세스도 사용합니다. 내부 모드는 자식 프로세스를 실행하고, 외부 모드는 일반적으로 사이드카 컨테이너와 같이 별도로 실행합니다. 각 계층은 서로 다른 방식으로 고장이 나지만, 브라우저는 모두 동일한 메시지로 연결 실패를 보고합니다.
다음 순서로 진단하십시오
VPS(virtual private server)에서 다음 명령을 실행하고 본인의 시스템에 출력되는 값을 읽으십시오. 포럼 게시물의 숫자와 비교하지 마십시오. 여기서 중요한 값은 타인이 아닌 본인의 서버 상태를 설명합니다.
docker ps -a --filter name=n8n
docker logs --tail 200 --timestamps n8n
docker inspect n8n | grep -iE 'Status|Running|RestartCount|OOMKilled|ExitCode'
docker stats --no-streamdocker ps -a의 STATUS 열은 컨테이너가 현재 상태로 유지된 시간을 나타냅니다. 이 시간을 문제가 발생한 시점과 비교하십시오. 배너가 나타나기 훨씬 전부터 컨테이너가 실행 중이었다면 해당 시점에 컨테이너가 재시작된 것은 아니지만, n8n이 계속 가용 상태였음을 보장하지는 않습니다. 다음 섹션에서 다룰 웹소켓 경로로 넘어가기 전에 /healthz으로 도달 가능성을 확인하고, /healthz/readiness로 데이터베이스 연결 및 마이그레이션 여부를 확인하십시오.
RestartCount는 Docker가 해당 컨테이너를 재시작한 횟수입니다. 숫자를 기록한 뒤 1분 정도 기다렸다가 다시 확인하십시오. 지켜보는 동안 숫자가 계속 올라간다면 재시작 루프가 발생한 것이며, 각 재시작 직전의 로그 줄에 그 원인이 기록되어 있습니다.
OOMKilled은 참 또는 거짓을 나타내는 플래그입니다. 참은 Docker가 컨테이너 내에서 메모리 부족(OOM)으로 인한 강제 종료를 기록했음을 의미합니다. 로그 및 커널 메시지와 함께 확인하여 어떤 프로세스가 종료되었는지, 그리고 메모리 압박이 컨테이너 제한 때문인지 아니면 시스템 전체의 문제인지 파악하십시오.
ExitCode은 컨테이너가 마지막으로 종료될 때 반환한 코드입니다. 각 코드의 의미를 모두 외울 필요는 없습니다. 본인의 코드를 확인한 뒤, 같은 타임스탬프의 docker logs 끝부분을 읽으십시오. 로그의 마지막 부분과 메모리 부족 플래그를 함께 보면 무슨 일이 일어났는지 알 수 있으며, 하나만 봐서는 잘못된 결론을 내릴 수 있습니다.
docker stats는 현재 적용된 제한과 함께 실시간 메모리 사용량을 보여줍니다. 두 번째 터미널에서 이 명령을 실행해 둔 상태로 오류를 일으키는 워크플로우를 트리거하여, 장애가 발생하는 동안 숫자가 어떻게 변하는지 관찰하십시오.
연결 끊김 배너는 대개 리버스 프록시 문제입니다
n8n 에디터는 실행 진행 상황을 캔버스에 스트리밍하기 위해 백엔드와 하나의 장기 연결을 유지합니다. 기본적으로 이 연결은 WebSocket을 사용하며, 이는 N8N_PUSH_BACKEND 설정으로 선택되고 기본값은 websocket입니다. WebSocket은 Connection: Upgrade 및 Upgrade: websocket 헤더를 포함한 일반적인 HTTP 요청으로 시작됩니다. 서버가 101 Switching Protocols로 응답하면, 이후 양측은 동일한 TCP 소켓을 양방향으로 사용합니다.
두 가지 프록시 문제가 이 연결을 끊습니다. 첫째, 프록시가 업스트림에 HTTP/1.0을 사용하거나 업그레이드 헤더를 제거하여 업그레이드가 발생하지 않고 에디터가 무한 재연결을 시도하는 경우입니다. 둘째, 업그레이드는 성공했으나 프록시가 소켓을 유휴 상태로 간주하여 닫아버리는 경우입니다. 메시지가 없는 WebSocket은 유휴 연결과 동일하게 보이기 때문입니다. n8n 자체도 인증 실패나 요청 검증 실패(pushRef 누락 또는 유효하지 않은 origin 등)로 인해 푸시 연결을 거부할 수 있습니다. 배너는 브라우저가 채널을 잃었다고 알리는 것이며, 컨테이너가 정상이라는 증거는 아닙니다.
설정을 변경하기 전에 브라우저에서 이를 확인하십시오. 개발자 도구를 열고 Network 탭으로 이동한 뒤 WS로 필터링하고 에디터를 새로고침하십시오. 푸시 요청은 101 Switching Protocols에 도달하여 연결이 유지되어야 합니다. 일반적인 상태 코드를 반환하거나 몇 초마다 다시 나타나는 푸시 요청이 있다면, 응답 내용과 n8n 로그에서 프록시, 인증 또는 origin 관련 오류를 확인해야 합니다.
에디터 연결을 유지하는 nginx 설정
nginx는 명시적으로 요청하지 않으면 upgrade 헤더를 전달하지 않습니다. Connection 및 Upgrade은 nginx가 통과 과정에서 제거하는 hop-by-hop 헤더이므로, 두 헤더를 모두 다시 추가해야 합니다. 업스트림 프로토콜은 nginx 릴리스에 따라 다릅니다. 2026년 3월에 출시된 1.29.7 버전부터 proxy_pass는 기본적으로 백엔드와 HTTP/1.1로 통신하며, 이전 버전에서는 HTTP/1.0을 사용했기 때문에 upgrade를 처리할 수 없었습니다. nginx -v을 실행하여 사용 중인 버전을 확인하십시오. 아래 설정은 proxy_http_version 1.1을 명시하여 두 환경 모두에서 작동하도록 하며, 1.29.7 이상 버전에서는 해당 줄이 기본값을 재확인하는 역할을 합니다. map 블록은 server 내부가 아닌 http 컨텍스트에 위치해야 합니다. 아래 서버 블록의 나머지 부분이 생소하다면 nginx 서버 블록의 줄 단위 상세 설명에서 각 지시어의 역할을 확인할 수 있습니다.
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}server {
listen 443 ssl;
http2 on;
server_name n8n.example.com;
location / {
proxy_pass http://127.0.0.1:5678;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
proxy_buffering off;
}
}proxy_read_timeout는 기본값이 60초이며, 백엔드로부터 데이터를 읽는 간격을 기준으로 업그레이드된 WebSocket 연결에도 적용됩니다. n8n은 60초마다 푸시 핑을 보내므로, 워크플로 인스턴스가 유휴 상태여도 소켓에 트래픽이 없는 것은 아닙니다. 타임아웃 시간을 늘리면 기본 타임아웃과 충돌하지 않고 핑이 도착할 여유가 생기며, 주기적인 핑 프레임이 타임아웃을 초기화합니다.
sudo nginx -t && sudo systemctl reload nginx
sudo nginx -T | grep -iE 'proxy_http_version|upgrade|proxy_read_timeout'nginx -T은 현재 실행 중인 프로세스가 로드한 설정을 검사하는 대신, 포함된 파일을 포함한 설정 파일 전체를 테스트하고 출력합니다. 리로드가 성공했는지도 확인하십시오. include 줄이 참조하지 않는 파일에 설정이 머물러 있으면, 올바른 수정 사항을 적용해도 아무런 변화가 없는 것처럼 보일 수 있습니다.
그런 다음 n8n이 프록시 뒤에 있음을 알려야 합니다. n8n은 이 값들을 사용하여 URL을 생성하기 때문입니다.
environment:
- N8N_HOST=n8n.example.com
- N8N_PROTOCOL=https
- N8N_PORT=5678
- N8N_PROXY_HOPS=1
- N8N_WEBHOOK_URL=https://n8n.example.com/N8N_PROXY_HOPS의 기본값은 0이며, 이는 n8n이 연결된 주소를 클라이언트 주소로 취급하고 X-Forwarded-For를 무시함을 의미합니다. 이 값을 컨테이너 앞단에 있는 프록시 개수로 설정하십시오. 2026년 10월 기준으로 N8N_WEBHOOK_URL이 현재 사용되는 이름이며, 이전 버전인 WEBHOOK_URL도 여전히 작동하지만 시작 시 경고 메시지가 출력됩니다.
Traefik은 WebSocket을 자동으로 전달합니다
Traefik은 미들웨어나 추가 레이블 없이도 WebSocket 업그레이드 요청을 전달합니다. Traefik의 HTTP 타임아웃 기본값은 업그레이드된 WebSocket에 대해 타임아웃을 설정하지 않습니다. 아래의 설정값은 entryPoint에 적용됩니다. 2026년 10월 기준 Traefik v3에서 idleTimeout는 유휴 HTTP keep-alive 연결에 대해 기본값 180초를 사용하며, readTimeout은 요청 본문을 포함한 읽기 작업에 대해 기본값 60초를 사용합니다. 응답 쓰기 타임아웃은 프로토콜 업그레이드를 명시적으로 제외합니다. 이 예시는 HTTP 타임아웃을 변경하는 것이며, WebSocket 배너 문제에 대한 확정적인 해결책은 아닙니다.
entryPoints:
websecure:
address: ":443"
transport:
respondingTimeouts:
readTimeout: 0
idleTimeout: 3600sCaddy는 reverse_proxy에서 업그레이드를 자동으로 처리하며 별도의 지시어가 필요하지 않습니다. 프록시를 관리하는 주체가 따로 있어 설정을 변경할 수 없는 경우, N8N_PUSH_BACKEND=sse를 사용하여 푸시 채널을 전환하십시오. SSE(server-sent events)는 연결이 유지되는 일반적인 HTTP 응답이므로 업그레이드를 거부하는 프록시 환경에서도 작동합니다. 단, 공격적인 유휴 타임아웃 설정이 적용되어 있다면 연결이 끊길 수 있습니다. 프록시 선택은 별개의 결정 사항이며, Nginx, Caddy, Traefik 비교 문서에서 각 도구의 운영 비용을 확인할 수 있습니다.
컨테이너가 실제로 재시작되는 경우
RestartCount 수치가 상승한다면 컨테이너가 실패하고 있으며 Docker가 이를 다시 실행하고 있는 것입니다. 로그의 타임스탬프를 각 재시작 시점과 대조하여 직전에 발생한 내용을 확인하십시오. 일반적인 원인으로는 시작을 방해하는 설정 오류, n8n이 연결할 수 없는 데이터베이스, 실행 중 발생하는 크래시, 메모리 부족으로 인한 프로세스 종료(OOM kill) 등이 있습니다.
권한 문제는 조용히 발생하므로 볼륨부터 확인하십시오. 공식 이미지는 권한이 없는 사용자 node로 실행되며 데이터를 /home/node/.n8n에 저장합니다. 바인드 마운트(bind mount)가 해당 사용자에 대해 쓰기 권한을 갖지 못하면 프로세스는 데이터를 기록하려 할 때 실패하며, 재시작 정책(restart policy)으로 인해 이 실패가 반복될 수 있습니다.
docker compose config
docker run --rm -it --entrypoint sh docker.n8n.io/n8nio/n8n -c 'id'
docker exec n8n ls -ld /home/node/.n8n새로 생성된 명명된 볼륨(named volume)은 Docker가 데이터를 채울 때 이미지 디렉터리의 소유권을 상속받지만, 기존 볼륨은 여전히 권한 확인이 필요합니다. 바인드 마운트를 사용해야 한다면 chown 명령을 사용하여 호스트 디렉터리의 소유자를 id 명령이 출력한 숫자 형태의 사용자 ID로 변경하십시오. 호스트와 컨테이너 간의 소유권 매핑은 한 번 이해해 두는 것이 좋으며, PUID 및 PGID 설명 문서에서 이러한 이미지가 파일을 작성할 주체를 결정하는 방식을 다룹니다.
크래시처럼 보이는 OOM(Out of Memory) 킬
n8n 프로세스 위에는 두 개의 독립적인 메모리 상한선이 존재하며, 각각 실패 방식이 다릅니다. 컨테이너 컨트롤 그룹(cgroup) 제한은 커널에 의해 강제됩니다. 사용량이 제한에 도달하고 이를 줄일 수 없으면 커널은 OOM 킬러를 호출합니다. 사용량은 일시적으로 해당 제한을 초과할 수 있습니다. OOM 킬이 발생하면 프로세스는 마지막 로그 항목을 기록할 기회조차 얻지 못하며, Docker는 이를 OOMKilled에 기록합니다. V8 힙 제한은 Node.js 내부에서 강제됩니다. 이를 초과하면 치명적인 힙 오류가 발생하며 커널 OOM 킬 없이 프로세스가 종료됩니다. 브라우저에서 볼 때는 두 현상이 동일하게 보입니다. 이들을 구분하려면 로그와 함께 docker inspect를 읽어보십시오.
Node 힙 상한선을 컨테이너 제한보다 낮게 설정하여 네이티브 할당, 버퍼, 기타 힙 영역 및 컨테이너 내 다른 프로세스를 위한 여유 공간을 확보하십시오. 힙 상한선을 높이면 V8이 자체 제한에 도달하기 전에 커널 OOM 킬이 발생할 위험이 커지지만, 이것이 반드시 발생한다는 보장은 없습니다. 메모리는 회수되거나 스왑될 수 있으며, 작업 부하가 두 제한 중 어느 것에도 도달하지 않을 수 있기 때문입니다. 반대로 힙 상한선을 낮춘다고 해서 컨테이너 OOM 킬 이전에 반드시 힙 오류가 발생한다는 보장도 없습니다.
services:
n8n:
image: docker.n8n.io/n8nio/n8n
restart: unless-stopped
environment:
- NODE_OPTIONS=--max-old-space-size=<MiB, below the container limit>
deploy:
resources:
limits:
memory: <your container limit>힙 플레이스홀더를 --max-old-space-size=SIZE 형식의 MiB 단위 숫자 값으로 교체하십시오. 두 숫자 모두 실제 VPS 사양을 고려하여 데이터베이스, 프록시, 운영체제를 위한 여유 공간을 남겨두고 선택하십시오. docker stats --no-stream는 현재 사용량과 적용된 제한을 함께 출력하므로, 작성한 제한이 Docker에 의해 실제로 적용되었는지 확인할 수 있습니다. Compose 메모리 제한 적용 방식에서 여러 설정이 중복될 때 어떤 키가 우선하는지 확인할 수 있습니다.
실행 데이터는 사용자 모르게 증가합니다
워크플로가 실행되는 동안 단일 실행은 모든 노드의 출력값을 보유하며, n8n은 실행 저장 설정에 따라 해당 데이터를 저장합니다. 이로 인해 두 가지 결과가 발생합니다. 데이터의 양과 각 노드가 수행하는 작업은 최대 메모리 사용량에 영향을 미치므로, 1만 개의 행을 한 번에 처리하는 워크플로는 200개씩 처리하는 동일한 워크플로와는 완전히 다른 프로그램이 됩니다. 또한 저장된 복사본은 누군가 삭제하기 전까지 계속 증가합니다.
정리(Pruning) 기능은 두 번째 문제를 해결합니다. 2026년 10월 기준으로 기본 설정은 정리가 활성화되어 있으며, EXECUTIONS_DATA_MAX_AGE는 336시간(14일), EXECUTIONS_DATA_PRUNE_MAX_COUNT은 10000으로 설정되어 있습니다. 이는 SQLite를 실행하는 소규모 VPS 환경에서는 넉넉한 수치입니다. SQLite는 모든 데이터를 하나의 파일에 저장하며, 에디터를 서비스하는 동일한 프로세스가 해당 파일을 읽고 써야 하기 때문입니다.
environment:
- EXECUTIONS_DATA_PRUNE=true
- EXECUTIONS_DATA_MAX_AGE=72
- EXECUTIONS_DATA_PRUNE_MAX_COUNT=1000
- EXECUTIONS_DATA_SAVE_ON_SUCCESS=none
- EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS=falseEXECUTIONS_DATA_SAVE_ON_SUCCESS=none은 공격적인 설정입니다. 이 설정을 사용하면 성공한 실행 데이터 저장이 비활성화됩니다. EXECUTIONS_DATA_SAVE_ON_ERROR이 기본값인 all로 유지되는 경우 실패한 실행 데이터는 보존되며, 개별 워크플로 설정으로 이러한 선택을 재정의할 수 있습니다. 이 설정은 신중하게 결정하십시오. 오류를 발생시키지 않고 잘못된 출력값을 생성한 워크플로를 조사할 방법이 사라질 수 있기 때문입니다. 또한 정리는 행을 먼저 삭제된 것으로 표시한 뒤 나중에 제거하며, SQLite는 디스크 공간을 반환하는 대신 해제된 페이지를 재사용하므로 설정을 변경하는 즉시 디스크상의 파일 크기가 줄어들지는 않습니다.
저장된 총 데이터량이 아닌 최대 메모리 사용량을 줄이려면 실행당 처리하는 데이터 양을 줄여야 합니다. 대규모 작업은 작은 결과값을 부모 워크플로로 반환하는 하위 워크플로로 분할하고, Loop Over Items 노드를 사용하여 일괄 처리하며, 전체 데이터 세트를 Code 노드에 담지 않도록 하십시오.
바이너리 파일은 메모리를 거치지 않아야 합니다
N8N_DEFAULT_BINARY_DATA_MODE은 기본적으로 default로 설정되어 있으며, 이는 실행 중인 프로세스의 메모리에 바이너리 데이터를 유지합니다. 워크플로가 다운로드하는 파일은 해당 메모리 사용량을 증가시킵니다. 일반적인 JSON 작업으로는 도달하기 어려운 한계를 대용량 첨부 파일을 가져오는 워크플로가 초과할 수 있으며, 이 때문에 특정 워크플로 실행 시점에 충돌이 발생합니다.
environment:
- N8N_DEFAULT_BINARY_DATA_MODE=filesystemfilesystem를 사용하면 바이너리 데이터는 N8N_BINARY_DATA_STORAGE_PATH 아래에 기록됩니다. 이 경로는 기본적으로 n8n 사용자 폴더 내부에 위치하므로 다른 모든 데이터와 동일한 볼륨에 저장됩니다. 설정을 변경하기 전에 해당 볼륨에 충분한 공간이 있는지 확인하십시오. N8N_PAYLOAD_SIZE_MAX는 들어오는 웹훅 페이로드의 최대 크기를 MiB(메비바이트) 단위로 설정하며 기본값은 16입니다. 이 값을 높이면 더 큰 요청을 수용할 수 있지만, 그만큼 메모리 비용이 증가한다는 점을 감안해야 합니다.
서버를 공유하는 다른 프로세스들은 동일한 RAM을 두고 경쟁합니다. 데이터베이스 컨테이너를 추가한 후 OOM(Out of Memory) 종료가 발생하기 시작했다면, 데이터베이스를 Docker에서 실행할지 호스트에서 실행할지에 대한 선택이 현재 직면한 트레이드오프입니다.
재시작 정책 및 재부팅 후 서비스 복구
재시작 정책이 없는 컨테이너는 종료되거나 호스트가 재부팅되면 다시 실행되지 않습니다. restart: unless-stopped는 두 경우 모두 컨테이너를 다시 시작하지만, 사용자가 직접 중지한 컨테이너는 그대로 유지합니다. restart: always은 사용자가 의도적으로 중지한 컨테이너라도 Docker가 다시 시작될 때 함께 실행합니다.
n8n은 N8N_ENDPOINT_HEALTH이라는 상태 확인 엔드포인트를 제공하며, 기본값은 healthz입니다. 호스트에서 먼저 이 경로를 확인하여 해당 인스턴스에서 올바른 경로인지 검증하십시오.
curl -fsS http://127.0.0.1:5678/healthz
docker exec n8n which wget curl
sudo systemctl is-enabled docker상태 확인(healthcheck) 자체만으로는 아무것도 재시작하지 않습니다. Compose는 컨테이너를 unhealthy 상태로 표시할 뿐이며, 재시작 정책은 컨테이너가 종료될 때만 작동합니다. 컨테이너가 unhealthy 상태라는 이유만으로 재시작하려면 외부 감시 도구가 필요합니다. 실제로 작동하는 상태 확인 작성하기와 재부팅 후 스택을 다시 시작하도록 만들기에서 이 두 가지 측면을 모두 다룹니다.
n8n은 정상인데 워크플로가 실행되지 않는 경우
이 현상은 배너가 표시되지 않으며 재시작도 발생하지 않습니다. 컨테이너는 실행 중이고 에디터도 정상 작동하지만, 실행 목록에 예상했던 실행 기록이 나타나지 않습니다. 다음 네 가지 사항을 확인하십시오.
- 워크플로가 게시되지 않았습니다. Schedule Trigger를 사용하는 워크플로를 저장하고 게시해야 프로덕션 스케줄이 작동합니다.
- 시간대가 일치하지 않습니다. Schedule Trigger는 워크플로에 설정된 시간대를 우선 사용하며, 설정되지 않은 경우 인스턴스 시간대를 사용합니다.
GENERIC_TIMEZONE의 기본값은America/New_York입니다. 워크플로 시간대를 설정하거나 인스턴스 기본값을 본인의 시간대로 변경하십시오. - 실행이 유예 기간을 놓쳤습니다. n8n 2.45.0부터는 내구성 있는 스케줄러(durable scheduler)가 기본 활성화되어 예정된 실행을 데이터베이스에 기록합니다. 기록된 실행은 재시작 후 유예 기간 내에 지연 실행되지만, 기간을 초과하면 설정된 misfire policy에 따라 건너뛰거나 즉시 실행됩니다. 이전 방식인 메모리 내 스케줄러는 다운타임 동안 예정된 실행을 건너뜁니다.
- 워크플로가 비활성화되었습니다.
N8N_WORKFLOW_AUTODEACTIVATION_ENABLED은 기본적으로 꺼져 있습니다. 이 기능이 켜져 있으면 반복적으로 충돌하는 워크플로는 게시가 취소되며, 이후에는 아무도 활성화하지 않은 워크플로와 동일하게 보입니다.
실행 목록을 열고 해당 워크플로로 필터링하십시오. 실패 항목이 있다면 워크플로 자체의 문제입니다. 만약 같은 서버에서 호스팅하는 다른 서비스에 대해 429 오류가 발생했다면, 제한은 n8n이 아닌 해당 서비스의 것입니다. SearXNG 429 해결 가이드에서 서버 IP를 차단하는 엔진과 서비스 자체의 속도 제한기를 구분하는 방법을 확인할 수 있습니다. 실행 기록이 전혀 없는 경우는 실행 저장 기능이 비활성화되었거나 정리(pruning) 작업으로 기록이 삭제되었을 때도 발생하므로, 트리거 문제로 단정하기 전에 해당 설정을 먼저 확인하십시오.
가장 먼저 변경해야 할 사항
- 파일을 수정하기 전에 먼저 자신의 컨테이너에서
STATUS,RestartCount,OOMKilled를 읽어 보십시오. - 컨테이너가 계속 실행 중이라면 n8n의 연결 가능 여부와 데이터베이스 준비 상태를 확인한 다음, 프록시, 인증, 오리진 또는 타임아웃 오류가 있는지 푸시 연결을 검사하십시오.
OOMKilled가 true로 설정되어 있다면 의도적으로 선택한 컨테이너 제한을 설정하고, Node 힙 상한을 설정할 때 그보다 낮은 여유 공간을 두며, 바이너리 데이터를filesystem으로 전환하십시오.- 아무런 반응이 없다면 워크플로가 게시되었는지, 유효 시간대가 본인의 시간대와 일치하는지, 스케줄러 및 미스파이어(misfire) 설정이 예상과 일치하는지 확인하십시오.
이 설정 대부분은 정상적으로 설치된 환경 위에 한 번 설정하고 잊어버려도 되는 구성입니다. 아직 설치를 진행 중이라면 HTTPS를 사용하는 Docker 기반 n8n 가이드가 이 설정들이 속한 기본 문서입니다.
FAQ
컨테이너가 실행 중인데 n8n 에디터에 연결 끊김 배너가 나타나는 이유는 무엇입니까?
에디터는 실행 진행 상황을 스트리밍하기 위해 WebSocket 연결을 유지합니다. 리버스 프록시가 Connection: Upgrade 및 Upgrade: websocket 헤더를 전달하지 않거나 업스트림에서 HTTP/1.1을 사용하지 않으면 업그레이드가 완료되지 않습니다. 이 경우 n8n은 정상 상태임에도 브라우저는 계속해서 재연결을 시도합니다. Nginx를 사용하는 경우 proxy_set_header 라인 두 개가 모두 필요하며, 1.29.7 이전 버전에서는 proxy_http_version 1.1 설정도 추가해야 합니다(최신 버전은 기본적으로 HTTP/1.1을 사용합니다). proxy_read_timeout 값을 기본값인 60초보다 높게 설정하면 n8n의 주기적인 핑이 도달할 여유가 생깁니다. 워크플로우가 조용하다고 해서 연결이 유휴 상태가 되는 것은 아닙니다. n8n은 유효하지 않은 푸시 요청과 인증 실패를 거부하므로 응답 및 애플리케이션 로그를 확인하십시오. sudo nginx -T를 사용하여 설정 파일을 확인하고 리로드가 성공했는지 확인하십시오.
메모리 부족(OOM)으로 인한 종료와 일반적인 크래시를 어떻게 구분합니까?
docker inspect n8n | grep -iE 'OOMKilled|ExitCode|RestartCount' 명령을 실행하고 OOMKilled 플래그를 확인하십시오. True이면 Docker가 메모리 부족으로 인한 종료를 기록한 것입니다. 이 경우 피해를 입은 프로세스는 마지막 로그를 기록할 기회가 없지만, 이전 컨테이너 로그는 여전히 도움이 될 수 있습니다. False이면서 docker logs 끝에 치명적인 힙 오류가 있다면 Node.js가 V8 힙을 모두 소진한 것입니다. NODE_OPTIONS=--max-old-space-size=SIZE을 컨테이너 제한보다 낮은 MiB 단위의 숫자로 설정하여 다른 메모리 사용을 위한 여유 공간을 확보하십시오. 이는 V8 old space를 제한하지만, 커널 OOM 킬이 발생하기 전에 힙 오류가 발생함을 보장하지는 않습니다.
실행 데이터를 정리하면 즉시 디스크 공간이 확보됩니까?
아니요. EXECUTIONS_DATA_PRUNE은 오래된 실행 데이터를 삭제 대상으로 표시하며, EXECUTIONS_DATA_PRUNE_HARD_DELETE_INTERVAL에 설정된 일정에 따라 이후 단계에서 제거됩니다. SQLite의 경우 파일 시스템으로 공간을 반환하는 대신 해제된 페이지를 재사용하므로, 행이 삭제된 후에도 디스크 사용량은 한동안 일정하게 유지됩니다. EXECUTIONS_DATA_MAX_AGE 및 EXECUTIONS_DATA_PRUNE_MAX_COUNT을 서버 환경에 맞게 설정한 뒤, 즉시 확인하지 말고 다음 날 다시 확인하십시오.
n8n이 재시작되는 동안 예약된 워크플로우가 실행되지 않은 이유는 무엇입니까?
n8n 2.45.0부터 기본적으로 활성화된 내구적 스케줄러(durable scheduler)는 예정된 실행을 데이터베이스에 저장합니다. 기록된 실행은 n8n이 유예 기간 내에 복구되면 지연 실행됩니다. 해당 기간이 지나면 트리거의 미스파이어 정책(misfire policy)에 따라 백로그를 건너뛸지 아니면 따라잡기 실행을 할지 결정합니다. 버전, 스케줄러 설정, 스케줄 트리거 옵션을 확인하십시오. 메모리 내 스케줄러를 사용하는 이전 버전의 인스턴스는 다운타임 중에 예정된 실행을 건너뜁니다.
헬스체크가 응답하지 않는 n8n을 재시작합니까?
그렇지 않습니다. Compose 헬스체크는 컨테이너를 '정상' 또는 '비정상'으로 표시할 뿐입니다. 재시작 정책은 컨테이너가 종료될 때 작동하므로, restart: unless-stopped은 의도적으로 중지되지 않았고 Docker가 시작되는 경우 종료 후 또는 호스트 재부팅 후에 서비스를 복구합니다. sudo systemctl is-enabled docker를 통해 이를 확인하십시오. 비정상 상태에 대응하려면 상태를 읽고 서비스를 재시작하는 외부 감시 도구가 필요합니다.