此版本仍在开发中，目前尚不稳定。如需最新稳定版本，请使用 Spring Cloud Config 5.0.1！spring-doc.cadn.net.cn

Git 后端

默认的 EnvironmentRepository 实现使用 Git 后端，这在管理升级和物理环境以及审计变更方面非常便捷。要更改存储库的位置，您可以在配置服务器（例如在 application.yml 中）设置 spring.cloud.config.server.git.uri 配置属性。如果您使用 file: 前缀进行设置，它应能从本地仓库中正常工作，从而让您无需服务器即可快速轻松地开始开发。然而，在这种情况下，服务器直接在本地仓库上操作，而无需对其进行克隆（是否为裸仓库并不重要，因为配置服务器永远不会对“远程”仓库进行任何更改）。为了扩展配置服务器并使其具备高可用性，您需要确保所有服务器实例都指向同一个仓库，因此只有共享文件系统才能满足要求。即使在这种情况下，也建议为共享文件系统仓库使用 ssh: 协议，以便服务器可以对其进行克隆，并将本地工作副本用作缓存。spring-doc.cadn.net.cn

此存储库实现将 HTTP 资源的 {label} 参数映射到 Git 标签（提交 ID、分支名称或标签）。
如果 Git 分支或标签名称中包含斜杠（/），则 HTTP URL 中的标签应改用特殊字符串 ({special-string}) 指定（以避免与其他 URL 路径产生歧义）。
例如，若标签为 foo/bar，替换斜杠后得到的标签为：foo({special-string})bar。
特殊字符串 ({special-string}) 也可应用于 {application} 参数。
如果您使用命令行客户端（如 curl），请注意 URL 中的括号——您应使用单引号（' '）将其从 shell 中转义。spring-doc.cadn.net.cn

跳过SSL证书验证

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

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

设置连接超时

您可以配置配置服务器等待获取 HTTP 或 SSH 连接的时间（以秒为单位）。使用 git.timeout 属性（默认值为 5）。spring-doc.cadn.net.cn

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

Git URI 中的占位符

Spring Cloud Config Server 支持带有占位符的 Git 仓库 URL，用于 {application} 和 {profile}（如果需要的话还可包括 {label}），但请注意，标签最终仍会以 Git 标签的形式应用。因此，您可以通过采用类似以下的结构，来支持“每个应用一个仓库”的策略。spring-doc.cadn.net.cn

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

您还可以通过使用类似的模式但配合{profile}来支持‘每个配置文件一个仓库’的策略。spring-doc.cadn.net.cn

此外，在您的 {application} 参数中使用特殊字符串 ({special-string}) 可以启用对多个组织的支持，如下例所示：spring-doc.cadn.net.cn

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

其中 {application} 是在请求时以以下格式提供的： organization({special-string})application。spring-doc.cadn.net.cn

模式匹配与多个仓库

