使用环境变量管理实例设置(Manage instance settings using environment variables)#

你可以通过环境变量管理部分实例设置，而不是通过用户界面进行配置。当你自动部署 n8n 实例时（例如通过内部部署管道），这非常有用。

🌐 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.

每个支持的区域都有一个名为 <AREA>_MANAGED_BY_ENV 的专用环境变量。将此变量设置为 true 可激活该区域的环境变量管理。n8n 然后会应用相关的环境变量并锁定匹配的 UI 控件。

🌐 Each supported area has a dedicated environment variable named <AREA>_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)#

当你将 <AREA>_MANAGED_BY_ENV 设置为 true 时：

🌐 When you set <AREA>_MANAGED_BY_ENV to true:

n8n 会在每次启动时重新应用环境变量中的设置。
匹配的用户界面控件变为只读。

当 <AREA>_MANAGED_BY_ENV 是 false（默认值）时，n8n 会忽略相关的环境变量，即使你设置了它们。

🌐 When <AREA>_MANAGED_BY_ENV is false (the default), n8n ignores the related environment variables, even if you set them.

关闭 *_MANAGED_BY_ENV 时，值仍然存在

将 *_MANAGED_BY_ENV 设置回 false 会恢复 UI 写入权限，但会保留上次应用的值。如果你想修改这些值，可以之后通过 UI 进行编辑。

意外的只读 UI 控件

如果某个设置显示为只读，而你没有预料到，请检查你环境中相应的 *_MANAGED_BY_ENV 变量是否为 true。

支持的区域及其激活变量：

🌐 The supported areas and their activating variables:

实例所有者：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

将 <AREA>_MANAGED_BY_ENV 设置为激活该组

除非 <AREA>_MANAGED_BY_ENV 为 true，否则一个区域的其他环境变量没有效果。将其设置为 true 以激活该组。

实例所有者(Instance owner)#

Available from n8n v2.17.0

预先从环境变量中配置实例所有者，而不是通过应用内设置进行配置。设置完成后要更改所有者邮箱，请参阅为自托管 n8n 更改实例所有者邮箱。

🌐 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.

N8N_INSTANCE_OWNER_PASSWORD_HASH 必须是一个 bcrypt 哈希

此变量期望一个预先哈希的 bcrypt 值。设置明文密码会导致登录失败。

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.

Owner email must be unique

N8N_INSTANCE_OWNER_EMAIL must not already belong to another user on the instance. This setting updates the existing instance owner account; it doesn't transfer ownership to another existing user or merge user accounts. To use an email address that already belongs to another user, change or delete that user first so the email becomes available.

单点登录(SSO)#

Available from n8n v2.18.0

功能可用性

单点登录适用于商务和企业计划。

从环境变量配置单点登录。

🌐 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.

开放ID连接(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#

SAML 元数据变量是互斥的

请设置 N8N_SSO_SAML_METADATA（内联 XML）或 N8N_SSO_SAML_METADATA_URL（URL），但不能同时设置两者。

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)#

Available from n8n v2.18.0

通过环境变量管理实例安全策略，包括多因素认证强制执行和个人空间限制。

🌐 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)#

Available from n8n v2.19.0

通过环境变量管理日志流目标。有关每个目标的 JSON 格式，请参阅使用环境变量配置。

🌐 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#

Available from n8n v2.20.0

从环境变量管理实例级 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)#

Available from n8n v2.21.0

通过环境变量管理已安装的社区包集合。n8n 在每次启动时都会将已安装的包与列表进行对比。通过管理的包无法通过 UI 卸载或更新。

🌐 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 也必须设置为 true（默认值）。当社区包被禁用时，n8n 会忽略 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV 并记录警告。

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)#

以下示例配置了一个实例，其中所有六个区域都由环境变量管理。它创建了实例所有者，配置了 OIDC 单点登录，强制执行 MFA，注册了一个 webhook 日志流目的地，启用 MCP 访问，并管理了一个社区软件包。

🌐 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.