Git 後端

EnvironmentRepository 的預設實現使用 Git 後端，這對於管理升級和物理環境以及審計更改非常方便。要更改倉庫的位置，您可以在配置伺服器中（例如在 application.yml 中）設定 spring.cloud.config.server.git.uri 配置屬性。如果您使用 file: 字首進行設定，它應該可以從本地倉庫工作，這樣您就可以快速輕鬆地開始，而無需伺服器。但是，在這種情況下，伺服器直接在本地倉庫上操作而無需克隆它（它是否是裸倉庫無關緊要，因為配置伺服器從不更改“遠端”倉庫）。要擴充套件配置伺服器並使其高可用，您需要讓所有伺服器例項都指向同一個倉庫，因此只有共享檔案系統才能工作。即使在這種情況下，最好使用 ssh: 協議來訪問共享檔案系統倉庫，以便伺服器可以克隆它並使用本地工作副本作為快取。

此倉庫實現將 HTTP 資源的 {label} 引數對映到 Git 標籤（提交 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 Server 支援帶有 {application} 和 {profile} 佔位符的 Git 倉庫 URL（如果您需要，也可以是 {label}，但請記住標籤仍然作為 Git 標籤應用）。因此，您可以使用類似於以下結構來支援“每個應用程式一個倉庫”策略

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

您還可以透過使用類似模式但帶有 {profile} 來支援“每個配置檔案一個倉庫”策略。

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

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

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

模式匹配和多個倉庫

Spring Cloud Config 還支援透過應用程式和配置檔名稱進行模式匹配來滿足更復雜的需求。模式格式是 {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/*（它只匹配所有配置檔案中名為 simple 的一個應用程式）。“local”倉庫匹配所有配置檔案中以 local 開頭的所有應用程式名稱（/* 字尾會自動新增到任何沒有配置檔案匹配器的模式）。

“simple”示例中使用的“一行”快捷方式只能在唯一要設定的屬性是 URI 時使用。如果您需要設定其他任何內容（憑據、模式等），則需要使用完整形式。

倉庫中的 pattern 屬性實際上是一個數組，因此您可以使用 YAML 陣列（或屬性檔案中的 [0]、[1] 等字尾）來繫結到多個模式。如果您將執行具有多個配置檔案的應用程式，您可能需要這樣做，如以下示例所示

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 猜測，包含不以 * 結尾的配置檔案的模式意味著您實際上想匹配以該模式開頭的配置檔案列表（因此 */staging 是 ["*/staging", "*/staging,*"] 的快捷方式，等等）。這在例如您需要在本地執行“development”配置檔案中的應用程式，但在遠端執行“cloud”配置檔案中的應用程式時很常見。

每個倉庫還可以選擇將配置檔案儲存在子目錄中，並且可以指定用於搜尋這些目錄的模式，即 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 的配置倉庫。所有其他倉庫都不會被克隆，直到請求了該倉庫的配置。

在配置伺服器啟動時設定要克隆的倉庫有助於快速識別配置錯誤的配置源（例如無效的倉庫 URI），而配置伺服器正在啟動。如果配置源未啟用 cloneOnStart，則配置伺服器可能會成功啟動，但配置源配置錯誤或無效，並且在應用程式從該配置源請求配置之前不會檢測到錯誤。

身份驗證

要在遠端倉庫上使用 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 也應該可以直接使用。重要的是 Git 伺服器的條目必須存在於 ~/.ssh/known_hosts 檔案中，並且必須是 ssh-rsa 格式。不支援其他格式（例如 ecdsa-sha2-nistp256）。為避免意外，您應該確保 known_hosts 檔案中只有一個 Git 伺服器條目，並且它與您提供給配置伺服器的 URL 匹配。如果您在 URL 中使用主機名，則您希望在 known_hosts 檔案中精確地是該主機名（而不是 IP）。倉庫透過 JGit 訪問，因此您找到的任何相關文件都應該適用。HTTPS 代理設定可以在 ~/.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 Server 還支援 AWS CodeCommit 身份驗證。AWS CodeCommit 在命令列使用 Git 時使用身份驗證助手。此助手不與 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 Server 還支援針對 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 中點選“克隆”，然後選擇“手動生成的憑據”。不要生成任何憑據，只需複製顯示的 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 Server 使用的 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` 方法之前具有鍵盤互動式身份驗證，這應該可以避免登入提示。

Git 搜尋路徑中的佔位符

Spring Cloud Config Server 還支援帶有 {application} 和 {profile} 佔位符（如果您需要，也可以是 {label}）的搜尋路徑，如以下示例所示

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

前面的列表導致在倉庫中搜索與目錄同名的檔案（以及頂層）。萬用字元在帶有佔位符的搜尋路徑中也有效（任何匹配的目錄都包含在搜尋中）。

Git 倉庫中的強制拉取

如前所述，Spring Cloud Config Server 會克隆遠端 git 倉庫，以防本地副本變得髒（例如，資料夾內容被 OS 程序更改），導致 Spring Cloud Config Server 無法從遠端倉庫更新本地副本。

為了解決這個問題，有一個 force-pull 屬性，它使 Spring Cloud Config Server 在本地副本髒時強制從遠端倉庫拉取，如以下示例所示

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 Server 在將分支檢出到本地倉庫（例如透過標籤獲取屬性）後會克隆遠端 git 倉庫，因此它將永久保留此分支，直到下次伺服器重新啟動（這將建立新的本地倉庫）。因此，可能會出現遠端分支被刪除但其本地副本仍然可用於獲取的情況。如果 Spring Cloud Config Server 客戶端服務以 --spring.cloud.config.label=deletedRemoteBranch,master 啟動，它將從 deletedRemoteBranch 本地分支獲取屬性，而不是從 master 獲取。

為了保持本地倉庫分支幹淨並與遠端倉庫同步，可以設定 deleteUntrackedBranches 屬性。它將使 Spring Cloud Config Server 強制從本地倉庫刪除未跟蹤的分支。示例

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 控制配置伺服器從 Git 後端獲取更新配置資料的頻率。此屬性的值以秒為單位指定。預設值為 0，這意味著配置伺服器將在每次請求時從 Git 倉庫獲取更新的配置。如果值為負數，則不會進行重新整理。

預設標籤

Git 的預設標籤是 main。如果您不設定 spring.cloud.config.server.git.defaultLabel 並且不存在名為 main 的分支，配置伺服器將預設嘗試檢出名為 master 的分支。如果您想停用回退分支行為，可以將 spring.cloud.config.server.git.tryMasterBranch 設定為 false。

在容器中使用 Git 執行配置伺服器

如果在容器中執行配置伺服器時遇到類似於以下內容的 java.io.IOException

2022-01-03 20:04:02,892 [tributeWriter-2] ERROR org.eclipse.jgit.util.FS$FileStoreAttributes.saveToConfig - Cannot save config file 'FileBasedConfig[/.config/jgit/config]'
java.io.IOException: Creating directories for /.config/jgit failed

您必須

在容器內提供具有可寫主目錄的使用者。
在容器內設定環境變數 XDG_CONFIG_HOME 以指向 Java 程序具有寫入許可權的目錄。