Vault 后端

DeepSeek V3 中英对照 Vault Backend

Spring Cloud Config Server 也支持 Vault 作为后端。

Vault 是一个用于安全访问密钥的工具。密钥可以是任何您希望严格控制访问权限的内容，例如 API 密钥、密码、证书和其他敏感信息。Vault 为所有密钥提供了一个统一的接口，同时提供严格的访问控制并记录详细的审计日志。

有关 Vault 的更多信息，请参阅 Vault 快速入门指南。

要让配置服务器使用 Vault 后端，你可以使用 vault 配置文件来运行配置服务器。例如，在配置服务器的 application.properties 文件中，你可以添加 spring.profiles.active=vault。

默认情况下，Spring Cloud Config Server 使用基于令牌的身份验证从 Vault 获取配置。Vault 还支持其他身份验证方法，如 AppRole、LDAP、JWT、CloudFoundry、Kubernetes Auth。为了使用除 TOKEN 或 X-Config-Token 头之外的任何身份验证方法，我们需要在类路径中包含 Spring Vault Core，以便 Config Server 可以将身份验证委托给该库。请将以下依赖项添加到您的 Config Server 应用中。

Maven (pom.xml)

<dependencies>
	<dependency>
		<groupId>org.springframework.vault</groupId>
		<artifactId>spring-vault-core</artifactId>
	</dependency>
</dependencies>

Gradle (build.gradle)

dependencies {
    implementation "org.springframework.vault:spring-vault-core"
}

