n8n 2.0이 출시되며 몇 가지 중요한 변경이 함께 적용되었습니다. 이 문서는 호환성을 깨는 변경과 전환을 준비하기 위해 해야 할 작업을 정리합니다. 이번 업데이트는 보안을 강화하고, 구성을 단순화하며, 오래된 기능을 제거합니다.

n8n 2.0 출시는 안전하고 신뢰할 수 있으며 프로덕션 준비가 된 자동화 플랫폼을 제공하겠다는 n8n의 방향을 이어가는 것입니다. 이 메이저 버전에는 중요한 보안 강화와 더 이상 사용되지 않는 기능의 정리가 담겨 있습니다.

동작 변경#

서브 워크플로가 대기 상태에서 재개될 때 기대하는 서브 워크플로 데이터 반환(웹훅, 폼, HITL 등 대기)#

이전에는 실행(부모)이 서브 실행(자식)을 호출하고, 서브 실행 안에 서브 실행을 대기 상태로 만드는 노드가 있으며, 부모 실행이 서브 실행의 완료를 기다리도록 설정된 경우, 부모 실행은 잘못된 결과를 받았습니다.

대기 상태에 들어가는 경우는 예를 들어 서브 실행에 타임아웃이 65초보다 긴 Wait node가 있거나, 웹훅 호출이나 폼 제출이 있거나, 슬랙 노드 같은 human-in-the-loop 노드가 있을 때입니다.

부모 워크플로:

서브 워크플로:

n8n 1.0: 부모 실행은 서브 실행의 입력을 그대로 출력으로 재생성합니다.:

n8n 2.0: 부모 실행은 자식 실행의 결과를 받습니다:

이 덕분에 서브 워크플로에서 human-in-the-loop 노드를 쓰고, 그 결과(예: 작업 승인 또는 거부)를 부모 워크플로에서 활용할 수 있습니다.

마이그레이션 경로: 서브 워크플로를 호출하고 서브 워크플로의 입력을 받기를 기대하는 워크플로를 검토하세요. 부모 워크플로가 자식 워크플로 끝단의 출력을 받는 새 동작에 맞게 워크플로를 수정해야 합니다.

Start node 제거#

Start node는 더 이상 지원되지 않습니다. 워크플로를 시작하는 원래 방식이었지만, 지금은 더 구체적인 트리거 노드가 그 역할을 대신합니다.

마이그레이션 경로: 워크플로를 어떻게 쓰는지에 따라 Start node를 대체하세요:

• 수동 실행: Start node를 Manual Trigger node로 바꾸세요.
• 서브 워크플로: 다른 워크플로가 이 워크플로를 서브 워크플로로 호출한다면, Start node를 Execute Workflow Trigger node로 바꾸고 워크플로를 활성화하세요.
• 비활성화된 Start node: Start node가 비활성화되어 있다면 워크플로에서 삭제하세요.

워크플로 저장 및 게시#

새로운 워크플로 게시(publishing) 시스템이 기존의 active/inactive 토글을 대체합니다. 기존 "Activate/Deactivate" 토글은 새 "게시/게시 취소" 버튼이 됩니다. 이 변경으로 워크플로 변경 사항이 실제로 적용되는 시점을 더 잘 제어할 수 있어, 진행 중인 작업을 실수로 프로덕션에 배포할 위험이 줄어듭니다. 자세한 내용은 워크플로 저장 및 게시에서 확인할 수 있습니다.

중단된 서비스의 노드 제거#

연결하는 외부 서비스를 더 이상 이용할 수 없어서 다음 노드들이 제거되었습니다:

• Spontit node
• crowd.dev node
• Kitemaker node
• Automizy node

마이그레이션 경로: 워크플로에서 이 노드들을 사용 중이라면 오류를 피하기 위해 워크플로를 수정하거나 제거하세요.

보안#

Code node의 환경 변수 접근 기본 차단#

보안 강화를 위해 n8n은 기본적으로 Code node의 환경 변수 접근을 차단합니다. N8N_BLOCK_ENV_ACCESS_IN_NODE의 기본값이 이제 true로 설정됩니다.

마이그레이션 경로: 워크플로에서 Code node의 환경 변수 접근이 필요하면 환경 구성에 N8N_BLOCK_ENV_ACCESS_IN_NODE=false를 설정하세요. 민감한 데이터는 환경 변수 대신 자격 증명이나 다른 안전한 방법을 사용하세요.

설정 파일 권한 강제#

