n8n 패키지

요약

n8n 패키지 형식과 API는 아직 개발 중입니다. 패키지는 워크플로와 해당 의존성을 설명하는 매니페스트 파일을 함께 묶은 "스냅샷" tar 파일로, npm 패키지와 비슷합니다. n8n 인스턴스의 Public API를 통해, 또는 동일한 Public API 엔드포인트를 감싸는 n8n CLI를 통해 n8n 패키지를 가져오고 내보낼 수 있습니다.

Warning

베타

n8n 패키지 형식과 API는 아직 개발 중입니다. 주 버전(major version) 변경 없이도 호환성이 깨지는 변경이 발생할 수 있습니다. 메인 n8n 리포지터리의 GitHub 이슈를 통한 피드백을 환영합니다.

패키지는 워크플로와 해당 의존성을 설명하는 매니페스트 파일을 함께 묶은 "스냅샷" tar 파일로, npm 패키지와 비슷합니다. 한 n8n 인스턴스에서 패키지를 내보내 다른 인스턴스로 가져올 수 있습니다.

n8n 인스턴스의 Public API를 통해, 또는 동일한 Public API 엔드포인트를 감싸는 n8n CLI를 통해 n8n 패키지를 가져오고 내보낼 수 있습니다.

알려진 제한 사항#

다음 항목은 아직 n8n 패키지에서 지원되지 않습니다:

서브 워크플로
오류 워크플로
데이터 테이블
폴더
프로젝트

이러한 항목에 대한 지원을 추가하기 위해 작업 중입니다.

패키지에 포함되는 내용#

패키지는 확장자가 .n8np인 tar 파일입니다. 여기에는 manifest.json과 내보낸 워크플로, 그리고 해당 워크플로가 사용하는 자격 증명이 함께 포함됩니다. n8n은 자격 증명의 비밀 값을 패키지에 절대 포함하지 않습니다. 대신 자격 증명의 ID, 이름, 유형으로 이루어진 스텁을 내보내므로, 대상 인스턴스의 자격 증명과 매칭할 수 있습니다.

콘텐츠 개요#

.n8np 아카이브의 압축을 풀면 manifest.json 파일과 workflows 디렉터리가 포함된 디렉터리를 얻습니다. n8n은 내보낸 워크플로마다 하위 디렉터리를 하나씩 생성하며, 각 하위 디렉터리에는 해당 워크플로의 노드, 연결, 설정이 담긴 workflow.json 파일이 들어 있습니다:

export/
├── manifest.json
└── workflows/
    ├── marketing-agent/
    │   └── workflow.json
    └── personal-ai-assistant/
        └── workflow.json

manifest.json 파일은 패키지의 내용을 다음과 같이 설명합니다:

packageFormatVersion: 패키지 형식의 버전입니다.
exportedAt: n8n이 패키지를 생성한 타임스탬프입니다.
sourceN8nVersion: 패키지를 내보낸 n8n의 버전입니다.
sourceId: 패키지를 내보낸 n8n 인스턴스의 식별자입니다.
workflows: 내보낸 워크플로 목록으로, 각 항목에는 id, name, target(workflows 하위의 디렉터리 경로)이 포함됩니다.
requirements.credentials: 내보낸 워크플로가 사용하는 자격 증명 목록입니다. 각 항목에는 자격 증명의 id, name, type이 있으며, 해당 자격 증명을 사용하는 워크플로들의 ID(usedByWorkflows)를 나열합니다. n8n은 자격 증명의 비밀 값을 패키지에 포함하지 않습니다.

사용 사례#

인스턴스 간에 워크플로를 반복 가능하고 자동화된 방식으로 이동해야 할 때 n8n 패키지를 사용하세요. 일반적인 시나리오는 다음과 같습니다:

CI/CD 파이프라인: 자동화된 파이프라인의 일부로 개발 인스턴스에서 스테이징 또는 프로덕션으로 워크플로를 승격합니다.
백업: 워크플로와 자격 증명 참조를 내보내 나중에 복원하거나 새 인스턴스에서 재생성할 수 있도록 합니다.
워크플로 공유: 자격 증명의 비밀 값을 공유하지 않고 팀원이나 다른 팀에 워크플로를 전달합니다.
인스턴스 마이그레이션: 인스턴스를 통합하거나 새 환경을 구성할 때처럼, 한 n8n 인스턴스에서 다른 인스턴스로 워크플로를 이동합니다.

패키지 내보내기#

패키지를 내보내려면 포함할 워크플로의 ID와 함께 내보내기 엔드포인트를 호출하세요. n8n은 해당 워크플로와 자격 증명 스텁이 담긴 .n8np 파일을 반환합니다.

요청 및 응답에 대한 세부 정보는 Public API 참조 문서의 패키지 내보내기를 참고하세요.

