要在应用程序中使用这些功能，你可以将其构建为依赖 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 name，将使用 application。要修改这个名字，可以在 application.properties 文件中添加以下属性：

Config Server properties 在 /env 端点中显示为高优先级的属性源，如下例所示。

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

你应该把配置服务器的配置数据存储在哪里？支配这种行为的策略是 EnvironmentRepository，为 Environment 对象服务。这个 Environment 是来自Spring Environment（包括作为主要特性的 propertySources）的 domain 的浅拷贝。Environment 资源是由三个变量参数化的：

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

下面的客户应用示例具有这种引导配置（bootstrap configuration）：

（与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。

配置服务器带有一个健康指示器（Health Indicator），用于检查配置的 EnvironmentRepository 是否在工作。默认情况下，它要求 EnvironmentRepository 提供一个名为 app 的应用程序、default profile 和 EnvironmentRepository 实现提供的默认标签。

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

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

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

你可以用任何对你有意义的方式来保护你的配置服务器（从物理网络安全到 OAuth2 bearer token），因为 Spring Security 和 Spring Boot 提供对许多安全方面的支持。

要使用默认的 Spring Boot 配置的 HTTP Basic security，请在 classpath 上包含 Spring Security（例如，通过 spring-boot-starter-security）。默认的用户名是 user，密码是随机生成的。随机密码在实践中没有用，所以我们建议你配置密码（通过设置 spring.security.user.password），并对其进行加密（关于如何做的说明，见下文）。

如果远程属性源包含加密的内容（以 {cipher} 开头的值），它们在通过HTTP发送给客户端之前会被解密。这种设置的主要优点是，当属性值处于 "静态状态" 时（例如，在git仓库中），它们不需要是纯文本。如果一个值不能被解密，它就会被从属性源中删除，并添加一个额外的属性，其密钥相同，但前缀为 invalid 和一个表示 "不适用" 的值（通常是 <n/a>）。这主要是为了防止密码文本被用作密码而意外地泄露。

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

application.properties 文件中的加密值不能用引号包裹。否则，该值将不会被解密。下面的例子显示了可以工作的值：

你可以安全地将这个纯文本推送到共享的git仓库中，而 secret 密码仍然受到保护。

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

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

在你把它放在YAML或属性文件中，以及在你提交和推送到远程（可能是不安全的）存储之前，采取加密的值并添加 {cipher} 前缀。