Spring Cloud Config 还包括对更复杂需求的支持，支持根据应用程序名称和配置文件名称进行模式匹配。模式格式为以逗号分隔的 {application}/{profile} 个名称列表，其中包含通配符（注意：以通配符开头的模式可能需要加引号），如下例所示：spring-doc.cadn.net.cn

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 开头的应用名称（在任何不包含配置文件匹配器的模式末尾，系统会自动添加 /* 后缀）。spring-doc.cadn.net.cn

在“简单”示例中使用的“一行式”快捷方式仅当需要设置的唯一属性是 URI 时才可使用。如果需要设置其他内容（如凭据、模式等），则必须使用完整形式。

仓库中的 pattern 属性实际上是一个数组，因此您可以使用 YAML 数组（或属性文件中的 [0]、[1] 等后缀）来绑定多个模式。如果要运行具有多个配置文件的应用程序，您可能需要这样做，如下例所示：spring-doc.cadn.net.cn

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,*"] 的快捷方式，依此类推）。

spring-doc.cadn.net.cn

这种情况很常见，例如，您需要在本地以 “development” 配置文件运行应用程序，同时又需在远程以 “cloud” 配置文件运行。spring-doc.cadn.net.cn

每个存储库还可以可选地在子目录中存储配置文件，并且可以指定搜索这些目录的模式，如 search-paths 所示。以下示例显示了位于顶层的配置文件：spring-doc.cadn.net.cn

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

在前面的示例中，服务器会在顶层目录以及 foo/ 子目录中查找配置文件，并且还会查找任何以 bar 开头的子目录。spring-doc.cadn.net.cn

默认情况下，服务器在首次请求配置时会克隆远程仓库。服务器可配置为在启动时克隆这些仓库，如下所示的顶级示例：spring-doc.cadn.net.cn

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，然后才开始接受任何请求。所有其他仓库直到从该仓库请求配置后才会被克隆。spring-doc.cadn.net.cn

在配置服务器启动时，将存储库设置为要克隆的仓库，有助于在配置服务器启动过程中快速识别配置源的错误配置（例如无效的仓库 URI），而无需等待应用程序从该配置源请求配置。

spring-doc.cadn.net.cn

当某个配置源未启用 cloneOnStart 时，配置服务器可能成功启动，但其使用了错误或无效的配置源；此时系统不会立即检测到错误，直到有应用程序向该配置源请求配置信息时才会发现问题。spring-doc.cadn.net.cn

身份验证

要对远程仓库使用 HTTP 基本认证，请分别添加 username 和 password 属性（而非在 URL 中），如下例所示：spring-doc.cadn.net.cn

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 进行访问，因此您在 JGit 上找到的任何文档均适用。HTTPS 代理设置可在 ~/.git/config 中设置，或（如同其他任何 JVM 进程一样）通过系统属性（-Dhttps.proxyHost 和 -Dhttps.proxyPort）进行设置。spring-doc.cadn.net.cn

如果您不知道您的 ~/.git 目录位于何处，可使用 git config --global 来修改设置（例如，git config --global http.sslVerify false）。

JGit 要求 RSA 密钥使用 PEM 格式。下面是一个来自 OpenSSH 的 ssh-keygen 示例命令，该命令可生成符合要求的密钥格式：spring-doc.cadn.net.cn

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 密钥将无法加载。该错误表现如下：spring-doc.cadn.net.cn

- 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 的示例，用于生成符合要求格式的新密钥。spring-doc.cadn.net.cn

与 AWS CodeCommit 的身份验证

Spring Cloud Config Server 还支持 AWS CodeCommit 身份验证。
AWS CodeCommit 在使用 Git 命令行时会使用一个身份验证辅助工具。
但该辅助工具不适用于 JGit 库，因此当 Git URI 匹配 AWS CodeCommit 的模式时，会为 AWS CodeCommit 创建一个 JGit 凭据提供程序（CredentialProvider）。
AWS CodeCommit 的 URI 遵循以下模式：spring-doc.cadn.net.cn

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

如果您为 AWS CodeCommit URI 提供了用户名和密码，它们必须是提供对存储库访问权限的 AWS 访问密钥 ID 和秘密访问密钥。
如果您未指定用户名和密码，则会通过使用 默认凭证提供程序链 来检索访问密钥 ID 和秘密访问密钥。spring-doc.cadn.net.cn

如果您的 Git URI 与 CodeCommit URI 模式（如前所示）匹配，则必须在用户名和密码中提供有效的 AWS 凭据，或在默认凭据提供程序链所支持的任一位置中提供。
AWS EC2 实例可使用 EC2 实例的 IAM 角色。spring-doc.cadn.net.cn

software.amazon.awssdk:auth jar 是一个可选依赖项。

spring-doc.cadn.net.cn

如果 software.amazon.awssdk:auth jar 不在您的类路径中，则无论 Git 服务器 URI 为何，AWS Code Commit 凭据提供程序均不会被创建。spring-doc.cadn.net.cn

与 Google Cloud Source 的身份验证

Spring Cloud Config Server 还支持对 Google Cloud Source 仓库进行身份验证。spring-doc.cadn.net.cn

如果您的 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 界面中点击“克隆”，然后选择“手动生成凭据”。请勿生成任何凭据，只需复制显示的 URI 即可。spring-doc.cadn.net.cn

Google Cloud Source 凭据提供程序将使用 Google Cloud Platform 应用默认凭据。有关如何为系统创建应用默认凭据的详细信息，请参阅 Google Cloud SDK 文档。此方法在开发环境中适用于用户账户，在生产环境中适用于服务账户。spring-doc.cadn.net.cn

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）。spring-doc.cadn.net.cn

  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 配置属性。spring-doc.cadn.net.cn

<p>表 1. SSH 配置属性</p>
属性名称 备注

忽略本地SSH设置spring-doc.cadn.net.cn

如果 true，则使用基于属性的配置而非基于文件的 SSH 配置。必须设置为 spring.cloud.config.server.git.ignoreLocalSshSettings，不能在仓库定义内部设置。spring-doc.cadn.net.cn

privateKeyspring-doc.cadn.net.cn

有效的 SSH 私钥。如果 ignoreLocalSshSettings 为 true 且 Git URI 格式为 SSH，则必须设置。spring-doc.cadn.net.cn

hostKeyspring-doc.cadn.net.cn

有效的 SSH 主机密钥。如果也设置了 hostKeyAlgorithm，则必须设置。spring-doc.cadn.net.cn

hostKeyAlgorithmspring-doc.cadn.net.cn

其中一个 ssh-dss, ssh-rsa, ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, or ecdsa-sha2-nistp521。如果也设置了 hostKey，则必须设置。spring-doc.cadn.net.cn

strictHostKeyCheckingspring-doc.cadn.net.cn

true 或 false。如果为 false，则忽略主机密钥相关的错误。spring-doc.cadn.net.cn

knownHostsFilespring-doc.cadn.net.cn

自定义 .known_hosts 文件的位置。spring-doc.cadn.net.cn

首选认证方式spring-doc.cadn.net.cn

重写服务器身份验证方法的顺序。这应允许在服务器在 publickey 方法之前执行键盘交互式身份验证时绕过登录提示。spring-doc.cadn.net.cn

Git 搜索路径中的占位符

Spring Cloud Config Server 还支持包含占位符的搜索路径，用于 {application} 和 {profile}（如果您需要，还可使用 {label}），如下例所示：spring-doc.cadn.net.cn

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

前面的清单会导致在存储库中搜索与目录同名的文件（以及顶层目录）。通配符在搜索路径中也有效，并支持占位符（任何匹配的目录都将包含在搜索中）。spring-doc.cadn.net.cn

强制拉取 Git 仓库

如前所述，Spring Cloud Config Server 会在本地副本变得“脏”（例如，由操作系统进程更改文件夹内容）时，克隆远程 Git 仓库，以确保 Spring Cloud Config Server 能够从远程仓库更新本地副本。spring-doc.cadn.net.cn

为了解决此问题，有一个 force-pull 属性，可使 Spring Cloud Config Server 在本地副本已脏时强制从远程仓库拉取，如下例所示：spring-doc.cadn.net.cn

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

如果您配置了多个仓库（multiple-repositories），可以为每个仓库单独配置 force-pull 属性，如以下示例所示：spring-doc.cadn.net.cn

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 中获取。spring-doc.cadn.net.cn

为了保持本地仓库分支的整洁并同步远程仓库，可设置 deleteUntrackedBranches 属性。这将使 Spring Cloud Config Server 强制 删除本地仓库中未跟踪的分支。
示例：spring-doc.cadn.net.cn

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 仓库中获取最新的配置。如果该值为负数，则不会进行刷新。spring-doc.cadn.net.cn

defaultLabel

默认用于 Git 的标签是 main。如果您未设置 spring.cloud.config.server.git.defaultLabel，且不存在名为 main 的分支，则配置服务器将默认也会尝试检出一个名为 master 的分支。如果您希望禁用备用分支行为，可将 spring.cloud.config.server.git.tryMasterBranch 设置为 false。spring-doc.cadn.net.cn

使用 Git 在容器中运行配置服务器

如果您在运行配置服务器（Config Server）时，其容器环境与以下情况类似，可能会遇到 java.io.IOException：spring-doc.cadn.net.cn

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

您必须选择以下任一选项：spring-doc.cadn.net.cn

  1. 为用户提供一个可写入的主目录，该目录位于容器内部。spring-doc.cadn.net.cn

  2. 设置容器内的环境变量 XDG_CONFIG_HOME，使其指向一个 Java 进程具有写入权限的目录。spring-doc.cadn.net.cn