본문으로 건너뛰기

n8n v2.0 주요 변경 사항 | n8n 문서

n8n v2.0이 곧 출시됩니다. 이 문서에서는 중요한 주요 변경 사항과 전환을 위해 준비해야 할 조치를 설명합니다. 이번 업데이트는 보안을 강화하고, 설정을 단순화하며, 레거시 기능을 제거합니다.

n8n 2.0 출시는 안전하고 신뢰할 수 있으며 운영 환경에 적합한 자동화 플랫폼을 제공하려는 n8n의 약속을 이어갑니다. 이 주요 버전에는 중요한 보안 강화와 사용 중단된 기능 정리가 포함되어 있습니다.

동작 변경​

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

이전에는 부모 실행(Parent execution)이 자식 실행을 대기 상태로 만들 수 있는 노드가 포함된 자식 워크플로를 호출하고, 부모 실행이 자식 실행 완료를 기다리도록 설정된 경우 부모 실행이 올바르지 않은 결과를 받았습니다.

예를 들어 자식 실행에 대기 시간이 65초를 초과하는 Wait 노드, Webhook 호출, 폼 제출 또는 사람의 검토가 필요한 노드(예: Slack 노드)가 포함된 경우 대기 상태에 들어갑니다.

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

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

v1: 부모 실행은 자식 실행의 입력값을 그대로 출력으로 받았습니다: v1: 부모 실행은 자식 실행 결과를 받을 수 없음

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

이제 자식 워크플로에서 사람의 검토가 필요한 노드를 사용하고, 부모 워크플로에서 그 결과(예: 어떤 작업의 승인 또는 거부)를 활용할 수 있습니다.

마이그레이션 방법: 자식 워크플로를 호출하면서 자식 워크플로의 입력을 받을 것으로 기대하는 모든 워크플로를 검토하고, 새 동작에 맞게 업데이트하세요. 이제 부모 워크플로는 자식 워크플로의 입력이 아니라 자식 워크플로 마지막의 출력을 받습니다.

Start 노드 제거​

Start 노드는 더 이상 지원되지 않습니다. 이 노드는 워크플로를 시작하는 원래 방식이었지만, 이제는 더 목적에 맞는 트리거 노드로 대체되었습니다.

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

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

워크플로 저장 및 게시​

새로운 워크플로 게시 시스템이 기존 활성화/비활성화 토글 스위치를 대체합니다. 기존의 활성화/비활성화 토글은 새로운 게시/게시 취소 버튼으로 바뀝니다. 이 변경으로 워크플로 변경 사항을 언제 운영 환경에 반영할지 더 잘 제어할 수 있어, 진행 중인 변경 사항이 실수로 프로덕션 환경에 배포되는 위험을 줄일 수 있습니다. 자세한 내용은 워크플로 저장 및 게시를 참조하세요.

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

다음 노드는 연결된 외부 서비스가 더 이상 제공되지 않기 때문에 제거되었습니다.

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

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

보안​

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

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

마이그레이션 방법: 워크플로에서 Code 노드 내 환경 변수 접근이 필요하다면 환경 변수 설정에서 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 노드의 실행은 작업 실행기에서 수행됩니다.

마이그레이션 방법: 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은 Pyodide 기반 Python Code 노드와 도구를 제거하고, 이를 작업 실행기 기반 구현으로 대체합니다. 이 구현은 네이티브 Python을 사용하므로 보안과 성능이 더 뛰어납니다. v2.0부터는 외부 모드의 작업 실행기 및 네이티브 Python 도구와 함께만 Python Code 노드를 사용할 수 있습니다.

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

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

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

기본적으로 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 repository)를 차단합니다. N8N_GIT_NODE_DISABLE_BARE_REPOS의 기본값은 true로 설정되며, 이 설정을 변경하지 않으면 베어 리포지토리는 비활성화됩니다.

마이그레이션 방법: 워크플로에서 베어 리포지토리를 사용해야 한다면 환경 변수 설정에서 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 드라이버를 제거합니다. 연결 풀 드라이버가 유일한 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 CLI 옵션은 v2.0에서 제거됩니다.

마이그레이션 방법: 현재 개발 또는 테스트 목적으로 --tunnel 옵션을 사용하고 있다면 ngrok, localtunnel 또는 Cloudflare Tunnel 같은 다른 터널링 솔루션으로 전환하세요. 이 변경 사항을 반영하도록 워크플로와 문서도 업데이트하세요.

QUEUE_WORKER_MAX_STALLED_COUNT 제거​

QUEUE_WORKER_MAX_STALLED_COUNT 환경 변수와 Bull의 stalled 작업 재시도 메커니즘이 제거됩니다. 이 기능은 자주 혼란을 일으켰고 안정적으로 동작하지 않았기 때문입니다.

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

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으로 업데이트하는 동안 문제가 발생하면 도움이 필요할 경우 커뮤니티 포럼에서 지원을 받으세요.