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

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

application.properties当此 HTTP 服务器运行时，它会从端口 8888 上的默认本地配置服务器（如果正在运行）获取外部配置。要修改启动行为，您可以使用以下命令更改配置服务器的位置：例子：

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

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

名为 的属性源configserver:<URL of remote repository>/<file name>包含foo值为 的属性bar。

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

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

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

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

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

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

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

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

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

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

您可以通过任何对您有意义的方式来保护您的配置服务器（从物理网络安全到 OAuth2 不记名令牌），因为 Spring Security 和 Spring Boot 为许多安全安排提供支持。

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

如果远程属性源包含加密内容（以 开头的值{cipher}），则它们会在通过 HTTP 发送到客户端之前被解密。此设置的主要优点是属性值在“静止”时（例如，在 git 存储库中）不需要采用纯文本形式。如果某个值无法解密，则会将其从属性源中删除，并使用相同的密钥添加一个附加属性，但前缀为invalid和 ，表示“不适用”（通常为<n/a>）。这主要是为了防止密文被用作密码而意外泄露。

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

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

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

服务器还公开/encrypt端点/decrypt（假设这些端点是安全的并且仅由授权代理访问）。如果编辑远程配置文件，则可以使用配置服务器通过 POST 到端点来加密值/encrypt，如以下示例所示：

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

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

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

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

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

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

要配置对称密钥，您需要设置encrypt.key为秘密字符串（或使用ENCRYPT_KEY环境变量以使其远离纯文本配置文件）。

要配置非对称密钥，请使用密钥库（例如，由keytoolJDK 附带的实用程序创建的密钥库）。密钥库属性encrypt.keyStore.*等于*

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

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

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

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

定位器查找名为“testkey”的键。{secret:…​}还可以通过使用前缀中的值来提供秘密。但是，如果未提供，则默认情况下使用密钥库密码（这是在构建密钥库且不指定机密时获得的密码）。如果您确实提供了机密，您还应该使用自定义的SecretLocator.

当密钥仅用于加密几个字节的配置数据（即它们不在其他地方使用）时，从加密角度来看，几乎不需要密钥轮换。但是，您有时可能需要更改密钥（例如，在发生安全漏洞时）。在这种情况下，所有客户端都需要更改其源配置文件（例如，在 git 中）并{key:…​}在所有密码中使用新的前缀。请注意，客户端需要首先检查配置服务器密钥库中的密钥别名是否可用。

有时您希望客户端在本地解密配置，而不是在服务器中解密。在这种情况下，如果您提供encrypt.*配置来定位密钥，您仍然可以拥有/encrypt和/decrypt端点，但您需要通过spring.cloud.config.server.encrypt.enabled=false将bootstrap.[yml|properties]. 如果您不关心端点，那么如果您不配置密钥或启用标志，它应该可以工作。

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

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

Environment您的应用程序可能需要针对其环境量身定制的通用纯文本配置文件，而不是使用抽象（或 YAML 或属性格式中的替代表示形式之一）。配置服务器通过位于 的附加端点提供这些/{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.

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

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

如果您想直接从后端存储库（而不是从配置服务器）读取应用程序的配置，那么您基本上需要一个没有端点的嵌入式配置服务器。@EnableConfigServer您可以通过不使用注释 (set )来完全关闭端点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并在配置服务器中激活 Spring Cloud Bus，则会/monitor启用端点。

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

默认配置可直接用于 Github、Gitlab、Gitea、Gitee、Gogs 或 Bitbucket。除了来自 Github、Gitlab、Gitee 或 Bitbucket 的 JSON 通知之外，您还可以通过 POST 到/monitor格式编码的正文参数来触发更改通知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:前缀将导致 Config Client 在无法连接到 Config Server 时失败。要更改配置服务器的位置，请设置spring.cloud.config.uriurl 或将 url 添加到spring.config.import语句中，例如spring.config.import=optional:configserver:http://myhost:8888. import 属性中的位置优先于 uri 属性。

Spring Boot Config Data 通过两步过程解析配置。首先，它使用配置文件加载所有配置default 。这允许 Spring Boot 收集可能激活任何其他配置文件的所有配置。收集所有激活的配置文件后，它将加载活动配置文件的任何附加配置。因此，您可能会看到向 Spring Cloud Config Server 发出多个请求来获取配置。这是正常现象，是 Spring Boot 在使用spring.config.import. 在以前版本的 Spring Cloud Config 中，仅发出一个请求，但这意味着您无法从来自配置服务器的配置激活配置文件。现在，仅使用“默认”配置文件的附加请求使这成为可能。

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

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

在某些情况下，如果某个服务无法连接到配置服务器，您可能希望该服务启动失败。如果这是所需的行为，请设置引导配置属性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.*。

Retry 适用于 Spring Bootspring.config.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对于回滚到以前版本的配置很有用。使用默认的 Config Server 实现，它可以是 git 标签、分支名称或提交 ID。标签也可以作为逗号分隔的列表提供。在这种情况下，将一项一项地尝试列表中的项目，直到其中一项成功为止。在处理功能分支时，此行为非常有用。例如，您可能希望将配置标签与您的分支对齐，但将其设为可选（在这种情况下，请使用spring.cloud.config.label=myfeature,develop）。

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

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

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

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

如果您在 Config Server 上使用 HTTP 基本安全性，则当前仅当您将凭据嵌入到属性下指定的每个 URL 中时，才可以支持每个 Config Server 身份验证凭据spring.cloud.config.uri。如果您使用任何其他类型的安全机制，则（当前）无法支持每个配置服务器的身份验证和授权。

如果要配置超时阈值：

如果您在服务器上使用 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-typePKCS12。当省略密码属性时，假定密码为空。

如果您使用另一种形式的安全性，则可能需要提供 aRestTemplate（ConfigServicePropertySourceLocator例如，通过在引导上下文中获取它并注入它）。

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

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 本机映像。

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

您可以在下面找到该项目声明的所有跨度的列表。