Git Backend

EnvironmentRepository 的默认实现使用 Git 后端，这对于管理升级和物理环境以及审计更改非常方便。要更改存储库的位置，可以在 Config Server 中设置 spring.cloud.config.server.git.uri 配置属性（例如，在 application.yml 中）。如果使用 file: 前缀设置它，它应该能从本地存储库工作，这样你就可以快速轻松地开始工作，而无需服务器。但是，在这种情况下，服务器直接操作本地存储库，而不克隆它（不管它是不是裸机都不重要，因为 Config Server 永远不会更改“远程”存储库）。要纵向扩展 Config Server 并使其具有很高的可用性，你需要让服务器的所有实例都指向同一个存储库，因此只有共享的文件系统能正常工作。即使在这种情况下，也最好为共享文件系统存储库使用 ssh: 协议，这样服务器就可以克隆它并将本地工作副本用作缓存。此存储库实现将 HTTP 资源的 {label} 参数映射到 git 标签（提交 ID、分支名称或标记）。如果 git 分支或标记名称包含斜杠 (/)，则 HTTP URL 中的标签应改用特殊字符串 ({special-string}) 指定（以避免与其他 URL 路径混淆）。例如，如果标签是 foo/bar，替换斜杠将产生以下标签：foo({special-string})bar。特殊字符串 ({special-string}) 的包含也可以应用于 {application} 参数。如果你使用诸如 curl 之类的命令行客户端，请小心 URL 中的括号——你应该用单引号 (``) 从 shell 中转义它们。

Skipping SSL Certificate Validation

可以通过将 git.skipSslValidation 属性设置为 true（默认值为 false）来禁用配置服务器对 Git 服务器的 SSL 证书的验证。

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

Setting HTTP Connection Timeout

你可以配置配置服务器获取 HTTP 连接所需的时间（以秒为单位）。使用 git.timeout 属性（默认值为 5）。

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

Placeholders in 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。

Pattern Matching and Multiple Repositories

Spring Cloud Config 还包括支持针对 application 和 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/（它仅匹配所有配置文件中的一个名为 “simple” 的应用程序）。“local” 存储库匹配所有以 “local” 开头的应用程序名称，无论使用哪种配置文件（没有 profile 匹配器的任何模式都会自动添加后缀 /）。

仅当要设置的唯一属性是 URI 时，才能使用 “simple” 示例中使用的 “one-liner” 快捷方式。如果您需要设置任何其他内容（凭据、模式等），则需要使用完整表单。

