Git 後端

EnvironmentRepository 的預設實作使用 Git 後端，這對於管理升級和實體環境以及稽核變更非常方便。若要變更儲存庫的位置，您可以在 Config 伺服器中設定 spring.cloud.config.server.git.uri 組態屬性 (例如在 application.yml 中)。如果您使用 file: 前綴設定它，它應該可以從本機儲存庫運作，讓您可以快速且輕鬆地開始使用，而無需伺服器。然而，在這種情況下，伺服器直接在本機儲存庫上運作，而不會複製它 (即使它不是裸儲存庫也沒關係，因為 Config 伺服器永遠不會對「遠端」儲存庫進行變更)。為了擴展 Config 伺服器並使其具有高可用性，您需要讓伺服器的所有實例都指向相同的儲存庫，因此只有共用檔案系統才適用。即使在這種情況下，最好也對共用檔案系統儲存庫使用 ssh: 通訊協定，以便伺服器可以複製它並使用本機工作副本作為快取。

此儲存庫實作將 HTTP 資源的 {label} 參數對應到 git 標籤 (commit id、分支名稱或標籤)。如果 git 分支或標籤名稱包含斜線 (/)，則 HTTP URL 中的標籤應改用特殊字串 ({special-string}) 指定 (以避免與其他 URL 路徑混淆)。例如，如果標籤是 foo/bar，則替換斜線將產生以下標籤：foo({special-string})bar。特殊字串 ({special-string}) 也可應用於 {application} 參數。如果您使用命令列用戶端 (例如 curl)，請小心 URL 中的括號 — 您應該使用單引號 ('') 從 shell 逸出它們。

略過 SSL 憑證驗證

可以透過將 git.skipSslValidation 屬性設定為 true (預設為 false) 來停用組態伺服器對 Git 伺服器 SSL 憑證的驗證。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://example.com/my/repo
          skipSslValidation: true

設定連線逾時

您可以設定組態伺服器等待取得 HTTP 或 SSH 連線的時間 (以秒為單位)。使用 git.timeout 屬性 (預設為 5)。

spring:
  cloud:
    config:
      server:
        git:
          uri: https://example.com/my/repo
          timeout: 4

Git URI 中的佔位符

Spring Cloud Config 伺服器支援具有 {application} 和 {profile} (以及 {label}，如果您需要) 佔位符的 git 儲存庫 URL。因此，您可以使用類似以下的結構來支援「每個應用程式一個儲存庫」的原則

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/myorg/\{application}

您也可以使用類似的模式但使用 {profile} 來支援「每個 Profile 一個儲存庫」的原則。

此外，在您的 {application} 參數中使用特殊字串 "({special-string})" 可以啟用對多個組織的支援，如下例所示

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/\{application}

其中 {application} 在請求時以以下格式提供：organization({special-string})application。

模式比對與多個儲存庫

Spring Cloud Config 也包含對應用程式和 Profile 名稱進行模式比對，以支援更複雜的需求。模式格式是以逗號分隔的 {application}/{profile} 名稱清單，其中包含萬用字元 (請注意，以萬用字元開頭的模式可能需要加上引號)，如下例所示

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          repos:
            simple: https://github.com/simple/config-repo
            special:
              pattern: special*/dev*,*special*/dev*
              uri: https://github.com/special/config-repo
            local:
              pattern: local*
              uri: file:/home/configsvc/config-repo

如果 {application}/{profile} 不符合任何模式，則會使用在 spring.cloud.config.server.git.uri 下定義的預設 URI。在上述範例中，對於「simple」儲存庫，模式為 simple/* (它只符合所有 Profile 中名為 simple 的一個應用程式)。「local」儲存庫符合所有 Profile 中以 local 開頭的所有應用程式名稱 (/* 後綴會自動新增至任何沒有 Profile 比對器的模式)。

只有在要設定的唯一屬性是 URI 時，才能使用「simple」範例中使用的「單行」捷徑。如果您需要設定其他任何內容 (認證、模式等等)，則需要使用完整形式。

repo 中的 pattern 屬性實際上是一個陣列，因此您可以使用 YAML 陣列 (或屬性檔案中的 [0]、[1] 等後綴) 來繫結到多個模式。如果您要執行具有多個 Profile 的應用程式，您可能需要這樣做，如下例所示

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          repos:
            development:
              pattern:
                - '*/development'
                - '*/staging'
              uri: https://github.com/development/config-repo
            staging:
              pattern:
                - '*/qa'
                - '*/production'
              uri: https://github.com/staging/config-repo