n8n은 보안을 위해 구성 파일에 엄격한 파일 권한을 요구하게 됩니다. 기본적으로 구성 파일은 0600 권한을 사용해야 하며, 파일 소유자만 읽고 쓸 수 있습니다. 이 방식은 SSH가 개인키를 보호하는 방식과 비슷합니다.

마이그레이션 경로: n8n 2.0 전에 이 동작을 테스트하려면 N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true를 설정하세요. 환경에서 파일 권한을 지원하지 않는 경우(예: Windows)에는 N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=false를 설정해 이 요구를 끄세요.

태스크 러너 기본 활성화#

n8n은 보안과 격리를 강화하기 위해 태스크 러너를 기본으로 활성화합니다. 모든 Code node 실행은 태스크 러너에서 실행됩니다.

마이그레이션 경로: n8n 2.0으로 업그레이드하기 전에 N8N_RUNNERS_ENABLED=true를 설정해 이 동작을 테스트하세요. 인프라가 태스크 러너 실행 요구 사항을 충족하는지 확인하세요. 보안을 더 강화하려면 외부 모드 사용을 고려하세요.

Code node에서 $evaluateExpression이 더 이상 작동하지 않음#

Code node 실행이 이제 기본적으로 보안 모드의 태스크 러너에서 실행되므로, Code node 안에서 $evaluateExpression() 편의 메서드는 더 이상 작동하지 않습니다. 보안 모드는 문자열을 코드로 평가하는 기능을 끄는데, 표현식이 바로 이 메커니즘에 의존하기 때문입니다. 따라서 Code node에서 $evaluateExpression()을 호출하면 null이나 오류를 반환합니다. Edit Fields (Set) node 같은 일반 노드 필드의 표현식은 영향을 받지 않습니다.

마이그레이션 경로: 표현식 평가를 Code node 밖으로 옮기세요. 우선순위는 다음과 같습니다:

• $evaluateExpression()을 호출하는 대신 로직을 JavaScript로 직접 작성하세요.
• Code node 이전의 Edit Fields (Set) node에서 표현식을 평가한 뒤, 들어오는 아이템에서 결과를 읽으세요.
• 다른 방법이 없으면 N8N_RUNNERS_INSECURE_MODE=true를 설정해 꺼진 JavaScript 기능을 다시 켜세요. 이렇게 하면 태스크 러너의 보안 조치가 꺼지며, 프로덕션에서 사용하는 것은 권장하지 않습니다.

Code node에서 $evaluateExpression()은 향후 버전에서 완전히 제거될 수 있으므로, N8N_RUNNERS_INSECURE_MODE=true는 임시 해결책으로만 보고 영구적인 대책으로 삼지 마세요.

n8nio/n8n Docker 이미지에서 태스크 러너 제거#

n8n 2.0부터 메인 n8nio/n8n Docker 이미지에는 외부 모드용 태스크 러너가 포함되지 않습니다. 외부 모드로 태스크 러너를 실행하려면 별도의 n8nio/runners Docker 이미지를 사용해야 합니다.

마이그레이션 경로: Docker에서 외부 모드로 태스크 러너를 실행 중이라면, n8nio/n8n 대신 n8nio/runners 이미지를 쓰도록 설정을 바꾸세요.

Pyodide 기반 Python Code node 및 도구 제거#

n8n은 Pyodide 기반 Python Code node와 도구를 제거하고, 네이티브 Python을 쓰는 태스크 러너 기반 구현으로 대체합니다. 보안과 성능이 더 좋아집니다. n8n 2.0부터는 Python Code node는 외부 모드의 태스크 러너와 네이티브 Python 도구와 함께만 사용할 수 있습니다.

네이티브 Python Code node는 Pyodide 기반 버전에서 쓸 수 있던 _input 같은 내장 변수나 점 접근 표기법(dot access notation)을 지원하지 않습니다. 자세한 내용은 Code node 문서를 참조하세요.

네이티브 Python 도구는 AI 에이전트가 도구를 호출할 때 전달하는 입력 문자열에 대해 _query를 지원합니다.

마이그레이션 경로: Code node에서 Python을 계속 쓰려면 외부 모드로 태스크 러너를 설정하고, 기존 Python Code node와 도구의 호환성을 검토하세요.

ExecuteCommand 및 LocalFileTrigger node 기본 비활성화#

n8n은 보안 위험이 있어 ExecuteCommand와 LocalFileTrigger node를 기본적으로 비활성화합니다. 이 노드들은 임의의 명령 실행과 파일 시스템 접근을 허용합니다.

