快速开始

DeepSeek V3 中英对照 Quick Start

本节将介绍如何开始使用 Vault 和 Spring Cloud Vault。

前提条件

要开始使用 Vault 和本指南，你需要一个提供以下功能的类 UNIX 操作系统：

• wget、openssl 和 unzip

• 至少 Java 17 以及正确配置的 JAVA_HOME 环境变量

备注

本指南从 Spring Cloud Vault 的角度解释了用于集成测试的 Vault 设置。您可以直接在 Vault 项目网站上找到入门指南：developer.hashicorp.com/vault/tutorials

安装 Vault

$ wget https://releases.hashicorp.com/vault/${vault_version}/vault_${vault_version}_${platform}.zip
$ unzip vault_${vault_version}_${platform}.zip

备注

这些步骤可以通过下载并运行 install_vault.sh 来完成。

为 Vault 创建 SSL 证书

接下来，你需要生成一组证书：

• 根证书颁发机构

• Vault 证书（解密后的密钥 work/ca/private/localhost.decrypted.key.pem 和证书 work/ca/certs/localhost.cert.pem）

请务必将根证书导入到符合 Java 规范的信任存储中。

实现这一点的最简单方法是使用OpenSSL。

备注

create_certificates.sh 在 work/ca 目录下创建证书，并生成一个 JKS 信任库 work/keystore.jks。如果你想按照本快速入门指南运行 Spring Cloud Vault，需要将 spring.cloud.vault.ssl.trust-store 属性配置为 file:work/keystore.jks 来配置信任库。

启动 Vault 服务器

接下来创建一个类似这样的配置文件：

backend "inmem" {
}

listener "tcp" {
  address = "0.0.0.0:8200"
  tls_cert_file = "work/ca/certs/localhost.cert.pem"
  tls_key_file = "work/ca/private/localhost.decrypted.key.pem"
}

disable_mlock = true

备注

你可以在 vault.conf 找到示例配置文件。

$ vault server -config=vault.conf

Vault 已启动，正在监听 0.0.0.0:8200，使用 inmem 存储和 https。启动时，Vault 处于密封状态且未初始化。

备注

如果你想运行测试，请保持 Vault 未初始化状态。测试将初始化 Vault 并创建根令牌 00000000-0000-0000-0000-000000000000。

如果你想在你的应用中使用 Vault 或尝试它，那么你需要先初始化它。

$ export VAULT_ADDR="https://localhost:8200"
$ export VAULT_SKIP_VERIFY=true # Don't do this for production
$ vault operator init

你应该会看到类似这样的内容：

Key 1: 7149c6a2e16b8833f6eb1e76df03e47f6113a3288b3093faf5033d44f0e70fe701
Key 2: 901c534c7988c18c20435a85213c683bdcf0efcd82e38e2893779f152978c18c02
Key 3: 03ff3948575b1165a20c20ee7c3e6edf04f4cdbe0e82dbff5be49c63f98bc03a03
Key 4: 216ae5cc3ddaf93ceb8e1d15bb9fc3176653f5b738f5f3d1ee00cd7dccbe926e04
Key 5: b2898fc8130929d569c1677ee69dc5f3be57d7c4b494a6062693ce0b1c4d93d805
Initial Root Token: 19aefa97-cccc-bbbb-aaaa-225940e63d76

Vault initialized with 5 keys and a key threshold of 3. Please
securely distribute the above keys. When the Vault is re-sealed,
restarted, or stopped, you must provide at least 3 of these keys
to unseal it again.

Vault does not store the master key. Without at least 3 keys,
your Vault will remain permanently sealed.

Vault 将初始化并返回一组解封密钥和根令牌。选择 3 个密钥来解封 Vault。将 Vault 令牌存储在 VAULT_TOKEN 环境变量中。

$ vault operator unseal (Key 1)
$ vault operator unseal (Key 2)
$ vault operator unseal (Key 3)
$ export VAULT_TOKEN=(Root token)
# Required to run Spring Cloud Vault tests after manual initialization
$ vault token create -id="00000000-0000-0000-0000-000000000000" -policy="root"