repo 中的 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 猜测包含一个不会以 implies that you actually want to match a list of profiles starting with this pattern (so /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

在前面的示例中，服务器在 itaccepts 接受任何请求之前，在启动时克隆 team-a 的 config-repo。在请求存储库的配置之前，不会克隆所有其他存储库。

将存储库设置为在 Config Server 启动时克隆可以帮助快速识别配置错误的配置源（例如无效的存储库 URI），同时 Config Server 正在启动。在未为某个配置源启用 cloneOnStart 的情况下，Config Server 可能会使用错误配置或无效的配置源成功启动，并且不会在应用程序从该配置源请求配置之前检测到错误。

Authentication

要在远程存储库上使用 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 位置（例如 ` git@github.com:configuration/cloud-configuration`）时，SSH 也应该开箱即用。Git 服务器的条目出现在 ~/.ssh/known_hosts`文件中并采用 `ssh-rsa`格式这一点很重要。不支持其他格式（例如 `ecdsa-sha2-nistp256）。为了避免造成意外，您应确保 known_hosts`文件中 Git 服务器仅存在一个条目，并且它与您提供给 Config Server 的 URL 匹配。如果您在 URL 中使用主机名，您希望 `known_hosts`文件中存在精确的主机名（而不是 IP）。存储库使用 JGit 进行访问，因此您应该可以应用在此方面找到的任何文档。可以在 `~/.git/config`或（以与任何其他 JVM 进程相同的方式）使用系统属性 (-Dhttps.proxyHost`和 -Dhttps.proxyPort）中设置 HTTPS 代理设置。

如果您不知道您的 ~/.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 的示例，用于生成采用合适格式的新密钥。

Authentication with AWS CodeCommit

Spring Cloud Config Server 还支持 AWS CodeCommit身份验证。从命令行使用 Git 时，AWS CodeCommit 使用身份验证帮助器。JGit 库不会使用此帮助器，因此如果 Git URI 匹配 AWS CodeCommit 模式，它会创建一个 JGit 凭证提供者用于 AWS CodeCommit。AWS CodeCommit URI 遵循此模式：

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

如果您提供一个用户名和密码与 AWS CodeCommit URI 搭配使用，它们必须是 AWS accessKeyId and secretAccessKey才能访问存储库。如果您不指定用户名和密码，accessKeyId 和 secretAccessKey 将使用 Default Credential Provider Chain检索。

如果您的 Git URI 匹配 CodeCommit URI 模式（如前文所示），则必须在用户名和密码或默认凭证提供程序链支持的位置之一中提供有效的 AWS 凭证。AWS EC2 实例可能使用 IAM Roles for EC2 Instances。

software.amazon.awssdk:auth jar 是一个可选的依赖项。如果 software.amazon.awssdk:auth jar 不在您的类路径中，则无论 git 服务器 URI 如何，都不会创建 AWS Code Commit 凭据提供程序。

Authentication with 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 采用格式 https://source.developers.google.com/p/${GCP_PROJECT}/r/${REPO}。要获取存储库的 URI，请在 Google Cloud Source UI 中单击 “克隆”，然后选择 “手动生成凭据”。不要生成任何凭据，只需复制显示的 URI 即可。

Google Cloud Source 凭证提供程序将使用 Google Cloud Platform 应用程序默认凭证。请参阅 Google Cloud SDK documentation了解如何为系统创建应用程序默认凭证。此方法适用于开发环境中的用户帐户和生产环境中的服务帐户。

com.google.auth:google-auth-library-oauth2-http 是一个可选的依赖项。如果 google-auth-library-oauth2-http jar 不在您的类路径中，则无论 git 服务器 URI 如何，都不会创建 Google Cloud Source 凭据提供程序。

Git SSH configuration using properties

默认情况下，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: git@gitserver.com: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 配置属性。

Table 1. SSH Configuration Properties
Property Name	Remarks
ignoreLocalSshSettings	如果 `true`，使用基于属性而非基于文件的 SSH 配置。必须在 `spring.cloud.config.server.git.ignoreLocalSshSettings`、not 中设置为存储库定义。
privateKey	有效的 SSH 私钥。如果 `ignoreLocalSshSettings` 为 true 且 Git URI 为 SSH 格式，则必须设置。
hostKey	有效的 SSH 主机密钥。如果 `hostKeyAlgorithm` 也设置了，则必须设置。
hostKeyAlgorithm	`ssh-dss, ssh-rsa, ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521` 中的一个。当同时设置 `hostKey` 时必须设置。
strictHostKeyChecking	`true` 或 `false`。如果为假，则忽略主机密钥的错误。
knownHostsFile	自定义 `.known_hosts` 文件的位置。
preferredAuthentications	覆盖服务器身份验证方法顺序。如果服务器在 `publickey` 方法前具有基于键盘的交互身份验证，这应该允许其规避登录提示。

Placeholders in Git Search Paths

Spring Cloud Config Server 还支持一个带有 {application} 和 {profile}（如果你需要的话，还有 {label}）占位符的搜索路径，如下例所示：

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

前面的清单在存储库中搜索与目录同名的文件（以及顶级）。通配符在带有占位符的搜索路径中也是有效的（搜索中包括任何匹配的目录）。

Force pull in Git Repositories

如前所述，如果本地副本变脏（例如，文件夹内容被操作系统进程更改）以至于 Spring Cloud Config Server 无法从远程存储库更新本地副本，则 Spring Cloud Config Server 会克隆远程 Git 存储库。

为了解决这个问题，有一个 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。

Deleting untracked branches in Git Repositories

由于 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 Refresh Rate

你可以使用 spring.cloud.config.server.git.refreshRate 控制配置服务器从 Git 后端获取更新的配置数据的时间间隔。此属性的值以秒为单位指定。默认值为 0，这意味着配置服务器将在每次请求时从 Git 仓库获取更新的配置。如果值为负数，则不会发生刷新。

Default Label

Git 使用的默认标签是“main”。如果你没有设置 spring.cloud.config.server.git.defaultLabel 并且名为 main 的分支不存在，则配置服务器默认还会尝试结账名为 master 的分支。如果你想禁用回退分支行为，你可以将 spring.cloud.config.server.git.tryMasterBranch 设为 false。