要在应用程序中使用这些功能，您可以将其构建为依赖于 spring-cloud-config-client 的 Spring Boot 应用程序（有关示例，请参阅 config-client 的测试用例或示例应用程序）。添加依赖项最方便的方法是使用 Spring Boot starter 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 文件中：

配置服务器属性在 /env 端点中显示为高优先级属性源，如以下示例所示。

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

Config Server 的配置数据应该存储在哪里？管理此行为的策略是 EnvironmentRepository，它提供 Environment 对象。此 Environment 是 Spring Environment 领域的一个浅层副本（包括 propertySources 作为主要功能）。Environment 资源由三个变量参数化：

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

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

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

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

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

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

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

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

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

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

要使用默认的 Spring Boot 配置的 HTTP 基本安全，请在类路径中包含 Spring Security（例如，通过 spring-boot-starter-security）。默认用户名是 user，密码是随机生成的。随机密码在实践中没有用，因此我们建议您配置密码（通过设置 spring.security.user.password）并对其进行加密（请参阅下文了解操作说明）。

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

如果您为配置客户端应用程序设置了远程配置仓库，它可能包含一个类似于以下的 application.yml：

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

您可以安全地将此明文推送到共享的 git 仓库，并且秘密密码仍然受到保护。

服务器还公开了 /encrypt 和 /decrypt 端点（假设这些端点是安全的，并且只有经过授权的代理才能访问）。如果您编辑远程配置文件，您可以使用 Config Server 通过 POST 请求到 /encrypt 端点来加密值，如以下示例所示：

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

获取加密值，并在将其放入 YAML 或属性文件之前，以及在将其提交并推送到远程（可能不安全）存储之前，添加 {cipher} 前缀。

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

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 主体和一个设置为 push 的标头（X-Github-Event）。如果您添加对 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 原生镜像。实现原生镜像支持受到 graal#5134 的阻碍，并且可能需要完成 https://github.com/graalvm/taming-build-time-initialization 上的工作才能修复。

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

要在 application.properties 中可选地连接到配置服务器，请进行以下设置：

这将连接到默认位置“https://: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。导入属性中的位置优先于 uri 属性。

Spring Boot 配置数据通过两步过程解析配置。首先，它使用 default 配置文件加载所有配置。这允许 Spring Boot 收集可能激活任何附加配置文件的所有配置。在收集所有已激活的配置文件后，它将加载活动配置文件的任何附加配置。因此，您可能会看到对 Spring Cloud Config Server 发出多个请求以获取配置。这是正常的，并且是 Spring Boot 在使用 spring.config.import 时加载配置的副作用。在 Spring Cloud Config 的早期版本中，只发出一个请求，但这意味​​着您无法从 Config Server 的配置中激活配置文件。现在，使用“default”配置文件发出的额外请求使这成为可能。

要使用旧版引导方式连接到 Config Server，必须通过属性或 spring-cloud-starter-bootstrap 启动器启用引导。该属性是 spring.cloud.bootstrap.enabled=true。它必须设置为系统属性或环境变量。一旦启用了引导，类路径中带有 Spring Cloud Config Client 的任何应用程序都将按如下方式连接到 Config Server：当配置客户端启动时，它会绑定到 Config Server（通过 spring.cloud.config.uri 引导配置属性），并使用远程属性源初始化 Spring Environment。

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

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

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

重试适用于 Spring Boot spring.config.import 语句和正常属性。但是，如果导入语句位于配置文件中，例如 application-prod.properties，那么您需要不同的方式来配置重试。配置需要作为 URL 参数放置在导入语句上。

这将设置 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 标签、分支名称或提交 ID。标签也可以作为逗号分隔的列表提供。在这种情况下，列表中的项将逐个尝试，直到一个成功。当在功能分支上工作时，这种行为可能很有用。例如，您可能希望将配置标签与您的分支对齐，但使其可选（在这种情况下，使用 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（Internal Server Error）响应或 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 基本安全，目前仅当您将凭据嵌入到 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（例如，通过在引导上下文中获取并注入它）。

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 原生镜像。

以下是本项目声明的所有指标列表。

以下是本项目声明的所有 Span 列表。