跳至主要內容

Spring Cloud Config Server、Client 与配置仓库工具手册

高谷深陵大约 17 分钟约 5122 字
Spring Cloud Config Server Client 与配置仓库治理知识海报
Spring Cloud Config Server、Client 与配置仓库参考图从 Config Server 与 Git / native backend 进入 application、profile、label、propertySources、refresh 和凭证治理。高清原图

配置仓库已经提交，服务为什么仍然没有变化

一次典型故障是：配置仓库中的超时已经从 2000 改成 5000，Config Server 的 HTTP 响应也能看到新值，但订单服务仍按旧超时运行。这里至少跨过了三道边界：Git 提交是否被 Config Server 拉到本地克隆，application/profile/label 是否选择了正确的 Environment，客户端是否重新加载并把新值绑定到正在使用的对象。把“Git 有新提交”等同于“运行实例已经生效”，会让排障从一开始就走错方向。

Config Server 把后端数据映射成 Spring Environment。请求路径中的 {application} 对应客户端 spring.application.name，{profile} 对应活动 profile，{label} 表示版本化配置集。响应里的 propertySources 按优先级从高到低排列；同名 key 最终取哪个值，应该从这个顺序解释，而不是只搜索文件内容。

先锁定一条兼容的发行线

Spring Cloud Config 不能脱离 Spring Boot 和 Spring Cloud release train 单独选版本。稳定参考文档提供 5.0.4、4.3.4、4.2.4 和 4.1.7 等版本线；5.0.4 随 Spring Cloud release train 版本 2025.1.2 使用，该 train 对应 Spring Boot 4.0.x，Spring Cloud release train 版本 2025.1.2 也支持 Boot 4.1.x。这些数字都是正式版本标识，不是日历承诺。

新项目先在 Spring Initializr 选择 Boot 和 Config Server/Config Client，再用 Spring Cloud 兼容矩阵核对 release train。下面示例使用 Boot 4.1.0 和 Spring Cloud release train 版本 2025.1.2；维护中的 Boot 3 项目应继续选择兼容的 4.x Config 线，不要为了追随 Config 5.x 跨代升级运行时。

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>4.1.0</version>
</parent>

<properties>
  <java.version>17</java.version>
  <spring-cloud.version>${env.SPRING_CLOUD_RELEASE_TRAIN}</spring-cloud.version>
</properties>

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-dependencies</artifactId>
      <version>${spring-cloud.version}</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-config-server</artifactId>
  </dependency>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
  </dependency>
</dependencies>

运行构建前把 SPRING_CLOUD_RELEASE_TRAIN 注入为上方核对的 release train 版本；若项目由 Initializr 生成，也可以保留它直接写入的 BOM 版本。Server 与 Client 都由同一 BOM 管理，不在单个依赖上另钉版本。

Spring Cloud Config 和 Spring Cloud 的代码采用 Apache-2.0 许可证。许可证宽松不代表仓库中的业务配置、第三方驱动或企业支持服务自动使用同一许可；引入商业 Git、Vault 或托管平台时仍要分别核对授权和支持周期。

从一个本地 Git 仓库启动 Config Server

准备 JDK 17+、Maven、Git，并确认 8888 未占用。启动类只有一个关键开关：

@SpringBootApplication
@EnableConfigServer
public class ConfigServerApplication {
  public static void main(String[] args) {
    SpringApplication.run(ConfigServerApplication.class, args);
  }
}

先创建可审计的配置仓库：

mkdir -p ~/te-config-repo
cd ~/te-config-repo
git init -b main

cat > application.yml <<'EOF'
logging:
  level:
    root: INFO
EOF

cat > order-service-dev.yml <<'EOF'
feature:
  order:
    verify: true
order:
  timeout-ms: 3000
EOF

git add application.yml order-service-dev.yml
git commit -m "初始化订单服务配置"

application.yml 对所有客户端共享，order-service-dev.yml 只作用于 order-service 的 dev profile。Config Server 配置如下：

server:
  port: 8888

spring:
  cloud:
    config:
      server:
        accept-empty: false
        git:
          uri: file://${user.home}/te-config-repo
          default-label: main
          clone-on-start: true

