跳到主要内容

通过环境变量管理实例设置

可以通过环境变量管理部分实例设置，无需在界面中配置。自动创建 n8n 实例时，例如通过内部部署流水线，这种方式很有用。

每个支持的配置领域都有一个名为 <AREA>_MANAGED_BY_ENV 的专用环境变量。将其设为 true，即可启用该领域的环境变量管理。之后，n8n 会应用相关环境变量，并锁定对应的界面控件。

工作原理 ​

将 <AREA>_MANAGED_BY_ENV 设为 true 后：

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

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

信息

关闭 *_MANAGED_BY_ENV 后仍会保留原值

将 *_MANAGED_BY_ENV 改回 false，会恢复界面的修改权限，但保留最后一次应用的值。之后如需修改，请通过界面编辑。

信息

界面控件意外变为只读

如果某项设置意外显示为只读，请检查环境中对应的 *_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_ENVBooleanfalse设为 true，通过环境变量管理实例所有者。当值为 true 时，n8n 会在每次启动时覆盖下方的实例所有者信息，锁定该用户的界面控件，并拒绝通过 API 修改。
N8N_INSTANCE_OWNER_EMAILString-实例所有者的电子邮件地址。
N8N_INSTANCE_OWNER_FIRST_NAMEString-实例所有者的名。
N8N_INSTANCE_OWNER_LAST_NAMEString-实例所有者的姓。
N8N_INSTANCE_OWNER_PASSWORD_HASHString-实例所有者密码的 bcrypt 哈希值。设置明文密码会导致无法登录。
注意

所有者邮箱必须唯一

N8N_INSTANCE_OWNER_EMAIL 不能已属于实例中的其他用户。此设置更新现有实例所有者账号，不会将所有权转移给其他现有用户，也不会合并账号。要使用已属于其他用户的邮箱，请先更改或删除该用户，释放邮箱。

SSO ​

信息

功能可用范围

单点登录可用于：

  • **自托管：**商业版、企业版。

n8n Cloud Enterprise 也支持单点登录，但不通过本页的环境变量配置。

自 n8n 2.18.0 起，支持通过环境变量管理 SSO。

通过环境变量配置单点登录。

启用与共享设置 ​

变量类型默认值说明
N8N_SSO_MANAGED_BY_ENVBooleanfalse设为 true，通过环境变量管理 SSO。当值为 true 时，n8n 会在每次启动时应用 SSO 变量，并锁定对应的界面控件。
N8N_SSO_USER_ROLE_PROVISIONING枚举字符串：disabled、instance_role、instance_and_project_rolesdisabledn8n 为通过 SSO 登录的用户配置角色的方式。disabled 不配置任何角色；instance_role 仅配置实例级角色；instance_and_project_roles 同时配置实例角色和项目角色。

OIDC ​

变量类型默认值说明
N8N_SSO_OIDC_LOGIN_ENABLEDBooleanfalse是否启用 OIDC 登录。
N8N_SSO_OIDC_CLIENT_IDString-身份提供商签发的 OIDC 客户端 ID。
N8N_SSO_OIDC_CLIENT_SECRETString-身份提供商签发的 OIDC 客户端密钥。
N8N_SSO_OIDC_DISCOVERY_ENDPOINTString-OIDC 发现端点 URL，即身份提供商的 .well-known/openid-configuration URL。
N8N_SSO_OIDC_PROMPTString-可选的 OIDC prompt 参数，随授权请求发送，例如 login 或 consent。
N8N_SSO_OIDC_ACR_VALUESString-可选的 OIDC acr_values 参数，用于请求特定身份验证上下文，例如需要升级验证的 MFA 流程。

SAML ​

注意

SAML 元数据变量互斥

设置 N8N_SSO_SAML_METADATA（直接提供 XML）或 N8N_SSO_SAML_METADATA_URL（URL）中的一个，不要同时设置。

