환경 변수로 인스턴스 설정 관리
n8n v2.25UI를 통해 설정하는 대신, 환경 변수를 통해 인스턴스 설정의 일부를 관리할 수 있습니다. 지원되는 각 영역에는 _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를 다시 false로 설정하면 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가 true가 아니면 아무런 효과가 없습니다. 그룹을 활성화하려면 true로 설정하세요.
인스턴스 소유자#
앱 내 설정 과정 대신 환경 변수를 통해 인스턴스 소유자를 사전 프로비저닝합니다. 설정 후 소유자 이메일을 변경하려면 셀프 호스팅 n8n의 인스턴스 소유자 이메일 변경을 참조하세요.
이 변수는 사전 해시된 bcrypt 값을 기대합니다. 평문 비밀번호를 설정하면 로그인이 중단됩니다.
이 섹션의 내용은 원문 문서를 참조하세요. (instance-owner.md)
SSO#
싱글 사인온은 Business 및 Enterprise 플랜에서 사용할 수 있습니다.
환경 변수를 통해 싱글 사인온을 설정합니다.
활성화 및 공통 설정#
이 섹션의 내용은 원문 문서를 참조하세요. (sso-activation.md)
OIDC#
이 섹션의 내용은 원문 문서를 참조하세요. (sso-oidc.md)
SAML#
N8N_SSO_SAML_METADATA(인라인 XML) 또는 N8N_SSO_SAML_METADATA_URL(URL) 중 하나만 설정하고, 둘 다 설정하지 마세요.
이 섹션의 내용은 원문 문서를 참조하세요. (sso-saml.md)
보안 정책#
MFA 적용 및 개인 공간 제한을 포함하여 환경 변수를 통해 인스턴스 보안 정책을 관리합니다.
이 섹션의 내용은 원문 문서를 참조하세요. (security-policy.md)
로그 스트리밍#
환경 변수를 통해 로그 스트리밍 대상을 관리합니다. 대상별 JSON 형식은 환경 변수를 사용한 설정을 참조하세요.
이 섹션의 내용은 원문 문서를 참조하세요. (log-streaming.md)
MCP#
환경 변수를 통해 인스턴스 수준 MCP 접근을 관리합니다.
이 섹션의 내용은 원문 문서를 참조하세요. (mcp.md)
커뮤니티 패키지#
환경 변수를 통해 설치된 커뮤니티 패키지 세트를 관리합니다. n8n은 매번 시작할 때마다 설치된 패키지를 목록과 대조하여 조정합니다. 관리되는 패키지는 UI를 통해 제거하거나 업데이트할 수 없습니다.
N8N_COMMUNITY_PACKAGES_ENABLED도 true(기본값)로 설정해야 합니다. 커뮤니티 패키지가 비활성화되어 있으면 n8n은 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV를 무시하고 경고를 기록합니다.
이 섹션의 내용은 원문 문서를 참조하세요. (community-packages.md)
통합 예시#
다음 예시는 여섯 가지 영역 모두를 환경 변수로 관리하는 인스턴스를 설정합니다. 인스턴스 소유자를 생성하고, 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"}]'
환경 변수 설정#
환경 변수를 설정하는 지원 방법은 설정 방법을 참조하세요.