패키지 내보내기와 가져오기를 제약하는 요소(크기 제한, 라이선스 기능, API 키 스코프, 관측성)에 대한 레퍼런스입니다.

패키지 크기 제한#

네 개의 환경 변수가 가져오기에서 허용하는 범위를 제한합니다. 작은 아카이브가 거대한 크기로 풀리는 상황으로부터 인스턴스를 보호합니다.

이 중 하나라도 초과하면 어떤 제한에 걸렸는지 알려 주는 400이 반환됩니다.

가져오기 요청에는 구성할 수 없는 제한이 몇 가지 더 적용됩니다. 요청당 정확히 하나의 파일, 옵션 필드당 64 KB입니다. 후자는 사실상 --bindings 값의 상한입니다.

내보내기는 ID를 그룹당 300개로 제한하며, 워크플로, 폴더, 프로젝트 ID를 각각 따로 계산합니다. 내보낼 항목 선택을 참고하세요.

아카이브 검증#

크기 제한 외에도, n8n은 패키지 형태가 아닌 아카이브를 거부하며 각각 400을 반환합니다.

• manifest.json이 아카이브의 첫 번째 파일이어야 합니다.
• 항목 경로에는 영문자, 숫자, ., _, /, -만 사용할 수 있으므로, ASCII가 아닌 문자가 포함된 경로의 아카이브는 거부됩니다.
• 경로는 상대 경로여야 하고, 패키지 루트를 벗어날 수 없으며, 고유해야 합니다.
• 항목은 파일 또는 디렉터리여야 합니다. 심볼릭 링크와 하드 링크는 거부됩니다.
• packageFormatVersion이 정확히 일치해야 합니다. 버전 호환성을 참고하세요.

매니페스트가 참조하지 않는 파일은 무시되지만, 크기 및 항목 수 제한에는 여전히 포함됩니다.

라이선스 기능#

패키지 자체를 위한 라이선스 기능은 없습니다. 이 기능은 n8n Cloud와 셀프 호스팅 n8n의 모든 플랜과 에디션에서 사용할 수 있으며, 내보내기에는 라이선스 기능이 전혀 필요하지 않습니다.

가져오기는 두 가지 라이선스 기능을 확인하며, 실제로 수행할 작업에 한해서만 확인합니다.

• 폴더: 패키지에 폴더가 포함된 경우 항상 확인합니다. 패키지가 선언한 내용을 기준으로 판단하므로, 대상에 모든 폴더가 이미 존재하더라도 적용됩니다.
• 변수: 가져오기가 실제로 변수를 만들거나 덮어쓸 때만 확인합니다. 모든 변수가 대상에서 해석되는 패키지는 변수를 하나도 쓰지 않으므로 라이선스도 변수 스코프도 필요하지 않습니다.

프로젝트 패키지를 가져오려면 팀 프로젝트를 지원하는 라이선스도 필요합니다.

라이선스 기능이 없으면 해당 기능의 이름을 알려 주는 403이 반환됩니다.

패키지는 n8n API를 통해서만 접근할 수 있으므로 인스턴스에서 API가 활성화되어 있어야 합니다. 인스턴스로 패키지가 들어오거나 나가지 못하게 하려면 퍼블릭 API를 비활성화하거나, workflow:export 및 workflow:import 스코프가 있는 API 키를 발급하지 마세요.

API 키 스코프#

두 엔드포인트 모두 API 키로 인증하며, 가져오기는 해당 키의 사용자에게 귀속됩니다.

내보내기#

가져오기#

dataTable:update와 마지막 네 개는 가져오기가 실제로 쓰게 될 내용을 기준으로 판단하므로, 참조하는 태그나 변수가 모두 이미 일치하는 패키지에는 두 스코프 모두 필요하지 않습니다. 나머지는 패키지가 선언한 내용을 기준으로 판단하므로, 참조하는 모든 테이블이 이미 존재하더라도 dataTable:create가 필요합니다.

멤버 역할의 API 키는 프로젝트 패키지를 가져올 수 없고, 폴더가 포함된 패키지를 가져올 수 없으며, 변수를 만들거나 덮어쓸 수 없습니다. project:create, project:update, folder:create, folder:update, variable:create, variable:update는 소유자 및 관리자 스코프이기 때문입니다. 멤버는 workflow:export, workflow:import, project:export, variable:list, dataTable:create, dataTable:update, tag:create, tag:update를 가질 수 있으므로, 멤버도 내보내기 시 변수 값을 함께 묶을 수 있습니다.

API 키 스코프는 사용자 본인의 권한을 대체하는 것이 아니라 그 위에 추가로 확인됩니다. 내보내기에서는 읽을 수 있는 항목만 가져갈 수 있으므로, n8n은 각 워크플로, 폴더, 프로젝트, 자격 증명에 대한 접근 권한을 확인합니다. 가져오기에서는 대상 프로젝트에 쓸 수 있는 권한을 확인합니다. 읽을 수 없는 자격 증명은 함께 묶이지 않고 요구 사항으로 기록되므로, 인스턴스의 일부만 볼 수 있는 상태에서 만든 패키지에는 대상이 무엇을 제공해야 하는지가 분명하게 담깁니다.

태그를 만들 권한이나 데이터 테이블을 만들거나 변경할 권한이 없는 경우에는 403이 아니라 차단 이슈로 보고됩니다. 가져오기가 거부되는 이유를 참고하세요.

변수 제한#

인스턴스에는 보유할 수 있는 변수 수에 제한이 있으며, 전역 변수와 프로젝트 스코프 변수를 합쳐서 계산합니다. n8n은 새 변수로 인해 제한을 넘게 되는 가져오기를 아무것도 쓰기 전에 거부합니다. 이슈에는 제한, 남은 여유, 가져오기가 필요로 한 변수 수, 해당 변수 목록이 표시됩니다.

새 변수만 제한에 포함됩니다. 기존 변수를 덮어쓰는 것은 이미 계산에 포함되어 있으므로 여유를 소모하지 않습니다. 또한 n8n은 가져오기가 실제로 만들 항목을 기준으로 계산하므로, 패키지 내 여러 프로젝트가 필요로 하는 전역 변수 하나는 한 번만 계산됩니다.

이벤트#

두 작업 모두 로그 스트리밍 및 텔레메트리 경로로 이벤트를 내보내므로, 누가 무엇을 옮겼는지 감사할 수 있습니다.

인스턴스로 들어오거나 나가는 모든 패키지를 추적하려면 로그 스트리밍 대상이 네 이벤트를 모두 구독하게 하세요. 로그 스트리밍 이벤트는 엔티티 ID를 포함하고, 대응하는 텔레메트리 이벤트는 엔티티별 개수를 포함합니다. 실패 이벤트는 사유를 access-denied, entity-not-found, blocked, validation 중 하나로 분류합니다.

각 이벤트 페이로드의 내용은 내보내기 페이지의 이벤트와 가져오기 페이지의 이벤트를 참고하세요.

다음 읽을거리#

• 패키지 내보내기 및 패키지 가져오기: 이러한 제한이 적용되는 옵션을 설명합니다.
• 가져오기 동작 방식: 라이선스 및 스코프 확인이 가져오기에 어떻게 맞물리는지 설명합니다.

관련 리소스#

• n8n 패키지
• 패키지 형식
• 패키지 내보내기
• 패키지 가져오기
• 가져오기 동작 방식