환경 변수로 커뮤니티 패키지 관리
n8n v2.25셀프 호스팅 n8n에서는 환경 변수를 통해 설치된 커뮤니티 패키지 목록을 관리할 수 있습니다. N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true로 n8n을 처음 시작하면, n8n은 현재 설치된 커뮤니티 패키지 중 N8N_COMMUNITY_PACKAGES에 포함되지 않은 패키지를 모두 제거합니다.
셀프 호스팅 n8n에서는 환경 변수를 통해 설치된 커뮤니티 패키지 목록을 관리할 수 있습니다. n8n은 매 시작 시 설치된 패키지를 목록과 비교하여 누락된 패키지를 설치하고, 버전을 수정하며, 목록에 없는 패키지를 제거합니다. 이 방법을 사용하면 예를 들어 배포 파이프라인을 통해 고정된 패키지 세트로 인스턴스를 부트스트랩할 수 있습니다.
N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true로 n8n을 처음 시작하면, n8n은 현재 설치된 커뮤니티 패키지 중 N8N_COMMUNITY_PACKAGES에 포함되지 않은 패키지를 모두 제거합니다. UI를 통해 이미 패키지를 관리하고 있다면, 이 변수를 활성화하기 전에 Community nodes 설정 페이지를 확인하고 유지하려는 패키지를 N8N_COMMUNITY_PACKAGES에 추가하세요.
구성#
n8n 인스턴스에 다음 환경 변수를 설정한 후 재시작합니다:
이 섹션의 내용은 원문 문서를 참조하세요. (community-packages.md)
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이 검증된 패키지 레지스트리에서 패키지를 조회하여 해당 버전을 사용합니다. 패키지가 검증되지 않은 경우 npm이 해석하는 버전을 설치하며, 재시작 시 버전을 재조정하지 않습니다. |
checksum |
string | 아니요 | 해석된 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-..." }
]
패키지가 검증된 패키지 레지스트리에 없고 N8N_UNVERIFIED_PACKAGES_ENABLED가 false인 경우, n8n이 시작에 실패합니다. 해당 패키지에 checksum을 지정하거나, N8N_UNVERIFIED_PACKAGES_ENABLED=true로 설정하거나, 검증된 패키지를 선택하세요.
환경 변수를 설정하는 방법은 구성 방법을 참조하세요.
패키지 관리#
패키지를 추가, 제거, 업그레이드 또는 다운그레이드하려면 N8N_COMMUNITY_PACKAGES를 편집하고 n8n을 재시작합니다. n8n은 다음 시작 시 새 목록에 맞게 패키지를 재조정합니다.
노드 개발자는 새 버전에서 호환성을 깨는 변경을 도입할 수 있습니다. 호환성을 깨는 변경이란 이전 기능을 손상시키는 업데이트입니다. 버전을 변경할 때 주의하세요. 새 버전에서 문제가 발생하면 version을 이전 값으로 되돌리고 n8n을 재시작하여 롤백하세요.