InfoGrab DocsInfoGrab Docs

n8n 3.0 호환성을 깨는 변경

요약

이 문서는 2026년 10월 예정인 n8n 3.0 전환에 대비해 알아야 할 호환성을 깨는 변경과 필요한 조치를 안내합니다. n8n 3.0 릴리즈는 안전하고 신뢰할 수 있으며 프로덕션에 적합한 자동화 플랫폼을 제공하겠다는 n8n의 노력을 이어가는 버전입니다.

이 문서는 2026년 10월 예정인 n8n 3.0 전환에 대비해 알아야 할 호환성을 깨는 변경과 필요한 조치를 안내합니다. 이번 업데이트는 보안을 강화하고, 구성을 단순화하며, 레거시 기능을 제거합니다.

n8n 3.0 릴리즈는 안전하고 신뢰할 수 있으며 프로덕션에 적합한 자동화 플랫폼을 제공하겠다는 n8n의 노력을 이어가는 버전입니다. 이 메이저 버전에는 중요한 보안 개선과 사용 중단 예정 기능의 정리가 포함됩니다.

배포#

셀프 호스팅 n8n에는 Docker 기반 배포 필요#

셀프 호스팅 n8n에는 Docker 기반 배포가 필요합니다. n8n 3.0은 npm 또는 npx n8n으로 실행하는 설치 방식을 더 이상 지원하지 않습니다.

해야 할 일: npm 또는 npx n8n으로 n8n을 실행하고 있다면, n8n 3.0으로 업그레이드하기 전에 Docker 기반 배포로 이전할 계획을 세우세요. 로컬 설치라면 Docker Compose가 가장 간단한 방법이 될 것으로 예상됩니다.

단계별 마이그레이션 가이드는 곧 공개될 예정입니다.

커뮤니티 노드 개발#

이 변경은 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을 직접 실행하려면 n8n-node dev --external-n8n을 사용하고 해당 인스턴스를 N8N_DEV_RELOAD=true로 시작하세요. n8n 버전을 고정하려면 태그를 지정하세요. 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이 읽을 수 없는 데이터베이스 대신 빈 인스턴스가 생깁니다.
  • 해야 할 일: 업그레이드하거나 이미지를 변경하기 전에 보관하려는 테스트 워크플로를 내보내세요. 볼륨을 나열하고 재설정하려면 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_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의 n8n 3.0 마이그레이션 보고서를 확인하세요.

제거된 노드 및 헬퍼#

n8n 3.0은 새로운 패턴으로 대체된 이전 노드, 모드 및 헬퍼를 제거합니다.

제거된 노드#

  • Function 노드(레거시)
  • Function Item 노드(레거시)
  • Item Lists 노드(레거시)
  • LangChain Code 노드(레거시)
  • AI Transform 노드: n8n은 업그레이드 시 기존 노드를 생성된 JavaScript를 그대로 유지한 Code 노드로 자동 마이그레이션하므로, 기존 워크플로는 변경 없이 계속 작동합니다. 더 이상 AI Transform 노드를 추가할 수 없으므로, Code 노드에서 JavaScript를 직접 작성하세요.
  • 해야 할 일: 업그레이드하기 전에 영향을 받는 워크플로를 현재 권장되는 대안으로 마이그레이션하세요.
    • 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를 사용합니다.