变量类型默认值说明
N8N_SSO_SAML_LOGIN_ENABLEDBooleanfalse是否启用 SAML 登录。
N8N_SSO_SAML_METADATAString-以 XML 字符串提供的 SAML 身份提供商元数据。与 N8N_SSO_SAML_METADATA_URL 互斥，不要同时设置。
N8N_SSO_SAML_METADATA_URLString-用于获取 SAML 身份提供商元数据的 URL。与 N8N_SSO_SAML_METADATA 互斥，不要同时设置。

安全策略 ​

信息

功能可用范围

自 n8n 2.18.0 起，支持通过环境变量管理安全策略。

通过环境变量管理实例安全策略，包括强制多因素身份验证（MFA）和个人空间限制。

变量类型默认值说明
N8N_SECURITY_POLICY_MANAGED_BY_ENVBooleanfalse设为 true，通过环境变量管理安全策略。当值为 true 时，n8n 会在每次启动时应用安全策略变量，并锁定对应的界面控件。
N8N_MFA_ENFORCED_ENABLEDBooleanfalse是否强制所有用户使用双因素身份验证：true 表示强制，false 表示不强制。
N8N_PERSONAL_SPACE_PUBLISHING_ENABLEDBooleantrue是否允许用户从个人空间发布：true 表示允许，false 表示不允许。
N8N_PERSONAL_SPACE_SHARING_ENABLEDBooleantrue是否允许用户从个人空间共享资源：true 表示允许，false 表示不允许。

日志流 ​

信息

功能可用范围

自 n8n 2.19.0 起，支持通过环境变量管理日志流。

通过环境变量管理日志流的目标。各类目标的 JSON 结构请参阅通过环境变量配置。

变量类型默认值说明
N8N_LOG_STREAMING_MANAGED_BY_ENVBooleanfalse设为 true，通过环境变量管理日志流。当值为 true 时，n8n 会在每次启动时应用日志流变量，并锁定对应的界面控件。
N8N_LOG_STREAMING_DESTINATIONSJSON 字符串-日志流目标的 JSON 数组。每个目标是一个对象，包含 type 字段，其值为 webhook、syslog 或 sentry，以及该类型对应的配置。

MCP ​

信息

功能可用范围

自 n8n 2.20.0 起，支持通过环境变量管理实例级 MCP 访问。

通过环境变量管理实例级 MCP 访问。

变量类型默认值说明
N8N_MCP_MANAGED_BY_ENVBooleanfalse设为 true，通过环境变量管理 MCP 设置。当值为 true 时，n8n 会在每次启动时应用 MCP 变量，并锁定对应的界面控件。
N8N_MCP_ACCESS_ENABLEDBooleanfalse是否启用实例级 MCP 访问：true 表示启用，false 表示禁用。

社区节点包 ​

信息

功能可用范围

自 n8n 2.21.0 起，支持通过环境变量管理已安装的社区节点包。

通过环境变量管理已安装的社区节点包集合。n8n 会在每次启动时，根据列表校正已安装的包。受管理的包无法通过界面卸载或更新。

N8N_COMMUNITY_PACKAGES_ENABLED 也必须设为 true，即默认值。禁用社区节点包时，n8n 会忽略 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV 并记录警告。

变量类型默认值说明
N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENVBooleanfalse设为 true，通过环境变量管理已安装的社区节点包。当值为 true 时，n8n 会在每次启动时根据 N8N_COMMUNITY_PACKAGES 校正已安装的包：安装缺失的包、纠正版本，并卸载当前已安装但不在列表中的所有包。**Community nodes（社区节点）**设置页会变为只读，启用期间无法通过界面安装、更新或卸载包。
N8N_COMMUNITY_PACKAGESJSON 字符串-要安装的社区节点包的 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"}]'

设置环境变量 ​

支持的环境变量设置方式请参阅配置方式。

相关资源 ​

本文为社区中文翻译。查看对应英文原文