要在应用程序中使用这些功能，您可以将其构建为一个依赖于 spring-cloud-config-client 的 Spring Boot 应用程序（例如，参见 config-client 的测试用例或示例应用程序）。添加依赖项最方便的方法是使用 Spring Boot 启动器 org.springframework.cloud:spring-cloud-starter-config。Maven 用户还有一个父 pom 和 BOM（spring-cloud-starter-parent），Gradle 和 Spring CLI 用户还有一个 Spring IO 版本管理属性文件。以下示例显示了一个典型的 Maven 配置

现在您可以创建一个标准的 Spring Boot 应用程序，例如以下 HTTP 服务器

当这个 HTTP 服务器运行时，它会从默认的本地配置服务器（如果正在运行）在 8888 端口获取外部配置。要修改启动行为，您可以通过使用 application.properties 来更改配置服务器的位置，如下所示

默认情况下，如果没有设置应用程序名称，将使用 application。要修改名称，可以将以下属性添加到 application.properties 文件中

Config Server 属性会作为高优先级属性源出现在 `/env` 端点中，如下所示。

名为 `configserver:<远程仓库 URL>/<文件名>` 的属性源包含值为 `bar` 的 `foo` 属性。

您应该在哪里存储 Config Server 的配置数据？管理此行为的策略是 `EnvironmentRepository`，它提供 `Environment` 对象。此 `Environment` 是 Spring `Environment` 领域的浅拷贝（主要特征是包含 `propertySources`）。`Environment` 资源由三个变量参数化

仓库实现通常表现得像一个 Spring Boot 应用程序，从与 {application} 参数相等的 `spring.config.name` 和与 {profiles} 参数相等的 `spring.profiles.active` 中加载配置文件。配置文件的优先级规则与常规 Spring Boot 应用程序中相同：活动配置文件优先于默认配置，如果存在多个配置文件，则最后一个配置文件获胜（类似于向 `Map` 中添加条目）。

以下示例客户端应用程序具有此引导配置

(与常规 Spring Boot 应用程序一样，这些属性也可以通过环境变量或命令行参数设置)。

如果仓库是基于文件的，服务器会从 `application.yml`（所有客户端共享）和 `foo.yml`（`foo.yml` 优先）创建一个 `Environment`。如果 YAML 文件内部有指向 Spring 配置文件的文档，则这些配置文件的优先级更高（按列出的配置文件顺序）。如果存在特定于配置文件的 YAML（或 properties）文件，这些文件的优先级也高于默认文件。更高的优先级意味着在 `Environment` 中更早列出的 `PropertySource`。（这些相同的规则也适用于独立的 Spring Boot 应用程序）。

您可以将 `spring.cloud.config.server.accept-empty` 设置为 `false`，以便在找不到应用程序时服务器返回 HTTP 404 状态。默认情况下，此标志设置为 `true`。

Config Server 自带一个健康检查指示器，用于检查配置的 EnvironmentRepository 是否正常工作。默认情况下，它会向 EnvironmentRepository 请求名为 app、profile 为 default 以及由 EnvironmentRepository 实现提供的默认 label 的应用程序。

您可以配置健康检查指示器以检查更多应用程序以及自定义 profile 和自定义 label，如下例所示：

您可以通过将 management.health.config.enabled 设置为 false 来禁用健康检查指示器。

此外，您可以通过设置属性 spring.cloud.config.server.health.down-health-status（默认值为 DOWN）来提供自定义的 down 状态。

您可以以对您有意义的任何方式保护您的 Config Server（从物理网络安全到 OAuth2 bearer 令牌），因为 Spring Security 和 Spring Boot 支持许多安全安排。

要使用默认的 Spring Boot 配置的 HTTP Basic 安全性，请在 classpath 中包含 Spring Security（例如，通过 spring-boot-starter-security）。默认用户名为 user，密码是随机生成的。随机密码在实践中用途不大，因此我们建议您配置密码（通过设置 spring.security.user.password）并对其进行加密（有关如何执行此操作的说明，请参阅下文）。

如果远程属性源包含加密内容（值以 {cipher} 开头），它们将在通过 HTTP 发送给客户端之前被解密。这种设置的主要优点是属性值在“静止”时（例如，在 git 仓库中）无需明文。如果某个值无法解密，它将从属性源中移除，并添加一个具有相同 key 但前缀为 invalid 且值为“不适用”（通常为 <n/a>）的附加属性。这主要是为了防止密文被用作密码并意外泄露。