제거된 표현식 헬퍼#

  • n8n 3.0에서는 더 이상 사용되지 않는 $getPairedItem 표현식 헬퍼를 제거합니다.
    • 해야 할 일: 대신 n8n의 표준 항목 연결을 사용하세요. 예를 들어 pairedItem 속성 또는 $(\"<node-name>\").item을 사용합니다.

Execute Workflow 노드의 항목별 한 번 실행 모드 제거#

n8n 3.0은 Execute Workflow 노드에서 Run once for each item 모드를 제거합니다. 이 모드를 사용하는 워크플로는 업데이트하기 전까지 실패합니다.

해야 할 일: 대신 Run once with all items 모드의 Execute Workflow 노드 앞에 Loop Over Items 노드를 사용하세요.

여러 출력이 있는 노드의 Always Output Data#

Always Output Data가 켜져 있으면 If 및 Switch처럼 여러 출력을 가진 노드는 이제 모든 출력이 비어 있을 때만 빈 항목을 추가합니다. 이전에는 각 빈 출력에 빈 항목이 추가되어 실행되지 않아야 할 브랜치가 실행됐습니다.

해야 할 일: 플래그가 지정된 노드를 검토하고 의도에 맞게 설정을 조정하세요.

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로 설정된 워크플로는 업데이트 후에도 동일하게 작동합니다. SQL Agent 사용 사례에는 최신 AI Agent 노드와 함께 Postgres 또는 MySQL 도구 서브 노드를 사용하세요.

보안#

기본적으로 n8n을 더 안전하게 만들기 위해 보안 기본값이 강화됩니다. 이러한 변경은 기존 워크플로 또는 크리덴셜에 영향을 줄 수 있습니다.

  • 위험한 리소스 이름의 처리 강화.
  • 더 안전한 크리덴셜 동작.
  • 기본적으로 키 순환 활성화.

더 커진 기본 SSRF 차단 목록#

N8N_SSRF_PROTECTION_ENABLED가 true이고 N8N_SSRF_BLOCKED_IP_RANGES에 default가 포함된 경우, n8n 3.0은 공유 주소 공간(100.64.0.0/10)과 IPv6 전환 범위도 차단합니다.

해야 할 일: 워크플로가 이 범위의 호스트를 호출한다면 해당 IP 범위를 N8N_SSRF_ALLOWED_IP_RANGES에 추가하거나 호스트 이름을 N8N_SSRF_ALLOWED_HOSTNAMES에 추가하세요. N8N_SSRF_BLOCKED_IP_RANGES에서는 default를 유지하세요. 이는 localhost, 사설 네트워크, 클라우드 메타데이터 엔드포인트를 포함한 기본 제공 전체 목록의 키워드입니다. 리터럴 범위로 바꾸면 현재 기본 제공 목록의 모든 범위를 직접 나열해야 합니다.

Compression 노드의 더 낮은 압축 해제 한도#

기본 N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES가 2 GiB에서 256 MiB로 낮아지고, 기본 N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES가 5,000에서 1,000으로 낮아집니다.

해야 할 일: 워크플로에서 256 MiB보다 크거나 항목이 1,000개를 초과하는 아카이브의 압축을 해제하는 경우, n8n 3.0으로 업그레이드하기 전에 이 변수를 이전 값(2147483648 및 5000)으로 명시적으로 설정하세요.

구성#

n8n 3.0은 이전 동작만 유지하던 일부 기본값을 변경하고 설정을 제거합니다. 해당 인스턴스에 영향을 주는 각 항목에 대해 n8n은 2.x에서 시작 시 더 이상 사용되지 않음을 알리는 경고를 로그에 기록합니다.

스토리지 디렉터리 이름 변경#

첫 시작 시 n8n 3.0은 ~/.n8n/binaryData를 ~/.n8n/storage로 이름을 바꾸고 N8N_MIGRATE_FS_STORAGE_PATH를 제거합니다.

해야 할 일: ~/.n8n/binaryData에 볼륨을 마운트했다면 대신 ~/.n8n/storage에 마운트하거나, 기존 경로를 유지하려면 N8N_STORAGE_PATH를 설정하세요. 두 디렉터리가 모두 있으면 n8n은 시작하지 않습니다. ~/.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에서 확인되지 않은 커뮤니티 노드를 계속 설치하려면 N8N_UNVERIFIED_PACKAGES_ENABLED=true를 설정하세요.
  • 태스크 러너 타임아웃이 짧아집니다. N8N_RUNNERS_TASK_TIMEOUT의 기본값이 300(5분)에서 60(1분)으로 낮아집니다. 더 오래 실행되는 Code 노드 태스크는 실패합니다.
    • 해야 할 일: 태스크에 1분 이상이 필요하다면 N8N_RUNNERS_TASK_TIMEOUT을 명시적으로 설정하세요.
  • 큐 모드에서는 수동 실행이 항상 워커에서 실행됩니다. OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS가 제거됩니다.
    • 해야 할 일: 변수를 제거하세요. 이제 수동 실행도 처리하는 워커에 제공하는 메모리를 검토하세요.
  • N8N_DB_PING_TIMEOUT 제거. n8n은 더 이상 이 변수로 대체하지 않습니다.
    • 해야 할 일: 대신 DB_PING_TIMEOUT_MS를 설정하세요.

종료되는 기능#

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를 사용하는 모든 인스턴스의 이 변경 사항을 확인할 수 있습니다.
  • 편집기에서 URL로 워크플로 가져오기: n8n 3.0에서는 이를 제거합니다. 다른 가져오기 방법은 계속 지원됩니다. 복사하여 붙여넣기, 편집기 UI 메뉴의 Import from File, CLI 및 n8n API가 이에 해당합니다.
  • 기능하지 않는 노드: n8n 3.0에서는 이를 제거합니다.
  • 프로젝트 역할에 외부 시크릿 허용 설정: n8n 3.0에서는 이를 제거합니다. 이제 프로젝트 편집자와 관리자는 기본적으로 프로젝트에서 외부 시크릿에 접근할 수 있습니다. 프로젝트 역할을 계속 제한하려면 사용자 지정 프로젝트 역할을 사용하세요. 이는 외부 시크릿을 사용할 수 있는 n8n Enterprise에 적용됩니다.
  • Code 노드의 Ask AI 탭: n8n 3.0에서는 이를 제거합니다.

n8n은 n8n 3.0 릴리즈가 다가오면 전체 세부 정보, 마이그레이션 가이드 및 링크로 이 페이지를 업데이트할 예정입니다.

n8n 3.0 호환성을 깨는 변경

n8n v2.39
원문 보기

요약

이 문서는 2026년 10월 예정인 n8n 3.0 전환에 대비해 알아야 할 호환성을 깨는 변경과 필요한 조치를 안내합니다. n8n 3.0 릴리즈는 안전하고 신뢰할 수 있으며 프로덕션에 적합한 자동화 플랫폼을 제공하겠다는 n8n의 노력을 이어가는 버전입니다.

이 문서는 2026년 10월 예정인 n8n 3.0 전환에 대비해 알아야 할 호환성을 깨는 변경과 필요한 조치를 안내합니다. 이번 업데이트는 보안을 강화하고, 구성을 단순화하며, 레거시 기능을 제거합니다.

n8n 3.0 릴리즈는 안전하고 신뢰할 수 있으며 프로덕션에 적합한 자동화 플랫폼을 제공하겠다는 n8n의 노력을 이어가는 버전입니다. 이 메이저 버전에는 중요한 보안 개선과 사용 중단 예정 기능의 정리가 포함됩니다.

배포#

셀프 호스팅 n8n에는 Docker 기반 배포 필요#

셀프 호스팅 n8n에는 Docker 기반 배포가 필요합니다. n8n 3.0은 npm 또는 npx n8n으로 실행하는 설치 방식을 더 이상 지원하지 않습니다.

해야 할 일: npm 또는 npx n8n으로 n8n을 실행하고 있다면, n8n 3.0으로 업그레이드하기 전에 Docker 기반 배포로 이전할 계획을 세우세요. 로컬 설치라면 Docker Compose가 가장 간단한 방법이 될 것으로 예상됩니다.

단계별 마이그레이션 가이드는 곧 공개될 예정입니다.

커뮤니티 노드 개발#

이 변경은 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을 직접 실행하려면 n8n-node dev --external-n8n을 사용하고 해당 인스턴스를 N8N_DEV_RELOAD=true로 시작하세요. n8n 버전을 고정하려면 태그를 지정하세요. 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이 읽을 수 없는 데이터베이스 대신 빈 인스턴스가 생깁니다.
  • 해야 할 일: 업그레이드하거나 이미지를 변경하기 전에 보관하려는 테스트 워크플로를 내보내세요. 볼륨을 나열하고 재설정하려면 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_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의 n8n 3.0 마이그레이션 보고서를 확인하세요.

제거된 노드 및 헬퍼#

n8n 3.0은 새로운 패턴으로 대체된 이전 노드, 모드 및 헬퍼를 제거합니다.

제거된 노드#

  • Function 노드(레거시)
  • Function Item 노드(레거시)
  • Item Lists 노드(레거시)
  • LangChain Code 노드(레거시)
  • AI Transform 노드: n8n은 업그레이드 시 기존 노드를 생성된 JavaScript를 그대로 유지한 Code 노드로 자동 마이그레이션하므로, 기존 워크플로는 변경 없이 계속 작동합니다. 더 이상 AI Transform 노드를 추가할 수 없으므로, Code 노드에서 JavaScript를 직접 작성하세요.
  • 해야 할 일: 업그레이드하기 전에 영향을 받는 워크플로를 현재 권장되는 대안으로 마이그레이션하세요.
    • 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를 사용합니다.

제거된 표현식 헬퍼#

  • n8n 3.0에서는 더 이상 사용되지 않는 $getPairedItem 표현식 헬퍼를 제거합니다.
    • 해야 할 일: 대신 n8n의 표준 항목 연결을 사용하세요. 예를 들어 pairedItem 속성 또는 $(\"<node-name>\").item을 사용합니다.

Execute Workflow 노드의 항목별 한 번 실행 모드 제거#

n8n 3.0은 Execute Workflow 노드에서 Run once for each item 모드를 제거합니다. 이 모드를 사용하는 워크플로는 업데이트하기 전까지 실패합니다.

해야 할 일: 대신 Run once with all items 모드의 Execute Workflow 노드 앞에 Loop Over Items 노드를 사용하세요.

여러 출력이 있는 노드의 Always Output Data#

Always Output Data가 켜져 있으면 If 및 Switch처럼 여러 출력을 가진 노드는 이제 모든 출력이 비어 있을 때만 빈 항목을 추가합니다. 이전에는 각 빈 출력에 빈 항목이 추가되어 실행되지 않아야 할 브랜치가 실행됐습니다.

해야 할 일: 플래그가 지정된 노드를 검토하고 의도에 맞게 설정을 조정하세요.

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로 설정된 워크플로는 업데이트 후에도 동일하게 작동합니다. SQL Agent 사용 사례에는 최신 AI Agent 노드와 함께 Postgres 또는 MySQL 도구 서브 노드를 사용하세요.

보안#

기본적으로 n8n을 더 안전하게 만들기 위해 보안 기본값이 강화됩니다. 이러한 변경은 기존 워크플로 또는 크리덴셜에 영향을 줄 수 있습니다.

  • 위험한 리소스 이름의 처리 강화.
  • 더 안전한 크리덴셜 동작.
  • 기본적으로 키 순환 활성화.

더 커진 기본 SSRF 차단 목록#

N8N_SSRF_PROTECTION_ENABLED가 true이고 N8N_SSRF_BLOCKED_IP_RANGES에 default가 포함된 경우, n8n 3.0은 공유 주소 공간(100.64.0.0/10)과 IPv6 전환 범위도 차단합니다.

해야 할 일: 워크플로가 이 범위의 호스트를 호출한다면 해당 IP 범위를 N8N_SSRF_ALLOWED_IP_RANGES에 추가하거나 호스트 이름을 N8N_SSRF_ALLOWED_HOSTNAMES에 추가하세요. N8N_SSRF_BLOCKED_IP_RANGES에서는 default를 유지하세요. 이는 localhost, 사설 네트워크, 클라우드 메타데이터 엔드포인트를 포함한 기본 제공 전체 목록의 키워드입니다. 리터럴 범위로 바꾸면 현재 기본 제공 목록의 모든 범위를 직접 나열해야 합니다.

Compression 노드의 더 낮은 압축 해제 한도#

기본 N8N_COMPRESSION_NODE_MAX_DECOMPRESSED_SIZE_BYTES가 2 GiB에서 256 MiB로 낮아지고, 기본 N8N_COMPRESSION_NODE_MAX_ZIP_ENTRIES가 5,000에서 1,000으로 낮아집니다.

해야 할 일: 워크플로에서 256 MiB보다 크거나 항목이 1,000개를 초과하는 아카이브의 압축을 해제하는 경우, n8n 3.0으로 업그레이드하기 전에 이 변수를 이전 값(2147483648 및 5000)으로 명시적으로 설정하세요.

구성#

n8n 3.0은 이전 동작만 유지하던 일부 기본값을 변경하고 설정을 제거합니다. 해당 인스턴스에 영향을 주는 각 항목에 대해 n8n은 2.x에서 시작 시 더 이상 사용되지 않음을 알리는 경고를 로그에 기록합니다.

스토리지 디렉터리 이름 변경#

첫 시작 시 n8n 3.0은 ~/.n8n/binaryData를 ~/.n8n/storage로 이름을 바꾸고 N8N_MIGRATE_FS_STORAGE_PATH를 제거합니다.

해야 할 일: ~/.n8n/binaryData에 볼륨을 마운트했다면 대신 ~/.n8n/storage에 마운트하거나, 기존 경로를 유지하려면 N8N_STORAGE_PATH를 설정하세요. 두 디렉터리가 모두 있으면 n8n은 시작하지 않습니다. ~/.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에서 확인되지 않은 커뮤니티 노드를 계속 설치하려면 N8N_UNVERIFIED_PACKAGES_ENABLED=true를 설정하세요.
  • 태스크 러너 타임아웃이 짧아집니다. N8N_RUNNERS_TASK_TIMEOUT의 기본값이 300(5분)에서 60(1분)으로 낮아집니다. 더 오래 실행되는 Code 노드 태스크는 실패합니다.
    • 해야 할 일: 태스크에 1분 이상이 필요하다면 N8N_RUNNERS_TASK_TIMEOUT을 명시적으로 설정하세요.
  • 큐 모드에서는 수동 실행이 항상 워커에서 실행됩니다. OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS가 제거됩니다.
    • 해야 할 일: 변수를 제거하세요. 이제 수동 실행도 처리하는 워커에 제공하는 메모리를 검토하세요.
  • N8N_DB_PING_TIMEOUT 제거. n8n은 더 이상 이 변수로 대체하지 않습니다.
    • 해야 할 일: 대신 DB_PING_TIMEOUT_MS를 설정하세요.

종료되는 기능#

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를 사용하는 모든 인스턴스의 이 변경 사항을 확인할 수 있습니다.
  • 편집기에서 URL로 워크플로 가져오기: n8n 3.0에서는 이를 제거합니다. 다른 가져오기 방법은 계속 지원됩니다. 복사하여 붙여넣기, 편집기 UI 메뉴의 Import from File, CLI 및 n8n API가 이에 해당합니다.
  • 기능하지 않는 노드: n8n 3.0에서는 이를 제거합니다.
  • 프로젝트 역할에 외부 시크릿 허용 설정: n8n 3.0에서는 이를 제거합니다. 이제 프로젝트 편집자와 관리자는 기본적으로 프로젝트에서 외부 시크릿에 접근할 수 있습니다. 프로젝트 역할을 계속 제한하려면 사용자 지정 프로젝트 역할을 사용하세요. 이는 외부 시크릿을 사용할 수 있는 n8n Enterprise에 적용됩니다.
  • Code 노드의 Ask AI 탭: n8n 3.0에서는 이를 제거합니다.

n8n은 n8n 3.0 릴리즈가 다가오면 전체 세부 정보, 마이그레이션 가이드 및 링크로 이 페이지를 업데이트할 예정입니다.