n8n 3.0 호환성을 깨는 변경
n8n v2.47요약
n8n 3.0에는 몇 가지 중요한 변경이 포함되어 있습니다. n8n 3.0.0은 현재 얼리 액세스 릴리즈로 제공됩니다. 업그레이드하기 전에 Settings > Migration Report에서 n8n 3.0 마이그레이션 도구를 사용하세요.
n8n 3.0에는 몇 가지 중요한 변경이 포함되어 있습니다. 이 문서는 전환에 대비해 알아야 할 호환성을 깨는 변경과 필요한 조치를 안내합니다. 이번 업데이트는 보안을 강화하고, 구성을 단순화하며, 레거시 기능을 제거합니다.
얼리 액세스 릴리즈
n8n 3.0.0은 현재 얼리 액세스 릴리즈로 제공됩니다.
업그레이드하기 전에 Settings > Migration Report에서 n8n 3.0 마이그레이션 도구를 사용하세요. 이 보고서에는 사용 중인 인스턴스에서 확인이 필요한 워크플로와 인스턴스 설정이 나열되므로, 이 페이지의 모든 변경을 직접 하나씩 확인할 필요가 없습니다.
배포#
셀프 호스팅 n8n에는 Docker 기반 배포 필요#
셀프 호스팅 n8n에는 Docker 기반 배포가 필요합니다. n8n 3.0은 npm 또는 npx n8n으로 실행하는 설치 방식을 더 이상 지원하지 않으며, n8n 3.0은 실행 가능한 n8n 패키지를 npm에 게시하지 않습니다.
해야 할 일: npm 또는 npx n8n으로 n8n을 실행하고 있다면, n8n 3.0으로 업그레이드하기 전에 Docker 기반 배포로 이전하세요. 가장 빠른 방법은 한 줄 설정으로, Docker를 확인하고 구성 파일을 작성한 뒤 명령 한 번으로 새 n8n 인스턴스를 시작합니다.
curl -fsSL https://get.n8n.io | sh
이미 자체 Docker Compose 파일을 실행하고 있다면 전환할 필요가 없습니다. 팀 또는 프로덕션 인스턴스라면 Docker Compose를 사용하여 설치에서 내장 SQLite 데이터베이스 대신 Postgres로 n8n을 실행하는 방법을 확인하세요.
커뮤니티 노드 개발#
노드 설명에서 defaults.color 제거#
n8n 3.0은 노드 설명 유형에서 더 이상 사용되지 않는 defaults.color 속성을 제거합니다. 이 속성은 Font Awesome 아이콘(icon: 'fa:...')에만 색을 입혔습니다. 이 속성을 여전히 설정한 커뮤니티 노드는 계속 작동하지만, 에디터에는 Font Awesome 아이콘이 중립 색상으로 표시됩니다. n8n은 파일 아이콘에 색을 입히지 않으므로 파일 아이콘(icon: 'file:...')을 사용하는 노드는 영향을 받지 않습니다.
해야 할 일: defaults.color를 제거하세요. 노드가 Font Awesome 아이콘을 사용한다면 표준 매개변수 참조에서 권장하는 대로 SVG 또는 PNG 파일 아이콘으로 교체하세요.
나머지 변경은 n8n-node dev의 테스트 루프에만 영향을 줍니다. n8n-node build, n8n-node lint, n8n-node release, npm create @n8n/node는 변경되지 않습니다.
n8n-node dev에 Docker 또는 Podman 필요#
n8n-node dev는 기존에 npx n8n@latest로 n8n을 시작했습니다. n8n 3.0은 npm에 실행 가능한 n8n 패키지를 게시하지 않으므로, 이 명령은 이제 컨테이너에서 공식 이미지를 실행합니다.
해야 할 일: 기본 컨테이너 경로를 사용하려면 Docker 또는 Podman을 설치하세요. 외부에서 관리하는 인스턴스를 대신 사용하려면 n8n-node dev --external-n8n을 실행하고 해당 인스턴스를 N8N_DEV_RELOAD=true로 시작하세요. 컨테이너 경로에서 버전을 고정하려면 태그를 지정하세요. n8n-node dev --n8n-image docker.n8n.io/n8nio/n8n:<n8n-version>. 핫 리로드는 POST /rest/dev/reload를 제공하는 이미지에서만 작동하므로, 이전 태그에서는 노드가 로드되지만 변경 사항을 적용하려면 다시 시작해야 합니다.
n8n-node dev 테스트 데이터가 이미지별 컨테이너 볼륨으로 이동#
노드를 테스트하면서 만든 워크플로와 자격 증명은 이제 ~/.n8n-node-cli/.n8n이 아니라 n8n-node-cli-data-<image> 컨테이너 볼륨에 저장됩니다. n8n은 데이터베이스를 앞으로만 마이그레이션하므로 --n8n-image마다 별도 볼륨이 할당됩니다. 이미지를 바꾸면 이전 n8n 버전이 읽을 수 없는 데이터베이스 대신 빈 인스턴스가 생깁니다.
이전 버전의 테스트 데이터는 넘어오지 않습니다
CLI를 업그레이드하거나 이미지를 변경하기 전에 보관하려는 테스트 워크플로를 내보내세요.
해야 할 일: 보관하려는 테스트 워크플로를 내보내세요. 볼륨을 나열하고 재설정하려면 docker volume ls --filter name=n8n-node-cli-data 및 docker volume rm <volume> 또는 이에 해당하는 podman 명령을 사용하세요.
--custom-user-folder는 --external-n8n과 함께만 적용#
이 플래그는 예전에 CLI가 노드를 연결할 위치를 지정하는 데 사용됐습니다. 이제는 직접 실행하는 인스턴스의 N8N_USER_FOLDER를 지정하며, 컨테이너 모드에서는 아무 효과가 없습니다.
해야 할 일: --custom-user-folder를 전달하는 경우 --external-n8n을 추가하고, 동일한 N8N_USER_FOLDER로 해당 인스턴스를 시작하세요.
제거된 노드 및 헬퍼#
n8n 3.0은 새로운 패턴으로 대체된 이전 노드, 모드 및 헬퍼를 제거합니다.
제거된 노드#
제거된 노드를 사용하는 워크플로는 실행할 때 실패합니다. 이러한 워크플로가 게시된 상태라면 n8n 3.0이 시작될 때 활성화되지 않으므로 트리거가 더 이상 실행되지 않습니다. 업그레이드하기 전에 Settings > Migration Report에서 인스턴스의 영향을 받는 워크플로를 확인할 수 있으며, 사용 중단 및 버전별 노드 페이지에서 여기에 나열된 모든 노드의 최종 버전을 확인할 수 있습니다.
- Function 노드(레거시)
- Function Item 노드(레거시)
- Item Lists 노드(레거시)
- LangChain Code 노드(레거시)
- Cron 및 Interval 노드
- HTML Extract 노드
- iCalendar 노드
- Convert to/from binary data 노드
- Read Binary File, Read Binary Files, Write Binary File 노드
- Read PDF 노드
- Workflow Trigger 노드
- Orbit 노드
- OpenAI 노드(레거시). AI 섹션의 현재 OpenAI 노드는 유지됩니다.
- OpenAI Assistant 및 OpenAI Model 노드
- HTTP Request Tool 노드(레거시). HTTP Request 노드를 도구로 사용하는 방식은 유지됩니다.
- SerpApi (Google Search) 노드
- Manual Chat Trigger 노드
- Chat Messages Retriever 노드
- Motorhead 및 Zep 메모리 노드
- Binary Input Loader, JSON Input Loader, GitHub Document Loader 노드
- In Memory Vector Store Insert, In Memory Vector Store Load, Pinecone: Insert, Pinecone: Load, Supabase: Insert, Supabase: Load, Zep Vector Store, Zep Vector Store: Insert, Zep Vector Store: Load 노드
- AI Transform 노드: 더 이상 AI Transform 노드를 추가하거나 실행할 수 없습니다. 기존 노드가 계속 작동하게 하려면 Settings > Migration Report에서 Code 노드로 마이그레이션하세요. 마이그레이션은 생성된 JavaScript를 그대로 유지하므로 워크플로가 동일한 코드를 실행합니다. n8n은 업그레이드 시 이러한 노드를 자동으로 마이그레이션하지 않습니다. 코드를 생성한 적이 없는 AI Transform 노드는 보고서에서 마이그레이션할 수 없으므로 Code 노드로 직접 교체하세요.
- 해야 할 일: 업그레이드하기 전에 영향을 받는 워크플로를 현재 권장되는 대안으로 마이그레이션하세요.
- Function 및 Function Item 노드를 Code 노드로 교체합니다. Function 대신 Run Once for All Items 모드를 사용하고, Function Item 대신 Run Once for Each Item 모드를 사용합니다.
- Item Lists 노드를 사용 중인 작업에 맞는 노드로 교체합니다. Split Out, Aggregate, Sort, Limit, Remove Duplicates 또는 Summarize를 사용합니다.
- Cron 및 Interval을 Schedule Trigger 노드로 교체합니다.
- HTML Extract를 HTML 노드의 Extract HTML Content 작업으로 교체합니다.
- iCalendar를 Convert to File 노드의 Convert to ICS 작업으로 교체합니다.
- Convert to/from binary data를 Convert to File 또는 Extract from File 노드로 교체합니다.
- Read Binary File, Read Binary Files, Write Binary File을 Read/Write Files from Disk 노드로 교체합니다.
- Read PDF를 Extract from File 노드의 Extract From PDF 작업으로 교체합니다.
- Workflow Trigger를 n8n Trigger 노드로 교체합니다.
- 레거시 OpenAI 노드와 OpenAI Assistant 노드를 OpenAI 노드로 교체합니다. 어시스턴트에는 이 노드의 Assistant 리소스를 사용합니다.
- OpenAI Model을 OpenAI Chat Model 노드로 교체합니다.
- 레거시 HTTP Request Tool을 AI Agent 노드의 Tool 입력에 연결한 HTTP Request 노드로 교체합니다.
- Manual Chat Trigger를 Chat Trigger 노드로 교체합니다.
- Chat Messages Retriever를 Chat Memory Manager 노드로 교체하거나, Chat Trigger 노드에서 이전 세션을 불러옵니다.
- Binary Input Loader, JSON Input Loader, GitHub Document Loader를 Default Data Loader 노드로 교체합니다. GitHub 콘텐츠는 먼저 GitHub 노드로 가져옵니다.
- Insert 및 Load 벡터 스토어 노드를 해당 스토어의 단일 노드인 Simple Vector Store, Pinecone Vector Store 또는 Supabase Vector Store로 교체합니다. 노드에서 작업(Insert Documents, Get Many, Retrieve Documents)을 선택합니다.
- **LangChain Code**에는 직접적인 대체 노드가 없습니다.
- Motorhead, Zep, Zep Vector Store 노드에는 직접적인 대체 노드가 없습니다. 지원되는 다른 메모리 또는 벡터 스토어 노드를 사용하세요.
- **SerpApi (Google Search)**에는 직접적인 대체 노드가 없습니다. 도구로 연결한 HTTP Request 노드로 SerpApi REST API를 호출하거나, 확인된 커뮤니티 노드를 사용하세요.
- Orbit에는 대체 노드가 없습니다. Orbit 서비스가 종료되었습니다.
제거된 표현식 헬퍼#
n8n 3.0은 더 이상 사용되지 않는 $getPairedItem 표현식 헬퍼를 제거합니다. 이 헬퍼를 여전히 호출하는 표현식은 노드가 실행될 때 실패합니다.
해야 할 일: 대신 n8n의 표준 항목 연결을 사용하세요. $getPairedItem은 세 가지 형태로 대체됩니다.
$('<node-name>').item은 현재 항목이 연결된<node-name>의 항목을 반환합니다.$('<node-name>').itemMatching(<item-index>)는<item-index>의 입력 항목이 연결된<node-name>의 항목을 반환합니다.$('<node-name>').pairedItem(<item-index>)는<item-index>의 페어링된 항목을 직접 반환합니다.
Execute Sub-workflow 노드: Local File 및 URL 소스 제거#
n8n 3.0은 Execute Sub-workflow 노드의 Source 매개변수에서 Local File 및 URL 옵션을 제거합니다. 이 옵션은 노드 버전 1.1 이하에서만 제공되었습니다. 이러한 소스를 여전히 사용하는 노드는 오류와 함께 실패합니다.
해야 할 일: 하위 워크플로를 인스턴스로 가져와 Database 소스로 선택하거나, Define Below 소스(노드 버전 1.1 이하에서는 Parameter)로 JSON을 붙여 넣으세요. 업그레이드하기 전에 Settings > Migration Report에서 영향을 받는 노드를 확인하세요.
Code 노드에서 $evaluateExpression() 제거#
n8n 3.0은 Code 노드(JavaScript)에서 $evaluateExpression() 편의 메서드를 제거합니다. 안전하지 않은 모드(N8N_RUNNERS_INSECURE_MODE=true)의 태스크 러너만 영향을 받습니다. n8n 2.0부터 기본값인 보안 모드 러너에서는 이미 이 호출이 실패합니다.
해야 할 일: 대신 노드 필드에서 표현식을 평가하세요. 예를 들어 Code 노드 앞의 Edit Fields (Set) 노드에서 평가한 후 입력 항목에서 결과를 읽습니다. $evaluateExpression()은 {{ }} 표현식 필드에서 계속 작동합니다.
AI Agent 노드: 이전 에이전트 모드 제거#
AI Agent 노드의 버전 1은 SQL Agent, Conversational Agent, OpenAI Functions Agent, Plan and Execute Agent, ReAct Agent를 포함한 여러 에이전트 유형 모드를 지원했습니다. n8n 3.0에서는 이러한 모드와 함께 노드 버전 1을 제거합니다.
해야 할 일: AI Agent 노드의 버전 1을 사용하는 모든 워크플로와 템플릿을 최신 버전으로 업데이트하세요. 최신 버전은 제거된 모든 모드를 Tools Agent로 대체하며, 이미 Tools Agent로 설정된 워크플로는 업데이트 후에도 동일하게 작동합니다. SQL Agent 사용 사례에는 최신 AI Agent 노드와 함께 Postgres 또는 MySQL 도구 서브 노드를 사용하세요.
Edit Image 노드: 노드 버전 1 및 1.1 제거#
n8n 3.0은 Edit Image 노드의 더 이상 사용되지 않는 노드 버전 1과 1.1 지원을 제거합니다. 이 버전을 여전히 사용하는 워크플로는 노드를 업그레이드할 때까지 오류와 함께 실패합니다.
노드 버전 2는 다른 이미지 처리 라이브러리를 사용하므로 이미지 출력이 달라질 수 있습니다. 마이그레이션은 블러 설정을 변환하지만 Sigma는 제거합니다. 텍스트 배치가 달라질 수 있습니다. Get Information은 정규화된 결과를 반환합니다. PNG와 TIFF 출력은 Quality 설정을 무시합니다. 크기가 0이거나 음수인 크기 조정 작업은 실패합니다.
해야 할 일: 업그레이드하기 전에 Settings > Migration Report로 이동하여 영향을 받는 워크플로를 확인하세요. 보고서에서 마이그레이션하거나, 각 Edit Image 노드를 노드 버전 2로 직접 업데이트하세요. 그런 다음 출력을 테스트하세요. 특히 이미지를 블러 처리하거나 크기를 조정하는 워크플로, 텍스트를 추가하는 워크플로, 이미지 정보를 읽는 워크플로, PNG 또는 TIFF 품질을 설정하는 워크플로를 테스트하세요.
동작 변경#
n8n 3.0은 일부 노드와 자격 증명의 동작을 변경합니다. 이러한 노드는 계속 사용할 수 있지만 기존 워크플로의 결과가 달라질 수 있습니다.
여러 출력이 있는 노드의 Always Output Data#
**Always Output Data**가 켜져 있으면 If 및 Switch처럼 여러 출력을 가진 노드는 이제 모든 출력이 비어 있을 때만 빈 항목을 추가합니다. 이전에는 각 빈 출력에 빈 항목이 추가되어 실행되지 않아야 할 브랜치가 실행됐습니다.
해야 할 일: 업그레이드하기 전에 Settings > Migration Report에서 이 변경의 영향을 받는 노드를 확인하세요. 각 노드를 검토하고 의도에 맞게 설정을 조정하세요.
Gmail Trigger 노드: 이전 버전은 버전 1.4로 실행#
n8n 3.0은 Gmail Trigger 노드 버전 1~1.3의 별도 동작을 제거합니다. 이 버전을 사용하는 워크플로는 계속 로드되지만 노드는 버전 1.4 동작으로 실행됩니다.
- Max Emails per Poll이 모든 폴링에 적용됩니다. 기본값은 이메일 10개이며 최대 50개까지 설정할 수 있습니다. 나머지 이메일은 이후 폴링에서 가져옵니다.
- Include Drafts 필터를 켜지 않으면 노드가 임시 보관 메일을 건너뜁니다. 버전 1과 1.1은 기본적으로 임시 보관 메일을 포함했습니다.
- 받은편지함에 없는 보낸 이메일과 예약 이메일은 더 이상 워크플로를 트리거하지 않습니다.
해야 할 일: 버전 1.4 미만의 Gmail Trigger 노드가 있는 워크플로를 검토하세요. 업그레이드하기 전에 Settings > Migration Report에서 영향을 받는 노드를 확인하세요. 워크플로가 임시 보관 메일에 의존한다면 Include Drafts를 켜세요. 워크플로가 보낸 이메일이나 예약 이메일에 의존한다면, 트리거를 Schedule Trigger 노드로 교체하고 그 뒤에 Gmail 노드의 Get Many 메시지 작업을 연결하세요.
Webflow OAuth2 자격 증명: Legacy 토글 기본값 꺼짐#
Webflow OAuth2 API 자격 증명의 Legacy 토글 기본값이 꺼짐입니다. 새 자격 증명은 Webflow v2 API 범위(cms:read cms:write sites:read forms:read)를 요청합니다. Legacy 값을 명시적으로 저장한 적이 없는 기존 자격 증명은 다음에 다시 연결할 때 이 범위를 요청합니다. 연결된 자격 증명은 계속 작동합니다. n8n은 저장된 토큰을 건드리지 않으며, 토큰 갱신 시에는 범위를 전송하지 않습니다.
해야 할 일: 레거시 Webflow OAuth 앱이나 버전 1의 Webflow 노드처럼 더 이상 사용되지 않는 Webflow v1 Data API를 여전히 사용한다면, 자격 증명을 다시 연결하기 전에 Legacy를 켜세요. 요청한 범위가 앱에 구성되어 있지 않으면 Webflow가 연결을 거부합니다.
Chat Trigger 노드: WebSocket 메시지는 JSON 프레임#
Chat Trigger 노드가 Using Response Nodes 응답 모드(Chat 노드가 응답을 보내는 모드)에서 사용하는 채팅 WebSocket 엔드포인트는 이제 모든 프레임을 type 필드가 있는 JSON 객체로 보냅니다. type은 heartbeat, continue, error, message, with-buttons 중 하나입니다. 이전에는 제어 프레임과 일반 텍스트 응답이 원시 문자열이었습니다. 이제 텍스트 응답은 { "type": "message", "text": "..." }입니다. 클라이언트는 { "type": "heartbeat-ack" }로 하트비트에 응답하며, n8n은 JSON이 아닌 수신 프레임을 무시합니다.
n8n 채팅 위젯(@n8n/chat)은 버전 1.31.0부터 두 형식을 모두 이해하며, 호스팅된 채팅 페이지는 항상 최신 위젯을 로드합니다.
해야 할 일: 채팅 WebSocket과 직접 통신하는 사용자 지정 채팅 클라이언트를 만들었다면 모든 프레임을 JSON으로 파싱하고 type에 따라 분기하세요. @n8n/chat을 직접 임베드한다면 n8n을 업그레이드하기 전에 버전 1.31.0 이상으로 업데이트하세요.
보안#
기본적으로 n8n을 더 안전하게 만들기 위해 보안 기본값이 강화됩니다. 이러한 변경은 기존 워크플로 또는 자격 증명에 영향을 줄 수 있습니다.
기본적으로 암호화 키 순환 활성화#
n8n 3.0은 암호화 키 순환을 기본적으로 켭니다. 이전에는 셀프 호스팅 인스턴스가 이 기능을 직접 옵트인해야 했습니다. 기능이 켜지면 n8n은 Settings > Data Encryption Keys에서 순환할 수 있는 데이터 암호화 키를 유지합니다. 업그레이드 전에 암호화된 자격 증명과 기타 데이터는 계속 읽을 수 있으며, n8n은 각 레코드를 다음에 업데이트할 때 현재 키로 다시 암호화합니다.
이 기능을 켜는 것은 이전에는 되돌릴 수 없었습니다. n8n 2.40.3부터는 다시 끌 수 있습니다.
해야 할 일: 없습니다. 다른 업그레이드와 마찬가지로 먼저 데이터베이스를 백업하세요.
Slack API 자격 증명에 서명 시크릿 필요#
n8n 3.0은 Slack API 자격 증명에 서명 시크릿을 필수로 요구합니다. Slack Trigger 노드는 이를 기준으로 수신 요청을 검증합니다. Slack Trigger 노드가 있는 워크플로를 게시하거나 n8n이 시작될 때 n8n은 자격 증명을 확인하며, 시크릿이 없으면 활성화를 중단합니다.
조치가 필요한 시점은 자격 증명을 사용하는 방식에 따라 다릅니다.
- Slack Trigger 노드가 있는 워크플로: 업그레이드하기 전에 시크릿을 추가하세요. 추가하기 전까지는 워크플로 게시가 실패합니다. 이미 게시된 워크플로는 업그레이드 후 활성화되지 않으며 이벤트 수신을 중단합니다.
- 그 밖의 모든 Slack 워크플로: 다음에 자격 증명을 편집할 때 시크릿을 추가하세요.
업그레이드하기 전에 시크릿을 추가하세요
Slack API 자격 증명에 서명 시크릿이 있을 때까지 Slack Trigger 노드가 있는 워크플로는 이벤트를 수신하지 못합니다.
해야 할 일:
- Slack 앱 설정에서 Basic Information을 열고 Signing Secret을 복사합니다.
- n8n의 Slack API 자격 증명의 Signature Secret 필드에 붙여 넣습니다.
- 워크플로를 다시 게시합니다.
더 커진 기본 SSRF 차단 목록#
N8N_SSRF_PROTECTION_ENABLED가 true이고 N8N_SSRF_BLOCKED_IP_RANGES에 default가 포함된 경우, n8n 3.0은 기본 제공 기본 목록에 네 가지 범위를 추가합니다.
| 범위 | 설명 |
|---|---|
::/128 |
IPv6 미지정 주소 |
100.64.0.0/10 |
공유 주소 공간(통신사급 NAT) |
2002::/16 |
6to4 |
64:ff9b::/96 |
NAT64 잘 알려진 프리픽스 |
이 범위의 호스트에 대한 요청은 실패합니다.
해야 할 일: 워크플로가 이 범위의 호스트를 호출한다면 해당 IP 범위를 N8N_SSRF_ALLOWED_IP_RANGES에 추가하거나 호스트 이름을 N8N_SSRF_ALLOWED_HOSTNAMES에 추가하세요. N8N_SSRF_BLOCKED_IP_RANGES에서는 default를 유지하세요. 이는 localhost, 사설 네트워크, 클라우드 메타데이터 엔드포인트를 포함한 기본 제공 전체 목록의 키워드입니다. 리터럴 범위로 바꾸면 현재 기본 제공 목록의 모든 범위를 직접 나열해야 합니다. SSRF 보호 활성화와 SSRF 보호 환경 변수를 참조하세요.
Compression 노드의 더 낮은 압축 해제 한도#
기본 N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES가 2 GiB에서 256 MiB로 낮아지고, 기본 N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES가 5,000에서 1,000으로 낮아집니다. Compression 노드는 두 한도 중 하나라도 초과하는 아카이브에서 실패합니다.
해야 할 일: 워크플로에서 256 MiB보다 크거나 항목이 1,000개를 초과하는 아카이브의 압축을 해제하는 경우, n8n 3.0으로 업그레이드하기 전에 이 변수를 이전 값(2147483648 및 5000)으로 명시적으로 설정하세요. 노드 환경 변수 참조를 확인하세요.
구성#
n8n 3.0은 이전 동작만 유지하던 일부 기본값을 변경하고 설정을 제거합니다. 해당 인스턴스에 영향을 주는 각 항목에 대해 n8n은 2.x에서 시작 시 더 이상 사용되지 않음을 알리는 경고를 로그에 기록합니다.
N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION 제거#
n8n 3.0은 N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION 환경 변수를 제거합니다. workflow.preExecute 외부 훅이 예외를 발생시키면 n8n은 실행 레코드를 만들지 않습니다. 실행이 시작되지 않으므로 Insights나 라이선스 사용량에도 집계되지 않습니다. 이전 동작을 유지할 방법은 없습니다.
해야 할 일: 훅이 예외를 발생시켜도 실패한 실행을 기록하도록 N8N_PRE_EXECUTE_ERROR_CREATES_EXECUTION=true를 설정해 사용했다면, n8n 3.0으로 업그레이드하기 전에 이 변수를 제거하세요. 업그레이드 후 n8n은 이 변수를 무시합니다. 이렇게 기록되던 실패한 실행 레코드를 알림에 활용했다면, 알림을 외부 훅 자체로 옮기세요. 업그레이드하기 전에 Settings > Migration Report에서 이 인스턴스에 변수가 설정되어 있는지 확인할 수 있습니다.
스토리지 디렉터리 이름 변경#
첫 시작 시 n8n 3.0은 ~/.n8n/binaryData를 ~/.n8n/storage로 이름을 바꾸고 N8N_MIGRATE_FS_STORAGE_PATH를 제거합니다.
두 디렉터리가 모두 있으면 n8n이 시작하지 않습니다
~/.n8n/binaryData와 ~/.n8n/storage가 모두 있으면 n8n 3.0은 어느 쪽을 사용할지 추측하지 않고 오류와 함께 중단됩니다.
해야 할 일: ~/.n8n/binaryData에 볼륨을 마운트했다면 대신 ~/.n8n/storage에 마운트하거나, 기존 경로를 유지하려면 N8N_STORAGE_PATH를 이전 경로로 설정하세요. 두 디렉터리가 모두 있으면 ~/.n8n/binaryData의 콘텐츠를 ~/.n8n/storage로 옮기고 ~/.n8n/binaryData를 제거한 후 n8n을 다시 시작하세요. 볼륨 마운트 없이 기본 경로를 사용한다면 조치할 필요가 없습니다. 바이너리 데이터 처리를 참조하세요.
메모리 내 바이너리 데이터 모드 제거#
N8N_DEFAULT_BINARY_DATA_MODE=default는 더 이상 유효하지 않습니다. 이를 계속 사용하는 인스턴스는 업그레이드 시 filesystem으로 전환됩니다.
해야 할 일: N8N_DEFAULT_BINARY_DATA_MODE를 filesystem, s3, azure, 또는 database로 설정하고 컨테이너의 마운트된 디스크에 바이너리 데이터를 저장할 여유 공간이 있는지 확인하세요. 바이너리 데이터 환경 변수 참조를 확인하세요.
변경된 기본값 및 제거된 변수#
- 확인되지 않은 커뮤니티 패키지가 기본적으로 비활성화됩니다.
N8N_UNVERIFIED_PACKAGES_ENABLED의 기본값이true에서false로 바뀝니다. 업그레이드 후에는 npm에서 확인되지 않은 커뮤니티 노드를 설치할 수 없고, 설치된 노드도 더 이상 로드되지 않습니다.- 해야 할 일: npm에서 확인되지 않은 커뮤니티 노드를 계속 설치하려면
N8N_UNVERIFIED_PACKAGES_ENABLED=true를 설정하거나, 확인된 커뮤니티 노드로 이전하세요.
- 해야 할 일: npm에서 확인되지 않은 커뮤니티 노드를 계속 설치하려면
- 태스크 러너 타임아웃이 짧아집니다.
N8N_RUNNERS_TASK_TIMEOUT의 기본값이300(5분)에서60(1분)으로 낮아집니다. 더 오래 실행되는 Code 노드 태스크는 실패합니다.- 해야 할 일: 태스크에 1분 이상이 필요하다면
N8N_RUNNERS_TASK_TIMEOUT을 명시적으로 설정하세요. 태스크 러너 환경 변수를 참조하세요.
- 해야 할 일: 태스크에 1분 이상이 필요하다면
- 큐 모드에서는 수동 실행이 항상 워커에서 실행됩니다.
OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS가 제거됩니다.- 해야 할 일: 변수를 제거하세요. 이제 수동 실행도 처리하는 워커에 제공하는 메모리를 검토하세요. 큐 모드 활성화를 참조하세요.
N8N_DB_PING_TIMEOUT제거. n8n은 더 이상 이 변수로 대체하지 않습니다.- 해야 할 일: 대신
DB_PING_TIMEOUT_MS를 설정하세요. 데이터베이스 환경 변수를 참조하세요.
- 해야 할 일: 대신
N8N_WORKFLOW_TAGS_DISABLED제거. 워크플로 태그는 항상 켜져 있으며 n8n은 이 변수를 무시합니다. 태그가 꺼져 있는 동안에도 n8n은 태그 데이터를 유지했으므로, 업그레이드 후 기존 태그가 에디터와 API에 다시 표시됩니다.- 해야 할 일: 구성에서 변수를 제거하세요.
종료되는 기능#
n8n 3.0에서는 일부 레거시 또는 사용량이 적은 제품 기능을 종료합니다. 마이그레이션 경로 또는 대안이 있는 경우 n8n에서 가이드를 제공합니다.
- Chat Hub: n8n 3.0은 기본적으로 Chat Hub 모듈을 끕니다. 내비게이션에서 Chat 섹션이 사라지고 Chat Hub 엔드포인트가 응답하지 않습니다. 채팅 세션, 에이전트, 메시지는 데이터베이스에 유지됩니다. n8n 4.0에서 이 기능이 제거됩니다.
- 해야 할 일: 여전히 Chat Hub가 필요하다면
N8N_ENABLED_MODULES환경 변수에chat-hub를 추가하세요. 이 변수는 쉼표로 구분한 목록이므로 이미 활성화한 모듈은 유지해야 합니다. 예:N8N_ENABLED_MODULES=agents,chat-hub. 이렇게 하면 n8n 3.x 라인에서만 Chat Hub를 계속 사용할 수 있고, n8n은 시작 시 더 이상 사용되지 않음을 알리는 경고를 출력합니다. 업그레이드하기 전에 Settings > Migration Report에서 Chat Hub를 사용하는 모든 인스턴스에 이 변경이 미치는 영향을 확인하세요.
- 해야 할 일: 여전히 Chat Hub가 필요하다면
- 편집기에서 URL로 워크플로 가져오기: n8n 3.0에서는 이를 제거합니다. 에디터 UI 메뉴에서 Import from URL 옵션이 사라집니다.
- 해야 할 일: 다른 가져오기 방법을 사용하세요. 복사하여 붙여넣기, 에디터 UI 메뉴의 Import from File, CLI, n8n API가 이에 해당합니다. URL에서 가져오기를 자동화했다면 HTTP Request 노드로 워크플로 JSON을 가져온 뒤 n8n API로 워크플로를 만드세요.
- 프로젝트 역할에 외부 시크릿 허용 설정: n8n 3.0에서는 이를 제거합니다. 이제 프로젝트 편집자와 관리자는 기본적으로 프로젝트에서 외부 시크릿에 접근할 수 있습니다. 이는 외부 시크릿을 사용할 수 있는 n8n Enterprise에 적용됩니다.
- 해야 할 일: 이 설정으로 외부 시크릿에 접근할 수 있는 프로젝트 역할을 제한했다면, 업그레이드하기 전에 원하는 접근 권한을 가진 사용자 지정 프로젝트 역할을 만드세요. 그렇지 않으면 업그레이드 시 모든 프로젝트 편집자와 관리자가 외부 시크릿에 접근할 수 있게 됩니다.
- Code 노드의 Ask AI 탭: n8n 3.0에서는 Code 노드에서 Ask AI 탭을 제거합니다. 이미 이 탭으로 생성한 코드는 노드에 그대로 남아 계속 실행됩니다.
- 해야 할 일: Code 탭에서 JavaScript 또는 Python을 직접 작성하세요.