Spring Cloud 會猜測包含不以 * 結尾的 Profile 的模式表示您實際上想要比對以此模式開頭的 Profile 清單 (因此 */staging 是 ["*/staging", "*/staging,*"] 等等的捷徑)。這在例如您需要在本機以「development」Profile 執行應用程式，但在遠端以「cloud」Profile 執行應用程式的情況下很常見。

每個儲存庫也可以選擇性地將組態檔儲存在子目錄中，並且可以將搜尋這些目錄的模式指定為 search-paths。以下範例顯示頂層的組態檔

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          search-paths:
            - foo
            - bar*

在前面的範例中，伺服器會在頂層和 foo/ 子目錄中搜尋組態檔，也會搜尋名稱以 bar 開頭的任何子目錄。

預設情況下，伺服器會在首次請求組態時複製遠端儲存庫。伺服器可以設定為在啟動時複製儲存庫，如下面的頂層範例所示

spring:
  cloud:
    config:
      server:
        git:
          uri: https://git/common/config-repo.git
          repos:
            team-a:
                pattern: team-a-*
                cloneOnStart: true
                uri: https://git/team-a/config-repo.git
            team-b:
                pattern: team-b-*
                cloneOnStart: false
                uri: https://git/team-b/config-repo.git
            team-c:
                pattern: team-c-*
                uri: https://git/team-a/config-repo.git

在前面的範例中，伺服器會在啟動時 (在接受任何請求之前) 複製 team-a 的 config-repo。所有其他儲存庫在請求來自儲存庫的組態之前都不會複製。

將儲存庫設定為在 Config 伺服器啟動時複製，可以協助快速識別組態來源設定錯誤 (例如無效的儲存庫 URI)，同時 Config 伺服器正在啟動。如果未針對組態來源啟用 cloneOnStart，Config 伺服器可能會在組態來源設定錯誤或無效的情況下成功啟動，並且在應用程式請求來自該組態來源的組態之前，不會偵測到錯誤。

驗證

若要在遠端儲存庫上使用 HTTP 基本驗證，請分別新增 username 和 password 屬性 (不在 URL 中)，如下例所示

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          username: trolley
          password: strongpassword

如果您不使用 HTTPS 和使用者認證，當您將金鑰儲存在預設目錄 (~/.ssh) 中，且 URI 指向 SSH 位置 (例如 [email protected]:configuration/cloud-configuration) 時，SSH 也應該可以正常運作。重要的是，~/.ssh/known_hosts 檔案中存在 Git 伺服器的項目，且格式為 ssh-rsa。不支援其他格式 (例如 ecdsa-sha2-nistp256)。為了避免意外，您應該確保 known_hosts 檔案中只有 Git 伺服器的一個項目，且該項目與您提供給 Config 伺服器的 URL 相符。如果您在 URL 中使用主機名稱，您希望在 known_hosts 檔案中擁有完全相同的主機名稱 (而不是 IP)。儲存庫是透過使用 JGit 存取的，因此您找到的任何相關文件都應該適用。HTTPS Proxy 設定可以在 ~/.git/config 中設定，或 (以與任何其他 JVM 程序相同的方式) 使用系統屬性 (-Dhttps.proxyHost 和 -Dhttps.proxyPort) 設定。

如果您不知道 ~/.git 目錄在哪裡，請使用 git config --global 來操作設定 (例如，git config --global http.sslVerify false)。

JGit 需要 PEM 格式的 RSA 金鑰。以下是 ssh-keygen (來自 openssh) 命令範例，它將產生正確格式的金鑰

ssh-keygen -m PEM -t rsa -b 4096 -f ~/config_server_deploy_key.rsa

警告：使用 SSH 金鑰時，預期的 ssh 私密金鑰必須以 -----BEGIN RSA PRIVATE KEY----- 開頭。如果金鑰以 -----BEGIN OPENSSH PRIVATE KEY----- 開頭，則在啟動 spring-cloud-config 伺服器時將無法載入 RSA 金鑰。錯誤訊息如下所示

