n8n 中文文档

使用环境变量管理实例设置

您可以通过环境变量管理部分实例设置,而不是在 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"}]'

设置环境变量

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

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。