n8n v2.0이 릴리즈되었으며, 여기에는 몇 가지 중요한 변경 사항이 포함되어 있습니다. 이 문서는 주요 변경 사항과 전환을 준비하기 위해 취해야 할 조치를 설명합니다. 이번 업데이트는 보안을 강화하고, 구성을 단순화하며, 레거시 기능을 제거합니다.

n8n 2.0 릴리즈는 안전하고 신뢰할 수 있으며 프로덕션 준비가 된 자동화 플랫폼을 제공하려는 n8n의 노력을 이어갑니다. 이 메이저 버전에는 중요한 보안 강화와 더 이상 사용되지 않는 기능의 정리가 포함되어 있습니다.

동작 변경 사항#

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

이전에는 실행(부모)이 서브 실행(자식)을 호출했을 때, 서브 실행에 대기 상태로 진입하게 만드는 노드가 포함되어 있고 부모 실행이 서브 실행의 완료를 기다리도록 설정되어 있는 경우, 부모 실행이 잘못된 결과를 받게 되었습니다.

예를 들어 서브 실행에 타임아웃이 65초를 초과하는 Wait 노드, 웹훅 호출, 폼 제출, 또는 Slack 노드와 같은 human-in-the-loop 노드가 포함되어 있으면 대기 상태로 진입하게 됩니다.

부모 워크플로:

서브 워크플로:

v1: 부모 실행은 서브 실행의 입력을 자신의 출력으로 그대로 재현합니다.

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

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

마이그레이션 방법: 서브 워크플로를 호출하고 서브 워크플로의 입력을 받을 것으로 기대하는 워크플로가 있는지 검토하세요. 이러한 워크플로를 업데이트하여, 부모 워크플로가 자식 워크플로의 마지막에서 나온 출력을 대신 받는 새로운 동작을 처리하도록 하세요.

Start 노드 제거#

Start 노드는 더 이상 지원되지 않습니다. 이 노드는 원래 워크플로를 시작하는 방법이었지만, 이제 더 구체적인 트리거 노드가 이를 대체합니다.

마이그레이션 방법: 워크플로 사용 방식에 따라 Start 노드를 다음과 같이 교체하세요:

• 수동 실행: Start 노드를 Manual Trigger 노드로 교체하세요.
• 서브 워크플로: 다른 워크플로가 이 워크플로를 서브 워크플로로 호출하는 경우, Start 노드를 Execute Workflow Trigger 노드로 교체하고 워크플로를 발행(publish)하세요.
• 비활성화된 Start 노드: Start 노드가 비활성화되어 있다면 워크플로에서 삭제하세요.

워크플로 저장 및 발행#

새로운 워크플로 발행 시스템이 기존의 활성/비활성 토글을 대체합니다. 즉, 기존의 "Activate/Deactivate" 토글이 새로운 "Publish/Unpublish" 버튼으로 바뀝니다. 이 변경으로 워크플로 변경 사항이 언제 실제로 반영될지 더 잘 제어할 수 있게 되어, 작업 중인 변경 사항이 실수로 프로덕션에 배포될 위험이 줄어듭니다. 자세한 내용은 다음을 참고하세요: 워크플로 저장 및 발행.

서비스 종료로 인해 제거된 노드#

다음 노드들은 연결 대상 외부 서비스가 더 이상 존재하지 않아 제거되었습니다:

• Spontit 노드
• crowd.dev 노드
• Kitemaker 노드
• Automizy 노드

마이그레이션 방법: 워크플로에서 이러한 노드를 사용하고 있다면, 오류를 방지하기 위해 해당 워크플로를 업데이트하거나 제거하세요.

보안#

기본적으로 Code node에서 환경 변수 접근 차단#

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

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

설정 파일 권한 강제 적용#

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

마이그레이션 방법: v2.0 이전에 이 동작을 테스트하려면 N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true로 설정하세요. 환경이 파일 권한을 지원하지 않는 경우(예: Windows), N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=false로 설정하여 이 요구 사항을 비활성화하세요.

기본적으로 태스크 러너 활성화#

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

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

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

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

마이그레이션 방법: 다음 순서로 표현식 평가를 Code node 밖으로 이동하세요:

• $evaluateExpression()을 호출하는 대신 JavaScript로 로직을 직접 작성하세요.
• Code node 이전에 Edit Fields (Set) 노드에서 표현식을 평가한 다음, 들어오는 아이템에서 결과를 읽으세요.
• 다른 대안이 없는 경우, N8N_RUNNERS_INSECURE_MODE=true로 설정하여 비활성화된 JavaScript 기능을 다시 활성화할 수 있습니다. 이는 태스크 러너의 보안 조치를 해제하는 것이므로 프로덕션 환경에서는 권장하지 않습니다.

