n8n 中文文档

外部秘密

提示

Feature availability 功能可用性

外部密钥可用于:

  • n8n Cloud: Enterprise
  • Self-hosted: Enterprise

n8n 支持以下密钥提供商:1Password(使用 Connect Server)、AWS Secrets Manager、Azure Key Vault、GCP Secrets Manager、HashiCorp Vault 和 Infisical。n8n 不支持 HashiCorp Vault Secrets。

  • 从 n8n 2.10.0 开始,您可以为每个密钥提供程序连接多个保管库。旧版本仅支持每个提供商一个保管库。
  • 从 n8n 2.13.0 开始,如果启用,项目编辑者可以在其项目中使用外部密钥,项目管理员还可以管理项目保管库。

存储在外部密钥存储中的凭证仅会在凭据字段中解析,不会在其他支持表达式的字段中解析。

您可以使用外部机密存储来管理 n8n 的凭据[^1]。

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

全球金库

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

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

项目金库

实例管理员可以与特定的项目共享保管库。将保管库分配给项目后,只有该项目的凭据才能引用其机密。您可以选择将 Vault 绑定到单个项目或保持全局。

要更改保管库范围:

  1. 在 n8n 中,转到 Settings 设置 > External Secrets 外部密钥。
  2. 找到要配置的保管库并选择 Edit 编辑。
  3. 在 Share 共享 下,选择以下选项之一:
    • Global 全局:在整个 n8n 实例中共享此保管库。这允许实例中的凭据引用这些密钥。
    • Project 项目:将此保管库限制为特定项目。选择项目后,只有该项目中的凭据可以访问这些密钥。
  4. Save 保存 配置。

将 n8n 连接到您的秘密存储

提示

Secret values 秘密价值观

n8n 仅支持机密的纯文本值,而不支持 JSON 对象。

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

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

1密码

提示

1Password Connect Server required 1 需要密码连接服务器

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

选择一种身份验证方法:

  • IAM User IAM 用户: 提供 IAM 用户的 access key ID 访问密钥 ID、secret access key 秘密访问密钥 和 region 区域。
  • Auto Detect 自动检测: n8n 使用 AWS SDK 默认凭据提供程序链,从 n8n 运行所在的环境中自动查找凭据(例如环境变量、共享凭据文件或 EC2/ECS/EKS 实例角色)。如果 n8n 已在具有 AWS 凭据的环境中运行,可以使用此方法,无需管理长期访问密钥。

无论选择哪种方法,底层 IAM 身份都必须拥有 secretsmanager:ListSecrets、secretsmanager:BatchGetSecretValue 和 secretsmanager:GetSecretValue 权限。

警告

Auto Detect 和使用 Auto Detect 时的密钥范围

n8n 不会为该保管库接收任何凭据输入,而是解析运行环境中可用的身份。这意味着同一 n8n 实例上使用 Auto Detect 配置的每个保管库都会共享同一个 IAM 身份和权限集。您无法为不同的 Auto Detect 保管库分配不同的 IAM 范围(例如,将一个保管库限制为某个项目的密钥,将另一个保管库限制为其他项目的密钥)。

如果需要按保管库、项目或团队限制密钥访问,请改用 IAM User IAM 用户:为每个保管库创建单独的 IAM 用户和访问密钥,并为每个用户附加 ARN 范围策略(请参阅下方按 ARN 限制范围的策略示例)。Auto Detect 最适合单个全局保管库,或所有共享该保管库的项目都应使用相同 AWS 访问权限的设置。

要让 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 密钥保管库

提示

Feature availability 功能可用性

Azure Cloud 设置从 n8n 2.35.0 起可用。早期版本只能连接 Azure Public Cloud。现有配置不受影响:它们会继续使用 Azure Public Cloud。

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

选择托管 Key Vault 的 Azure Cloud 环境。该设置会确定保管库 URL 和 Microsoft Entra 授权主机:

Azure Cloud 保管库 URL 后缀 Entra 授权主机
Azure Public Cloud(默认) vault.azure.net https://login.microsoftonline.com
Azure US Government vault.usgovcloudapi.net https://login.microsoftonline.us
Azure China vault.azure.cn https://login.partner.microsoftonline.cn
Custom 提供完整 URL 提供主机

对于 Azure Public Cloud、Azure US Government 和 Azure China,请提供 Vault Name 保管库名称。n8n 会根据名称和所选云环境的后缀构建保管库 URL。

