환경 변수를 사용하여 인스턴스 설정 관리하기
n8n v2.29UI를 통해 구성하는 대신 환경 변수로 인스턴스 설정의 일부를 관리할 수 있습니다. 지원되는 각 영역에는 _MANAGED_BY_ENV라는 전용 환경 변수가 있습니다. _MANAGED_BY_ENV를 true로 설정하면 다음과 같이 동작합니다.
UI를 통해 구성하는 대신 환경 변수로 인스턴스 설정의 일부를 관리할 수 있습니다. 이는 내부 배포 파이프라인 등을 통해 n8n 인스턴스를 자동으로 프로비저닝할 때 유용합니다.
지원되는 각 영역에는 _MANAGED_BY_ENV라는 전용 환경 변수가 있습니다. 이 변수를 true로 설정하면 해당 영역에 대한 환경 변수 관리가 활성화됩니다. 그러면 n8n이 관련 환경 변수를 적용하고 일치하는 UI 컨트롤을 잠급니다.
작동 방식#
_MANAGED_BY_ENV를 true로 설정하면 다음과 같이 동작합니다.
- n8n이 시작할 때마다 환경 변수의 설정을 다시 적용합니다.
- 일치하는 UI 컨트롤이 읽기 전용이 됩니다.
_MANAGED_BY_ENV가 false(기본값)이면 n8n은 관련 환경 변수를 설정하더라도 무시합니다.
*_MANAGED_BY_ENV를 끄면 값이 유지됩니다
*_MANAGED_BY_ENV를 다시 false로 설정하면 UI 쓰기 권한이 복원되지만, 마지막으로 적용된 값은 그대로 유지됩니다. 값을 변경하려면 이후 UI를 통해 편집하세요.
예상치 못한 읽기 전용 UI 컨트롤
설정이 읽기 전용으로 표시되는데 예상하지 못한 경우, 사용 중인 환경에서 일치하는 *_MANAGED_BY_ENV 변수가 true로 설정되어 있는지 확인하세요.
지원되는 영역과 이를 활성화하는 변수는 다음과 같습니다.
- 인스턴스 소유자:
N8N_INSTANCE_OWNER_MANAGED_BY_ENV - SSO:
N8N_SSO_MANAGED_BY_ENV - 보안 정책:
N8N_SECURITY_POLICY_MANAGED_BY_ENV - 로그 스트리밍:
N8N_LOG_STREAMING_MANAGED_BY_ENV - MCP:
N8N_MCP_MANAGED_BY_ENV - 커뮤니티 패키지:
N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV
그룹을 활성화하려면 _MANAGED_BY_ENV를 설정하세요
_MANAGED_BY_ENV가 true가 아니면 해당 영역의 다른 환경 변수는 아무 효과가 없습니다. 그룹을 활성화하려면 이 값을 true로 설정하세요.
인스턴스 소유자#
n8n v2.17.0부터 제공됩니다
앱 내 설정 과정을 거치는 대신 환경 변수로 인스턴스 소유자를 사전 프로비저닝합니다. 설정 후 소유자 이메일을 변경하려면 셀프 호스팅 n8n의 인스턴스 소유자 이메일 변경을 참고하세요.
N8N_INSTANCE_OWNER_PASSWORD_HASH는 반드시 bcrypt 해시여야 합니다
이 변수는 사전 해시된 bcrypt 값을 필요로 합니다. 평문 비밀번호를 설정하면 로그인이 깨집니다.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
SSO#
n8n v2.18.0부터 제공됩니다
기능 제공 범위
싱글 사인온은 Business 및 Enterprise 플랜에서 제공됩니다.
환경 변수로 싱글 사인온을 구성합니다.
활성화 및 공통 설정#
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
OIDC#
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
SAML#
SAML 메타데이터 변수는 상호 배타적입니다
N8N_SSO_SAML_METADATA(인라인 XML) 또는 N8N_SSO_SAML_METADATA_URL(URL) 중 하나만 설정하고, 둘 다 설정하지 마세요.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
보안 정책#
n8n v2.18.0부터 제공됩니다
MFA 강제 적용 및 개인 공간 제한을 포함하여 환경 변수로 인스턴스 보안 정책을 관리합니다.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
로그 스트리밍#
n8n v2.19.0부터 제공됩니다
환경 변수로 로그 스트리밍 대상을 관리합니다. 대상별 JSON 형식은 환경 변수를 사용하여 구성하기를 참고하세요.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
MCP#
n8n v2.20.0부터 제공됩니다
환경 변수로 인스턴스 수준 MCP 액세스를 관리합니다.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
커뮤니티 패키지#
n8n v2.21.0부터 제공됩니다
환경 변수로 설치된 커뮤니티 패키지 집합을 관리합니다. n8n은 시작할 때마다 설치된 패키지를 목록과 대조하여 조정합니다. 관리 대상 패키지는 UI를 통해 제거하거나 업데이트할 수 없습니다.
N8N_COMMUNITY_PACKAGES_ENABLED도 true(기본값)로 설정되어 있어야 합니다. 커뮤니티 패키지가 비활성화된 경우, n8n은 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV를 무시하고 경고를 기록합니다.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
종합 예제#
다음 예제는 여섯 개 영역 모두를 환경 변수로 관리하도록 인스턴스를 구성합니다. 이 예제는 인스턴스 소유자를 생성하고, OIDC SSO를 구성하고, MFA를 강제하고, 웹훅 로그 스트리밍 대상을 등록하고, MCP 액세스를 활성화하고, 커뮤니티 패키지를 관리합니다.
# Instance owner
export N8N_INSTANCE_OWNER_MANAGED_BY_ENV=true
export N8N_INSTANCE_OWNER_EMAIL=<owner-email>
export N8N_INSTANCE_OWNER_FIRST_NAME=<first-name>
export N8N_INSTANCE_OWNER_LAST_NAME=<last-name>
export N8N_INSTANCE_OWNER_PASSWORD_HASH=<bcrypt-hash>
# SSO using OIDC
export N8N_SSO_MANAGED_BY_ENV=true
export N8N_SSO_USER_ROLE_PROVISIONING=instance_role
export N8N_SSO_OIDC_LOGIN_ENABLED=true
export N8N_SSO_OIDC_CLIENT_ID=<client-id>
export N8N_SSO_OIDC_CLIENT_SECRET=<client-secret>
export N8N_SSO_OIDC_DISCOVERY_ENDPOINT=<discovery-url>
# Security policy
export N8N_SECURITY_POLICY_MANAGED_BY_ENV=true
export N8N_MFA_ENFORCED_ENABLED=true
export N8N_PERSONAL_SPACE_PUBLISHING_ENABLED=false
export N8N_PERSONAL_SPACE_SHARING_ENABLED=false
# Log streaming
export N8N_LOG_STREAMING_MANAGED_BY_ENV=true
export N8N_LOG_STREAMING_DESTINATIONS='[{"type":"webhook","url":"https://logs.example.com/n8n"}]'
# MCP
export N8N_MCP_MANAGED_BY_ENV=true
export N8N_MCP_ACCESS_ENABLED=true
# Community packages
export N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true
export N8N_COMMUNITY_PACKAGES='[{"name":"n8n-nodes-foo","version":"1.2.3"}]'
환경 변수 설정하기#
환경 변수를 설정하는 지원 방법은 구성 방법을 참고하세요.