/encrypt 和 /decrypt 端点也都接受 /*/{application}/{profiles} 形式的路径，当客户端调用 main environment 资源时，可用于在每个应用（名称）和每个文件的基础上控制加密。

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

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

配置服务器可以使用对称（共享）密钥或非对称密钥（RSA密钥对）。非对称选择在安全性方面更胜一筹，但使用对称密钥通常更方便，因为它是在 application.properties 中配置的单一属性值。

要配置对称密钥，你需要将 encrypt.key 设置为一个 secret String（或者使用 ENCRYPT_KEY 环境变量来避免直接写入纯文本配置文件）。

要配置非对称钥匙，请使用 keystore（例如，由 JDK 附带的 keytool 工具创建）。keystore 的属性是 encrypt.keyStore.*，其中 * 等于

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

要创建一个用于测试的 keystore，你可以使用类似于以下的命令：

把 server.jks 文件放在 classpath中（例如），然后，在你的 bootstrap.yml 中，为配置服务器创建以下设置：

除了加密属性值中的 {cipher} 前缀外，配置服务器在（Base64编码的）密码文本开始前寻找零个或多个 {name:value} 前缀。密钥被传递给 TextEncryptorLocator，它可以做任何需要的逻辑来为密码定位一个 TextEncryptor。如果你已经配置了一个keystore（encrypt.keystore.location），默认的 locator 会寻找具有由 key 前缀提供的别名的key，其密码文本类似于以下内容：

该 locator 寻找一个名为 "testkey" 的密钥。也可以通过在前缀中使用 {secret:…​} 值来提供一个secret。然而，如果没有提供，默认情况下是使用keystore password （当你建立一个keystore而没有指定一个secret时，你会得到这样的密码）。如果你提供了一个secret，你也应该用一个自定义的 SecretLocator 来加密这个 secret。

当key只被用来加密几个字节的配置数据时（也就是说，它们没有被用在其他地方），从密码学的角度来看，key的轮换几乎没有必要。然而，你可能偶尔需要改变key（例如，在安全漏洞的情况下）。在这种情况下，所有的客户都需要改变他们的源配置文件（例如，在git中），并在所有密码中使用新的 {key:…​} 前缀。请注意，客户需要首先检查配置服务器 keystore 中的 key 别名是否可用。

有时你想让客户端在本地解密配置，而不是在服务器中进行解密。在这种情况下，如果你提供 encrypt.* 配置来定位一个密钥，你仍然可以有 /encrypt 和 /decrypt 端点，但你需要通过在 bootstrap.[yml|properties] 中放置 spring.cloud.config.server.encrypt.enabled=false 来明确关闭出站属性的解密功能。如果你不关心端点，如果你不配置 key 或 enabled 的标志，它应该可以工作。

来自 environment 端点的默认JSON格式非常适合Spring应用程序使用，因为它直接映射到 Environment 抽象。如果你愿意，你可以通过在资源路径中添加一个后缀（".yml"、".yaml" 或 ".properties"）来消费YAML或Java properties 的相同数据。这对于那些不关心JSON端点的结构或其提供的额外元数据的应用程序的消费是非常有用的（例如，不使用Spring的应用程序可能会从这种方法的简单性中受益）。

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

你的应用程序可能需要为其环境量身定制的通用纯文本配置文件，而不是使用 Environment 抽象（或YAML或properties格式中的一种替代表示）。配置服务器通过 /{application}/{profile}/{label}/{path} 的额外端点提供这些文件，其中 application、profile 和 label 的含义与常规环境端点相同，但 path 是一个文件名的路径（如 log.xml）。这个端点的源文件的位置与 environment 端点的相同。对于properties和YAML文件，也使用同样的搜索路径。然而，不是聚合所有匹配的资源，而是只返回第一个匹配的资源。

找到资源后，正常格式的占位符（${…​}）通过使用提供的application name、profile和标label的有效 Environment 来解决。通过这种方式，资源端点与environment端点紧密结合。

目前，Spring Cloud Config 可以为git、SVN、本地后端和AWS S3提供纯文本。对git、SVN和本地后端的支持是相同的。AWS S3的工作方式有些不同。下面的章节展示了每一种的工作方式：

为了从配置服务器获取二进制文件，你将需要发送一个 application/octet-stream 的 Accept header。

配置服务器最好作为一个独立的应用程序运行。然而，如果需要的话，你可以把它嵌入到另一个应用程序中。要做到这一点，请使用 @EnableConfigServer 注解。在这种情况下，一个名为 spring.cloud.config.server.bootstrap 的可选属性会很有用。它是一个标志，表示服务器是否应该从自己的远程资源库配置自己。默认情况下，该标志是关闭的，因为它可能延迟启动。然而，当嵌入到另一个应用程序中时，以与其他应用程序相同的方式初始化是有意义的。当设置 spring.cloud.config.server.bootstrap 为 true 时，你还必须使用 复合 environment repository配置。例如

要改变服务器端点的位置，你可以（选择性地）设置 spring.cloud.config.server.prefix（例如，/config），以在一个前缀下提供资源。该前缀应以 / 开头，但不以 / 结尾。它被应用于配置服务器中的 @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 body 和一个设置为 push 的头（X-Github-Event）。如果你添加了对 spring-cloud-config-monitor 库的依赖，并在你的配置服务器中激活了Spring Cloud Bus，那么就会启用 /monitor 端点。

当 webhook 被激活时，配置服务器会向它认为可能发生变化的应用程序发送一个 RefreshRemoteApplicationEvent。变化检测可以是战略性的。然而，默认情况下，它寻找与应用程序名称相匹配的文件中的变化（例如，foo.properties 是针对 foo 应用程序的，而 application.properties 是针对所有应用程序的）。当你想覆盖该行为时，要使用的策略是 PropertyPathNotificationExtractor，它接受请求 header 和 body 作为参数，并返回一个变化的文件路径列表。

默认配置可以在Github、Gitlab、Gitea、Gitee、Gogs或Bitbucket中使用。除了来自Github、Gitlab、Gitee或Bitbucket的JSON通知外，你还可以通过向 /monitor 发送带有表单编码的 body 参数的 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 属性导入配置数据的新方法。现在，这是与配置服务器绑定的默认方式。

要选择性地连接到配置服务器，请在 application.properties 中设置以下内容：

这将在 "http://localhost:8888" 的默认位置连接到配置服务器。删除 optional: 前缀将导致配置客户端在无法连接到配置服务器时失败。要改变配置服务器的位置，可以设置 spring.cloud.config.uri 或在 spring.config.import 语句中添加url，如 spring.config.import=optional:configserver:http://myhost:8888。import 属性中的位置优先于 uri 属性。

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

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

在某些情况下，如果服务不能连接到配置服务器，你可能想让它启动失败。如果这是需要的行为，请设置 bootstrap 配置属性 spring.cloud.config.fail-fast=true，使客户端以异常停止。

如果你预计配置服务器在你的应用程序启动时可能偶尔不可用，你可以让它在失败后继续尝试。首先，你需要设置 spring.cloud.config.fail-fast=true。然后你需要将 spring-retry 和 spring-boot-starter-aop 添加到你的 classpath。默认行为是重试六次，初始退避间隔为1000ms，后续退避的指数乘数为1.1。你可以通过设置 spring.cloud.config.retry.* 配置属性来配置这些属性（以及其他属性）。

重试在 Spring Boot 的 spring.config.import 语句中起作用，正常的 properties 也起作用。但是，如果 import 语句是在配置文件中，比如 application-prod.properties，那么你需要用不同的方式来配置重试。配置需要作为url参数放在 import 语句中。

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

配置服务为来自 /{application}/{profile}/{label} 的属性源提供服务，其中客户端应用程序的默认绑定如下：

你可以通过设置 spring.cloud.config.*（其中 * 是 name、profile 或 label）来覆盖所有的配置。label 对于回滚到以前版本的配置非常有用。在默认的配置服务器实现中，它可以是一个 git label、分支名称或提交ID。label 也可以以逗号分隔的列表形式提供。在这种情况下，列表中的项目会被逐一尝试，直到有一个成功。这种行为在处理一个特性分支时很有用。例如，你可能想让配置 label 与你的分支保持一致，但让它成为可选项（在这种情况下，使用 spring.cloud.config.label=myfeature,develop）。

当你部署了多个配置服务器实例，并且预计一个或多个实例会时常不可用或无法满足请求时（比如Git服务器宕机），为了确保高可用性，你可以指定多个URL（在 spring.cloud.config.uri 属性下以逗号分隔的列表形式）或让所有实例在Eureka等服务注册中心注册（如果使用 Discovery-First Bootstrap 模式）。

spring.cloud.config.uri 下列出的 URL 将按照列出的顺序进行尝试。默认情况下，配置客户端将尝试从每个URL获取属性，直到尝试成功，以确保高可用性。

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

可以在一个 spring.config.import key 下指定多个位置，而不是 spring.cloud.config.uri。位置将按照它们被定义的顺序进行处理，后面的导入优先。但是，如果 spring.cloud.config.fail-fast 为 true，如果第一次配置服务器调用因任何原因而不成功，配置客户端将失败。如果 fail-fast 为 false，它将尝试所有的URL，直到有一个调用成功，不管失败的原因是什么。（spring.cloud.config.multiple-uri-strategy 不适用于在 spring.config.import 下指定URL的情况）。

如果你在配置服务器上使用 HTTP basic security，目前只有在你将凭证嵌入你在 spring.cloud.config.uri 属性下指定的每个 URL 中时，才可能支持每个配置服务器的认证凭证。如果你使用任何其他类型的安全机制，你（目前）无法支持每台配置服务器的认证和授权。

如果你想配置超时阈值：

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

下面的例子显示了传递相同信息的另一种方式：

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

如果你在 Cloud Foundry 上部署应用程序，提供密码的最佳方式是通过服务凭证（如 URI 中，因为它不需要在配置文件中）。以下示例适用于本地和 Cloud Foundry 上用户提供的名为 configserver 的服务：

如果配置服务器需要客户端的TLS证书，你可以通过 properties 配置客户端的 TLS 证书和 trust store，如下面的例子所示：

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

如果你使用另一种形式的安全，你可能需要向 ConfigServicePropertySourceLocator 提供一个 RestTemplate（例如，通过在 bootstrap 上下文中抓取并注入它）。

Vault支持在存储在Vault中的值中嵌套key的能力，如下面的例子所示：

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

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

前面的代码将设置 name 变量的值为 appAsecret。

从 4.0.0 开始，Spring Cloud Config Client 支持 Spring AOT 转换和 GraalVM 原生镜像。

Below you can find a list of all metrics declared by this project.

Below you can find a list of all spans declared by this project.