外部密钥(External secrets)#

功能可用性

外部密钥在企业自托管和企业云计划中可用。
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 的凭据。

🌐 You can use an external secrets store to manage credentials for n8n.

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

🌐 n8n stores all credentials encrypted in its database, and restricts access to them by default. With the external secrets feature, you can store sensitive credential information in an external vault, and have n8n load it in when required. This provides an extra layer of security and allows you to manage credentials used across multiple n8n environments in one central place.

全球金库(Global vaults)#

默认情况下，秘密保险库是全局的：实例中的用户可以使用引用该保险库中秘密的凭据。

🌐 By default, a secrets vault is global: users across the instance can use credentials that reference secrets from that vault.

在个人项目中，只有实例所有者和管理员可以使用凭据中全局金库的机密。

🌐 In personal projects, only instance owners and admins can use secrets from global vaults in credentials.

项目金库(Project vaults)#

实例管理员可以将保管库与特定的项目共享。一旦你将保管库分配给一个项目，只有该项目的凭据才能引用其秘密。你可以选择将保管库绑定到单个项目，或者保持其全局性。

🌐 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.

要更改保险库范围：

🌐 To change the vault scope:

在 n8n 中，前往设置 > 外部密钥。
找到你想配置的保险库，然后选择编辑。
在共享下，选择以下选项之一：
- 全局：在整个 n8n 实例中共享此保险库。这允许实例中的凭证引用这些秘密。
- 项目：将此保险库限制到特定项目。选择一个项目会将秘密访问限制为仅该项目的凭据。
保存你的配置。

将 n8n 连接到你的密钥库(Connect n8n to your secrets store)#

秘密值

n8n 仅支持明文值作为密钥，而不支持 JSON 对象。

在 n8n 中，前往设置 > 外部密钥。
点击 添加秘密库。
为你的保险库输入一个唯一名称。当在凭证中的 {{ $secrets.<vault-name>... }} 表达式引用此保险库时，这将是第一个部分。
选择一个支持的秘密提供者。
输入你的提供商凭据。有关详细信息，请参阅下面的特定提供商部分。
保存你的配置。

只要此存储已连接，你就可以在凭据中引用其秘密。

🌐 As long as this store is connected, you can reference its secrets in credentials.

1Password#

需要 1Password Connect 服务器

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

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