마이그레이션 경로: 이 노드들이 필요하면 NODES_EXCLUDE 환경 변수를 바꿔 n8n 구성의 비활성화된 노드 목록에서 제거하세요. 예를 들어 NODES_EXCLUDE="[]"로 설정하면 모든 노드를 활성화하고, 필요한 노드만 골라 제거할 수도 있습니다.

OAuth 콜백 URL에 기본으로 인증 요구#

n8n은 기본적으로 OAuth 콜백 엔드포인트에 인증을 요구하게 됩니다. N8N_SKIP_AUTH_ON_OAUTH_CALLBACK의 기본값이 true(인증 불필요)에서 false(인증 필요)로 바뀝니다.

마이그레이션 경로: n8n 2.0으로 업그레이드하기 전에 N8N_SKIP_AUTH_ON_OAUTH_CALLBACK=false를 설정하고, 인증이 켜진 상태에서 OAuth 연동이 작동하는지 테스트하세요.

N8N_RESTRICT_FILE_ACCESS_TO 기본값 설정#

n8n은 파일 작업이 가능한 위치를 제어하기 위해 N8N_RESTRICT_FILE_ACCESS_TO에 기본값을 설정합니다. 이는 ReadWriteFile과 ReadBinaryFiles node에 영향을 줍니다. 기본적으로 이 노드들은 ~/.n8n-files 디렉터리의 파일만 접근할 수 있습니다.

마이그레이션 경로: 파일 노드를 사용하는 워크플로를 검토하고, 허용된 디렉터리의 파일만 접근하는지 확인하세요. 다른 디렉터리 접근을 허용해야 하면 N8N_RESTRICT_FILE_ACCESS_TO 환경 변수를 원하는 경로로 설정하세요.

N8N_GIT_NODE_DISABLE_BARE_REPOS 기본값을 true로 변경#

기본적으로 Git node는 보안상 bare 저장소를 차단합니다. N8N_GIT_NODE_DISABLE_BARE_REPOS의 기본값이 true로 설정되므로, 이 설정을 바꾸지 않으면 bare 저장소는 비활성화됩니다.

마이그레이션 경로: 워크플로에서 bare 저장소를 써야 한다면 환경 구성에 N8N_GIT_NODE_DISABLE_BARE_REPOS=false를 설정해 활성화하세요.

데이터#

MySQL/MariaDB 지원 중단#

n8n은 더 이상 MySQL과 MariaDB를 저장소 백엔드로 지원하지 않습니다. 이 지원은 n8n 1.0부터 권장되지 않았습니다(deprecated). 호환성과 장기 지원이 가장 좋은 PostgreSQL을 사용하세요. MySQL node는 이전과 동일하게 계속 지원됩니다.

마이그레이션 경로: n8n 2.0으로 업그레이드하기 전에 데이터베이스 마이그레이션 도구로 MySQL이나 MariaDB의 데이터를 PostgreSQL이나 SQLite로 옮기세요.

SQLite 레거시 드라이버 제거#

n8n은 안정성 문제로 레거시 SQLite 드라이버를 제거합니다. 풀링(pooling) 드라이버가 기본이자 유일한 SQLite 드라이버가 됩니다. 풀링 드라이버는 WAL 모드, 단일 쓰기 연결, 읽기 연결 풀을 사용합니다. 벤치마크 결과 최대 10배 빠른 것으로 나타났습니다.

마이그레이션 경로: sqlite-pooled 드라이버가 자동으로 기본값이 됩니다. 지금 DB_SQLITE_POOL_SIZE를 0보다 큰 값으로 설정하면 풀링을 켤 수 있습니다. 기본 풀 크기는 2로 설정됩니다.

인메모리 바이너리 데이터 모드 제거#

n8n은 실행 중 바이너리 데이터를 메모리에 들고 있는 N8N_DEFAULT_BINARY_DATA_MODE의 default 모드를 제거합니다. 성능과 안정성을 위해 n8n 2.0부터는 다음 옵션만 제공됩니다:

• filesystem: 바이너리 데이터를 파일 시스템에 저장합니다. 일반 모드의 기본 옵션입니다.
• database: 바이너리 데이터를 데이터베이스에 저장합니다. 큐 모드의 기본 옵션입니다.
• s3: 바이너리 데이터를 S3 호환 스토어에 저장합니다.

N8N_AVAILABLE_BINARY_DATA_MODES 설정도 제거되므로, 이제 모드는 N8N_DEFAULT_BINARY_DATA_MODE로만 결정됩니다.

마이그레이션 경로: 파일 시스템 모드나 데이터베이스 모드는 구성에 따라 자동으로 사용됩니다. n8n 인스턴스에 바이너리 데이터를 저장할 디스크 공간이 충분한지 확인하세요. 자세한 내용은 바이너리 데이터 구성을 참조하세요.