Spring Cloud Vault 可以访问不同的资源。默认情况下，secret 后端是启用的，它通过 JSON 端点访问 secret 配置设置。

HTTP 服务以以下形式提供资源：

/secret/{application}/{profile}
/secret/{application}
/secret/{defaultContext}/{profile}
/secret/{defaultContext}

其中，"application" 作为 spring.application.name 注入到 SpringApplication 中（即在常规 Spring Boot 应用中通常为 "application"），"profile" 是活动配置文件（或以逗号分隔的属性列表）。从 Vault 检索的属性将"按原样"使用，无需对属性名称添加额外前缀。

客户端使用

要在应用程序中使用这些功能，只需将其构建为依赖 spring-cloud-vault-config 的 Spring Boot 应用程序（例如，可参考测试用例）。Maven 配置示例如下：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>${springBootVersion}</version>
    <relativePath /> <!-- lookup parent from repository -->
</parent>

<dependencies>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-vault-config</artifactId>
        <version>5.0.1</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

<!-- repositories also needed for snapshots and milestones -->

然后你可以创建一个标准的 Spring Boot 应用，比如这个简单的 HTTP 服务器：

@SpringBootApplication
@RestController
public class Application {

    @RequestMapping("/")
    public String home() {
        return "Hello World!";
    }

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

当它运行时，如果默认的本地 Vault 服务器在端口 8200 上运行，它将从该服务器获取外部配置。要修改启动行为，您可以使用 application.properties 更改 Vault 服务器的位置，例如

spring.cloud.vault:
    host: localhost
    port: 8200
    scheme: https
    uri: https://localhost:8200
    connection-timeout: 5000
    read-timeout: 15000
spring.config.import: vault://

• host 设置 Vault 主机的主机名。主机名将用于 SSL 证书验证

• port 设置 Vault 端口

• scheme 将方案设置为 http 将使用纯 HTTP。支持的方案有 http 和 https

• uri 使用 URI 配置 Vault 端点。优先级高于 host/port/scheme 配置

• connection-timeout 设置连接超时时间（毫秒）

• read-timeout 设置读取超时时间（毫秒）

• spring.config.import 使用所有启用的密钥后端（默认启用键值存储）将 Vault 挂载为 PropertySource

启用更多集成需要额外的依赖项和配置。根据您设置 Vault 的方式，您可能需要额外的配置，例如 SSL 和 身份验证。

如果应用程序导入了 spring-boot-starter-actuator 项目，Vault 服务器的状态将通过 /health 端点提供。

可以通过属性 management.health.vault.enabled 来启用或禁用 vault 健康指示器（默认为 true）。

备注

从 Spring Cloud Vault 3.0 和 Spring Boot 2.4 开始，属性源的引导上下文初始化（bootstrap.yml、bootstrap.properties）已被弃用。取而代之的是，Spring Cloud Vault 更倾向于使用 Spring Boot 的 Config Data API，该 API 允许从 Vault 导入配置。采用 Spring Boot Config Data 方法时，你需要设置 spring.config.import 属性才能绑定到 Vault。你可以在配置数据位置部分了解更多相关信息。你可以通过设置配置属性 spring.cloud.bootstrap.enabled=true 或包含依赖项 org.springframework.cloud:spring-cloud-starter-bootstrap 来启用引导上下文。

身份验证

Vault 需要一个认证机制来授权客户端请求。

Spring Cloud Vault 支持多种认证机制，用于应用程序与 Vault 进行身份验证。

如需快速入门，请使用 Vault 初始化 时打印的根令牌。

spring.cloud.vault:
    token: 19aefa97-cccc-bbbb-aaaa-225940e63d76
spring.config.import: vault://

注意

请仔细考虑您的安全需求。如果您想快速开始使用 Vault，静态令牌认证是可以的，但静态令牌没有进一步的保护措施。任何向非预期方的泄露都会允许使用关联的令牌角色访问 Vault。