為了在應用程式中使用這些功能，您可以將其建置為依賴 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 伺服器運行時，它會從預設的本機 config 伺服器（如果正在運行）在埠 8888 上取得外部組態。要修改啟動行為，您可以使用 application.properties 變更 config 伺服器的位置，如下列範例所示

預設情況下，如果未設定應用程式名稱，將使用 application。要修改名稱，可以將以下屬性新增至 application.properties 檔案

Config 伺服器屬性在 /env 端點中顯示為高優先級屬性來源，如下列範例所示。

名為 configserver:<遠端儲存庫的 URL>/<檔案名稱> 的屬性來源包含值為 bar 的 foo 屬性。

您應該將 Config 伺服器的組態資料儲存在哪裡？控制此行為的策略是 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 profile 以及 EnvironmentRepository 實作提供的預設標籤。

您可以配置健康指示器以檢查更多應用程式以及自訂 profile 和自訂標籤，如下例所示

您可以透過設定 management.health.config.enabled=false 來停用健康指示器。

此外，您可以透過設定屬性 spring.cloud.config.server.health.down-health-status (預設值為 "DOWN') 來提供您自己的自訂 down 狀態。

您可以使用任何對您有意義的方式（從實體網路安全性到 OAuth2 bearer token）來保護您的 Config Server，因為 Spring Security 和 Spring Boot 為許多安全性安排提供了支援。

若要使用預設的 Spring Boot 配置的 HTTP Basic 安全性，請在 classpath 上包含 Spring Security（例如，透過 spring-boot-starter-security）。 預設值是 username 為 user 和隨機產生的密碼。 隨機密碼在實務上沒有用處，因此我們建議您配置密碼（透過設定 spring.security.user.password）並對其進行加密（請參閱下面的說明，瞭解如何執行此操作）。

如果遠端屬性來源包含加密內容 (值以 {cipher} 開頭)，則會在透過 HTTP 發送給用戶端之前解密。此設定的主要優點是屬性值在「靜止狀態」(例如，在 git 儲存庫中) 時不需要以純文字形式存在。如果值無法解密，則會從屬性來源中移除，並新增一個具有相同金鑰但前綴為 invalid 的額外屬性，以及表示「不適用」的值 (通常為 <n/a>)。這主要是為了防止密文被當作密碼使用並意外洩漏。

如果您為組態用戶端應用程式設定遠端組態儲存庫，則它可能包含類似於以下的 application.yml

application.properties 檔案中的加密值不得用引號括起來。否則，該值不會被解密。以下範例顯示可行的值

您可以安全地將此純文字推送到共用 git 儲存庫，而密碼仍然受到保護。

伺服器還公開了 /encrypt 和 /decrypt 端點 (假設這些端點是安全的，並且僅由授權代理程式存取)。如果您編輯遠端組態檔案，則可以使用 Config Server 透過 POST 請求到 /encrypt 端點來加密值，如下列範例所示

反向操作也可透過 /decrypt 取得 (前提是伺服器已配置對稱金鑰或完整金鑰對)，如下列範例所示

取得加密值，並在您將其放入 YAML 或 properties 檔案之前，以及在您提交並推送至遠端 (可能不安全) 儲存之前，新增 {cipher} 前綴。

/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 properties。這對於不關心 JSON 端點結構或它們提供的額外元資料的應用程式使用可能很有用 (例如，不使用 Spring 的應用程式可能會受益於這種方法的簡潔性)。

YAML 和 properties 表示形式具有一個額外的標誌 (作為名為 resolvePlaceholders 的布林查詢參數提供)，以指示是否應在輸出中解析來源文件中的佔位符 (以標準 Spring ${…​} 形式)，如果可能的話。對於不了解 Spring 佔位符慣例的使用者來說，這是一個有用的功能。

您的應用程式可能需要通用純文字組態檔案，這些檔案是根據其環境量身定制的，而不是使用 Environment 抽象概念 (或 YAML 或 properties 格式的替代表示形式之一)。Config Server 透過 /{application}/{profile}/{label}/{path} 的額外端點提供這些檔案，其中 application、profile 和 label 與常規環境端點的含義相同，但 path 是檔案名稱的路徑 (例如 log.xml)。此端點的來源檔案與環境端點的來源檔案位於相同的位置。相同的搜尋路徑用於 properties 和 YAML 檔案。但是，不是聚合所有匹配的資源，而是僅傳回第一個匹配的資源。

找到資源後，會使用提供的應用程式名稱、profile 和標籤的有效 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 前綴之下)。

如果您想要直接從後端儲存庫讀取應用程式的組態 (而不是從 config server 讀取)，則基本上需要一個沒有端點的嵌入式 config server。您可以完全關閉端點，方法是不使用 @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 通知之外，您還可以透過 POST 請求到 /monitor，並在 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 的預設方式。

若要選擇性地連線到 config server，請在 application.properties 中設定以下內容

這將連線到預設位置為 "http://localhost: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 Config Data 以兩步驟流程解析組態。首先，它使用 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 啟動器啟用 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 中 (預設為 "http://localhost:8888")。

在某些情況下，如果服務無法連線到 Config Server，您可能希望使服務啟動失敗。如果這是所需的行為，請設定 bootstrap 組態屬性 spring.cloud.config.fail-fast=true，以使用戶端因異常而停止。

如果您預期 config server 在您的應用程式啟動時偶爾可能不可用，您可以使其在失敗後繼續嘗試。首先，您需要設定 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 陳述式，並且普通屬性也適用。但是，如果 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 標籤、分支名稱或提交 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 (內部伺服器錯誤) 回應，或 Config Client 從 Config Server 收到 401 (由於錯誤的認證或其他原因)，則 Config Client 不會嘗試從其他 URL 擷取屬性。400 錯誤 (可能除了 404 之外) 表示使用者問題，而不是可用性問題。請注意，如果 Config Server 設定為使用 Git 伺服器，並且對 Git 伺服器的呼叫失敗，則可能會發生 404 錯誤。

可以在單一 spring.config.import 金鑰下指定多個位置，而不是 spring.cloud.config.uri。位置將按照定義的順序處理，後面的 import 優先。但是，如果 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 安全性，則用戶端需要知道密碼 (以及使用者名稱，如果它不是預設值)。您可以透過 config server URI 或透過單獨的使用者名稱和密碼屬性來指定使用者名稱和密碼，如下列範例所示

以下範例顯示了傳遞相同資訊的替代方法

spring.cloud.config.password 和 spring.cloud.config.username 值會覆寫 URI 中提供的任何內容。

如果您將應用程式部署在 Cloud Foundry 上，則提供密碼的最佳方法是透過服務認證 (例如在 URI 中，因為它不需要在組態檔案中)。以下範例適用於本機以及 Cloud Foundry 上名為 configserver 的使用者提供的服務

如果 config server 需要用戶端 TLS 憑證，您可以透過屬性配置用戶端 TLS 憑證和信任儲存庫，如下列範例所示

需要將 spring.cloud.config.tls.enabled 設定為 true 才能啟用 Config Client 端的 TLS。當省略 spring.cloud.config.tls.trust-store 時，會使用 JVM 預設的信任儲存庫。spring.cloud.config.tls.key-store-type 和 spring.cloud.config.tls.trust-store-type 的預設值為 PKCS12。當密碼屬性被省略時，會假設為空密碼。

如果您使用其他形式的安全性，您可能需要提供一個 RestTemplate 給 ConfigServicePropertySourceLocator（例如，透過在啟動引導 (bootstrap) 內容中抓取並注入它）。

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 列表。