accept-empty: false 让不存在的应用返回 404，避免空 Environment 被误判为正常；default-label 固定默认分支；clone-on-start 在服务启动时发现仓库 URI 或凭证错误，而不是等第一个客户端请求才暴露。官方 Git backend 的当前默认 label 已是 main，当 main 不存在时会尝试 master；可用 try-master-branch: false 关闭回退。团队仍应显式写出默认 label，让回滚和迁移不依赖隐含行为。

Windows 的绝对文件 URI 要写成 file:///C:/...。容器中还要给运行用户可写的 home 或显式 Git basedir，否则 JGit 可能因无法创建配置目录而失败。

启动并读取：

./mvnw spring-boot:run

curl -fsS http://127.0.0.1:8888/order-service/dev
curl -fsS http://127.0.0.1:8888/order-service/dev/main

预期 JSON 中 name 为 order-service，profiles 包含 dev，label 为 main，propertySources 里能看到 order-service-dev.yml 和共享 application.yml。响应还会携带 Git version，它是证明 Config Server 读到哪个提交的直接证据。

正向实验：从远程属性绑定到运行对象

客户端加入 spring-cloud-starter-config 和 Actuator，然后配置：

spring:
  application:
    name: order-service
  profiles:
    active: dev
  config:
    import: configserver:http://127.0.0.1:8888
  cloud:
    config:
      label: main

management:
  endpoints:
    web:
      exposure:
        include: health,refresh

这里没有 optional:，因此 Config Server 不可达会阻止启动，适合把集中配置视为启动必需条件的环境。spring.config.import 是 Config Data 方式，不需要 bootstrap.yml。启动时看到对 Config Server 的多次请求通常不是重复故障：Boot 先用 default profile 拉取，以便远程配置激活额外 profile，再为最终活动 profile 拉取一次。

用类型化配置承接字段，并明确默认值与校验：

@Validated
@ConfigurationProperties(prefix = "order")
public record OrderProperties(
    @Min(100) @Max(30000) int timeoutMs) {
}

启动日志应显示已经定位到 Config Server 和对应 Environment。可增加一个仅在隔离实验中使用的只读端点返回 timeoutMs，第一次应得到 3000。随后把配置仓库改成 5000 并提交：

git add order-service-dev.yml
git commit -m "调整订单超时"

curl -fsS http://127.0.0.1:8888/order-service/dev/main
curl -fsS -X POST http://127.0.0.1:8080/actuator/refresh

第一条响应的 version 应变为新提交，并出现 5000；第二条响应通常列出发生变化的 key。只有重新绑定范围内的对象才会变化。@ConfigurationProperties 会参与重新绑定，普通单例中构造时复制的值不会凭空改变；需要重建的对象使用 @RefreshScope，但数据库连接池、线程池等有状态资源还要评估重建和并发切换风险。

反向实验：让错误 label 明确失败

保持 accept-empty: false，请求不存在的 label：

curl -i http://127.0.0.1:8888/order-service/dev/branch-does-not-exist

预期是非 2xx 响应，Config Server 日志包含 checkout 或 label 查找失败。若客户端配置成该 label，启动也应失败。这个反例把“仓库不可达”和“版本选择错误”分开：前者通常在 clone/fetch 阶段失败，后者在 checkout 指定 label 时失败。

再做一次可用性反例。把客户端 import 改成：

spring:
  config:
    import: optional:configserver:http://127.0.0.1:9999

停止 Config Server 后启动客户端，应用可以继续启动并使用本地默认值，日志会留下连接失败证据。去掉 optional: 再启动，预期在 Config Data 导入阶段失败。optional: 不是“更高可用”，而是把配置中心故障转化为默认值运行；对支付开关、权限策略等关键配置，这可能比启动失败更危险。团队要逐服务记录 fail-open 或 fail-closed 选择。

删除远程 key 也是一个重要反例。提交删除后调用 /actuator/refresh，某些既有绑定对象不会按预期清空缺失值。不要把“refresh 返回成功”当作删除已生效；检查业务对象的实际值，并为删除配置安排重启验证或显式的空值/禁用值迁移。

需要在启动阶段重试时，客户端还必须引入 spring-retry 和 spring-boot-starter-aop；只配置 spring.cloud.config.retry.* 不会形成完整重试链路：