동일한 엔드포인트를 감싸는 n8n CLI를 사용하여 패키지를 내보낼 수도 있습니다:

n8n-cli package export --workflow-id=<workflow-id> --output=export.n8np

워크플로 ID 또는 프로젝트 ID 중 하나만 지정하고, 둘 다 지정하지는 마세요.

플래그	설명
`-w, --workflow-id`	포함할 워크플로 ID입니다. 여러 개를 내보내려면 플래그를 반복하세요.
`-p, --project-id`	포함할 프로젝트 ID입니다. 여러 개를 내보내려면 플래그를 반복하세요.
`-o, --output`	패키지를 기록할 파일입니다. 기본값은 `export.n8np`입니다.

--workflow-id 또는 --project-id를 최소 하나 이상 지정하세요. 워크플로를 내보내려면 API 키가 workflow:export 권한 범위를 가지고 있어야 하며, 프로젝트를 내보내려면 project:export 권한 범위가 필요합니다.

패키지 가져오기#

패키지를 가져오려면 .n8np 파일과 함께 다음을 제어하는 옵션을 제공하세요:

워크플로가 어느 프로젝트와 폴더에 들어갈지
동일한 소스 ID를 가진 워크플로가 대상 인스턴스에 이미 존재할 경우 어떻게 처리할지
가져온 워크플로가 원래 ID를 유지할지 아니면 새 ID를 받을지
워크플로가 의존하는 자격 증명을 n8n이 어떻게 매칭할지

전체 옵션 목록은 Public API 참조 문서의 패키지 가져오기를 참고하세요.

동일한 엔드포인트를 감싸는 n8n CLI를 사용하여 패키지를 가져올 수도 있습니다:

n8n-cli package import --file=export.n8np --conflict-policy=fail
n8n-cli package import --file=export.n8np --project=<id> --conflict-policy=new-version
n8n-cli package import --file=export.n8np --conflict-policy=fail --credential-missing-mode=must-preexist

플래그	설명
`--file`	`.n8np` 패키지 파일의 경로입니다. 필수입니다.
`--conflict-policy`	소스 ID를 기준으로 워크플로가 이미 존재할 때 수행할 동작입니다: `new-version`, `fail`, `skip` 중 하나입니다. 필수입니다.
`--project`	대상 프로젝트 ID입니다. 기본값은 개인 프로젝트입니다.
`--folder`	프로젝트 내 대상 폴더 ID입니다. 기본값은 프로젝트 루트입니다.
`--workflow-id-policy`	가져온 워크플로가 소스 ID를 유지할지(`source`) 새 ID를 받을지(`new`)를 지정합니다.
`--credential-matching-mode`	대상 인스턴스에서 자격 증명 참조를 매칭하는 방식입니다(`id-only`, 향후 옵션 추가 예정).
`--credential-missing-mode`	참조된 자격 증명을 해결할 수 없을 때 수행할 동작입니다. 인스턴스 기본값인 `create-stub`은 대상 프로젝트에 빈 자리표시자(placeholder) 자격 증명을 생성합니다. `must-preexist`는 참조된 모든 자격 증명이 이미 존재해야 합니다.

가져오기를 수행하려면 API 키가 workflow:import 권한 범위를 가지고 있어야 합니다. --conflict-policy=fail에서의 워크플로 충돌이나 --credential-missing-mode=must-preexist에서의 미해결 자격 증명처럼 가져오기가 차단되는 경우, 명령은 0이 아닌 상태 코드로 종료되고 차단 원인이 되는 문제를 나열합니다. 기본값인 create-stub 모드에서는 n8n이 가져오기를 차단하는 대신 누락된 자격 증명을 스텁 처리합니다.

자격 증명 가져오기#

현재 이 가져오기 흐름은 자격 증명을 ID로만 매칭하며, 가져오기 전에 자격 증명이 대상 인스턴스에 이미 존재해야 합니다.

n8n 패키지

n8n v2.29

원문 보기

번역일: 2026-06-22

요약

Warning

베타

n8n 인스턴스의 Public API를 통해, 또는 동일한 Public API 엔드포인트를 감싸는 n8n CLI를 통해 n8n 패키지를 가져오고 내보낼 수 있습니다.

알려진 제한 사항#

다음 항목은 아직 n8n 패키지에서 지원되지 않습니다:

서브 워크플로
오류 워크플로
데이터 테이블
폴더
프로젝트

이러한 항목에 대한 지원을 추가하기 위해 작업 중입니다.

패키지에 포함되는 내용#

콘텐츠 개요#

export/
├── manifest.json
└── workflows/
    ├── marketing-agent/
    │   └── workflow.json
    └── personal-ai-assistant/
        └── workflow.json

manifest.json 파일은 패키지의 내용을 다음과 같이 설명합니다:

packageFormatVersion: 패키지 형식의 버전입니다.
exportedAt: n8n이 패키지를 생성한 타임스탬프입니다.
sourceN8nVersion: 패키지를 내보낸 n8n의 버전입니다.
sourceId: 패키지를 내보낸 n8n 인스턴스의 식별자입니다.
workflows: 내보낸 워크플로 목록으로, 각 항목에는 id, name, target(workflows 하위의 디렉터리 경로)이 포함됩니다.
requirements.credentials: 내보낸 워크플로가 사용하는 자격 증명 목록입니다. 각 항목에는 자격 증명의 id, name, type이 있으며, 해당 자격 증명을 사용하는 워크플로들의 ID(usedByWorkflows)를 나열합니다. n8n은 자격 증명의 비밀 값을 패키지에 포함하지 않습니다.

사용 사례#

인스턴스 간에 워크플로를 반복 가능하고 자동화된 방식으로 이동해야 할 때 n8n 패키지를 사용하세요. 일반적인 시나리오는 다음과 같습니다:

CI/CD 파이프라인: 자동화된 파이프라인의 일부로 개발 인스턴스에서 스테이징 또는 프로덕션으로 워크플로를 승격합니다.
백업: 워크플로와 자격 증명 참조를 내보내 나중에 복원하거나 새 인스턴스에서 재생성할 수 있도록 합니다.
워크플로 공유: 자격 증명의 비밀 값을 공유하지 않고 팀원이나 다른 팀에 워크플로를 전달합니다.
인스턴스 마이그레이션: 인스턴스를 통합하거나 새 환경을 구성할 때처럼, 한 n8n 인스턴스에서 다른 인스턴스로 워크플로를 이동합니다.

패키지 내보내기#

요청 및 응답에 대한 세부 정보는 Public API 참조 문서의 패키지 내보내기를 참고하세요.

동일한 엔드포인트를 감싸는 n8n CLI를 사용하여 패키지를 내보낼 수도 있습니다:

n8n-cli package export --workflow-id=<workflow-id> --output=export.n8np

워크플로 ID 또는 프로젝트 ID 중 하나만 지정하고, 둘 다 지정하지는 마세요.

플래그	설명
`-w, --workflow-id`	포함할 워크플로 ID입니다. 여러 개를 내보내려면 플래그를 반복하세요.
`-p, --project-id`	포함할 프로젝트 ID입니다. 여러 개를 내보내려면 플래그를 반복하세요.
`-o, --output`	패키지를 기록할 파일입니다. 기본값은 `export.n8np`입니다.

패키지 가져오기#

패키지를 가져오려면 .n8np 파일과 함께 다음을 제어하는 옵션을 제공하세요:

워크플로가 어느 프로젝트와 폴더에 들어갈지
동일한 소스 ID를 가진 워크플로가 대상 인스턴스에 이미 존재할 경우 어떻게 처리할지
가져온 워크플로가 원래 ID를 유지할지 아니면 새 ID를 받을지
워크플로가 의존하는 자격 증명을 n8n이 어떻게 매칭할지

전체 옵션 목록은 Public API 참조 문서의 패키지 가져오기를 참고하세요.

동일한 엔드포인트를 감싸는 n8n CLI를 사용하여 패키지를 가져올 수도 있습니다:

n8n-cli package import --file=export.n8np --conflict-policy=fail
n8n-cli package import --file=export.n8np --project=<id> --conflict-policy=new-version
n8n-cli package import --file=export.n8np --conflict-policy=fail --credential-missing-mode=must-preexist

플래그	설명
`--file`	`.n8np` 패키지 파일의 경로입니다. 필수입니다.
`--conflict-policy`	소스 ID를 기준으로 워크플로가 이미 존재할 때 수행할 동작입니다: `new-version`, `fail`, `skip` 중 하나입니다. 필수입니다.
`--project`	대상 프로젝트 ID입니다. 기본값은 개인 프로젝트입니다.
`--folder`	프로젝트 내 대상 폴더 ID입니다. 기본값은 프로젝트 루트입니다.
`--workflow-id-policy`	가져온 워크플로가 소스 ID를 유지할지(`source`) 새 ID를 받을지(`new`)를 지정합니다.
`--credential-matching-mode`	대상 인스턴스에서 자격 증명 참조를 매칭하는 방식입니다(`id-only`, 향후 옵션 추가 예정).
`--credential-missing-mode`	참조된 자격 증명을 해결할 수 없을 때 수행할 동작입니다. 인스턴스 기본값인 `create-stub`은 대상 프로젝트에 빈 자리표시자(placeholder) 자격 증명을 생성합니다. `must-preexist`는 참조된 모든 자격 증명이 이미 존재해야 합니다.

자격 증명 가져오기#

현재 이 가져오기 흐름은 자격 증명을 ID로만 매칭하며, 가져오기 전에 자격 증명이 대상 인스턴스에 이미 존재해야 합니다.