Code node의 $evaluateExpression()은 향후 버전에서 완전히 제거될 수 있으므로, N8N_RUNNERS_INSECURE_MODE=true는 영구적인 해결책이 아니라 임시 우회 수단으로 취급하세요.

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

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

마이그레이션 방법: 외부 모드로 Docker에서 태스크 러너를 실행하고 있다면, n8nio/n8n 대신 n8nio/runners 이미지를 사용하도록 설정을 업데이트하세요.

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

n8n은 Pyodide 기반 Python Code node 및 도구를 제거하고, 보안과 성능 향상을 위해 네이티브 Python을 사용하는 태스크 러너 기반 구현으로 대체합니다. v2.0부터는 외부 모드의 태스크 러너와 네이티브 Python 도구를 사용해야만 Python Code node를 사용할 수 있습니다.

네이티브 Python Code node는 Pyodide 기반 버전에서 사용 가능했던 _input과 같은 내장 변수나 dot 접근 표기법을 지원하지 않습니다. 자세한 내용은 Code node 문서를 참고하세요.

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

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

기본적으로 ExecuteCommand 및 LocalFileTrigger 노드 비활성화#

n8n은 보안 위험이 있기 때문에 기본적으로 ExecuteCommand와 LocalFileTrigger 노드를 비활성화합니다. 이 노드들은 사용자가 임의의 명령을 실행하고 파일 시스템에 접근할 수 있도록 허용합니다.

마이그레이션 방법: 이 노드들을 사용해야 한다면, NODES_EXCLUDE 환경 변수를 업데이트하여 n8n 구성의 비활성화된 노드 목록에서 제거하세요. 예를 들어, 모든 노드를 활성화하려면 NODES_EXCLUDE="[]"로 설정하거나, 필요한 특정 노드만 제거하세요.

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

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

마이그레이션 방법: v2.0으로 업그레이드하기 전에 N8N_SKIP_AUTH_ON_OAUTH_CALLBACK=false로 설정하고, 인증이 활성화된 상태에서 OAuth 통합이 정상적으로 작동하는지 테스트하세요.

N8N_RESTRICT_FILE_ACCESS_TO의 기본값 설정#

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

마이그레이션 방법: 파일 노드를 사용하는 워크플로를 검토하여, 허용된 디렉터리 내의 파일에만 접근하도록 하세요. 다른 디렉터리에 대한 접근이 필요하다면, N8N_RESTRICT_FILE_ACCESS_TO 환경 변수를 원하는 경로로 설정하세요.

N8N_GIT_NODE_DISABLE_BARE_REPOS의 기본값을 true로 변경#

기본적으로 Git 노드는 보안상의 이유로 bare 리포지터리를 이제 차단합니다. N8N_GIT_NODE_DISABLE_BARE_REPOS의 기본값이 true로 설정되며, 이는 이 설정을 변경하지 않는 한 bare 리포지터리가 비활성화됨을 의미합니다.

마이그레이션 방법: 워크플로에서 bare 리포지터리를 사용해야 한다면, 환경 구성에서 N8N_GIT_NODE_DISABLE_BARE_REPOS=false로 설정하여 활성화하세요.

데이터#

MySQL/MariaDB 지원 중단#

n8n은 더 이상 MySQL과 MariaDB를 저장소 백엔드로 지원하지 않습니다. 이 지원은 v1.0에서 이미 지원 중단(deprecated)되었습니다. 최상의 호환성과 장기적인 지원을 위해 PostgreSQL을 사용하세요. MySQL 노드는 이전과 같이 계속 지원됩니다.

마이그레이션 방법: v2.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 모드를 제거합니다. 더 나은 성능과 안정성을 위해 v2부터는 다음 옵션을 사용할 수 있습니다:

• 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 변경 로그를 검토하고, 새 버전과의 호환성을 위해 .env 파일을 업데이트하세요.

n8n --tunnel 옵션 제거#

n8n --tunnel 명령줄 옵션은 v2.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 명령은 지원 중단(deprecated)되며, 유사한 기능을 더 명확하게 제공하는 두 개의 새로운 명령으로 대체됩니다:

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

마이그레이션 방법: 새로운 publish:workflow 명령을 사용하여 워크플로를 ID별로 개별적으로 발행하고, 선택적으로 버전을 지정하세요. 발행 취소(unpublish)의 경우, 새로운 unpublish:workflow 명령을 사용하세요. 이를 통해 워크플로 발행 상태에 대한 더 나은 명확성과 제어를 제공합니다.

외부 훅#

지원 중단되는 프런트엔드 워크플로 훅#

workflow.activeChange와 workflow.activeChangeCurrent 훅은 지원 중단(deprecated)됩니다. 이들은 새로운 훅 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으로 업데이트하는 동안 문제가 발생하면, 도움과 지원을 위해 커뮤니티 포럼을 방문하세요.