Skip to content

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

你可以通过环境变量管理一部分实例设置，而不是只通过 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。

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

  • Instance owner 实例所有者：N8N_INSTANCE_OWNER_MANAGED_BY_ENV
  • SSO: N8N_SSO_MANAGED_BY_ENV
  • Security policy 安全策略：N8N_SECURITY_POLICY_MANAGED_BY_ENV
  • Log streaming 日志流：N8N_LOG_STREAMING_MANAGED_BY_ENV
  • MCP: N8N_MCP_MANAGED_BY_ENV
  • Community packages 社区包：N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV

需要先设置 <AREA>_MANAGED_BY_ENV 才会启用整组变量

某个区域的其他环境变量只有在 <AREA>_MANAGED_BY_ENV 为 true 时才会生效。请先将它设为 true 以激活该组配置。

实例所有者#

自 n8n v2.17.0 起可用

你可以通过环境变量预配置实例所有者，而不必在应用内完成初始化设置。

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 哈希值。填入明文密码会导致无法登录。

SSO#

自 n8n v2.18.0 起可用

功能可用性

单点登录仅在 Business 和 Enterprise 计划中可用。

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

激活与共享设置#

变量 类型 默认值 说明
N8N_SSO_MANAGED_BY_ENV Boolean false 设为 true 后，可通过环境变量管理 SSO。启用后，n8n 会在每次启动时应用 SSO 相关变量，并锁定对应的 UI 控件。
N8N_SSO_USER_ROLE_PROVISIONING Enum string: disabled, instance_role, instance_and_project_roles disabled n8n 如何为通过 SSO 登录的用户配置角色。disabled 不会配置任何角色；instance_role 仅配置实例级角色；instance_and_project_roles 同时配置实例角色和项目角色。

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 metadata 变量互斥

请在 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 v2.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 v2.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 v2.20.0 起可用

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

变量 类型 默认值 说明
N8N_MCP_MANAGED_BY_ENV Boolean false 设为 true 后，可通过环境变量管理 MCP 设置。启用后，n8n 会在每次启动时应用 MCP 相关变量，并锁定对应的 UI 控件。
N8N_MCP_ACCESS_ENABLED Boolean false 是否启用实例级 MCP 访问：true 为启用，false 为禁用。

社区包#

自 n8n v2.21.0 起可用

通过环境变量管理已安装的社区包集合。n8n 会在每次启动时根据该列表与当前安装状态进行对账。被环境变量管理的包无法通过 UI 卸载或更新。

N8N_COMMUNITY_PACKAGES_ENABLED 也必须设为 true（默认值）。如果实例级别禁用了社区包，n8n 会忽略 N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV 并记录一条警告日志。

变量 类型 默认值 说明
N8N_COMMUNITY_PACKAGES_MANAGED_BY_ENV Boolean false 设为 true 后，可通过环境变量管理已安装的社区包。启用后，n8n 会在每次启动时根据 N8N_COMMUNITY_PACKAGES 对已安装包进行对账：安装缺失的包、修正版本，并且卸载所有未出现在列表中的当前已安装包。Community nodes 社区节点设置页会变为只读，启用期间无法在 UI 中安装、更新或卸载包。
N8N_COMMUNITY_PACKAGES JSON string - 要安装的社区包 JSON 数组。每一项都是一个对象，包含 name（必填）以及可选的 version 和 checksum 字段。你也可以把版本直接写进名称中，格式为 <package-name>@<version>。每个字段的完整说明请参阅环境变量安装。

组合示例#

以下示例展示了如何把这六个区域都交给环境变量管理。它会创建实例所有者、配置 OIDC SSO、强制启用 MFA、注册一个 webhook 日志流目标、启用 MCP 访问，并管理一个社区包。

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

设置环境变量#

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