환경 변수를 통한 설치
n8n v2.29셀프 호스팅 n8n에서는 환경 변수를 사용하여 설치된 커뮤니티 패키지 집합을 관리할 수 있습니다. 이 기능을 활성화하면 목록에 없는 패키지가 제거됩니다 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true로 n8n을 처음 시작하면, n8n은 N8N_COMMUNITY_PACKAGES에 포함되지 않은 현재 설치된 커뮤니티 패키지를 모두 제거합니다.
n8n v2.21.0부터 사용 가능
셀프 호스팅 n8n에서는 환경 변수를 사용하여 설치된 커뮤니티 패키지 집합을 관리할 수 있습니다. n8n은 시작할 때마다 설치된 패키지를 목록과 대조하여 조정하며, 누락된 패키지를 설치하고, 버전을 수정하고, 목록에 없는 패키지를 제거합니다. 예를 들어 배포 파이프라인을 통해 고정된 패키지 집합으로 인스턴스를 부트스트랩할 때 이 방법을 사용하세요.
이 기능을 활성화하면 목록에 없는 패키지가 제거됩니다
N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true로 n8n을 처음 시작하면, n8n은 N8N_COMMUNITY_PACKAGES에 포함되지 않은 현재 설치된 커뮤니티 패키지를 모두 제거합니다. 이미 UI를 통해 패키지를 관리하고 있다면, 이 변수를 활성화하기 전에 Community nodes 설정 페이지를 확인하고 유지하려는 패키지를 N8N_COMMUNITY_PACKAGES에 추가하세요.
구성#
n8n 인스턴스에 다음 환경 변수를 설정한 다음 재시작하세요.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
커뮤니티 패키지가 활성화되어 있어야 합니다
N8N_COMMUNITY_PACKAGES_ENABLED은 true(기본값)여야 합니다. 인스턴스 수준에서 커뮤니티 패키지가 비활성화되어 있으면, n8n은 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV를 무시하고 시작 시 경고를 기록합니다.
예를 들면 다음과 같습니다.
export N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true
export N8N_COMMUNITY_PACKAGES='[{"name":"n8n-nodes-foo","version":"1.2.3"}]'
N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV가 true인 동안에는 Community nodes 설정 페이지가 읽기 전용이 되어, UI에서 패키지를 설치, 업데이트, 제거할 수 없습니다.
패키지별 필드#
| 필드 | 유형 | 필수 여부 | 설명 |
|---|---|---|---|
name |
string | 예 | npm 패키지 이름입니다. <package-name>@<version> 형식으로 버전을 인라인으로 포함할 수 있습니다. 이 경우 version 필드를 다른 값으로 별도 설정하지 마세요. n8n은 충돌하는 버전을 거부합니다. |
version |
string | 아니오 | 버전 지정자입니다. 생략하면 n8n은 검증된 패키지(vetted-packages) 레지스트리에서 해당 패키지를 조회하여 그 버전을 사용합니다. 패키지가 검증되지 않은 경우, n8n은 npm이 확인(resolve)하는 버전을 설치하며 재시작 시에도 버전을 조정하지 않습니다. |
checksum |
string | 아니오 | 확인(resolve)된 tarball의 SHA-512 체크섬(sha512-...)입니다. version이 설정되어 있어야 합니다. n8n은 가능한 경우 검증된 레지스트리에서 체크섬을 자동으로 확인합니다. |
세 필드를 모두 사용한 예시입니다.
[
{ "name": "n8n-nodes-foo", "version": "1.2.3" },
{ "name": "n8n-nodes-bar@0.5.0" },
{ "name": "n8n-nodes-baz", "version": "2.0.0", "checksum": "sha512-..." }
]
검증되지 않은 패키지에는 체크섬이 필요합니다
패키지가 검증된 패키지(vetted-packages) 레지스트리에 없고 N8N_UNVERIFIED_PACKAGES_ENABLED가 false이면, n8n이 시작에 실패합니다. 해당 패키지에 checksum을 고정하거나, N8N_UNVERIFIED_PACKAGES_ENABLED=true를 설정하거나, 검증된 패키지를 선택하세요.
환경 변수를 설정하는 지원되는 방법은 구성 방법을 참조하세요.
패키지 관리#
패키지를 추가, 제거, 업그레이드 또는 다운그레이드하려면 N8N_COMMUNITY_PACKAGES를 수정하고 n8n을 재시작하세요. n8n은 다음 시작 시 새 목록으로 조정합니다.
버전 간 호환성을 깨는 변경 사항
노드 개발자는 노드의 새 버전에서 호환성을 깨는 변경 사항(breaking change)을 도입할 수 있습니다. 호환성을 깨는 변경 사항이란 이전 기능을 손상시키는 업데이트를 말합니다. 버전을 변경할 때는 주의하세요. 새 버전이 문제를 일으키는 경우, version을 이전 값으로 되돌리고 n8n을 재시작하여 롤백하세요.