跳到主要内容

服务注册配置

DeepSeek V3 中英对照 Advanced Topics Service Registry Configuration

你可以使用 DiscoveryClient（例如来自 Spring Cloud Consul）来定位 Vault 服务器，只需设置 spring.cloud.vault.discovery.enabled=true（默认为 false）。这样做的最终结果是，你的应用需要一个带有适当发现配置的 application.yml（或环境变量）。好处是，只要发现服务是一个固定点，Vault 就可以更改其坐标。默认的服务 ID 是 vault，但你可以在客户端使用 spring.cloud.vault.discovery.serviceId 来更改它。

所有发现客户端实现都支持某种元数据映射（例如，对于Eureka，我们有eureka.instance.metadataMap）。服务的某些附加属性可能需要在其服务注册元数据中进行配置，以便客户端能够正确连接。不提供传输层安全详细信息的服务注册中心需要提供一个scheme元数据条目，将其设置为https或http。如果未配置方案且服务未作为安全服务公开，则配置默认为spring.cloud.vault.scheme，当未设置时，该值为https。

spring.cloud.vault.discovery:
    enabled: true
    service-id: my-vault-service

Vault Client Fail Fast​

在某些情况下，如果服务无法连接到 Vault 服务器，可能需要使其启动失败。若希望实现此行为，请将引导配置属性 spring.cloud.vault.fail-fast=true 设置为 true，客户端将抛出异常并停止运行。

spring.cloud.vault:
    fail-fast: true

Vault Enterprise 命名空间支持​

Vault Enterprise 允许使用命名空间在单个 Vault 服务器上隔离多个 Vault。通过设置 spring.cloud.vault.namespace=… 来配置命名空间，可以在使用 Vault RestTemplate 或 WebClient 时，为每个发出的 HTTP 请求启用命名空间头部 X-Vault-Namespace。

请注意，此功能在 Vault 社区版中不受支持，且对 Vault 操作无影响。

spring.cloud.vault:
    namespace: my-namespace

Vault 客户端 SSL 配置​

SSL可以通过设置各种属性进行声明式配置。你可以设置javax.net.ssl.trustStore来配置JVM范围的SSL设置，或者设置spring.cloud.vault.ssl.trust-store来仅为Spring Cloud Vault Config设置SSL配置。

spring.cloud.vault:
    ssl:
        trust-store: classpath:keystore.jks
        trust-store-password: changeit
        trust-store-type: JKS
        enabled-protocols: TLSv1.2,TLSv1.3
        enabled-cipher-suites: TLS_AES_128_GCM_SHA256

  • trust-store 设置信任库的资源。SSL 安全保护的 Vault 通信将使用指定的信任库验证 Vault SSL 证书。

  • trust-store-password 设置信任库密码

  • trust-store-type 设置信任库类型。支持的值为所有支持的 KeyStore 类型，包括 PEM。

  • enabled-protocols 设置启用的 SSL/TLS 协议列表（自 3.0.2 版本起）。

  • enabled-cipher-suites 设置启用的 SSL/TLS 密码套件列表（自 3.0.2 版本起）。

请注意，只有在类路径中包含 Apache Http Components 或 OkHttp 客户端时，配置 spring.cloud.vault.ssl.* 才会生效。

租约生命周期管理（续租与撤销）​

对于每一个秘密，Vault 都会创建一个租约：包含诸如持续时间、可续期性等信息的元数据。

Vault 承诺数据在给定的持续时间或生存时间（TTL）内有效。一旦租约到期，Vault 可以撤销数据，而秘密的消费者将无法再确定其有效性。

Spring Cloud Vault 在创建登录令牌和密钥之后，会维护一个租约生命周期。也就是说，与租约关联的登录令牌和密钥会在租约到期前被安排续期，直到最终过期。应用程序关闭时会撤销已获取的登录令牌和可续期的租约。

密钥服务和数据库后端（如 MongoDB 或 MySQL）通常会生成可续期的租约，因此在应用程序关闭时，生成的凭据将被禁用。

备注

静态令牌不会更新或撤销。

默认情况下，租约续期和撤销功能是启用的，可以通过将 spring.cloud.vault.config.lifecycle.enabled 设置为 false 来禁用。不建议这样做，因为租约会过期，Spring Cloud Vault 将无法再访问 Vault 或使用生成的凭据的服务，并且在应用程序关闭后，有效的凭据仍保持活动状态。

spring.cloud.vault:
    config.lifecycle:
    	enabled: true
    	min-renewal: 10s
    	expiry-threshold: 1m
    	lease-endpoints: Legacy

  • enabled 控制是否续订与密钥关联的租约并轮换过期的密钥。默认启用。

  • min-renewal 设置续订租约前所需的最短持续时间。此设置可防止续订过于频繁。

  • expiry-threshold 设置过期阈值。租约将在其到期前配置的时间段内被续订。

  • lease-endpoints 设置续订和撤销的端点。对于 0.8 之前的 Vault 版本使用 Legacy，对于之后的版本使用 SysLeases。

  • lease-strategy 设置 LeaseStrategy (DropOnError, RetainOnError, RetainOnIoError) 以控制租约续订时的错误处理。

会话令牌生命周期管理（续期、重新登录和撤销）​

Vault 会话令牌（也称为 LoginToken）与租约非常相似，因为它具有 TTL、最大 TTL，并且可能会过期。一旦登录令牌过期，就无法再使用它与 Vault 进行交互。因此，Spring Vault 附带了一个 SessionManager API，用于命令式和响应式使用。

Spring Cloud Vault 默认维护会话令牌的生命周期。会话令牌采用惰性获取方式，因此实际的登录操作会延迟到首次使用 Vault 的会话绑定功能时执行。一旦 Spring Cloud Vault 获取到会话令牌，就会将其保留直至过期。下次使用会话绑定活动时，Spring Cloud Vault 会重新登录 Vault 并获取新的会话令牌。在应用程序关闭时，如果令牌仍处于活跃状态，Spring Cloud Vault 会撤销该令牌以终止会话。

会话生命周期默认启用，可以通过将 spring.cloud.vault.session.lifecycle.enabled 设置为 false 来禁用。不建议禁用此功能，因为会话令牌可能会过期，届时 Spring Cloud Vault 将无法再访问 Vault。

spring.cloud.vault:
    session.lifecycle:
        enabled: true
        refresh-before-expiry: 10s
        expiry-threshold: 20s

  • enabled 控制是否启用会话生命周期管理以续期会话令牌。默认启用。

  • refresh-before-expiry 控制会话令牌续期的时间点。刷新时间通过从令牌过期时间减去 refresh-before-expiry 来计算。默认为 5 秒。

  • expiry-threshold 设置过期阈值。该阈值代表将会话令牌视为有效的最小 TTL 持续时间。TTL 短于此阈值的令牌将被视为已过期并不再使用。应大于 refresh-before-expiry 以防止令牌过期。默认为 7 秒。