使用环境变量管理实例设置
您可以通过环境变量管理部分实例设置,而不是在 UI 中配置它们。当您通过内部部署管道等方式自动配置 n8n 实例时,这非常有用。
每个支持的区域都有一个名为 <AREA>_MANAGED_BY_ENV 的专用环境变量。将该变量设置为 true 可启用该区域的环境变量管理。n8n 随后会应用相关环境变量,并锁定对应的 UI 控件。
工作原理
当您将 <AREA>_MANAGED_BY_ENV 设置为 true 时:
- n8n 在每次启动时重新应用环境变量中的设置。
- 匹配的 UI 控件变为只读。
当 <AREA>_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
提示
设置 <AREA>_MANAGED_BY_ENV 以激活区域
除非 <AREA>_MANAGED_BY_ENV 为 true,否则该区域的其他环境变量不会生效。将它设置为 true 以启用整个区域。
实例所有者
提示
功能可用性
从 n8n 2.17.0 开始,可以通过环境变量进行实例所有者管理。
从环境变量中预先配置 实例所有者,而不是通过应用内设置。要在设置后更改所有者电子邮件,请参阅 更改自托管 n8n 的实例所有者电子邮件。
警告
N8N_INSTANCE_OWNER_PASSWORD_HASH 必须是 bcrypt 哈希
该变量需要一个预先哈希的 bcrypt 值。设置明文密码会中断登录。
| 变量 | 类型 | 默认 | 描述 |
|---|---|---|---|
N8N_INSTANCE_OWNER_MANAGED_BY_ENV |
Boolean | false |
设为 true 后,可通过环境变量管理实例所有者。启用后,n8n 会在每次启动时覆盖下方的实例所有者信息、锁定该用户在 UI 中的相关控件,并拒绝对其进行 API 写入。 |
N8N_INSTANCE_OWNER_EMAIL |
String | - | 实例所有者的邮箱地址。 |
N8N_INSTANCE_OWNER_FIRST_NAME |
String | - | 实例所有者的名字。 |
N8N_INSTANCE_OWNER_LAST_NAME |
String | - | 实例所有者的姓氏。 |
N8N_INSTANCE_OWNER_PASSWORD_HASH |
String | - | 实例所有者密码的 bcrypt 哈希值。填入明文密码会导致无法登录。 |
警告
Owner email must be unique 所有者电子邮件必须是唯一的
N8N_INSTANCE_OWNER_EMAIL 不得已属于实例上的其他用户。此设置更新现有实例所有者帐户;它不会将所有权转让给其他现有用户或合并用户帐户。要使用已属于其他用户的电子邮件地址,请先更改或删除该用户,以便电子邮件可用。
SSO
提示
功能可用性
单点登录可用于:
- 自托管: Business、Enterprise
n8n Cloud Enterprise 也支持单点登录,但不是通过本页所述环境变量。
从 n8n 2.18.0 开始,可以通过环境变量管理 SSO。
通过环境变量配置单点登录。
激活和共享设置
| 变量 | 类型 | 默认 | 描述 |
|---|---|---|---|
N8N_SSO_OIDC_LOGIN_ENABLED |
Boolean | false |
是否启用 OIDC 登录。 |
N8N_SSO_OIDC_CLIENT_ID |
String | - | 身份提供商签发的 OIDC client ID。 |
N8N_SSO_OIDC_CLIENT_SECRET |
String | - | 身份提供商签发的 OIDC client secret。 |
N8N_SSO_OIDC_DISCOVERY_ENDPOINT |
String | - | OIDC 发现端点 URL,也就是身份提供商的 .well-known/openid-configuration URL。 |
N8N_SSO_OIDC_PROMPT |
String | - | 可选的 OIDC prompt 参数,会随授权请求一起发送,例如 login 或 consent。 |
N8N_SSO_OIDC_ACR_VALUES |
String | - | 可选的 OIDC acr_values 参数。可用于请求特定的认证上下文,例如升级 MFA 流程。 |
OIDC
| 变量 | 类型 | 默认 | 描述 |
|---|---|---|---|
N8N_SSO_OIDC_LOGIN_ENABLED |
Boolean | false |
是否启用 OIDC 登录。 |
N8N_SSO_OIDC_CLIENT_ID |
String | - | 身份提供商签发的 OIDC client ID。 |
N8N_SSO_OIDC_CLIENT_SECRET |
String | - | 身份提供商签发的 OIDC client secret。 |
N8N_SSO_OIDC_DISCOVERY_ENDPOINT |
String | - | OIDC 发现端点 URL,也就是身份提供商的 .well-known/openid-configuration URL。 |
N8N_SSO_OIDC_PROMPT |
String | - | 可选的 OIDC prompt 参数,会随授权请求一起发送,例如 login 或 consent。 |
N8N_SSO_OIDC_ACR_VALUES |
String | - | 可选的 OIDC acr_values 参数。可用于请求特定的认证上下文,例如升级 MFA 流程。 |
SAML
警告
SAML 元数据变量是互斥的
设置 N8N_SSO_SAML_METADATA(内联 XML)或 N8N_SSO_SAML_METADATA_URL(URL),而不是同时设置两者。
| 变量 | 类型 | 默认 | 描述 |
|---|---|---|---|
N8N_SSO_SAML_LOGIN_ENABLED |
Boolean | false |
是否启用 SAML 登录。 |
N8N_SSO_SAML_METADATA |
String | - | SAML 身份提供商 metadata 的 XML 字符串。与 N8N_SSO_SAML_METADATA_URL 互斥,不要同时设置。 |
N8N_SSO_SAML_METADATA_URL |
String | - | 用于拉取 SAML 身份提供商 metadata 的 URL。与 N8N_SSO_SAML_METADATA 互斥,不要同时设置。 |
安全策略
提示
功能可用性
从 n8n 2.18.0 开始,可以通过环境变量管理安全策略。
通过环境变量管理实例安全策略,包括 MFA 强制执行和个人空间限制。
| 变量 | 类型 | 默认 | 描述 |
|---|---|---|---|
N8N_SECURITY_POLICY_MANAGED_BY_ENV |
Boolean | false |
设为 true 后,可通过环境变量管理安全策略。启用后,n8n 会在每次启动时应用安全策略相关变量,并锁定对应的 UI 控件。 |
N8N_MFA_ENFORCED_ENABLED |
Boolean | false |
是否对所有用户强制启用双因素认证:true 为强制,false 为不强制。 |
N8N_PERSONAL_SPACE_PUBLISHING_ENABLED |
Boolean | true |
用户是否可以从其个人空间发布工作流:true 为允许,false 为不允许。 |
N8N_PERSONAL_SPACE_SHARING_ENABLED |
Boolean | true |
用户是否可以从其个人空间共享资源:true 为允许,false 为不允许。 |
日志流
提示
功能可用性
从 n8n 2.19.0 开始,可以通过环境变量管理日志流。
通过环境变量管理日志流目标。有关每个目标的 JSON 结构,请参阅使用环境变量进行配置。
| 变量 | 类型 | 默认 | 描述 |
|---|---|---|---|
N8N_LOG_STREAMING_MANAGED_BY_ENV |
Boolean | false |
设为 true 后,可通过环境变量管理日志流。启用后,n8n 会在每次启动时应用日志流相关变量,并锁定对应的 UI 控件。 |
N8N_LOG_STREAMING_DESTINATIONS |
JSON string | - | 日志流目标的 JSON 数组。每个目标都是一个对象,type 可为 webhook、syslog 或 sentry,并附带该类型对应的配置。 |
MCP
提示
功能可用性
从 n8n 2.20.0 开始,可以通过环境变量管理实例级 MCP 访问。
通过环境变量管理实例级 MCP 访问。
| 变量 | 类型 | 默认 | 描述 |
|---|---|---|---|
N8N_INSTANCE_OWNER_MANAGED_BY_ENV |
Boolean | false |
设为 true 后,可通过环境变量管理实例所有者。启用后,n8n 会在每次启动时覆盖下方的实例所有者信息、锁定该用户在 UI 中的相关控件,并拒绝对其进行 API 写入。 |
N8N_INSTANCE_OWNER_EMAIL |
String | - | 实例所有者的邮箱地址。 |
N8N_INSTANCE_OWNER_FIRST_NAME |
String | - | 实例所有者的名字。 |
N8N_INSTANCE_OWNER_LAST_NAME |
String | - | 实例所有者的姓氏。 |
N8N_INSTANCE_OWNER_PASSWORD_HASH |
String | - | 实例所有者密码的 bcrypt 哈希值。填入明文密码会导致无法登录。 |
警告
Owner email must be unique 所有者电子邮件必须是唯一的
N8N_INSTANCE_OWNER_EMAIL 不得已属于实例上的其他用户。此设置更新现有实例所有者帐户;它不会将所有权转让给其他现有用户或合并用户帐户。要使用已属于其他用户的电子邮件地址,请先更改或删除该用户,以便电子邮件可用。
社区包
提示
功能可用性
从 n8n 2.21.0 开始,可以通过环境变量管理已安装的社区包。
通过环境变量管理已安装的社区节点包。n8n 会在每次启动时根据列表协调已安装的软件包。无法通过 UI 卸载或更新受管包。
N8N_COMMUNITY_PACKAGES_ENABLED 还必须设置为 true(默认值)。当禁用社区包时,n8n 会忽略 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV 并记录警告。
| 变量 | 类型 | 默认 | 描述 |
|---|---|---|---|
N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV |
布尔 | false |
设置为 true 以从环境变量管理已安装的社区包。当 true 时,n8n 在每次启动时根据 N8N_COMMUNITY_PACKAGES 协调已安装的软件包,安装丢失的软件包,更正版本和 uninstalling any currently-installed packages that aren't in the list 卸载列表中没有的所有当前安装的软件包。 Community nodes 社区节点 设置页面变为只读:启用此功能后,您无法从 UI 安装、更新或卸载软件包。 |
N8N_COMMUNITY_PACKAGES |
JSON 字符串 | - | 要安装的社区包的 JSON 数组。每个条目都是一个对象,具有 name(必需)以及可选的 version 和 checksum 字段。您还可以将版本嵌入名称中,如 <package-name>@<version>。有关每个字段的完整参考,请参阅环境变量安装。 |
组合示例
以下示例配置一个由环境变量管理全部六个区域的实例:创建实例所有者、配置 OIDC 和 SSO、强制执行 MFA、注册 Webhook 日志流目标、启用 MCP 访问并管理社区包。
# Instance owner <a href="#instance-owner" id="instance-owner"></a>
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 <a href="#sso-using-oidc" id="sso-using-oidc"></a>
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 <a href="#security-policy" id="security-policy"></a>
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 <a href="#log-streaming" id="log-streaming"></a>
export N8N_LOG_STREAMING_MANAGED_BY_ENV=true
export N8N_LOG_STREAMING_DESTINATIONS='[{"type":"webhook","url":"https://logs.example.com/n8n"}]'
# MCP <a href="#mcp" id="mcp"></a>
export N8N_MCP_MANAGED_BY_ENV=true
export N8N_MCP_ACCESS_ENABLED=true
# Community packages <a href="#community-packages" id="community-packages"></a>
export N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV=true
export N8N_COMMUNITY_PACKAGES='[{"name":"n8n-nodes-foo","version":"1.2.3"}]'
设置环境变量
有关设置环境变量的支持方法,请参阅 配置方法。