n8n v3 베타 먼저 올려 봤습니다: 셀프호스팅 2.45.3에서 3.0.0으로 업그레이드하는 순서와 확인할 것

n8n 3.0.0 베타가 2026년 10월 27일 나왔습니다. 3.x로 가는 것은 한 방향이라 한 번 올리면 2.x로 돌아갈 수 없습니다. 그래서 데이터팝콘이 운영하는 셀프호스팅 서버를 먼저 올려 보고, 실제로 거친 순서와 명령어, 걸린 시간, 예상하지 못했던 부분까지 그대로 적었습니다. 결론부터 말하면 재시작은 17초 만에 끝났고 게시된 워크플로우 8개가 그대로 살아 있었습니다.

이 글은 이런 분께 필요합니다

• Docker로 n8n을 셀프호스팅하면서 3.0 업그레이드를 고민하는 분
• 3.0에서 무엇이 바뀌고, 업그레이드 전에 무엇을 확인해야 하는지 알고 싶은 분
• 지금 바로 올릴지, 정식 버전을 기다릴지 판단할 근거가 필요한 분

먼저 알아 둘 세 가지

• 한 방향입니다. n8n 공식 안내는 3.x로 올리면 2.x로 돌아갈 수 없으니 테스트 서버부터 올리라고 권합니다. 문제가 생기면 백업을 복원하는 것 말고는 되돌릴 방법이 없습니다.
• 아직 베타입니다. 이 글을 쓰는 시점에 npm의 stable은 2.45.4이고 3.0.0은 베타(prerelease)입니다. 운영 서버라면 정식 버전을 기다리는 것도 좋은 선택입니다.
• Docker가 필요합니다. 3.0부터 npm이나 npx n8n으로 설치한 n8n은 지원하지 않습니다. npm으로 쓰고 있다면 Docker로 옮기는 것이 먼저입니다.

테스트 환경

• 업그레이드 전 n8n 2.45.3, 업그레이드 후 3.0.0
• Docker Compose (n8n 공식 설치 스크립트로 만든 구성: n8n, runners, Postgres 16, 샌드박스 서비스)
• 게시된 워크플로우 8개, 전체 워크플로우 18개, 커뮤니티 노드 1개
• 작업일 2026년 10월 28일

Step 1. 내 n8n이 3.0으로 갈 수 있는 구성인지 확인하기

왼쪽 아래 Help → About n8n에서 지금 버전을 확인합니다. 그리고 어떻게 설치했는지 확인합니다.

설치 방식	3.0 업그레이드
Docker, Docker Compose	이미지 태그만 바꾸면 됩니다
npm, npx n8n	지원하지 않습니다. Docker로 먼저 옮겨야 합니다
n8n Cloud	관리 화면에서 버전을 고릅니다. 베타는 3.0.0 Beta (early access)
1.x 버전	바로 3.0으로 갈 수 없습니다. 2.x를 거쳐야 합니다

저희 서버는 Docker Compose이고, .env 파일의 N8N_VERSION 하나가 n8n과 runners 이미지 태그를 함께 정하는 구조였습니다.

Step 2. 마이그레이션 리포트 읽기

Settings → Migration report를 엽니다. 2.39 이후 버전에 있는 메뉴로, 3.0으로 올렸을 때 문제가 될 워크플로우와 인스턴스 설정을 알려 줍니다. 저희 서버(2.45.3)는 워크플로우 18개 모두 호환된다고 나왔습니다.

Instance issues 탭에는 인스턴스 전체에 해당하는 변경 4개가 있었습니다.

리포트에는 항목마다 영향 정도가 붙어 있습니다. "Executions will fail"(실행 실패)과 "Upgrade blocked"(업그레이드 막힘)를 먼저 보고, "Behavior changes"(동작 변경)와 "Capability removed"(기능 제거)를 그다음에 봅니다.

리포트는 최신 2.x에서 보세요

