본문으로 건너뛰기

n8n v2.0 주요 변경 사항

n8n v2.0이 곧 출시됩니다. 이 문서에서는 중요한 주요 변경 사항과 원활한 전환을 위한 준비 조치를 안내합니다. 이번 업데이트는 보안을 강화하고 설정을 단순화하며 더 이상 지원되지 않는 기능을 제거합니다.

n8n 2.0의 출시는 안전하고 신뢰할 수 있으며 프로덕션 환경에서 바로 사용 가능한 자동화 플랫폼을 제공하겠다는 n8n의 약속을 이어갑니다. 이 메이저 버전은 중요한 보안 강화와 더불어 폐기된 기능들을 정리합니다.

동작 변경 사항​

자식 워크플로가 대기 상태에서 재개될 때 예상되는 데이터 반환​

이전에는 부모 실행(Parent)이 대기 상태로 들어가는 노드(예: Wait, Webhook, 폼 제출, Slack 인공 검토 등)를 포함하는 자식 워크플로를 호출하고, 부모 실행이 자식 워크플로 완료를 기다리도록 설정된 경우, 부모 실행이 잘못된 결과를 받았습니다.

예를 들어, 자식 워크플로에 65초 이상의 타임아웃이 있는 Wait 노드, Webhook 호출, 폼 제출 또는 Slack 노드와 같은 인공 검토 노드가 포함되어 있으면 대기 상태에 진입하게 됩니다.

부모 워크플로: 부모 워크플로

자식 워크플로: 자식 워크플로

v1: 부모 실행은 자식 워크플로의 입력을 출력으로 그대로 반환했습니다:
v1: 부모 실행이 자식 워크플로 결과를 받지 못함

v2: 부모 실행은 자식 워크플로의 결과를 정확히 받습니다:
v2: 부모 실행이 자식 워크플로 결과를 받음

이제 자식 워크플로 내에서 인공 검토 노드를 사용하고, 그 결과(예: 승인 또는 거부 여부)를 부모 워크플로에서 활용할 수 있습니다.

마이그레이션 경로: 자식 워크플로를 호출하면서 자식 워크플로의 입력값을 기대했던 모든 워크플로를 점검하세요. 이제 부모 워크플로는 자식 워크플로의 입력이 아닌 자식 워크플로의 최종 출력을 받게 되므로, 해당 워크플로를 새 동작에 맞게 업데이트해야 합니다.

Start 노드 제거​

Start 노드는 더 이상 지원되지 않습니다. 이 노드는 워크플로를 시작하는 초기 방식이었으나, 현재는 목적에 더 특화된 트리거 노드로 대체되었습니다.

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

  • 수동 실행: Start 노드를 Manual Trigger 노드로 교체하세요
  • 자식 워크플로: 다른 워크플로에서 이 워크플로를 자식 워크플로로 호출하는 경우, Start 노드를 Execute Workflow Trigger 노드로 교체하고, 해당 워크플로를 **게시(publish)**해야 합니다
  • 비활성화된 Start 노드: 이미 비활성화된 Start 노드는 워크플로에서 삭제하세요

워크플로 저장 및 게시​

기존의 "활성화/비활성화" 토글 스위치를 대체하는 새로운 워크플로 게시 시스템이 도입되었습니다. 기존의 토글은 이제 "게시/게시 취소(Publish/Unpublish)" 버튼으로 변경됩니다. 이를 통해 워크플로 변경 사항을 언제 프로덕션에 적용할지 더 정밀하게 제어할 수 있으며, 진행 중인 변경 사항이 실수로 배포되는 위험을 줄일 수 있습니다. 자세한 내용은 워크플로 저장 및 게시 문서를 참조하세요.

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

다음 노드는 연결된 외부 서비스가 더 이상 제공되지 않아 제거되었습니다:

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

마이그레이션 경로: 위 노드 중 하나라도 사용 중인 워크플로가 있다면, 오류를 방지하기 위해 해당 워크플로를 업데이트하거나 삭제하세요.

보안​

Code 노드의 환경 변수 접근 기본 차단​

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

마이그레이션 경로: Code 노드 내에서 환경 변수 접근이 필요한 경우, 환경 설정에서 N8N_BLOCK_ENV_ACCESS_IN_NODE=false로 설정하세요. 민감한 데이터의 경우 환경 변수 대신 자격 증명(Credentials) 또는 기타 보안 방법을 사용하는 것을 권장합니다.

설정 파일 권한 강제 적용​

보안 강화를 위해 n8n은 설정 파일에 대해 엄격한 파일 권한을 요구합니다. 기본적으로 설정 파일은 0600 권한(소유자만 읽기/쓰기 가능)을 가져야 하며, 이는 SSH가 개인 키를 보호하는 방식과 유사합니다.

마이그레이션 경로: v2.0 이전에 이 동작을 테스트하려면 N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true를 설정하세요. Windows와 같이 파일 권한을 지원하지 않는 환경에서는 N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=false로 설정하여 이 요구사항을 비활성화할 수 있습니다.

작업 실행기(Task Runner) 기본 활성화​

n8n은 보안성과 격리를 향상시키기 위해 작업 실행기(Task Runner)를 기본적으로 활성화합니다. 모든 Code 노드 실행은 작업 실행기에서 수행됩니다.

