Git 后端

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 中转义它们。

跳过 SSL 证书验证

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

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 开头的应用程序名称（/* 后缀自动添加到没有配置文件匹配器的任何模式）。

“简单”示例中使用的“单行”快捷方式仅当要设置的唯一属性是 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 的 config-repo，然后才接受任何请求。所有其他存储库都不会克隆，直到请求来自该存储库的配置。

在配置服务器启动时设置要克隆的存储库有助于快速识别配置源的错误配置（例如无效的存储库 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）。为了避免意外情况，您应该确保 Git 服务器的known_hosts文件中只存在一个条目，并且它与您提供给配置服务器的 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。