🌐 Provide your Connect Server URL and Access Token. The Connect Server URL is the address where your server is accessible (for example, http://localhost:8080). The Access Token is the token you created for the Connect Server integration.

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

AWS 密钥管理器(AWS Secrets Manager)#

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

🌐 Provide your access key ID, secret access key, and region. The IAM user must have the secretsmanager:ListSecrets, secretsmanager:BatchGetSecretValue, and secretsmanager:GetSecretValue permissions.

要授予 n8n 对 AWS Secrets Manager 中所有密钥的访问权限，你可以将以下策略附加到 IAM 用户：

🌐 To give n8n access to all secrets in your AWS Secrets Manager, you can attach the following policy to the IAM user:

{
	"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 范围的密钥，但不会提供对密钥值的访问权限。

🌐 You can also be more restrictive and give n8n access to select specific AWS Secret Manager secrets. You still need to allow the secretsmanager:ListSecrets and secretsmanager:BatchGetSecretValue permissions to access all resources. These permissions allow n8n to retrieve ARN-scoped secrets, but don't provide access to the secret values.

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

🌐 Next, you need set the scope for the secretsmanager:GetSecretValue permission to the specific Amazon Resource Names (ARNs) for the secrets you wish to share with n8n. Ensure you use the correct region and account ID in each resource ARNs. You can find the ARN details in the AWS dashboard for your secrets.

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

🌐 For example, the following IAM policy only allows access to secrets with a name starting with n8n in your specified AWS account and region:

{
	"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 文档。

🌐 For more IAM permission policy examples, consult the AWS documentation.

Azure 密钥保管库(Azure Key Vault)#

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

🌐 Provide your vault name, tenant ID, client ID, and client secret. Refer to the Azure documentation to register a Microsoft Entra ID app and create a service principal. n8n supports only single-line values for secrets.

GCP 密钥管理器(GCP Secrets Manager)#

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

🌐 Provide a Service Account Key (JSON) for a service account that has at least these roles: Secret Manager Secret Accessor and Secret Manager Secret Viewer. Refer to Google's service account documentation for more information.

HashiCorp Vault#

提供你的保险库实例的 Vault URL，并选择你的 身份验证方法。输入你的身份验证详细信息。可选地提供命名空间。

🌐 Provide the Vault URL for your vault instance, and select your Authentication Method. Enter your authentication details. Optionally provide a namespace.

请参阅 HashiCorp 文档以了解你的身份验证方法：
如果你使用 Vault 命名空间，你可以输入 n8n 应该连接的命名空间。有关 HashiCorp Vault 命名空间的更多信息，请参阅 Vault Enterprise 命名空间。

手动 KV 安装配置(Manual KV mount configuration)#

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

🌐 By default, n8n autodiscovers KV secret engines by reading sys/mounts. If your Vault token doesn't have access to sys/mounts, you can manually specify the KV engine mount path and version instead:

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

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

🌐 Your Vault token still needs read and list access to the KV path itself. The following example shows a minimal Vault policy for a KV v2 mount at secret/:

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

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

🌐 For KV v1, you only need a single policy path:

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

在 n8n 凭据中使用密钥(Use secrets in n8n credentials)#

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

🌐 To use a secret from your store in an n8n credential:

创建新的凭据，或打开现有凭据
在要使用密钥的字段中：
1. 鼠标悬停在字段上。
2. 选择 表达式。
在你想要使用秘密的字段中，输入引用该秘密名称的表达式：
1
{{ $secrets.<vault-name>.<secret-name> }}
<vault-name> is the one you entered when you added the store. Replace <secret-name> with the name as it appears in your vault.

在 n8n 环境中使用外部密钥(Using external secrets with n8n environments)#

n8n 的源代码控制和环境功能允许你创建不同的 n8n 环境，并由 Git 支持。该功能不支持在不同实例中使用不同的凭据。你可以使用外部秘密管理库来为不同环境提供不同的凭据，通过将每个 n8n 实例连接到不同的管理库或项目环境来实现。

🌐 n8n's Source control and environments feature allows you to create different n8n environments, backed by Git. The feature doesn't support using different credentials in different instances. You can use an external secrets vault to provide different credentials for different environments by connecting each n8n instance to a different vault or project environment.

例如，你有两个 n8n 实例，一个用于开发，一个用于生产。在你的秘密提供者中，创建一个包含两个环境的项目：开发和生产。为你的秘密提供者的每个环境生成一个令牌。使用开发环境的令牌连接你的开发 n8n 实例，使用生产环境的令牌连接你的生产 n8n 实例。

🌐 For example, you have two n8n instances, one for development and one for production. In your secrets provider, create a project with two environments, development and production. Generate a token for each environment of your secrets provider. Use the token for the development environment to connect your development n8n instance, and the token for your production environment to connect your production n8n instance.

在项目中使用外部密钥(Using external secrets in projects)#

你可以将保险库与项目共享，以便只有该项目的凭据可以引用其密钥。有关设置步骤，请参阅项目保险库。项目范围的保险库从版本 2.11.0 开始可用。

🌐 You can share a vault with a project so that only that project's credentials can reference its secrets. Refer to Project vaults for setup steps. Project-scoped vaults are available from version 2.11.0.

项目角色访问权限(Access for project roles)#

版本 2.13.0 及更高版本

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

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

🌐 From version 2.13.0, instance owners and admins can grant project editors and project admins access to external secrets.

要启用此功能：

🌐 To enable this:

前往设置 > 外部密钥。
打开 为项目角色启用外部密钥。

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

🌐 When enabled, Project Editors can:

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

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

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

全球金库访问

在设置 > 外部密钥 中创建的全局保管库可以在项目 > 设置中看到，但对项目角色来说是只读的。只有实例管理员可以修改或删除全局保管库。

自定义角色(Custom roles)#

为了实现更细粒度的访问控制，实例所有者和管理员可以创建一个自定义项目角色。前往设置 > 项目角色 > 创建角色。在权限列表中，进行以下配置：

🌐 For more fine-grained access control, instance owners and admins can create a custom project role. Go to Settings > Project roles > Create role. In the list of permissions, configure:

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

这两种权限是独立的。例如，一个角色可能只需要 Secrets 权限即可在凭据中使用密钥，而无需管理保管库。有关可用作用域的完整列表，请参阅 Secret vault scopes。

🌐 Both permissions are independent. For example, a role may need only the Secrets permission to use secrets in credentials without managing vaults. Refer to Secret vault scopes for the full list of available scopes.

故障排除(Troubleshooting)#

秘密不会在生产中解决(Secrets don't resolve in production)#

版本 2.13.0 及更高版本

从版本 2.13.0 起，拥有启用机密访问权限的项目编辑者和管理员可以在自己的凭据中使用外部机密。以下限制仅适用于较早的版本或当选择加入开关关闭时。

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

🌐 In versions before 2.13.0 (or when Enable external secrets for project roles is off), only instance owners and admins can resolve secrets at runtime. If an owner or admin updates another user's credential with a secrets expression, it may appear to work in preview but fail in production.

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

🌐 In this case, only use external secrets in credentials owned by an instance owner or admin.