<dependency>
  <groupId>org.springframework.retry</groupId>
  <artifactId>spring-retry</artifactId>
</dependency>
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-aop</artifactId>
</dependency>
spring:
  cloud:
    config:
      fail-fast: true
      request-connect-timeout: 2000
      request-read-timeout: 5000
      retry:
        max-attempts: 6
        initial-interval: 1000
        max-interval: 4000
        multiplier: 1.5
        use-random-policy: true

关闭 Config Server 后启动客户端，预期只重试到上限并以非零状态退出；恢复 Server 后重新启动，应取得明确的 Git version。若 import 写在 profile 专属文件中，重试参数要放到 configserver: URL 查询参数中，否则它们可能来不及影响导入阶段。随机退避用于缓解实例同时启动的冲击，总重试时间仍须小于编排平台的启动窗口。

application、profile、label 如何合并

文件后端会把共享 application.yml 与应用文件组合，再叠加 profile 文件。活动 profile 优先于默认配置；多个 profile 中靠后的 profile 优先。响应中越靠前的 propertySources 优先级越高，因此下面请求能直接解释覆盖结果：

curl -fsS http://127.0.0.1:8888/order-service/dev,mysql/main

label 在 Git 后端可以是分支、tag 或 commit id。分支适合并行开发，tag 适合可读的发布点，commit id 最精确但不便人工操作。回滚时可以 revert 配置仓库并形成新提交，也可以临时把客户端 label 固定到已验证 tag/commit；后者会把版本选择散落到应用部署配置中，恢复后必须统一清除。

Config Client 还支持逗号分隔的多个 label。Config 4.2.0+ 可配合 spring.cloud.config.send-all-labels=true 一次请求多个 label，但 Server 也必须至少为 4.2.0；版本不匹配会把整个逗号串当成一个 label。减少请求数之前先做 Server/Client 兼容测试。

Git、native 与 Vault 的选择不是同一种持久化

Git：变更审计与版本回滚优先

远程 Git 是默认后端。Config Server 会维护本地克隆，默认每次请求尝试从远端刷新；spring.cloud.config.server.git.refreshRate 以秒控制刷新间隔，0 表示每次请求刷新，负数表示不刷新。提高间隔能降低 Git 压力，却引入“仓库已提交、Server 仍返回旧 commit”的窗口，必须把响应 version 和最后 fetch 结果纳入观测。

本地克隆被其他进程改脏时，fetch/pull 可能失败。force-pull: true 会在脏目录时强制恢复，但也会删除本地意外修改；delete-untracked-branches: true 可清理远端已删除而本地仍残留的分支，避免客户端继续读到幽灵 label。这两个参数先在隔离环境验证，再用于共享服务。

HTTPS 凭证用独立 username、password 字段注入，不要嵌进 URI。SSH 由 JGit 读取，密钥格式和 known_hosts 支持与系统 Git 并不完全相同；遇到“命令行能 clone，Config Server 不能”时，要检查 JGit 日志、PEM 私钥格式和主机键，而不是关闭 TLS 校验。详细限制见官方 Git backend 文档。

native：本地联调快，但审计能力要自己补

不想准备 Git 时启用 native profile：

spring:
  profiles:
    active: native
  cloud:
    config:
      server:
        native:
          search-locations: file:${user.home}/te-config-native
          add-label-locations: false

默认搜索位置还包括 classpath、当前目录及其 config/。若没有占位符，native 默认会把 {label} 追加为子目录；add-label-locations: false 关闭这一行为。共享环境只有在文件系统可靠、所有 Config Server 实例看到同一内容且变更有外部审计时才适合 native，否则节点之间很容易返回不同配置。File System Backend列出了路径和 label 规则。

Vault：让 secret 留在密钥系统

Vault 后端适合密码、API key、证书等敏感值。启用 vault profile 后，默认使用 token 认证、secret backend 和 KV v1；KV v2 必须显式设置 kv-version: 2。最小配置示意：

spring:
  profiles:
    active: vault
  cloud:
    config:
      server:
        vault:
          host: vault.example.com
          port: 8200
          scheme: https
          backend: secret
          kv-version: 2