对于 Custom,请提供完整的 Vault URL(例如 https://my-vault.vault.usgovcloudapi.net),而不是保管库名称。您还可以设置可选的 Authority Host 授权主机(例如 https://login.microsoftonline.us),以便针对其他 Microsoft Entra 授权主机进行身份验证。将 Authority Host 留空以使用默认值(https://login.microsoftonline.com)。Custom 适用于 Azure Stack 或代理环境等设置。

GCP 机密管理器

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

HashiCorp Vault

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

手动 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 <a href="#read-and-list-secrets-at-the-secret-kv-v2-mount" id="read-and-list-secrets-at-the-secret-kv-v2-mount"></a>
path "secret/data/*" {
  capabilities = ["read"]
}
path "secret/metadata/*" {
  capabilities = ["read", "list"]
}

对于 KV v1,您只需要一个策略路径:

# Read and list secrets at the "kv/" KV v1 mount <a href="#read-and-list-secrets-at-the-kv-kv-v1-mount" id="read-and-list-secrets-at-the-kv-kv-v1-mount"></a>
path "kv/*" {
  capabilities = ["read", "list"]
}

Infisical

提示

Feature availability 功能可用性

Infisical 密钥管理支持从 n8n 2.26.0 起可用。

要连接 Infisical,请提供以下信息:

  • Site URL 站点 URL:Infisical 实例的基础 URL。默认为 https://app.infisical.com。仅在你自托管 Infisical 时需要更改。
  • Project ID 项目 ID:要读取密钥的 Infisical 项目 ID。
  • Environment 环境:环境 slug,例如 dev、staging 或 prod。
  • Secret Path 密钥路径:项目内要读取密钥的路径。默认为 /。
  • Authentication Method 身份验证方法:选择 Universal Auth(推荐)或 Access Token。

n8n 建议使用通用身份验证,它使用 Infisical 机器身份。令牌在过期前会自动刷新。

在 Infisical 中,授予机器身份角色以读取目标项目中的机密。内置 Viewer 角色有效,您也可以创建一个自定义角色,向 secrets 授予目标环境和秘密路径上的 Read Value 读取值 和 Describe Secret 描述秘密 权限。请参阅 Infisical 的 项目角色文档。

Universal Auth

提供:

  • Client ID 客户ID:机器身份的客户端ID。
  • Client Secret 客户秘密:机器身份的客户端密钥。

在 Infisical 中,创建一个机器身份,将其附加到具有上述角色的项目中,然后复制客户端 ID 和客户端密钥。请参阅 Infisical 的 通用授权文档。

Access Token

提供:

  • Access Token 访问令牌:机器身份内部发行的令牌。

在 Infisical 中,创建一个机器身份,将其附加到具有上述角色的项目,然后单击 Add Auth Method 并选择 Token Auth。请参阅 Infisical 的 令牌身份验证文档。

在 n8n 凭证中使用机密

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

  1. 创建一个新凭据,或打开一个现有凭据。
  2. 在要使用秘密的字段上:
    1. 将鼠标悬停在字段上。
    2. 选择 Expression 表达。
  3. 在要使用机密的字段中,输入引用机密名称的表达式[^2]: js {{ $secrets.<vault-name>.<secret-name> }} <vault-name> 是您添加存储时输入的名称。将 <secret-name> 替换为它在您的保管库中显示的名称。

在 n8n 环境中使用外部机密

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

例如,您有两个 n8n 实例,一个用于开发,一个用于生产。在您的密钥提供商中,创建一个包含开发和生产两个环境的项目。为每个环境分别生成 token。使用开发环境的 token 连接开发实例,使用生产环境的 token 连接生产实例。

在项目中使用外部机密

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

项目角色的访问权限

提示

Feature availability 功能可用性

向项目编辑者和项目管理员授予外部密钥访问权限的功能从 n8n 2.13.0 起可用。在 n8n 2.13.0 之前,在 RBAC 项目 中使用外部密钥需要 实例所有者或实例管理员 作为项目成员。

从 n8n 2.13.0 开始,实例所有者和管理员可以授予 项目编辑者 和 项目管理员 外部密钥的访问权限。

要启用此功能:

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

启用后,项目编辑者可以:

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

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

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

提示

Global vault access 全球金库访问

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

自定义角色

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

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

两种权限都是独立的。例如,角色可能只需要 Secrets 秘密 权限即可在凭证中使用机密,而无需管理保管库。有关可用范围的完整列表,请参阅 秘密保管库范围。

故障排除

秘密在生产中无法解析

提示

Feature availability 功能可用性

项目编辑者或管理员在启用密钥访问 后,可从 n8n 2.13.0 起在自己的凭据中使用外部密钥。以下限制仅适用于旧版本或选择加入开关关闭时。

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

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

有关保护和共享凭据的其他方式,请参阅管理凭据。

[^1]:在 n8n 中,凭据存储身份验证信息以连接特定的应用程序和服务。使用身份验证信息(用户名和密码、API 密钥、OAuth 密钥等)创建凭据后,您可以使用关联的应用程序节点与服务交互。 [^2]:在 n8n 中,表达式允许您通过执行 JavaScript 代码动态填充节点参数。您可以使用 n8n 表达式语法,使用来自先前节点、其他工作流程或 n8n 环境的数据来定义值,而不是提供静态值。

如果使用 terraform-aws-n8n 模块在 AWS 上部署 n8n,请参阅在 AWS 上配置 Enterprise 功能。

相关资源

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