跳到主要内容

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 使用基于 Token 的认证从 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 属性：

名称默认值
host127.0.0.1
port8200
schemehttp
backendsecret
defaultKeyapplication
defaultLabelmain (仅在 enableLabel 设置为 true 时使用)
enableLabelfalse
profileSeparator,
kvVersion1
skipSslValidationfalse
timeout5
namespacenull
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
sh

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

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

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

{
   "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"
         }
      }
   ]
}
json

客户端为让 Config Server 与 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
sh

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

启用按标签搜索​

默认情况下，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.
sh

解密 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
yaml

保险库配置​

设置与 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
yaml

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

属性格式化​

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

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

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

错误处理​

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