默认模式由客户端把 X-Config-Token 交给 Config Server，再由 Server 访问 Vault：

curl -fsS \
  -H "X-Config-Token: ${VAULT_TOKEN}" \
  http://127.0.0.1:8888/order-service/dev

这会把 Vault token 扩散到每个客户端。另一种方式是在 Config Server 配置 AppRole、Kubernetes Auth、JWT 等认证，并加入 Spring Vault Core，由 Server 集中持有 Vault 身份；这样客户端更简单，但 Config Server 身份的权限半径更大。选择时要比较 token 扩散、租户隔离、续租、审计和 Server 被攻破后的影响，不要把“接了 Vault”直接等同于敏感数据安全。Vault backend 文档还说明了 profile 路径、KV 版本和企业 namespace 头。

refresh 与 Bus 都是运行时变更入口

Git 提交只改变 Config Server 的数据源，不会主动改写所有客户端。单实例可通过重启或受保护的 /actuator/refresh 重新加载；Spring Cloud Bus 则借助 RabbitMQ 或 Kafka 把 refresh 事件广播到实例。加入 Bus 后暴露的是 /actuator/busrefresh，它会清空 RefreshScope 缓存并重新绑定 @ConfigurationProperties。

management.endpoints.web.exposure.include=busrefresh

Bus 解决事件分发，不保证每个实例完成同一业务结果。应记录配置 commit、事件 id、目标服务、每实例最后应用版本和失败重试；实例 bus id 必须唯一。/actuator/refresh、/actuator/busrefresh 和尤其能改 Environment 的 /actuator/busenv 都不能匿名暴露公网，要经过认证、授权、审计和速率限制。官方 Bus endpoint 文档列出了这些入口。

Webhook 配合 spring-cloud-config-monitor 可以把 Git 变更转成 RefreshRemoteApplicationEvent，但仓库事件、消息代理和实例消费新增了三个失败点。规模较小或配置变更低频时，滚动重启往往更容易证明一致；只有刷新时效目标确实需要时，再承担 Bus 的代理成本和运行复杂度。

{cipher} 不是凭证治理的终点

Config Server 可以在仓库中保存以 {cipher} 开头的密文，并在返回客户端前解密。/encrypt 和 /decrypt 是高敏感管理接口，只允许受控发布工具访问：

curl -fsS \
  -H "Content-Type: text/plain" \
  --data-binary "${PLAINTEXT_SECRET}" \
  http://127.0.0.1:8888/encrypt

将输出加上 {cipher} 后写入配置仓库。若密钥错误或密文损坏，Config Server 会移除原属性，并返回 invalid.<key>=<n/a>；这条字段是可稳定验证的反向证据：

curl -fsS http://127.0.0.1:8888/order-service/dev/main \
  | jq '.propertySources[].source | with_entries(select(.key | startswith("invalid.")))'

密文保护的是静态仓库，不保护 Config Server 内存、HTTP 返回、客户端 Environment 或日志。对称密钥、keystore 密码和解密权限仍要放在密钥系统中，设计轮换与多 key 过渡，并用 TLS 保护传输。更高敏感度或需要动态凭证的场景优先使用 Vault 等专用系统。加解密文档说明了失败字段和 endpoint 行为。

从故障现象反推所在层

现象第一证据常见原因修复后再验证
Server 启动成功，首次请求才失败clone/fetch 日志未启用 clone-on-start，URI 或凭证错误重启时完成 clone
Server 返回旧值响应 version 与远端 commitrefreshRate 窗口或本地克隆异常两者 commit 一致
label 请求失败HTTP 状态与 checkout 日志分支/tag 不存在或已删除指定有效 label 再读
profile 覆盖不符合预期propertySources 顺序多 profile 顺序错误对关键 key 逐层比对
客户端启动两次请求请求 profileConfig Data 两阶段加载default 与活动 profile 均成功
refresh 成功但 Bean 未变化refresh 返回 key、Bean 类型值被构造复制或对象不在刷新范围读取真实业务对象
解密后属性消失invalid.<key>密钥不匹配或密文损坏修复密钥后 invalid 字段消失
Vault 返回 403Vault audit logtoken/path/policy 不匹配最小权限身份读取目标路径

