[Docker] n8n docker compose 전환 시 워크플로우 사라짐 해결 방법 (데이터 복구 가이드)

 

안녕하세요, 워크플로우 아키텍트, 수월한입니다 👋

 

오늘은 Docker 환경에서 n8n을 운영하다가 자주 겪게 되는 식은땀 나는 상황, 바로 공들여 짠 워크플로우(Workflow)가 갑자기 사라지는 이슈와 그 해결 방법을 공유합니다.

 

특히 기존에 docker run 명령어로 간단히 사용하다가, 관리를 위해 docker-compose로 마이그레이션 하는 과정에서 데이터가 초기화되는 경험을 하신 분들이 많을 텐데요. 당황하지 마시고 아래 가이드를 따라오시면 데이터를 안전하게 복구할 수 있습니다.

🏗️ n8n Docker 데이터 저장 경로와 볼륨(Volume)의 이해

문제를 해결하기 전, n8n이 데이터를 어디에 저장하는지 먼저 짚어볼게요.

 

📦 n8n의 데이터 저장 위치

n8n은 모든 중요 데이터(워크플로우, Credential, 실행 기록 등)를 컨테이너 내부의 다음 경로에 저장합니다.

• 경로: `/home/node/.n8n`
• 핵심 파일: `database.sqlite` (이 안에 모든 설정이 들어있습니다)

🗃 Docker 볼륨(Volume)의 역할

Docker 컨테이너는 삭제되면 내부 데이터도 함께 사라지는 휘발성을 가져요. 따라서 데이터를 영구적으로 보존하려면 반드시 볼륨(Volume)을 통해 컨테이너 외부(호스트)에 데이터를 저장해야 합니다.

• `docker run`과 `docker-compose` 방식 모두 동일한 볼륨 경로를 바라보게 설정해야만 기존 데이터를 이어서 사용할 수 있습니다.

🚨 문제 상황: docker-compose 마이그레이션 후 초기화 현상

많은 분들이 겪는 상황은 다음과 같습니다.

 

기존 실행 방식 (docker run)

아마도 처음에 테스트 삼아 아래와 비슷하게 실행하셨을 수 있습니다. (이때 `-v` 옵션을 주지 않았거나, 익명 볼륨으로 생성되었을 가능성이 높습니다.)

docker run -it --name n8n -p 5678:5678 docker.n8n.io/n8nio/n8n

 

변경한 실행 방식 (docker-compose)

그리고 체계적인 관리를 위해 `docker-compose.yml`을 작성하여 실행하죠.

version: "3.8"
services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    volumes:
      - n8n_data:/home/node/.n8n  <-- 새로운 볼륨 연결
volumes:
  n8n_data:
    external: true

 

결과

`docker-compose up -d`로 실행하고 접속해 보니, 기존에 만들어둔 모든 워크플로우가 사라지고 초기 상태가 되는 경우입니다.

원인 분석: 데이터가 갇혀있다!

기존 `docker run`으로 실행했을 때, 명시적인 볼륨 마운트(`-v`)를 하지 않았다면 데이터는 기존 컨테이너 내부(/home/node/.n8n)에만 존재합니다. 새로 작성한 `docker-compose`는 `n8n_data`라는 새롭고 비어있는 볼륨을 연결했기 때문에, 당연히 n8n은 아무것도 없는 새 환경으로 실행된 거예요.

🛠️ 해결 방법: 컨테이너 내부 데이터를 볼륨으로 복구하기 (Step-by-Step)

해결책은 간단합니다. "기존 컨테이너 속에 갇힌 데이터를 꺼내서, 새로운 볼륨으로 옮겨주면" 됩니다.

 

Step 1. 기존 컨테이너에서 데이터 백업하기

먼저 기존 컨테이너(예: 이름이 n8n인 경우)에서 데이터를 로컬 PC로 복사합니다.

docker cp n8n:/home/node/.n8n ./n8n_backup

 

Step 2. 새 볼륨으로 데이터 복사하기

Docker의 임시 컨테이너(alpine)를 이용해 백업한 데이터를 `n8n_data` 볼륨으로 옮깁니다. (Windows 사용자는 경로 표기법 주의)

docker run --rm -v n8n_data:/data -v $(pwd)/n8n_backup:/backup alpine sh -c "cp -r /backup/* /data/"

 

