部署与运维
Manage settings using environment variables
You can manage a subset of instance settings from environment variables, instead of configuring them through the UI. This is useful when you provision n8n instances automatically, such as through an internal deployment pipeline.
Each supported area has a dedicated environment variable named _MANAGED_BY_ENV. Set this variable to true to activate environment variable management for that area. n8n then applies the related environment variables and locks the matching UI controls.
How it works
When you set _MANAGED_BY_ENV to true:
- n8n reapplies the settings from environment variables on every startup.
- The matching UI controls become read-only.
When _MANAGED_BY_ENV is false (the default), n8n ignores the related environment variables, even if you set them.
The supported areas and their activating variables:
- Instance owner:
N8N_INSTANCE_OWNER_MANAGED_BY_ENV - SSO:
N8N_SSO_MANAGED_BY_ENV - Security policy:
N8N_SECURITY_POLICY_MANAGED_BY_ENV - Log streaming:
N8N_LOG_STREAMING_MANAGED_BY_ENV - MCP:
N8N_MCP_MANAGED_BY_ENV - Community packages:
N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV
Instance owner
Pre-provision the instance owner from environment variables instead of going through the in-app setup. To change the owner email after setup, see Change the instance owner email for self-hosted n8n.
| Variable | Type | Default | Description |
|---|---|---|---|
N8N_INSTANCE_OWNER_MANAGED_BY_ENV |
Boolean | false |
Set to true to manage the instance owner from environment variables. When true, n8n overwrites the instance owner details below on every startup, locks the UI control for that user, and rejects API writes. |
N8N_INSTANCE_OWNER_EMAIL |
String | - | Email address for the instance owner. |
N8N_INSTANCE_OWNER_FIRST_NAME |
String | - | First name for the instance owner. |
N8N_INSTANCE_OWNER_LAST_NAME |
String | - | Last name for the instance owner. |
N8N_INSTANCE_OWNER_PASSWORD_HASH |
String | - | Bcrypt hash of the instance owner's password. Setting a plaintext password breaks login. |
SSO
Configure single sign-on from environment variables.
Activation and shared settings
| Variable | Type | Default | Description |
|---|---|---|---|
N8N_SSO_MANAGED_BY_ENV |
Boolean | false |
Set to true to manage SSO from environment variables. When true, n8n applies the SSO variables on every startup and locks the matching UI controls. |
N8N_SSO_USER_ROLE_PROVISIONING |
Enum string: disabled, instance_role, instance_and_project_roles |
disabled |
How n8n provisions roles for users who sign in through SSO. disabled doesn't provision any roles. instance_role provisions the instance-level role only. instance_and_project_roles provisions both instance and project roles. |
OIDC
| Variable | Type | Default | Description |
|---|---|---|---|
N8N_SSO_OIDC_LOGIN_ENABLED |
Boolean | false |
Whether to enable OIDC login. |
N8N_SSO_OIDC_CLIENT_ID |
String | - | OIDC client ID issued by your identity provider. |
N8N_SSO_OIDC_CLIENT_SECRET |
String | - | OIDC client secret issued by your identity provider. |
N8N_SSO_OIDC_DISCOVERY_ENDPOINT |
String | - | OIDC discovery endpoint URL (the .well-known/openid-configuration URL for your identity provider). |
N8N_SSO_OIDC_PROMPT |
String | - | Optional OIDC prompt parameter to send with the authorization request, for example login or consent. |
N8N_SSO_OIDC_ACR_VALUES |
String | - | Optional OIDC acr_values parameter. Use this to request a specific authentication context, for example a step-up MFA flow. |
SAML
| Variable | Type | Default | Description |
|---|---|---|---|
N8N_SSO_SAML_LOGIN_ENABLED |
Boolean | false |
Whether to enable SAML login. |
N8N_SSO_SAML_METADATA |
String | - | SAML identity provider metadata as an XML string. Mutually exclusive with N8N_SSO_SAML_METADATA_URL; don't set both. |
N8N_SSO_SAML_METADATA_URL |
String | - | URL to fetch SAML identity provider metadata from. Mutually exclusive with N8N_SSO_SAML_METADATA; don't set both. |
Security policy
Manage the instance security policy from environment variables, including MFA enforcement and personal space restrictions.
| Variable | Type | Default | Description |
|---|---|---|---|
N8N_SECURITY_POLICY_MANAGED_BY_ENV |
Boolean | false |
Set to true to manage the security policy from environment variables. When true, n8n applies the security policy variables on every startup and locks the matching UI controls. |
N8N_MFA_ENFORCED_ENABLED |
Boolean | false |
Whether to enforce two-factor authentication for all users (true) or not (false). |
N8N_PERSONAL_SPACE_PUBLISHING_ENABLED |
Boolean | true |
Whether users can publish from their personal space (true) or not (false). |
N8N_PERSONAL_SPACE_SHARING_ENABLED |
Boolean | true |
Whether users can share resources from their personal space (true) or not (false). |
Log streaming
Manage log streaming destinations from environment variables. See Configure using environment variables for the per-destination JSON shape.
| Variable | Type | Default | Description |
|---|---|---|---|
N8N_LOG_STREAMING_MANAGED_BY_ENV |
Boolean | false |
Set to true to manage log streaming from environment variables. When true, n8n applies the log streaming variables on every startup and locks the matching UI controls. |
N8N_LOG_STREAMING_DESTINATIONS |
JSON string | - | JSON array of log streaming destinations. Each destination is an object with a type of webhook, syslog, or sentry, plus the configuration for that type. |
MCP
Manage instance-level MCP access from environment variables.
| Variable | Type | Default | Description |
|---|---|---|---|
N8N_MCP_MANAGED_BY_ENV |
Boolean | false |
Set to true to manage MCP settings from environment variables. When true, n8n applies the MCP variables on every startup and locks the matching UI controls. |
N8N_MCP_ACCESS_ENABLED |
Boolean | false |
Whether to enable instance-level MCP access (true) or not (false). |
Community packages
Manage the set of installed community packages from environment variables. n8n reconciles the installed packages against the list on every startup. Managed packages can't be uninstalled or updated through the UI.
N8N_COMMUNITY_PACKAGES_ENABLED must also be set to true (the default). When community packages are disabled, n8n ignores N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV and logs a warning.
| Variable | Type | Default | Description |
|---|---|---|---|
N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV |
Boolean | false |
Set to true to manage installed community packages from environment variables. When true, n8n reconciles the installed packages against N8N_COMMUNITY_PACKAGES on every startup, installing missing packages, correcting versions, and uninstalling any currently-installed packages that aren't in the list. The Community nodes settings page becomes read-only: you can't install, update, or uninstall packages from the UI while this is enabled. |
N8N_COMMUNITY_PACKAGES |
JSON string | - | JSON array of community packages to install. Each entry is an object with a name (required) and optional version and checksum fields. You can also embed the version in the name as <package-name>@<version>. See environment variable installation for the full per-field reference. |
Combined example
The following example configures an instance with all six areas managed by environment variables. It creates the instance owner, configures OIDC SSO, enforces MFA, registers a webhook log streaming destination, enables MCP access, and manages a community package.
# 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"}]'Set environment variables
For the supported ways to set environment variables, see Configuration methods.
官方原文和授权
本页来自 N8N 英文官方网站固定快照，并转换成 xueai 静态页面。内容以 N8N 持续更新的官方页面为准。