外部密钥#

功能可用性

外部密钥适用于自托管 Enterprise 和 Cloud Enterprise 计划。
n8n 支持以下密钥提供商：1Password（通过 Connect Server）、AWS Secrets Manager、Azure Key Vault、GCP Secrets Manager 和 HashiCorp Vault。
从 n8n 2.10.0 版本起，您可以为每个密钥提供商连接多个保管库。旧版本仅支持每个提供商一个保管库。
从 2.13.0 版本起，启用后，项目编辑者可以在其项目中使用外部密钥，项目管理员还可以管理项目保管库。
n8n 不支持 HashiCorp Vault Secrets。

Infisical 弃用

Infisical 已弃用。从 2.10.0 版本起，无法连接新的 Infisical 保管库。现有的保管库暂时保留。

您可以使用外部密钥存储来管理 n8n 的凭据。

n8n 默认情况下将所有凭据加密存储在其数据库中，并限制对它们的访问。使用外部密钥功能，您可以将敏感凭据信息存储在外部保管库中，并让 n8n 在需要时加载它。这提供了额外的安全层，并允许您在一个中央位置管理跨多个 n8n 环境使用的凭据。

将 n8n 连接到您的密钥存储#

密钥值

n8n 仅支持密钥的纯文本值，不支持 JSON 对象。

在 n8n 中，转到 Settings 设置 > External Secrets 外部密钥。
点击 Add secrets vault 添加密钥保管库。
为您的保管库输入一个唯一名称。该名称将作为在凭据中使用 {{ $secrets.<vault-name>... }} 表达式引用此保管库时的第一个段。
选择一个受支持的密钥提供商。
输入您提供商的凭据。有关详细信息，请参阅下面的提供商特定部分。
Save 保存 您的配置。

只要此存储保持连接，您就可以在凭据中引用其密钥。

1Password#

需要 1Password Connect Server

n8n 与 1Password Connect Server 集成，这是一个用于机器访问 1Password 的自托管 API。它与个人或团队 1Password 账户不同。您必须部署并运行 Connect Server 才能使用此提供商。

提供您的 Connect Server URL 和 Access Token 访问令牌。Connect Server URL 是您的服务器可访问的地址（例如 http://localhost:8080）。Access Token 是您为 Connect Server 集成创建的令牌。

n8n 会读取该令牌可访问的所有保管库和项目。每个 1Password 项目都会成为一个密钥，其字段可作为属性访问。使用 {{ $secrets.<vault-name>.<item-title>.<field-label> }} 访问特定字段的值。

AWS Secrets Manager#

提供您的 access key ID 访问密钥 ID、secret access key 秘密访问密钥 和 region 区域。IAM 用户必须拥有 secretsmanager:ListSecrets、secretsmanager:BatchGetSecretValue 和 secretsmanager:GetSecretValue 权限。

要让 n8n 访问您 AWS Secrets Manager 中的所有密钥，您可以将以下策略附加到 IAM 用户：

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "AccessAllSecrets",
			"Effect": "Allow",
			"Action": [
				"secretsmanager:ListSecrets",
				"secretsmanager:BatchGetSecretValue",
				"secretsmanager:GetResourcePolicy",
				"secretsmanager:GetSecretValue",
				"secretsmanager:DescribeSecret",
				"secretsmanager:ListSecretVersionIds"
			],
			"Resource": "*"
		}
	]
}

您也可以更严格地控制，让 n8n 仅访问特定的 AWS Secret Manager 密钥。您仍然需要允许 secretsmanager:ListSecrets 和 secretsmanager:BatchGetSecretValue 权限来访问所有资源。这些权限允许 n8n 检索按 ARN 限定范围的密钥，但不提供对密钥值的访问。

接下来，您需要将 secretsmanager:GetSecretValue 权限的范围设置为您希望与 n8n 共享的密钥的特定 Amazon 资源名称（ARN）。确保在每个资源 ARN 中使用正确的区域和账户 ID。您可以在 AWS 控制台的密钥仪表板中找到 ARN 详细信息。

例如，以下 IAM 策略仅允许访问您指定的 AWS 账户和区域中名称以 n8n 开头的密钥：

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Sid": "ListingSecrets",
			"Effect": "Allow",
			"Action": [
				"secretsmanager:ListSecrets",
				"secretsmanager:BatchGetSecretValue"
			],
			"Resource": "*"
		},
		{
			"Sid": "RetrievingSecrets",
			"Effect": "Allow",
			"Action": [
				"secretsmanager:GetSecretValue",
				"secretsmanager:DescribeSecret"
			],
			"Resource": [
				"arn:aws:secretsmanager:us-west-2:123456789000:secret:n8n*"
			]
		}
	]
}

有关更多 IAM 权限策略示例，请参阅 AWS 文档。

Azure Key Vault#

提供您的 vault name 保管库名称、tenant ID 租户 ID、client ID 客户端 ID 和 client secret 客户端密钥。请参阅 Azure 文档以注册 Microsoft Entra ID 应用并创建服务主体。n8n 仅支持密钥的单行值。

GCP Secrets Manager#

提供一个具有至少以下角色的服务账户的 Service Account Key 服务账户密钥（JSON）：Secret Manager Secret Accessor 和 Secret Manager Secret Viewer。有关更多信息，请参阅 Google 的服务账户文档。

HashiCorp Vault#

提供您保管库实例的 Vault URL，并选择您的 Authentication Method 认证方法。输入您的认证详细信息。可选提供命名空间。

有关您的认证方法，请参阅 HashiCorp 文档：
如果您使用保管库命名空间，可以输入 n8n 应连接到的命名空间。有关 HashiCorp Vault 命名空间的更多信息，请参阅 Vault Enterprise 命名空间。