Step 3. 파일 권한 수정 (매우 중요 ⭐)

데이터를 옮겼더라도 권한이 맞지 않으면 n8n이 실행되지 않거나 오류(Permission denied)가 발생합니다. n8n은 node 유저(UID 1000) 권한을 사용하므로 소유권을 변경해야 합니다.

docker run --rm -it -v n8n_data:/data alpine sh

# 아래 명령어를 순서대로 입력하세요
chown -R 1000:1000 /data
chmod -R u+rwX,go-rwx /data
exit

 

Step 4. Docker Compose 재시작

이제 모든 준비가 끝났습니다. 컨테이너를 다시 띄웁니다.

 

docker-compose down && docker-compose up -d

 

Step 5. 결과 확인

브라우저에서 `http://localhost:5678`에 접속해 보세요. 사라졌던 워크플로우들이 다시 나타난 것을 확인할 수 있습니다!

⚙️ 안정적인 운영을 위한 필수 권장 설정 (Pro Tips)

단순히 실행만 되는 것이 아니라, 앞으로 장기적인 운영과 유지보수를 편하게 하기 위해 다음 설정들을 꼭 적용하시길 권장합니다.

1. env 환경 변수 추가 (보안 및 권한 관리)

`docker-compose.yml`과 같은 폴더에 `.env` 파일을 만들고 아래 내용을 추가하세요.

특히 `N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true` 옵션은 컨테이너 재시작 시 권한이 꼬여서 무한 재부팅되는 현상을 막아주는 '안전장치' 역할을 해요.

# n8n 설정 파일의 권한이 변경되지 않도록 강제하여 'Permission denied' 오류를 예방합니다.
N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true

# 무거운 작업을 처리할 때 안정성을 높여주는 러너(Runner) 모드를 활성화합니다.
N8N_RUNNERS_ENABLED=true

# (선택) 한국 시간 기준으로 스케줄러(Cron)를 작동시키려면 추가하세요.
GENERIC_TIMEZONE=Asia/Seoul
TZ=Asia/Seoul

 

2. 컨테이너 이름 고정 (관리 편의성)

`docker-compose.yml` 파일에서 서비스 부분에 container_name을 명시해 주세요.

이름을 지정하지 않으면 `docker_n8n_1` 처럼 매번 헷갈리는 이름이 자동 생성됩니다. 이름을 고정해 두면 나중에 로그를 확인하거나 디버깅할 때 `docker logs -f n8n-main` 처럼 훨씬 직관적으로 명령어를 사용할 수 있어요.

services:
  n8n:
    container_name: n8n-main  # <-- 이렇게 이름을 지어주세요
    image: docker.n8n.io/n8nio/n8n
    # ... (나머지 설정)

❓ 자주 묻는 질문 (FAQ)

Q1. n8n의 핵심 데이터베이스 파일은 무엇인가요?

A. 컨테이너 내 `/home/node/.n8n` 경로에 있는 `database.sqlite` 파일이에요. 이 파일만 잘 백업해 두셔도 워크플로우와 크리덴셜을 복구할 수 있습니다.

Q2. 복구 후 "Permission denied" 오류가 계속 발생해요.

A. Docker 볼륨의 소유 권한 문제예요. 위 Step 3의 `chown -R 1000:1000` 과정을 수행했는지 반드시 확인해 주세요. (n8n 이미지는 보안상 root가 아닌 node 유저 권한을 엄격하게 요구해요.)

Q3. 나중에 n8n 버전을 업데이트하려면 어떻게 하나요?

A. docker-compose를 사용 중이라면 다음 두 줄의 명령어로 간단히 업데이트 가능합니다. (데이터는 볼륨에 안전하게 저장되어 있으니 걱정하지 않으셔도 됩니다.)

docker-compose pull
docker-compose up -d

✨마무리

n8n을 Docker로 운영할 때 볼륨(Volume) 설정과 권한 관리는 가장 기초적이면서도 중요한 부분이죠. 이번 트러블슈팅 가이드가 여러분의 소중한 자동화 데이터를 지키는 데 도움이 되었기를 바랍니다. 🙌

 

혹시 따라 하시다가 막히는 부분이 있다면 언제든 댓글로 남겨주세요!