n8n은 최신 2.x 버전에 최신 리포트가 들어 있다고 안내합니다. 저희는 2.45.3의 리포트를 보고 올렸는데, 3.0.0으로 올린 뒤 리포트에 새 항목이 하나 생겼습니다(Step 7). 가능하면 2.x 최신(이 글 기준 2.45.4)으로 먼저 올린 뒤 리포트를 다시 보는 것을 추천합니다.

Step 3. 리포트 항목마다 내 서버에 해당하는지 확인하기

인스턴스 항목 4개를 하나씩 확인했습니다.

리포트 항목	확인 방법	저희 결과와 조치
코드 노드 기본 제한 시간 5분 → 1분	최근 실행 중 60초 넘게 걸린 것이 있는지 DB에서 조회	최근 30일 동안 없음. 조치 안 함
미검증 커뮤니티 패키지 기본 비활성화	Settings → Community nodes 목록 확인	@typesafe-ai/n8n-nodes-typesafe-ai 1개. 계속 불러오도록 환경 변수 추가
압축 노드 한도 축소 (2GiB → 256MiB, ZIP 항목 5000 → 1000)	큰 압축 파일을 다루는 워크플로우가 있는지	해당 워크플로우 없음
편집기의 "URL로 가져오기" 제거	쓰는 사람이 있는지	실행 중인 워크플로우에는 영향 없음

60초 넘게 걸린 실행은 Postgres에서 이렇게 찾았습니다.

select w.name, count(*), round(max(extract(epoch from (e."stoppedAt" - e."startedAt"))))
from execution_entity e
join workflow_entity w on w.id = e."workflowId"
where e."startedAt" > now() - interval '30 days'
  and e."stoppedAt" - e."startedAt" > interval '60 seconds'
group by w.name order by 2 desc;

결과가 없으면 1분 제한에 걸릴 코드 노드가 없다는 뜻입니다. 오래 걸리는 코드 노드가 있다면 N8N_RUNNERS_TASK_TIMEOUT을 직접 지정합니다.

커뮤니티 노드는 .env에 아래 한 줄을 넣어 3.0에서도 계속 불러오게 했습니다.

N8N_UNVERIFIED_PACKAGES_ENABLED=true

Step 4. 전체 백업 받기

되돌릴 방법이 백업 복원뿐이므로, 이 단계는 건너뛰면 안 됩니다. 저희는 세 가지를 받았습니다.

1. 데이터베이스: Postgres 덤프
2. n8n 데이터 폴더: 자격 증명을 푸는 암호화 키(config 파일)가 여기에 있습니다. 이것이 없으면 DB를 복원해도 자격 증명을 쓸 수 없습니다
3. 설정 파일: .env와 compose.yml

BK=~/n8n-backups/pre-v3-$(date +%Y%m%d-%H%M%S)
mkdir -p "$BK" && chmod 700 "$BK"

# 1) DB (컨테이너 이름은 각자 환경에 맞게)
docker exec n8n-postgres-1 pg_dump -U postgres -d n8n -Fc > "$BK/n8n.pgdump"

# 2) n8n 데이터 볼륨 (볼륨 이름은 docker volume ls로 확인)
docker run --rm -v n8n_n8n-data:/data:ro -v "$BK":/backup alpine \
  tar czf /backup/n8n-data.tgz -C /data .

# 3) 설정 파일
cp .env "$BK/env.bak"; cp compose.yml "$BK/"

백업이 제대로 됐는지도 확인합니다. 저희 결과는 DB 덤프 8.9MB, 데이터 폴더 220MB였고, 압축 파일 안에 config가 들어 있는 것과 덤프에 테이블 데이터 176개가 있는 것을 확인했습니다.

tar tzf "$BK/n8n-data.tgz" | grep "^./config$"
docker exec -i n8n-postgres-1 pg_restore -l < "$BK/n8n.pgdump" | grep -c "TABLE DATA"

Step 5. 새 이미지 먼저 받아 두기

컨테이너를 내리기 전에 이미지를 미리 받아 두면, 다운로드가 실패해도 지금 서버는 멀쩡합니다. n8n과 runners는 같은 버전을 써야 합니다.

docker pull docker.io/n8nio/n8n:3.0.0
docker pull ghcr.io/n8n-io/runners:3.0.0