구성 및 환경#

dotenv 업그레이드#

n8n은 dotenv 라이브러리로 .env 파일에서 환경 구성을 불러옵니다. 이 라이브러리가 버전 8.6.0에서 최신 버전으로 업그레이드되며, .env 파일의 파싱 방식이 바뀔 수 있습니다. 주요 호환성을 깨는 변경은 다음과 같습니다:

• 백틱 지원 (#615): 값에 백틱이 들어가면 작은따옴표나 큰따옴표로 감싸세요.
• 멀티라인 지원: 이제 멀티라인 값을 사용할 수 있습니다.
• #은 주석의 시작을 표시합니다: #로 시작하는 줄은 주석으로 처리됩니다.

마이그레이션 경로: dotenv changelog를 검토하고 .env 파일을 새 버전에 맞게 수정하세요.

n8n --tunnel 옵션 제거#

n8n --tunnel 명령줄 옵션은 n8n 2.0에서 제거됩니다.

마이그레이션 경로: 개발이나 테스트 용도로 --tunnel 옵션을 쓰고 있다면 ngrok, localtunnel, Cloudflare Tunnel 같은 대안 터널링 솔루션으로 바꾸세요. 워크플로와 문서도 이 변경에 맞게 수정하세요.

QUEUE_WORKER_MAX_STALLED_COUNT 제거#

QUEUE_WORKER_MAX_STALLED_COUNT 환경 변수와 멈춘(stalled) 작업에 대한 Bull 재시도 메커니즘이 제거됩니다. 혼란을 자주 일으키고 안정적으로 동작하지 않았기 때문입니다.

마이그레이션 경로: 구성에서 이 환경 변수를 삭제하세요. 업그레이드 후에는 n8n이 멈춘 작업을 자동으로 재시도하지 않습니다. 멈춘 작업을 처리해야 한다면 직접 재시도 로직이나 모니터링을 구현하는 것을 고려하세요.

N8N_CONFIG_FILES 제거#

N8N_CONFIG_FILES 환경 변수가 제거되었습니다.

마이그레이션 경로: 구성에서 이 환경 변수를 삭제하세요. 구성은 환경 변수, .env 파일 또는 _FILE 기반 구성으로 옮기세요.

CLI 및 워크플로#

CLI 명령 update:workflow 교체#

update:workflow CLI 명령은 더 이상 권장되지 않으며, 비슷한 기능을 더 명확하게 제공하는 두 개의 새 명령으로 대철됩니다:

• 매개변수 id와 versionId(선택)를 사용하는 publish:workflow
  • --all 매개변수는 프로덕션 환경에서 워크플로가 실수로 게시되는 것을 막기 위해 제거됩니다
• 매개변수 id와 all을 사용하는 unpublish:workflow

마이그레이션 경로: 워크플로를 개별 ID로 게시할 때는 새 publish:workflow 명령을 사용하고, 필요하면 버전을 지정하세요. 게시 취소에는 새 unpublish:workflow 명령을 사용하세요. 이렇게 하면 워크플로 게시 상태를 더 명확하게 제어할 수 있습니다.

외부 훅#

프런트엔드 워크플로 훅 권장 중단#

workflow.activeChange와 workflow.activeChangeCurrent 훅은 더 이상 권장되지 않으며, 새 훅 workflow.published로 대철됩니다. 새 훅은 워크플로의 어떤 버전이 게시되든 트리거됩니다.

마이그레이션 경로: 코드에서 workflow.activeChange와 workflow.activeChangeCurrent 대신 새 workflow.published 훅을 사용하도록 수정하세요. 이 훅은 동작이 더 일관되며, 워크플로 버전이 게시될 때마다 트리거됩니다.

릴리즈 채널#

n8n은 릴리즈 채널의 이름을 latest와 next에서 각각 stable과 beta로 바꿨습니다.

stable 태그는 가장 최신의 안정 릴리즈를, beta 태그는 가장 최신의 실험적 릴리즈를 나타냅니다. 이 태그들은 npm과 Docker Hub 양쪽에서 사용할 수 있습니다. 당분간 n8n은 latest와 next 태그를 계속 붙이지만, 향후 메이저 버전에서 이 태그들은 제거될 예정입니다.

권장: n8n 버전을 2.0.0 같은 특정 버전 번호로 고정하세요.

문제 보고#

n8n 2.0으로 업데이트하는 동안 문제가 발생하면 커뮤니티 포럼에서 도움과 지원을 받으세요.