要在應用程式中使用這些功能，您可以將其構建為一個依賴於 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 中進行如下設定

這將連線到預設位置 "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。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 的伺服器地址（預設為 "https://: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 列表。