저희 환경에서는 70초 걸렸고, 이미지 크기는 n8n 1.88GB, runners 871MB였습니다. 디스크 여유가 적다면 백업까지 합쳐 최소 3GB 이상은 비워 두세요.

Step 6. 버전을 바꾸고 다시 띄우기

실행 중인 작업이 없는지 확인한 뒤 진행합니다. 저희는 DB에서 running, new, waiting 상태 실행이 0건인 것을 보고 시작했습니다.

# .env의 버전만 바꿈
sed -i '' 's/^N8N_VERSION=.*/N8N_VERSION=3.0.0/' .env   # Linux는 sed -i

# n8n과 runners만 다시 띄움 (Postgres 등 다른 서비스는 그대로)
docker compose up -d --no-deps n8n runners

로그는 docker logs -f <n8n 컨테이너>로 봅니다. 저희 서버는 17초 만에 편집기가 다시 열렸습니다. 그 사이 로그에 나온 내용은 이렇습니다.

• Migrations in progress, please do NOT stop the process.(마이그레이션 중이니 중단하지 마세요) 뒤로 DB 마이그레이션 16개가 차례로 끝났습니다
• Recorded version change: 2.45.3 -> 3.0.0, Version: 3.0.0
• 경고 두 가지가 나왔지만 기동에는 지장이 없었습니다

로그 경고	뜻	조치
Postgres 16 is outside the supported range ... Upgrade to Postgres 17 or newer.	Postgres 16은 호환 지원만 받음	당장은 동작. Postgres 17 이상으로 옮길 계획 필요
WEBHOOK_URL -> Use N8N_WEBHOOK_URL instead	환경 변수 이름이 바뀔 예정	.env의 WEBHOOK_URL을 N8N_WEBHOOK_URL로 바꾸면 됨

마이그레이션 중에는 절대 멈추지 마세요

로그에 "Migrations in progress"가 보이는 동안 컨테이너를 멈추면 DB가 어중간한 상태로 남을 수 있습니다. 데이터가 많은 서버는 더 오래 걸릴 수 있으니 Editor is now accessible 줄이 나올 때까지 기다립니다.

Step 7. 업그레이드 후 확인하기

올라왔다고 끝이 아닙니다. 아래 순서로 확인했습니다.

1. 상태 확인: 서버 안에서 /healthz가 {"status":"ok"}, 외부 주소도 200
2. 버전: About n8n에서 3.0.0. 2.x에서 보이던 도움말 메뉴의 "Update (1 version behind)" 알림도 사라졌습니다

3. 게시된 워크플로우 수: 업그레이드 전 8개, 후 8개로 같은지 DB에서 확인

select count(*) from workflow_entity where active;

4. 코드 실행: JavaScript 코드 노드와 Python 코드 노드를 이은 점검용 워크플로우를 만들어 수동 실행했습니다. 둘 다 성공해서 runners도 3.0에서 정상인 것을 확인했고, 점검이 끝난 워크플로우는 보관(Archive) 처리했습니다.

5. 마이그레이션 리포트 다시 보기: 여기서 예상하지 못한 항목이 나왔습니다. 2.45.3에서는 18개 모두 호환이었는데, 3.0.0에서 다시 열어 보니 10개만 호환이고 문제 1건이 생겼습니다.

내용은 "Slack API 자격 증명의 Signature Secret(서명 시크릿) 칸이 이제 필수"라는 것입니다. 리포트 설명에 따르면 Slack 노드는 지금처럼 계속 동작하지만, 해당 자격 증명을 다시 저장하려면 서명 시크릿을 넣어야 합니다. 당장 멈추는 문제는 아니지만, Slack 앱 설정에서 서명 시크릿을 미리 찾아 두는 것이 좋습니다.

Step 8. 3.0에서 달라진 화면 둘러보기

이번 3.0.0은 큰 새 기능보다 정리에 가까운 버전이지만, 화면에서 바로 보이는 변화가 몇 가지 있었습니다.