默认情况下，配置服务器假定您的 Vault 服务器运行在 [127.0.0.1:8200](http://127.0.0.1:8200)。它还假定后端名称为 secret，密钥为 application。所有这些默认值都可以在配置服务器的 application.properties 文件中进行配置。下表描述了可配置的 Vault 属性：

名称	默认值
host	127.0.0.1
port	8200
scheme	http
backend	secret
fullKeyPath	false
defaultKey	application
defaultLabel	main (仅在 enableLabel 设置为 true 时使用)
enableLabel	false
profileSeparator	,
kvVersion	1
skipSslValidation	false
timeout	5
namespace	null

important

上表中所有属性都必须以 spring.cloud.config.server.vault 为前缀，或放置在复合配置的正确 Vault 部分中。

所有可配置属性均可在 org.springframework.cloud.config.server.environment.VaultEnvironmentProperties 中找到。

important

Vault 0.10.0 引入了版本化的键值后端（k/v 后端版本 2），它暴露的 API 与早期版本不同，现在需要在挂载路径和实际上下文路径之间添加 data/，并将密钥包装在 data 对象中。设置 spring.cloud.config.server.vault.kv-version=2 将考虑到这一点。

可选地，支持 Vault Enterprise 的 X-Vault-Namespace 头。要将其发送到 Vault，请设置 namespace 属性。

当配置服务器运行时，你可以向服务器发送 HTTP 请求，从 Vault 后端检索值。为此，你需要一个 Vault 服务器的令牌。

首先，在你的 Vault 中放置一些数据，如下例所示：

$ vault kv put secret/application foo=bar baz=bam
$ vault kv put secret/myapp foo=myappsbar

其次，向您的配置服务器发起 HTTP 请求以获取值，如下例所示：

$ curl -X "GET" "http://localhost:8888/myapp/default" -H "X-Config-Token: yourtoken"

您应该会看到类似以下的响应：

{
   "name":"myapp",
   "profiles":[
      "default"
   ],
   "label":null,
   "version":null,
   "state":null,
   "propertySources":[
      {
         "name":"vault:myapp",
         "source":{
            "foo":"myappsbar"
         }
      },
      {
         "name":"vault:application",
         "source":{
            "baz":"bam",
            "foo":"bar"
         }
      }
   ]
}

客户端向配置服务器提供必要认证以使其能与 Vault 通信的默认方式是设置 X-Config-Token 请求头。然而，您也可以省略该请求头，并通过设置与 Spring Cloud Vault 相同的配置属性，在服务器端配置认证。需要设置的属性是 spring.cloud.config.server.vault.authentication。它应设置为受支持的认证方法之一。您可能还需要根据所使用的认证方法设置其他特定属性，这些属性名称与 spring.cloud.vault 文档中记录的相同，但需使用 spring.cloud.config.server.vault 前缀。更多详细信息，请参阅 Spring Cloud Vault 参考指南。

important

如果您省略了 X-Config-Token 头信息，并使用服务器属性来设置身份验证，那么 Config Server 应用程序需要额外依赖 Spring Vault 来启用额外的身份验证选项。关于如何添加该依赖，请参阅 Spring Vault 参考指南。

多个属性源

在使用 Vault 时，你可以为应用程序提供多个属性源。例如，假设你已将数据写入 Vault 的以下路径：

secret/myApp,dev
secret/myApp
secret/application,dev
secret/application

写入 secret/application 的属性可供所有使用配置服务器的应用程序使用。名为 myApp 的应用程序可以访问写入 secret/myApp 和 secret/application 的任何属性。当 myApp 启用了 dev 配置文件时，写入上述所有路径的属性都可供其使用，列表中第一个路径的属性优先级高于其他路径。

消除复合属性源的歧义

默认情况下，配置服务器会根据保险库密钥生成属性源名称，例如上例中的 vault:myApp。当复合保险库后端具有相同的保险库密钥时，配置服务器客户端将覆盖先前的属性源。

当 fullKeyPath 设置为 true 时，属性源将包含完整的后端路径，例如 vault:secret/backendA/myApp 和 vault:secret/backendB/myApp，从而防止覆盖之前的属性源。

spring.cloud.config.server.composite:
  - type: vault
    fullKeyPath: true
    # ...
    backend: secret/backendA
  - type: vault
    fullKeyPath: true
    # ...
    backend: secret/backendB

启用按标签搜索

默认情况下，Vault后端在搜索密钥时不使用标签。您可以通过将enableLabel功能标志设置为true来更改此行为，并可选择设置defaultLabel。当未提供defaultLabel时，将使用main。

当 enableLabel 功能标志开启时，Vault 中的密钥路径应始终包含所有三个部分（应用名称、配置文件和标签）。因此，上一节中的示例在启用功能标志后，将变为：

secret/myApp,dev,myLabel
secret/myApp,default,myLabel       # default profile
secret/application,dev,myLabel     # default application name
secret/application,default,myLabel # default application name and default profile.

解密属性源中的 Vault 密钥

Spring Cloud Config Server 支持通过使用特殊占位符前缀 {vault} 来解密来自 Vault 的属性。此功能允许在运行时直接从 Vault 动态解析敏感配置属性。

配置步骤

所有与 Vault 集成的配置设置都应放置在您的 application.yml 或 application.properties 文件中。以下是激活 Vault 配置文件、连接到您的 Vault 服务器以及使用 {vault} 前缀格式化属性所需的具体配置。

启用 Vault 配置文件

激活您的 Spring Cloud Config Server 的 Vault 配置文件：

spring:
  profiles:
    active: vault

保险库配置

设置与您的 Vault 服务器的连接，并提供必要的身份验证详细信息：

spring:
  cloud:
    config:
      server:
        vault:
          host: vault.example.com
          port: 8200
          scheme: https
          backend: secret
          defaultKey: application
          kvVersion: 2
          authentication: TOKEN
          token: ${VAULT_TOKEN}
          skipSslValidation: true

这些设置指定了 Vault 服务器地址、身份验证方法以及访问 Vault 所需的令牌。

属性格式化

使用 {vault} 前缀定义属性，以指定用于检索机密的 Vault 路径和密钥：

some:
  sensitive:
    value: '{vault}:path/to/secret#key'

这种格式直接映射到 Vault 中存储密钥的位置 (path/to/secret) 以及要检索的特定密钥键 (key)。

错误处理

如果配置服务器在解密过程中遇到任何问题，例如路径错误、访问问题或密钥缺失，受影响的属性将被添加 invalid. 前缀，其值将被设置为 <n/a>。这种方法类似于处理带有 {cipher} 前缀的属性，但它是专门为与 Vault 集成而设计的，在解密失败时提供清晰的反馈。