마이그레이션 경로: v2.0으로 업그레이드하기 전에 N8N_RUNNERS_ENABLED=true를 설정하여 이 동작을 미리 테스트하세요. 인프라가 작업 실행기를 실행하는 데 필요한 조건을 충족하는지 확인하세요. 추가 보안을 원한다면 외부 모드(작업 실행기를 별도의 프로세스 또는 컨테이너에서 실행하는 방식) 사용을 고려해 보세요.

n8nio/n8n Docker 이미지에서 작업 실행기 제거​

v2.0부터 주요 n8nio/n8n Docker 이미지에는 외부 모드용 작업 실행기가 포함되지 않습니다. 외부 모드에서 작업 실행기를 실행하려면 별도의 n8nio/runners Docker 이미지를 사용해야 합니다.

마이그레이션 경로: Docker에서 외부 모드로 작업 실행기를 실행 중이라면, n8nio/n8n 대신 n8nio/runners 이미지를 사용하도록 설정을 업데이트하세요.

Pyodide 기반 Python Code 노드 및 도구 제거​

n8n은 보안성과 성능이 향상된 작업 실행기 기반의 네이티브 Python 구현으로 Pyodide 기반 Python Code 노드 및 도구를 대체합니다. v2.0부터 Python Code 노드는 외부 모드의 작업 실행기와 네이티브 Python 도구와 함께 사용할 수 있습니다.

네이티브 Python Code 노드는 Pyodide 버전에서 제공되던 _input 같은 내장 변수나 점(.) 표기법(dot notation)을 지원하지 않습니다. 자세한 내용은 Code 노드 문서를 참조하세요.

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

마이그레이션 경로: Code 노드에서 계속 Python을 사용하려면 외부 모드에서 작업 실행기를 설정하고, 기존 Python Code 노드 및 도구가 새 구현과 호환되는지 확인하세요.

ExecuteCommand 및 LocalFileTrigger 노드 기본 비활성화​

ExecuteCommand 및 LocalFileTrigger 노드를 사용하면 임의의 명령어를 실행하거나 파일 시스템에 직접 접근할 수 있어 보안 위험이 있습니다. 따라서 n8n은 이 노드들을 기본적으로 비활성화합니다.

마이그레이션 경로: 해당 노드를 사용해야 한다면, 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 repos)를 차단합니다. N8N_GIT_NODE_DISABLE_BARE_REPOS의 기본값이 true로 설정되며, 이 설정을 변경하지 않는 한 베어 리포지토리는 사용할 수 없습니다.

마이그레이션 경로: 워크플로에서 베어 리포지토리 사용이 필요하다면, 환경 설정에서 N8N_GIT_NODE_DISABLE_BARE_REPOS=false로 설정하여 활성화하세요.

데이터​

MySQL/MariaDB 지원 중단​

n8n은 더 이상 MySQL 및 MariaDB를 저장 백엔드로 지원하지 않습니다. 이 기능은 v1.0에서 이미 폐기되었으며, 최적의 호환성과 장기 지원을 위해 PostgreSQL 사용을 권장합니다.
참고: 여기서 말하는 ‘MySQL/MariaDB 지원 중단’은 n8n의 내부 데이터 저장소로서의 사용을 의미합니다. 외부 MySQL 데이터베이스에 연결하는 MySQL 통합 노드는 계속 지원됩니다.

마이그레이션 경로: v2.0으로 업그레이드하기 전에, 데이터베이스 마이그레이션 도구를 사용해 MySQL 또는 MariaDB의 데이터를 PostgreSQL 또는 SQLite로 이전하세요.

SQLite 레거시 드라이버 제거​

신뢰성 문제로 인해 n8n은 레거시 SQLite 드라이버를 제거합니다. 이제 연결 풀링(Connection 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은 .env 파일에서 환경 설정을 로드하기 위해 dotenv 라이브러리를 사용합니다. 이 라이브러리가 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 환경 변수와 Bull의 정체(stalled) 작업 재시도 메커니즘은 혼란을 초래하고 신뢰할 수 없어 제거됩니다.

마이그레이션 경로: 구성에서 이 환경 변수를 삭제하세요. 업그레이드 후 n8n은 더 이상 정체된 작업을 자동으로 재시도하지 않습니다. 정체 작업 처리가 필요하다면 자체 재시도 로직이나 모니터링을 구현하는 것을 고려하세요.

N8N_CONFIG_FILES 제거​

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

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

CLI 및 워크플로​

CLI 명령어 update:workflow 교체​

update:workflow CLI 명령어는 폐기되며, 유사한 기능과 더 명확한 의미를 제공하는 두 개의 새 명령어로 대체됩니다:

  • publish:workflow — id 및 선택적 versionId 인자 사용
  • --all 인자는 실수로 프로덕션에 워크플로를 게시하는 위험을 줄이기 위해 제거됨
  • unpublish:workflow — id 및 all 인자 사용

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

외부 훅(External Hooks)​

프론트엔드 워크플로 훅 폐기​

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으로 업데이트하는 과정에서 문제가 발생하면, 커뮤니티 포럼을 방문해 도움과 지원을 요청하세요.