- Error in object 'spring.cloud.config.server.git': codes [PrivateKeyIsValid.spring.cloud.config.server.git,PrivateKeyIsValid]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [spring.cloud.config.server.git.,]; arguments []; default message []]; default message [Property 'spring.cloud.config.server.git.privateKey' is not a valid private key]

為了修正上述錯誤，RSA 金鑰必須轉換為 PEM 格式。上面提供了使用 openssh 產生適當格式新金鑰的範例。

使用 AWS CodeCommit 進行驗證

Spring Cloud Config 伺服器也支援 AWS CodeCommit 驗證。從命令列使用 Git 時，AWS CodeCommit 會使用驗證協助程式。JGit 程式庫不使用此協助程式，因此如果 Git URI 符合 AWS CodeCommit 模式，則會建立 AWS CodeCommit 的 JGit CredentialProvider。AWS CodeCommit URI 遵循此模式

https://git-codecommit.${AWS_REGION}.amazonaws.com/v1/repos/${repo}

如果您提供具有 AWS CodeCommit URI 的使用者名稱和密碼，它們必須是提供儲存庫存取權的 AWS accessKeyId 和 secretAccessKey。如果您未指定使用者名稱和密碼，則會使用預設認證提供者鏈擷取 accessKeyId 和 secretAccessKey。

如果您的 Git URI 符合 CodeCommit URI 模式 (稍早顯示)，您必須在使用者名稱和密碼中或在預設認證提供者鏈支援的位置之一提供有效的 AWS 認證。AWS EC2 執行個體可以使用 EC2 執行個體的 IAM 角色。

software.amazon.awssdk:auth jar 是選用相依性。如果 software.amazon.awssdk:auth jar 不在您的類別路徑中，則無論 git 伺服器 URI 為何，都不會建立 AWS Code Commit 認證提供者。

使用 Google Cloud Source 進行驗證

Spring Cloud Config 伺服器也支援針對 Google Cloud Source 儲存庫進行驗證。

如果您的 Git URI 使用 http 或 https 通訊協定，且網域名稱是 source.developers.google.com，則將使用 Google Cloud Source 認證提供者。Google Cloud Source 儲存庫 URI 的格式為 source.developers.google.com/p/${GCP_PROJECT}/r/${REPO}。若要取得儲存庫的 URI，請在 Google Cloud Source UI 中按一下「Clone」，然後選取「Manually generated credentials」。請勿產生任何認證，只需複製顯示的 URI 即可。

Google Cloud Source 認證提供者將使用 Google Cloud Platform 應用程式預設認證。請參閱 Google Cloud SDK 文件，瞭解如何在系統上建立應用程式預設認證。此方法適用於開發環境中的使用者帳戶和生產環境中的服務帳戶。

com.google.auth:google-auth-library-oauth2-http 是選用相依性。如果 google-auth-library-oauth2-http jar 不在您的類別路徑中，則無論 git 伺服器 URI 為何，都不會建立 Google Cloud Source 認證提供者。

使用屬性進行 Git SSH 組態

