n8n 3.0 마이그레이션 도구
n8n v2.47요약
마이그레이션 도구는 n8n 인스턴스를 스캔하여 n8n 3.0에서 변경되는 워크플로와 인스턴스 설정을 나열하므로, 업그레이드 전에 문제를 해결할 수 있습니다. 전체 변경 사항 목록은 v3.0 주요 변경 사항을 참고합니다.
마이그레이션 도구는 n8n 인스턴스를 스캔하여 n8n 3.0에서 변경되는 워크플로와 인스턴스 설정을 나열하므로, 업그레이드 전에 문제를 해결할 수 있습니다. 에디터의 Settings > Migration Report에서 마이그레이션 리포트로 열 수 있습니다.
전체 변경 사항 목록은 v3.0 주요 변경 사항을 참고합니다.

마이그레이션 리포트를 사용할 수 있는 사용자#
모든 사용자가 마이그레이션 리포트를 열 수 있지만, 보이는 내용은 권한에 따라 다릅니다.
| 인스턴스 소유자 및 관리자 | 다른 사용자 | |
|---|---|---|
| 워크플로 이슈 보기 | 인스턴스의 모든 워크플로 | 편집할 수 있는 워크플로 |
| Instance issues 탭 보기 | 예 | 아니요, 탭이 표시되지 않습니다 |
| 리포트 새로고침 | 예 | 아니요 |
| 워크플로 소유자에게 알림 | 예, 이메일(SMTP)을 설정한 경우 | 아니요 |
다른 사용자에게는 페이지 상단에 "This report only includes the workflows you can edit."라는 안내가 표시됩니다.
호환성 요약 읽기#
페이지 상단의 진행 막대는 워크플로 중 n8n 3.0과 호환되는 수를 보여 줍니다. 호환되는 워크플로는 업그레이드 후에도 변경 없이 계속 작동합니다. 목표는 나머지 워크플로가 호환되지 못하게 하는 이슈와 인스턴스 이슈를 해결하는 것입니다.
n8n은 워크플로를 저장할 때 다시 확인하므로, 이슈를 해결하는 동안 리포트가 최신 상태로 유지됩니다. Last updated는 n8n이 마지막으로 전체 스캔을 실행한 시점을 보여 줍니다. 직접 전체 스캔을 실행하려면 Refresh를 선택합니다.
도구는 이슈를 두 개의 탭으로 구성합니다.
워크플로 이슈#
Workflow issues 탭에는 인스턴스의 워크플로에 영향을 주는 변경 사항이 나열됩니다. 각 이슈에는 다음 항목이 표시됩니다.
- 제목 및 설명: 무엇이 변경되고 왜 중요한지 설명합니다.
- 영향도 배지: 변경이 워크플로에 미치는 영향입니다. 배지 위에 마우스를 올리면 자세한 내용을 볼 수 있습니다. 영향도 수준을 참고합니다.
- 워크플로 수: 해당 이슈가 있는 워크플로의 수입니다. 선택하면 이슈의 상세 페이지가 열립니다.
- 미해결 수: 그중 아직 수정이 필요한 워크플로의 수입니다. 수정하지 않음(won't fix)으로 표시된 워크플로가 있으면 그 수가 옆에 나타납니다.
- 문서: v3.0 주요 변경 사항의 해당 섹션으로 연결되는 링크입니다.
인스턴스 이슈#
Instance issues 탭에는 환경 변수와 배포 설정처럼 인스턴스 전체에 영향을 주는 구성 변경 사항이 나열됩니다. 인스턴스 이슈에는 제목, 설명, 영향도 배지, 문서 링크가 있지만 인스턴스 전체에 적용되므로 워크플로 수는 없습니다. 이 탭은 인스턴스 소유자와 관리자에게만 표시됩니다.
영향도 수준#
각 이슈에는 다섯 가지 영향도 수준 중 하나가 지정됩니다.
| 영향도 | 의미 |
|---|---|
| Upgrade blocked | 업그레이드를 진행할 수 없거나 업그레이드 후 인스턴스가 시작되지 않을 수 있습니다. 가장 먼저 해결합니다. |
| Executions will fail | 영향을 받는 워크플로 또는 인스턴스가 업그레이드 후 실패합니다. 영향을 받는 노드 또는 설정을 업데이트하거나 교체합니다. |
| Executions might fail | 기본값이 변경되어 실행이 실패할 수 있습니다. 권장 사항을 읽고 현재 값을 유지합니다. |
| Behavior changes | 영향을 받는 워크플로는 계속 실행되지만 동작이 달라집니다. 업그레이드 전에 검토하고 테스트합니다. |
| Capability removed | 실행에는 영향이 없지만, 워크플로 또는 인스턴스가 사용하는 기능을 더 이상 사용할 수 없습니다. |
워크플로 이슈 처리#
이슈의 워크플로 수를 선택하면 상세 페이지가 열립니다. 이 페이지에는 영향을 받는 모든 워크플로가 다음 항목과 함께 나열됩니다.
- Name: 선택하면 에디터에서 워크플로가 열립니다.
- Owner: 수정을 담당하는 사람입니다. 소유자 지정을 참고합니다.
- Nodes affected: 이슈가 있는 노드입니다. 노드를 선택하면 해당 노드가 보이는 상태로 워크플로가 열립니다.
- State: 발견 항목이 Open, Notified, Won't fix 중 어느 상태인지 나타냅니다.
- Published: 워크플로가 라이브 상태인지와 마지막 업데이트 날짜입니다.
- Usage: 실행 횟수와 마지막 실행 날짜입니다.
여러 워크플로에 한 번에 작업하려면 각 워크플로 옆의 체크박스를 선택합니다. Migrate, Notify owners, Mark won't fix, Reopen, Clear selection이 있는 일괄 작업 막대가 나타납니다. 일부 작업은 해당하는 경우에만 나타납니다. 예를 들어 Migrate는 n8n이 자동으로 마이그레이션할 수 있는 이슈에만 표시됩니다.

먼저 수정할 워크플로 찾기#
목록을 좁히려면 검색 상자, 정렬 메뉴, 빠른 필터(Assigned to me, Open, Won't fix, Unassigned)를 사용합니다. Filters를 선택하면 다음 기준으로 필터링할 수 있습니다.
- 상태
- 마지막 실행
- 마지막 업데이트
- 실행 횟수
- 상태(게시 여부)
- 소유자
- 프로젝트
실행 횟수가 많은 순으로 정렬하면 가장 많이 사용하는 워크플로부터 수정할 수 있습니다. 워크플로가 12개월 넘게 실행되지 않았다면 배너가 나타나 수정하지 않음으로 표시하도록 제안하므로, 목록에서 방해가 되지 않게 할 수 있습니다.
워크플로 자동 마이그레이션#
일부 이슈에서는 n8n이 영향을 받는 노드를 대신 다시 작성할 수 있습니다. 이슈가 이를 지원하면 각 행에 Migrate 버튼이 나타납니다. 예를 들어 n8n은 Cron 노드를 Schedule Trigger 노드로 교체할 수 있습니다.
워크플로를 마이그레이션하려면 다음을 따릅니다.
- Migrate를 선택하거나, 여러 워크플로를 선택한 뒤 일괄 작업 막대에서 Migrate를 선택합니다.
- n8n이 변경할 노드 목록을 검토한 다음 확인합니다.
- n8n이 결과를 워크플로의 새 버전으로 저장합니다. 게시된 워크플로는 새 버전을 게시할 때까지 현재 버전을 계속 실행합니다.
- Publish를 선택하면 마이그레이션된 버전이 라이브 상태가 되고, Skip publishing을 선택하면 먼저 검토할 수 있습니다.
마이그레이션된 워크플로는 게시하기 전에 테스트합니다. 자동 마이그레이션은 노드 변경만 다루므로, 워크플로의 출력이 여전히 기대한 대로인지 확인합니다.
소유자 지정#
각 워크플로에는 수정을 책임지는 사람인 소유자를 지정할 수 있습니다. n8n은 워크플로에서 마지막으로 작업한 사용자를 제안하며, 눈에 띄는 단일 사용자가 없으면 워크플로 프로젝트의 소유자를 제안합니다. 변경하려면 Owner 열에서 소유자를 선택하고 다른 사용자를 고릅니다.
소유자에게 알림#
인스턴스 소유자와 관리자는 이슈에 대해 워크플로 소유자에게 이메일을 보낼 수 있습니다. 행에서 Notify owner를 선택하거나, 여러 워크플로를 선택한 뒤 Notify owners를 선택합니다. 워크플로의 상태가 Notified로 바뀝니다. 이메일을 다시 보내려면 Remind를 선택합니다.
알림을 보내려면 인스턴스에 이메일(SMTP)이 설정되어 있어야 하고, 워크플로에 이메일 주소가 있는 소유자가 있어야 합니다. 알림은 이슈를 해결하지 않습니다. 워크플로를 수정하거나 수정하지 않음으로 표시할 때까지 워크플로는 계속 미해결로 집계됩니다.
워크플로를 수정하지 않음으로 표시#
예를 들어 더 이상 사용하지 않는 워크플로처럼 수정할 계획이 없다면 상태를 Won't fix로 설정합니다. 그러면 해결된 것으로 집계되며 더 이상 미해결로 표시되지 않습니다. 되돌리려면 Reopen을 선택합니다. 나중에 이슈를 수정하면 n8n이 리포트에서 해당 항목을 제거합니다.
리포트 내보내기#
Export CSV를 선택하면 개요를 CSV 파일로 다운로드합니다. 마이그레이션 진행 상황을 n8n 지원팀 등과 공유할 때 사용합니다. 내보내기에는 리포트에서 보이는 것과 같은 워크플로와 이슈가 포함됩니다.
파일은 이슈마다 한 행으로 구성됩니다. 인스턴스 합계가 모든 행에 반복되므로 스프레드시트에서 그대로 열 수 있습니다. 열은 다음과 같습니다.
| 열 | 설명 |
|---|---|
target_version |
리포트가 점검하는 기준이 되는 n8n 버전입니다. |
current_version |
인스턴스가 실행 중인 n8n 버전입니다. |
synced_at |
n8n이 마지막으로 전체 스캔을 실행한 시점입니다. |
total_workflows |
리포트에 포함된 워크플로 수입니다. |
affected_workflows |
해결되지 않은 이슈가 하나 이상 있는 워크플로 수입니다. |
affected_instance_rules |
인스턴스 이슈 수입니다. |
rule_kind |
행이 워크플로 이슈인지 인스턴스 이슈인지 나타냅니다. |
rule_id |
이슈의 ID입니다. |
rule_title |
이슈의 제목입니다. |
impact |
식별자로 표시한 영향도 수준입니다. 예: executionsFail. |
impact_label |
리포트에 표시되는 영향도 수준입니다. 예: "Executions will fail". |
unresolved_workflows |
이슈가 open 또는 notified 상태인 워크플로 수입니다. |
wont_fix_workflows |
수정하지 않음으로 표시된 워크플로 수입니다. |
빈 리포트의 의미#
| 탭 | 비어 있을 때의 의미 |
|---|---|
| Workflow issues | 모든 워크플로가 n8n 3.0과 호환됩니다. 다음으로 Instance issues를 확인합니다. |
| Instance issues | 인스턴스 구성이 n8n 3.0에 대비되어 있습니다. 다음으로 Workflow issues를 확인합니다. |
| 둘 다 | 도구가 수정할 항목을 찾지 못했습니다. 도구가 감지할 수 없는 변경 사항은 v3.0 주요 변경 사항에서 검토한 뒤 업그레이드합니다. |
권장 워크플로#
- 평가합니다. 호환성 요약을 확인한 다음 두 탭을 둘러보며 작업량을 파악합니다.
- 영향도가 가장 높은 항목부터 시작합니다. Upgrade blocked와 Executions will fail 이슈를 먼저 수정하고, 이어서 Executions might fail, Behavior changes, Capability removed를 수정합니다.
- 워크플로 이슈를 수정합니다. 각 이슈를 열고 영향을 받는 워크플로를 마이그레이션하거나 편집한 뒤, 개발 환경에서 테스트합니다.
- 인스턴스 이슈를 수정합니다. 각 이슈의 설명에 따라 환경 변수와 서버 구성을 업데이트합니다.
- 검증합니다. 인스턴스 소유자와 관리자는 Refresh를 선택해 전체 스캔을 실행합니다. 다른 사용자는 리포트를 다시 불러오며, 이 리포트에는 본인이 저장한 워크플로가 반영됩니다. 미해결 이슈가 남아 있지 않은지, 호환 워크플로 수가 리포트의 전체 워크플로 수와 일치하는지 확인합니다.
- 업그레이드합니다. n8n 3.0으로 업그레이드합니다.