客户端连接多个 Config Server 时也要区分故障类型。spring.cloud.config.uri 支持按顺序尝试多个 URL，默认 multiple-uri-strategy=always；改成 connection-timeout-only 后，仅连接超时才切换，401、500 等错误不会被另一节点掩盖。spring.config.import 可列多个位置，但 multiple-uri-strategy 不适用于这种写法；在 import 模式下，fail-fast=true 会让第一次调用失败即终止，fail-fast=false 才会继续尝试其他位置。等价副本优先放在同一内部负载均衡地址后；直连多地址时必须验证各节点对同一 application/profile/label 返回相同 Git version，否则两个 200 也可能是配置分裂。

架构与容量取舍

单个 Config Server 加本地 Git 适合开发；共享环境通常部署多个无状态 Server 实例，前置内部负载均衡，后端使用高可用 Git 或 Vault。Server 实例虽然业务上无状态，却各自维护 Git 本地克隆和缓存；节点磁盘损坏、fetch 时间和分支残留会造成响应差异，因此要比较各节点返回的 commit，而不只是探测 /actuator/health。

容量主要受客户端启动风暴、Config Data 多次请求、Git fetch 频率、仓库数量与大小、label 数量、Vault 延迟和加解密开销影响。把数千个无关应用塞进一个仓库会放大 clone/fetch 和权限半径；一应用一仓库又会增加连接、凭证和运维对象。通常按组织边界或变更耦合度分仓，再用 repos pattern 路由，并为每个仓库设置 owner、保护分支和故障预算。

Git 后端适合审计、评审和版本化；native 适合快速实验或已有可靠共享文件系统；Vault 适合 secret 生命周期与细粒度策略；composite backend 能合并多源，却引入顺序、一致性和部分失败语义。若需求包含可视化编辑、按实例灰度、发布审核和即时回滚，专门配置平台可能比继续叠加 Config Server 周边组件更经济。

凭证、回滚与长期治理

Config Server 同时处于三个信任边界：它持有读取 Git/Vault 的凭证，向客户端返回配置，还暴露 Actuator 与加解密接口。服务本身需要 TLS 和认证；不同应用、profile 的读取权限不能只依赖“知道 URL”；Git deploy key、PAT、SSH private key、Vault 身份和加密 key 由密钥系统注入，并分别轮换。

配置仓库执行与代码仓库同级的保护：变更走评审，敏感扫描阻止明文 secret，主分支受保护，tag/commit 可追踪到变更单。每次发布记录仓库 commit、目标 application/profile/label、受影响 key、刷新方式、实例应用结果和回滚 commit。回滚优先使用 git revert 形成新历史；强制改写分支会让 Config Server 本地 clone 和审计记录产生分叉。

长期指标不使用固定万能阈值，而看负载下的趋势和不变量：各节点返回 commit 应一致；Git/Vault 错误不能随请求轮次增长；客户端启动失败与默认值回退符合既定策略；Bus 事件的目标实例最终收敛到同一配置版本；本地 clone 磁盘、分支数和仓库体积不应无界增长。成本不仅是 Server 实例，还包括消息代理、Vault、Git 高可用、密钥轮换、审计存储和团队值守。

清理实验与演练回滚

本地实验结束后停止 Config Server 和客户端，删除测试配置仓库、native 目录以及 Config Server 的临时 clone；若显式配置了 basedir，只删除已经核对过的实验目录。撤销 Git/Vault 测试凭证，清理 shell history 中误输入的 secret，并关闭临时暴露的 refresh、encrypt、decrypt endpoint。

共享环境退出前先把客户端迁移到新配置源或内置安全默认值，逐实例证明不再请求 Config Server，再撤销读取凭证和下线 Server。单纯删除 Git 仓库会让已有实例继续使用旧 Environment，新启动实例却失败，形成最难观察的分裂状态。

上线演练至少包含四条证据：错误 label 明确失败；Config Server 不可达时客户端按约定 fail-open 或 fail-closed；配置提交后各实例通过重启、refresh 或 Bus 收敛到同一 commit；回滚提交后运行对象恢复旧值。没有实际执行的环境实验应留在待办记录中，不能因为 HTTP 示例合理就声称生产链路已经通过。

跳到正文