바뀐 곳	2.45.3	3.0.0
왼쪽 메뉴 Assistant	Preview 표시	Preview 표시 없음
설정 메뉴	한 줄 목록	Personal, People & access, AI, Integrations, Security, Operations, Billing으로 묶임
로그인 방식	SSO, LDAP 메뉴가 따로	Authentication 한 곳으로 합쳐짐
보안 정책	Security & policies	Policies
암호화 키	메뉴 없음	Data encryption keys: 키 교체(Rotate key)와 이전 키 기록
Context	Skills "Coming soon"	Skills 사용 가능 ("Teach the assistant and agents how to work")
Chat	설정 메뉴에 있음	설정 메뉴와 왼쪽 메뉴에서 빠짐 (3.0에서 기본으로 꺼짐)

3.0은 자격 증명 같은 민감한 데이터를 암호화하는 키를 교체할 수 있는 기능을 기본으로 켭니다. 화면에서 키를 바꾸면 새 키가 활성화되고 이전 키는 기록으로 남습니다.

Step 9. 문제가 생기면 되돌리는 방법 정리해 두기

3.x에서 2.x로 바로 내려가는 방법은 없으므로, 되돌릴 때는 Step 4의 백업을 복원합니다. 순서는 이렇습니다.

1. n8n과 runners 컨테이너를 멈춥니다.
2. .env를 백업한 env.bak으로 되돌립니다(N8N_VERSION=2.45.3).
3. DB 덤프를 복원합니다.

docker exec -i n8n-postgres-1 pg_restore -U postgres -d n8n --clean --if-exists --no-owner < "$BK/n8n.pgdump"

4. 필요하면 데이터 볼륨도 n8n-data.tgz로 되돌린 뒤 docker compose up -d --no-deps n8n runners로 다시 띄웁니다.

백업 이후 3.0에서 생긴 실행 기록과 수정 사항은 복원하면 사라진다는 점도 기억해 두세요.

자주 겪는 문제와 해결

증상	원인	해결
npm으로 설치한 n8n을 3.0으로 못 올림	3.0은 Docker 배포만 지원	Docker로 옮긴 뒤 업그레이드
2.x 리포트는 문제 없음, 3.0에서 새 항목 등장	리포트 규칙이 버전마다 추가됨	최신 2.x로 먼저 올리고 리포트 재확인
커뮤니티 노드가 3.0에서 안 불러와짐	미검증 패키지 기본 비활성화	N8N_UNVERIFIED_PACKAGES_ENABLED=true
오래 걸리던 코드 노드가 중간에 끊김	기본 제한 시간 5분 → 1분	N8N_RUNNERS_TASK_TIMEOUT을 필요한 초로 지정
로그에 Postgres 16 경고	지원 범위는 Postgres 17 이상	당장은 동작. DB 업그레이드 계획 세우기
로그에 WEBHOOK_URL 경고	변수 이름 변경 예정	N8N_WEBHOOK_URL로 이름 변경
Slack 자격 증명 저장 시 오류	서명 시크릿 필수화	Slack 앱의 Signing Secret을 입력
자동 업데이트 스크립트가 3.x를 못 찾음	3.0부터 실행용 npm 패키지를 내지 않음	버전 조회를 npm 대신 Docker Hub나 GitHub 릴리스로 바꾸기

직접 확인하지 못한 것

• Step 9의 되돌리기는 실제로 해 보지 않았습니다. 2.x 자동 업데이트 때 같은 방식(pg_restore)으로 복원 절차를 만들어 둔 것을 정리했습니다.
• 업그레이드 직후에는 예약 실행이 돌아올 시간이 아니어서, 예약 트리거 실행은 수동 코드 실행으로 대신 확인했습니다.
• Slack 서명 시크릿 항목은 리포트 설명만 확인했고, 실제로 자격 증명을 다시 저장해 보지는 않았습니다.

참고 자료

• v3.0 Breaking changes (n8n 문서)
• Announcing n8n version 3.0 - coming soon! (n8n 커뮤니티, 2026-10-23)
• [email protected] 릴리스 노트 (GitHub, 2026-10-27)
• Update n8n (n8n 문서)