預設情況下，Spring Cloud Config 伺服器使用的 JGit 程式庫在使用 SSH URI 連線到 Git 儲存庫時，會使用 SSH 組態檔 (例如 ~/.ssh/known_hosts 和 /etc/ssh/ssh_config)。在 Cloud Foundry 等雲端環境中，本機檔案系統可能是暫時性的或不易存取的。對於這些情況，可以使用 Java 屬性設定 SSH 組態。為了啟動基於屬性的 SSH 組態，必須將 spring.cloud.config.server.git.ignoreLocalSshSettings 屬性設定為 true，如下例所示

  spring:
    cloud:
      config:
        server:
          git:
            uri: [email protected]:team/repo1.git
            ignoreLocalSshSettings: true
            hostKey: someHostKey
            hostKeyAlgorithm: ssh-rsa
            privateKey: |
                         -----BEGIN RSA PRIVATE KEY-----
                         MIIEpgIBAAKCAQEAx4UbaDzY5xjW6hc9jwN0mX33XpTDVW9WqHp5AKaRbtAC3DqX
                         IXFMPgw3K45jxRb93f8tv9vL3rD9CUG1Gv4FM+o7ds7FRES5RTjv2RT/JVNJCoqF
                         ol8+ngLqRZCyBtQN7zYByWMRirPGoDUqdPYrj2yq+ObBBNhg5N+hOwKjjpzdj2Ud
                         1l7R+wxIqmJo1IYyy16xS8WsjyQuyC0lL456qkd5BDZ0Ag8j2X9H9D5220Ln7s9i
                         oezTipXipS7p7Jekf3Ywx6abJwOmB0rX79dV4qiNcGgzATnG1PkXxqt76VhcGa0W
                         DDVHEEYGbSQ6hIGSh0I7BQun0aLRZojfE3gqHQIDAQABAoIBAQCZmGrk8BK6tXCd
                         fY6yTiKxFzwb38IQP0ojIUWNrq0+9Xt+NsypviLHkXfXXCKKU4zUHeIGVRq5MN9b
                         BO56/RrcQHHOoJdUWuOV2qMqJvPUtC0CpGkD+valhfD75MxoXU7s3FK7yjxy3rsG
                         EmfA6tHV8/4a5umo5TqSd2YTm5B19AhRqiuUVI1wTB41DjULUGiMYrnYrhzQlVvj
                         5MjnKTlYu3V8PoYDfv1GmxPPh6vlpafXEeEYN8VB97e5x3DGHjZ5UrurAmTLTdO8
                         +AahyoKsIY612TkkQthJlt7FJAwnCGMgY6podzzvzICLFmmTXYiZ/28I4BX/mOSe
                         pZVnfRixAoGBAO6Uiwt40/PKs53mCEWngslSCsh9oGAaLTf/XdvMns5VmuyyAyKG
                         ti8Ol5wqBMi4GIUzjbgUvSUt+IowIrG3f5tN85wpjQ1UGVcpTnl5Qo9xaS1PFScQ
                         xrtWZ9eNj2TsIAMp/svJsyGG3OibxfnuAIpSXNQiJPwRlW3irzpGgVx/AoGBANYW
                         dnhshUcEHMJi3aXwR12OTDnaLoanVGLwLnkqLSYUZA7ZegpKq90UAuBdcEfgdpyi
                         PhKpeaeIiAaNnFo8m9aoTKr+7I6/uMTlwrVnfrsVTZv3orxjwQV20YIBCVRKD1uX
                         VhE0ozPZxwwKSPAFocpyWpGHGreGF1AIYBE9UBtjAoGBAI8bfPgJpyFyMiGBjO6z
                         FwlJc/xlFqDusrcHL7abW5qq0L4v3R+FrJw3ZYufzLTVcKfdj6GelwJJO+8wBm+R
                         gTKYJItEhT48duLIfTDyIpHGVm9+I1MGhh5zKuCqIhxIYr9jHloBB7kRm0rPvYY4
                         VAykcNgyDvtAVODP+4m6JvhjAoGBALbtTqErKN47V0+JJpapLnF0KxGrqeGIjIRV
                         cYA6V4WYGr7NeIfesecfOC356PyhgPfpcVyEztwlvwTKb3RzIT1TZN8fH4YBr6Ee
                         KTbTjefRFhVUjQqnucAvfGi29f+9oE3Ei9f7wA+H35ocF6JvTYUsHNMIO/3gZ38N
                         CPjyCMa9AoGBAMhsITNe3QcbsXAbdUR00dDsIFVROzyFJ2m40i4KCRM35bC/BIBs
                         q0TY3we+ERB40U8Z2BvU61QuwaunJ2+uGadHo58VSVdggqAo0BSkH58innKKt96J
                         69pcVH/4rmLbXdcmNYGm6iu+MlPQk4BUZknHSmVHIFdJ0EPupVaQ8RHT
                         -----END RSA PRIVATE KEY-----

下表描述 SSH 組態屬性。

