n8n을 Traefik 3.3 및 Postgres 16으로 마이그레이션: 기술 가이드

데이터 손실 없는 안전한 n8n 마이그레이션: Traefik 3.3과 Postgres 16으로 업그레이드하기

오래된 Traefik과 Postgres 버전에서 n8n을 현대적인 스택으로 마이그레이션하려면 중요한 호환성 문제를 해결해야 합니다. 이 글은 Traefik 1.x와 Postgres 11에서 최신 버전으로 업그레이드할 때 데이터와 자격 증명을 보존하는 기술 가이드를 제공합니다.

준비 단계: 백업 및 암호화 키 보존

마이그레이션의 핵심 단계는 데이터를 제대로 내보내고 암호화 키를 보존하는 것입니다. 이를 하지 않으면 전송 후 자격 증명에 접근할 수 없게 됩니다. n8n의 경우 이는 매우 중요합니다. 시스템은 토큰과 비밀번호를 저장하기 위해 대칭 암호화를 사용하기 때문입니다.

다음 두 가지 필수 작업을 수행하세요:

• 적절한 복원을 위해 custom 형식으로 데이터베이스 덤프 생성:

docker exec -t postgres_db pg_dump -U root -d n8n -Fc > /tmp/n8n_backup.dump
docker cp postgres_db:/tmp/n8n_backup.dump ./n8n_backup.dump

• 구성에서 현재 암호화 키 추출. 출처는 두 곳일 수 있습니다:

- docker-compose.yml의 변수 N8N_ENCRYPTION_KEY

- 파일 ~/.n8n/config의 매개변수 encryptionKey

이 단계를 무시하면 시작 후 Needs first setup 오류가 발생합니다. 시스템은 데이터베이스를 인식하지만 저장된 자격 증명을 복호화할 수 없게 됩니다.

스택 배포: Traefik 3.3의 함정

Traefik 3.3을 배포할 때 Docker API와의 치명적인 비호환성 문제가 발생합니다. 라우터는 기본적으로 구버전 API(1.24)를 사용하지만, 현대적인 Docker 데몬은 1.41 이상을 요구합니다. 이로 인해 컨테이너를 탐지하려 할 때 404 오류가 발생합니다.

해결책 — 환경 변수에서 API 버전 강제 지정:

environment:
  - DOCKER_API_VERSION=1.41

이 변경으로 Traefik이 Docker Engine과 올바르게 상호작용합니다. 이를 하지 않으면 라우터가 n8n과 Postgres 컨테이너를 볼 수 없어 Docker Provider를 통한 자동 라우트 설정이 불가능합니다.

네트워크 격리 주의: 모든 서비스는 동일한 커스텀 네트워크(n8n_net)에 있어야 합니다. 이렇게 하면 컨테이너 간 안정적인 상호작용이 보장되고 라우팅 충돌이 없습니다. 올바른 구성 예시:

networks:
  n8n_net:
    name: n8n_net

services:
  traefik:
    networks:
      - n8n_net
  n8n:
    networks:
      - n8n_net
  postgres_db:
    networks:
      - n8n_net

Postgres 16에서 데이터베이스 복원: 권한 문제 수정

Postgres 16은 기본 보안 정책에 변화를 도입했습니다. public 스키마의 권한이 제한되어 n8n 시작 시 permission denied for schema public 오류가 발생합니다.

덤프 복원 후 실행:

docker cp n8n_backup.dump postgres_db:/tmp/
docker exec -i postgres_db pg_restore -U root -d n8n -1 /tmp/n8n_backup.dump

그 다음 데이터베이스 소유자에게 스키마에 대한 전체 권한 부여:

docker exec -it postgres_db psql -U root -d n8n -c "GRANT ALL ON SCHEMA public TO root;"

이는 n8n이 메타데이터 저장을 위해 public 스키마를 적극적으로 사용하기 때문입니다. 이 단계를 건너뛰면 n8n 컨테이너가 반복적으로 크래시합니다.

자격 증명 수정: "Needs first setup" 오류 피하기

환경 변수를 통해 N8N_ENCRYPTION_KEY를 올바르게 전달해도 n8n이 이를 무시할 수 있습니다. 이유는 환경 변수와 로컬 구성 파일 간 충돌 때문입니다. 첫 시작 시 시스템이 새로운 ~/.n8n/config 파일을 생성해 변수의 키를 덮어쓰기 때문입니다.

해결책:

• 컨테이너 내부의 구성 파일 삭제:

docker exec -it n8n rm /home/node/.n8n/config

• 서비스 재시작:

docker compose restart n8n

이렇게 하면 n8n이 로컬 파일 대신 환경 변수의 키를 사용하게 됩니다. 원본 N8N_ENCRYPTION_KEY 변수가 docker-compose.yml에 지정되어 있는지 확인하세요.

추가 주의사항: 백그라운드 프로세스와 SQLite

마이그레이션 중 백그라운드 작업에서 SQLite를 사용하는 문제(예: Telethon 기반 Telegram 파서)가 발생할 수 있습니다. 전송 후 sqlite3.OperationalError: database is locked 오류가 보입니다.

원인 — 데이터베이스를 잠그는 잔여 저널링 파일(.session-journal, .session-wal). 해결책:

• psmisc 유틸리티 설치:

apt install psmisc -y

• 잠금을 유지하는 프로세스 강제 종료:

fuser -k -v /root/parser_folder/session_name.session

• 임시 파일 삭제:

rm -f /root/parser_folder/session_name.session-journal
rm -f /root/parser_folder/session_name.session-wal

• 서비스 재시작:

systemctl restart service_name.service

중요: 저널 삭제는 메인 세션 파일에 영향을 주지 않습니다. Telegram 인증은 그대로 유지됩니다.

주요 포인트

• 암호화 키는 필수 — 원본 N8N_ENCRYPTION_KEY 없이는 모든 Credentials에 접근할 수 없습니다.
• Traefik은 명시적 API 지정 필요 — 컨테이너 탐지를 위해 DOCKER_API_VERSION=1.41 매개변수가 핵심입니다.
• Postgres 16은 권한 제한 — 수동으로 GRANT ALL ON SCHEMA public 실행.
• n8n 로컬 구성 충돌 — ~/.n8n/config 삭제로 암호화 키 문제 해결.
• SQLite 잠금은 정리 필요 — .journal 및 .wal 파일 제거로 백그라운드 프로세스 복원.

모든 단계를 완료하면 n8n이 모든 워크플로, 웹훅, 자격 증명을 보존한 채 시작됩니다. 주요 소프트웨어 버전 간 마이그레이션은 항상 위험을 수반하지만, 이 절차를 따르면 다운타임과 데이터 손실을 최소화할 수 있습니다.

— Editorial Team