Skip to content

使用环境变量管理实例设置(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 four 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

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

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

实例所有者(Instance owner)#

Available from n8n v2.17.0

预先从环境变量中预置实例所有者，而不是通过应用内设置进行配置。

🌐 Pre-provision the instance owner from environment variables instead of going through the in-app setup.

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.

单点登录(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.

组合示例(Combined example)#

以下示例配置了一个实例，其所有四个区域均由环境变量管理。它创建实例所有者，配置 OIDC 单点登录，强制使用多因素认证，并注册 webhook 日志流目标。

🌐 The following example configures an instance with all four areas managed by environment variables. It creates the instance owner, configures OIDC SSO, enforces MFA, and registers a webhook log streaming destination.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 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"}]'

设置环境变量(Set environment variables)#

有关支持的设置环境变量的方法，请参见配置方法。

🌐 For the supported ways to set environment variables, see Configuration methods.