手动 KV 挂载配置#

默认情况下，n8n 通过读取 sys/mounts 自动发现 KV 密钥引擎。如果您的 Vault 令牌没有访问 sys/mounts 的权限，您可以手动指定 KV 引擎挂载路径和版本：

KV Mount Path KV 挂载路径：您的 KV 密钥引擎的挂载路径（例如 secret/）。设置后，n8n 会跳过 sys/mounts 自动发现并直接使用此路径。留空则使用自动发现。
KV Version KV 版本：KV 引擎版本（v1 或 v2）。默认为 v2。仅在指定 KV Mount Path KV 挂载路径 时适用。

您的 Vault 令牌仍然需要对 KV 路径本身的读取和列表访问权限。以下示例展示了在 secret/ 挂载的 KV v2 的最小 Vault 策略：

# Read and list secrets at the "secret/" KV v2 mount
path "secret/data/*" {
  capabilities = ["read"]
}
path "secret/metadata/*" {
  capabilities = ["read", "list"]
}

对于 KV v1，您只需要一个策略路径：

# Read and list secrets at the "kv/" KV v1 mount
path "kv/*" {
  capabilities = ["read", "list"]
}

共享保管库#

默认情况下，密钥保管库是全局的：整个实例中的用户都可以使用引用该保管库密钥的凭据。

Instance admins can share a vault with a specific project. Once you assign a vault to a project, only that project’s credentials can reference its secrets. You can choose to tie a vault to a single project or keep it global.

要更改保管库范围：

在 n8n 中，转到 Settings 设置 > External Secrets 外部密钥。
找到要配置的保管库并选择 Edit 编辑。
在 Share 共享 下，选择以下选项之一：
- Global 全局：在您的整个 n8n 实例中共享此保管库。这允许整个实例中的凭据引用这些密钥。
- Project 项目：将此保管库限制到特定项目。选择某个项目会将密钥访问限制为仅该项目的凭据。
Save 保存 您的配置。

在 n8n 凭据中使用密钥#

要在 n8n 凭据中使用存储中的密钥：

创建新凭据或打开现有凭据。
在您要使用密钥的字段上：
1. 悬停在字段上。
2. 选择表达式。
在您要使用密钥的字段中，输入引用密钥名称的表达式：
1
{{ $secrets.<vault-name>.<secret-name> }}
<vault-name> 是您添加存储时输入的名称。将 <secret-name> 替换为它在您的保管库中显示的名称。

在 n8n 环境中使用外部密钥#

n8n 的源代码控制和环境功能允许您创建由 Git 支持的不同 n8n 环境。该功能不支持在不同实例中使用不同的凭据。您可以使用外部密钥保管库为不同环境提供不同凭据，方法是将每个 n8n 实例连接到不同的保管库或项目环境。 \ 例如，您有两个 n8n 实例，一个用于开发，一个用于生产。在您的密钥提供商中，创建一个具有两个环境（开发和生产）的项目。为每个环境生成一个令牌。使用开发环境的令牌连接您的开发 n8n 实例，使用生产环境的令牌连接您的生产 n8n 实例。

在项目中使用外部密钥#

您可以将保管库共享给项目，以便只有该项目的凭据可以引用其密钥。设置步骤请参阅共享保管库。项目范围的保管库从 2.11.0 版本起可用。

项目角色的访问权限#

2.13.0 及更高版本

在 2.13.0 版本之前，在 RBAC 项目中使用外部密钥需要实例所有者或实例管理员作为项目成员。

从 2.13.0 版本起，实例所有者和管理员可以授予项目编辑者和项目管理员访问外部密钥的权限。

要启用此功能：

转到 Settings 设置 > External Secrets 外部密钥。
开启 Enable external secrets for project roles 为项目角色启用外部密钥。

启用后，项目编辑者可以：

查看与项目共享的可用外部密钥保管库（在 Project 项目 > Settings 设置 中）。
在凭据中使用项目保管库中的密钥。

项目管理员拥有相同的访问权限，此外还可以：

为项目创建新的保管库（在 Project 项目 > Settings 设置 中）。
更新和删除分配给项目的保管库。

全局保管库访问

在 Settings 设置 > External Secrets 外部密钥 中创建的全局保管库在 Project 项目 > Settings 设置 中可见，但对项目角色为只读。只有实例管理员可以修改或删除全局保管库。

自定义角色#

要进行更细粒度的访问控制，实例所有者和管理员可以创建自定义项目角色。转到 Settings 设置 > Project roles 项目角色 > Create role 创建角色。在权限列表中，配置：

Secrets vaults 密钥保管库：控制保管库管理（创建、查看、编辑、删除和同步保管库）。
Secrets 密钥：控制该角色是否可以在凭据表达式中使用密钥。

两个权限是独立的。例如，一个角色可能只需要 Secrets 密钥 权限来在凭据中使用密钥，而不需要管理保管库。有关可用范围的完整列表，请参阅密钥保管库范围。

故障排除#

密钥在生产环境中无法解析#

2.13.0 及更高版本

从 2.13.0 版本起，启用了密钥访问权限的项目编辑者和管理员可以在自己的凭据中使用外部密钥。以下限制仅适用于旧版本或未开启此选项时。

在 2.13.0 之前的版本中（或当 Enable external secrets for project roles 为项目角色启用外部密钥 关闭时），只有实例所有者和管理员可以在运行时解析密钥。如果所有者或管理员使用密钥表达式更新了其他用户的凭据，它可能在预览中正常工作但在生产环境中失败。

在这种情况下，请仅在实例所有者或管理员拥有的凭据中使用外部密钥。