如果您为 config client 应用程序设置远程配置仓库，它可能包含类似以下的 application.yml：

application.properties 文件中的加密值不得用引号括起来。否则，该值将不会被解密。以下示例显示了有效的格式：

您可以安全地将此明文推送到共享 git 仓库，秘密密码将得到保护。

服务器还暴露了 /encrypt 和 /decrypt 端点（假定这些端点是安全的，并且仅由授权代理访问）。如果您编辑远程配置文件，可以使用 Config Server 通过向 /encrypt 端点发送 POST 请求来加密值，如下例所示：

反向操作也通过 /decrypt 可用（前提是服务器配置了对称 key 或完整的密钥对），如下例所示：

将加密值加上 {cipher} 前缀，然后将其放入 YAML 或 properties 文件中，再提交并推送到远程（可能不安全）存储。

/encrypt 和 /decrypt 端点也接受 /*/{application}/{profiles} 形式的路径，当客户端调用主环境资源时，可用于按应用程序（名称）和按 profile 控制加密。

spring 命令行客户端（安装了 Spring Cloud CLI 扩展）也可以用于加密和解密，如以下示例所示

要在文件中使用密钥（例如用于加密的 RSA 公钥），请在密钥值前加上 "@" 并提供文件路径，如以下示例所示

Config Server 可以使用对称（共享）密钥或非对称密钥（RSA 密钥对）。非对称密钥在安全性方面更优越，但使用对称密钥通常更方便，因为在 application.properties 中只需要配置一个属性值。

要配置对称密钥，您需要将 encrypt.key 设置为一个秘密字符串（或使用 ENCRYPT_KEY 环境变量以避免将其暴露在纯文本配置文件中）。

要配置非对称密钥，请使用密钥库（例如，通过 JDK 自带的 keytool 工具创建）。密钥库属性是 encrypt.keyStore.*，其中 * 等于

加密使用公钥完成，解密需要私钥。因此，原则上，如果您只想加密（并准备好自己在本地用私钥解密），您可以在服务器中仅配置公钥。实际上，您可能不想在本地解密，因为它将密钥管理过程分散到所有客户端，而不是集中在服务器中。另一方面，如果您的配置服务器相对不安全，并且只有少数客户端需要加密属性，那么这是一个有用的选项。

要创建用于测试的密钥库，可以使用类似于以下内容的命令

将 server.jks 文件放在类路径中（例如），然后在 Config Server 的 bootstrap.yml 中，创建以下设置

除了加密属性值中的 {cipher} 前缀之外，Config Server 还会查找在（Base64 编码的）密文开始之前的零个或多个 {name:value} 前缀。这些密钥被传递给 TextEncryptorLocator，它可以执行所需的任何逻辑来为密文定位一个 TextEncryptor。如果您配置了密钥库（encrypt.keystore.location），默认的定位器会查找由 key 前缀提供的别名密钥，其密文类似于

定位器查找名为 "testkey" 的密钥。也可以在前缀中使用 {secret:…​} 值来提供秘密。但是，如果未提供秘密，默认是使用密钥库密码（这是您构建密钥库且未指定秘密时获得的结果）。如果您提供了秘密，则还应该使用自定义的 SecretLocator 来加密秘密。

当密钥仅用于加密少量配置数据（即未在其他地方使用）时，从加密角度来看，密钥轮换几乎没有必要。但是，您可能偶尔需要更改密钥（例如，在安全漏洞事件中）。在这种情况下，所有客户端都需要更改其源代码配置文件（例如，在 git 中），并在所有密文中使用新的 {key:…​} 前缀。请注意，客户端需要首先检查密钥别名在 Config Server 密钥库中是否可用。

有时您希望客户端在本地解密配置，而不是在服务器中进行。在这种情况下，如果您提供了用于定位密钥的 encrypt.* 配置，您仍然可以拥有 /encrypt 和 /decrypt 端点，但您需要在 bootstrap.[yml|properties] 中明确关闭对出站属性的解密，方法是设置 spring.cloud.config.server.encrypt.enabled=false。如果您不关心这些端点，只需不配置密钥或启用标志即可。

环境端点提供的默认 JSON 格式非常适合 Spring 应用程序使用，因为它直接映射到 Environment 抽象。如果您愿意，可以通过向资源路径添加后缀（".yml"、".yaml" 或 ".properties"）来以 YAML 或 Java 属性格式使用相同的数据。这对于不关心 JSON 端点结构或其提供额外元数据的应用程序（例如，不使用 Spring 的应用程序）可能很有用，因为这种方法更简单。

YAML 和属性表示有一个额外的标志（作为布尔查询参数 resolvePlaceholders 提供），用于指示在可能的情况下，应在渲染输出之前解析源文档中的占位符（采用标准的 Spring ${…​} 形式）。这对于不了解 Spring 占位符约定的消费者来说是一个有用的功能。

除了使用 Environment 抽象（或其 YAML 或属性格式的替代表示）之外，您的应用程序可能还需要根据其环境定制的通用纯文本配置文件。Config Server 通过 /{application}/{profile}/{label}/{path} 的额外端点提供这些文件，其中 application、profile 和 label 与常规环境端点具有相同的含义，而 path 是指向文件名的路径（例如 log.xml）。此端点的源文件的查找方式与环境端点相同。属性文件和 YAML 文件使用相同的搜索路径。但是，不会聚合所有匹配的资源，只会返回第一个匹配的资源。

找到资源后，将使用提供的应用程序名称、配置文件和标签的有效 Environment 来解析正常格式（${…​}）的占位符。通过这种方式，资源端点与环境端点紧密集成。

目前，Spring Cloud Config 可以为 git、SVN、原生后端和 AWS S3 提供纯文本。对 git、SVN 和原生后端的支持是相同的。AWS S3 的工作方式略有不同。以下部分显示了它们各自的工作方式

为了从配置服务器提供二进制文件，您需要发送一个 Accept 头部，其值为 application/octet-stream。

Config Server 作为独立应用程序运行效果最佳。但是，如有需要，您可以将其嵌入到另一个应用程序中。为此，请使用 @EnableConfigServer 注解。在这种情况下，一个名为 spring.cloud.config.server.bootstrap 的可选属性可能很有用。它是一个标志，指示服务器是否应从其自己的远程仓库配置自身。默认情况下，此标志是关闭的，因为它可能会延迟启动。但是，当嵌入在另一个应用程序中时，以与任何其他应用程序相同的方式初始化是合理的。将 spring.cloud.config.server.bootstrap 设置为 true 时，您还必须使用 组合环境仓库配置。例如

要更改服务器端点的位置，您可以（可选）设置 spring.cloud.config.server.prefix（例如，/config），以在某个前缀下提供资源。此前缀应以 / 开头，但不以 / 结尾。它应用于 Config Server 中的 @RequestMappings（即在 Spring Boot 的 server.servletPath 和 server.contextPath 前缀之下）。

如果您想直接从后端仓库读取应用程序的配置（而不是从配置服务器），您基本上需要一个没有端点的嵌入式配置服务器。您可以通过不使用 @EnableConfigServer 注解来完全关闭端点（设置 spring.cloud.config.server.bootstrap=true）。

许多源代码仓库提供商（例如 Github、Gitlab、Gitea、Gitee、Gogs 或 Bitbucket）通过 webhook 通知您仓库的更改。您可以通过提供商的用户界面将 webhook 配置为一个 URL 和一组您感兴趣的事件。例如，Github 使用 POST 请求到 webhook，请求体是一个包含提交列表的 JSON，并且头部 (X-Github-Event) 设置为 push。如果您添加对 spring-cloud-config-monitor 库的依赖，并在 Config Server 中激活 Spring Cloud Bus，则会启用 /monitor 端点。

当 webhook 被激活时，Config Server 会发送一个定向到它认为可能已更改的应用程序的 RefreshRemoteApplicationEvent。更改检测可以进行策略化。但是，默认情况下，它查找与应用程序名称匹配的文件中的更改（例如，foo.properties 定向到 foo 应用程序，而 application.properties 定向到所有应用程序）。当您想要覆盖此行为时使用的策略是 PropertyPathNotificationExtractor，它接受请求头部和请求体作为参数，并返回一个已更改的文件路径列表。

默认配置与 Github、Gitlab、Gitea、Gitee、Gogs 或 Bitbucket 开箱即用。除了来自 Github、Gitlab、Gitee 或 Bitbucket 的 JSON 通知外，您还可以通过向 /monitor 发送 POST 请求并使用格式为 path={application} 的表单编码请求体参数来触发更改通知。这样做会将通知广播到与 {application} 模式匹配的应用程序（该模式可以包含通配符）。

自 4.0.0 起，Spring Cloud Config Server 支持 Spring AOT 转换。然而，目前尚不支持 GraalVM Native Image。实现 Native Image 支持被 graal#5134 阻止，并且可能需要完成 https://github.com/graalvm/taming-build-time-initialization 上的工作才能修复。

Spring Boot 2.4 引入了一种通过 spring.config.import 属性导入配置数据的新方法。这现在是绑定到 Config Server 的默认方式。

要选择性地连接到配置服务器，请在 application.properties 中进行如下设置

这将连接到默认位置 "http://localhost:8888" 的 Config Server。移除 optional: 前缀将导致 Config Client 在无法连接到 Config Server 时启动失败。要更改 Config Server 的位置，可以设置 spring.cloud.config.uri 或将 URL 添加到 spring.config.import 语句中，例如 spring.config.import=optional:configserver:http://myhost:8888。import 属性中的位置优先于 uri 属性。

Spring Boot 配置数据分两步解析配置。首先，它使用 default profile 加载所有配置。这允许 Spring Boot 收集所有可能激活任何其他 profile 的配置。收集到所有激活的 profile 后，它将为活动的 profile 加载任何额外的配置。因此，您可能会看到向 Spring Cloud Config Server 发出多个请求来获取配置。这是正常的，是 Spring Boot 使用 spring.config.import 加载配置的方式所带来的副作用。在 Spring Cloud Config 的早期版本中，只发出一个请求，但这表示您无法从 Config Server 获取的配置中激活 profile。现在，只需使用 'default' profile 发出的额外请求使这成为可能。

要使用连接到 Config Server 的传统 bootstrap 方式，必须通过属性或 spring-cloud-starter-bootstrap Starter 启用 bootstrap。该属性为 spring.cloud.bootstrap.enabled=true。它必须设置为系统属性或环境变量。启用 bootstrap 后，类路径中包含 Spring Cloud Config Client 的任何应用程序将按如下方式连接到 Config Server：当 config client 启动时，它会绑定到 Config Server（通过 spring.cloud.config.uri bootstrap 配置属性），并使用远程属性源初始化 Spring Environment。

这种行为的最终结果是，所有希望使用 Config Server 的客户端应用程序都需要一个 bootstrap.yml（或环境变量），并在其中设置 spring.cloud.config.uri 的服务器地址（默认为 "http://localhost:8888"）。

在某些情况下，如果您无法连接到 Config Server，您可能希望服务启动失败。如果这是期望的行为，请将 bootstrap 配置属性 spring.cloud.config.fail-fast=true 设置为使客户端抛出 Exception 并停止。

如果您期望 Config Server 在应用程序启动时可能偶尔不可用，您可以在失败后让它继续尝试。首先，您需要设置 spring.cloud.config.fail-fast=true。然后，您需要在类路径中添加 spring-retry 和 spring-boot-starter-aop。默认行为是重试六次，初始退避间隔为 1000ms，后续退避的指数乘数为 1.1。您可以通过设置 spring.cloud.config.retry.* 配置属性来配置这些属性（以及其他属性）。要使用随机指数退避策略，请将 spring.cloud.config.retry.useRandomPolicy 设置为 true。

重试功能与 Spring Boot 的 spring.config.import 语句和正常属性一起使用。但是，如果 import 语句位于 profile 中，例如 application-prod.properties，则需要另一种方式来配置重试。配置需要作为 URL 参数放置在 import 语句上。

这将设置 spring.cloud.config.fail-fast=true（请注意上面缺少前缀）和所有可用的 spring.cloud.config.retry.* 配置属性。

Config Service 从 /{application}/{profile}/{label} 提供属性源，其中客户端应用程序中的默认绑定如下

您可以通过设置 spring.cloud.config.* 来覆盖所有这些（其中 * 是 name、profile 或 label）。label 对于回滚到以前版本的配置很有用。对于默认的 Config Server 实现，它可以是 git label、分支名称或提交 ID。Label 也可以以逗号分隔的列表形式提供。在这种情况下，列表中的项会逐个尝试，直到成功。这种行为在处理 feature 分支时很有用。例如，您可能希望将配置标签与您的分支对齐，但使其成为可选的（在这种情况下，使用 spring.cloud.config.label=myfeature,develop）。

当您部署了多个 Config Server 实例，并期望有时一个或多个实例不可用或无法响应请求（例如 Git 服务器宕机）时，为了确保高可用性，您可以指定多个 URL（在 spring.cloud.config.uri 属性下以逗号分隔列表形式），或者让所有实例在像 Eureka 这样的服务注册中心注册（如果使用 Discovery-First Bootstrap 模式）。

在 spring.cloud.config.uri 下列出的 URL 会按照列表中的顺序尝试。默认情况下，Config Client 会尝试从每个 URL 获取属性，直到尝试成功，以确保高可用性。

但是，如果您只想在 Config Server 未运行时（即应用程序已退出）或发生连接超时时确保高可用性，请将 spring.cloud.config.multiple-uri-strategy 设置为 connection-timeout-only。（spring.cloud.config.multiple-uri-strategy 的默认值为 always。）例如，如果 Config Server 返回 500（内部服务器错误）响应，或者 Config Client 从 Config Server 收到 401（由于凭据错误或其他原因），则 Config Client 不会尝试从其他 URL 获取属性。400 错误（可能除了 404）表示用户问题，而不是可用性问题。请注意，如果 Config Server 设置为使用 Git 服务器，并且对 Git 服务器的调用失败，则可能会发生 404 错误。

可以在单个 spring.config.import 键下指定多个位置，而不是使用 spring.cloud.config.uri。位置将按定义的顺序处理，后面的导入优先。但是，如果 spring.cloud.config.fail-fast 为 true，则如果第一次调用 Config Server 因任何原因失败，Config Client 将会失败。如果 fail-fast 为 false，它将尝试所有 URL，直到有一个调用成功，无论失败原因是什么。（在使用 spring.config.import 指定 URL 时，spring.cloud.config.multiple-uri-strategy 不适用。）

如果您在 Config Server 上使用 HTTP basic 安全性，目前只有当您在 spring.cloud.config.uri 属性下指定的每个 URL 中嵌入凭据时，才支持每个 Config Server 的身份验证凭据。如果您使用任何其他类型的安全机制，则（目前）不支持每个 Config Server 的身份验证和授权。

如果要配置超时阈值

如果您在服务器上使用 HTTP Basic 安全性，客户端需要知道密码（如果不是默认用户名，则还需要用户名）。您可以通过配置服务器 URI 或通过单独的用户名和密码属性来指定用户名和密码，如以下示例所示

以下示例显示了传递相同信息的另一种方法

spring.cloud.config.password 和 spring.cloud.config.username 的值会覆盖 URI 中提供的任何内容。

如果您将应用程序部署到 Cloud Foundry 上，提供密码的最佳方式是通过服务凭据（例如在 URI 中，因为它不需要放在配置文件中）。以下示例在本地以及 Cloud Foundry 上名为 configserver 的用户提供服务中均可工作。

如果配置服务器需要客户端 TLS 证书，您可以通过属性配置客户端 TLS 证书和信任存储，如下例所示

spring.cloud.config.tls.enabled 需要设置为 true 以启用配置客户端 TLS。省略 spring.cloud.config.tls.trust-store 时，将使用 JVM 默认信任存储。spring.cloud.config.tls.key-store-type 和 spring.cloud.config.tls.trust-store-type 的默认值是 PKCS12。省略密码属性时，假定密码为空。

如果您使用其他形式的安全机制，您可能需要向 ConfigServicePropertySourceLocator 提供一个 RestTemplate（例如，在引导上下文 (bootstrap context) 中获取并注入它）。

Vault 支持在存储在 Vault 中的值中嵌套键，如下例所示

echo -n '{"appA": {"secret": "appAsecret"}, "bar": "baz"}' | vault write secret/myapp -

此命令将一个 JSON 对象写入您的 Vault。要在 Spring 中访问这些值，您可以使用传统的点(.) 注解，如下例所示

上述代码会将 name 变量的值设置为 appAsecret。

自 4.0.0 起，Spring Cloud Config Client 支持 Spring AOT 转换和 GraalVM native images。

您可以在下方找到此项目声明的所有指标列表。

您可以在下方找到此项目声明的所有 Span 列表。