要在應用程式中使用這些功能，您可以將其構建為依賴於 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 列表。