表 1. SSH 組態屬性
屬性名稱	備註
ignoreLocalSshSettings	如果為 `true`，則使用基於屬性的 SSH 組態，而不是基於檔案的 SSH 組態。必須設定為 `spring.cloud.config.server.git.ignoreLocalSshSettings`，而非儲存庫定義內部。
privateKey	有效的 SSH 私密金鑰。如果 `ignoreLocalSshSettings` 為 true 且 Git URI 為 SSH 格式，則必須設定。
hostKey	有效的 SSH 主機金鑰。如果也設定了 `hostKeyAlgorithm`，則必須設定。
hostKeyAlgorithm	`ssh-dss、ssh-rsa、ssh-ed25519、ecdsa-sha2-nistp256、ecdsa-sha2-nistp384 或 ecdsa-sha2-nistp521` 之一。如果也設定了 `hostKey`，則必須設定。
strictHostKeyChecking	`true` 或 `false`。如果為 false，則忽略主機金鑰的錯誤。
knownHostsFile	自訂 `.known_hosts` 檔案的位置。
preferredAuthentications	覆寫伺服器驗證方法順序。如果伺服器在 `publickey` 方法之前具有 keyboard-interactive 驗證，則這應允許規避登入提示。

Git 搜尋路徑中的佔位符

Spring Cloud Config 伺服器也支援具有 {application} 和 {profile} (以及 {label}，如果您需要) 佔位符的搜尋路徑，如下例所示

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          search-paths: '\{application}'

前面的清單會導致在與目錄同名的檔案 (以及頂層) 中搜尋儲存庫。萬用字元在具有佔位符的搜尋路徑中也有效 (任何符合的目錄都包含在搜尋中)。

強制提取 Git 儲存庫

如先前所述，如果本機副本變髒 (例如，資料夾內容被作業系統程序變更)，導致 Spring Cloud Config 伺服器無法從遠端儲存庫更新本機副本，則 Spring Cloud Config 伺服器會複製遠端 git 儲存庫。

為了解決此問題，有一個 force-pull 屬性，如果本機副本變髒，則會讓 Spring Cloud Config 伺服器強制從遠端儲存庫提取，如下例所示

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          force-pull: true

如果您有多個儲存庫組態，您可以針對每個儲存庫設定 force-pull 屬性，如下例所示

spring:
  cloud:
    config:
      server:
        git:
          uri: https://git/common/config-repo.git
          force-pull: true
          repos:
            team-a:
                pattern: team-a-*
                uri: https://git/team-a/config-repo.git
                force-pull: true
            team-b:
                pattern: team-b-*
                uri: https://git/team-b/config-repo.git
                force-pull: true
            team-c:
                pattern: team-c-*
                uri: https://git/team-a/config-repo.git

force-pull 屬性的預設值為 false。

刪除 Git 儲存庫中未追蹤的分支

由於 Spring Cloud Config 伺服器在將分支簽出到本機儲存庫後 (例如，透過標籤擷取屬性) 具有遠端 git 儲存庫的副本，因此它將永遠保留此分支，或直到下次伺服器重新啟動 (這會建立新的本機儲存庫) 為止。因此，可能會發生遠端分支已刪除，但其本機副本仍然可供擷取的情況。如果 Spring Cloud Config 伺服器用戶端服務以 --spring.cloud.config.label=deletedRemoteBranch,master 啟動，它將從 deletedRemoteBranch 本機分支擷取屬性，而不是從 master 擷取。

為了保持本機儲存庫分支的乾淨和與遠端同步 - 可以設定 deleteUntrackedBranches 屬性。這將使 Spring Cloud Config 伺服器強制從本機儲存庫刪除未追蹤的分支。範例

spring:
  cloud:
    config:
      server:
        git:
          uri: https://github.com/spring-cloud-samples/config-repo
          deleteUntrackedBranches: true

deleteUntrackedBranches 屬性的預設值為 false。

Git 重新整理速率

您可以使用 spring.cloud.config.server.git.refreshRate 控制 Config 伺服器從您的 Git 後端擷取更新的組態資料的頻率。此屬性的值以秒為單位指定。預設值為 0，表示 Config 伺服器會在每次請求時從 Git 儲存庫擷取更新的組態。如果值為負數，則不會發生重新整理。

預設標籤

用於 Git 的預設標籤為 main。如果您未設定 spring.cloud.config.server.git.defaultLabel 且名為 main 的分支不存在，則 Config 伺服器預設也會嘗試簽出名為 master 的分支。如果您想要停用後備分支行為，您可以將 spring.cloud.config.server.git.tryMasterBranch 設定為 false。