企业官网建设流程全解析

• 后端
• 认证鉴权
• 单点登录

CAS 的 Spring Cloud 配置服务器支持从 Microsoft Azure Key Vault Secrets 读取属性和设置，使敏感配置可以脱离应用包独立托管。本文以仓库中的 Spring Cloud Azure KeyVault 配置指南 为主体，结合模块源码与依赖声明，完整讲解如何在 WAR overlay 中引入cas-server-support-configuration-cloud-azure-keyvault模块、Azure Key Vault 的属性命名规则与.→-自动转换机制，以及该模块在配置服务器与 CAS 独立部署两种场景下的使用方式。读完本文，你将能够把 CAS 的系统配置平滑迁移到 Azure Key Vault，并掌握验证与排障的完整手段。

一、模块定位：外部化配置的最后一块拼图

CAS 本身支持使用外部且集中的配置服务器来获取状态与设置（详见 Configuration Server - Spring Cloud）。配置服务器对 CAS Web 应用而言完全透明——应用只向配置服务器请求属性，并不关心底层属性源是文件系统、git/svn仓库、MongoDb、Vault 还是云上的密钥服务。

Spring Cloud Azure KeyVault 模块正是这一机制下的又一个属性源：它让Spring Cloud 配置服务器（以及独立的 CAS server overlay）能够直接使用 Azure Key Vault Secrets 来定位属性和设置，将凭证、连接串等敏感信息集中托管在 Azure 中，避免配置散落在各部署环境里。

该模块在仓库中的定位可以精确印证：

• 模块目录：support/cas-server-support-configuration-cloud-azure-keyvault；
• build.gradle 中的描述为"Loads CAS configuration from Azure Key Vault so settings can be managed outside the application package."（从 Azure Key Vault 加载 CAS 配置，使设置可在应用包外部管理），所属分类为Configuration Management。

二、添加依赖：在 WAR Overlay 中引入模块

在 WAR overlay 中通过以下依赖启用该功能：

implementation "org.apereo.cas:cas-server-support-configuration-cloud-azure-keyvault"

从依赖声明可以看到该模块的技术底座（见 build.gradle）：

dependencies { implementation libraries.azurekeyvault implementation libraries.springcloudbootstrap implementation project(":core:cas-server-core-util-api") }

其中：

• libraries.azurekeyvault依赖组在 gradle/dependencies.gradle 中展开，由三个 Spring Cloud Azure 组件构成：
  • spring-cloud-azure-starter-keyvault-secrets：Key Vault 密钥读取的核心 starter；
  • spring-cloud-azure-starter-keyvault-sdk：Key Vault SDK 支持；
  • spring-cloud-azure-starter-actuator：健康检查与指标端点。
  • 依赖组统一排除了slf4j-api、nimbus-jose-jwt、spring-boot-starter-logging与spring-boot-starter-web，以避免与 CAS 自身的日志、JWT 与 Web 栈冲突。
• 上述依赖的版本由 gradle/libs.versions.toml 统一管理，当前仓库使用的 Spring Cloud Azure 版本为7.4.0（对应springCloudAzure版本目录项）。

说明：版本号以当前仓库 gradle/libs.versions.toml 实际声明为准，升级 CAS 版本时请同步核对。

三、核心要点：Azure Key Vault 的命名规则与属性自动转换

这是使用本模块时必须首先理解的关键机制。

Azure Key Vault 允许的密钥名称模式为^[0-9a-zA-Z-]+$，即只允许数字、大小写字母与连字符-。而 CAS 属性名通常包含.，例如cas.some.property，这种名称无法直接存入 Key Vault。

因此，存储属性时需将名称中的.全部替换为-：

模块会自动处理这一转换——你无需在代码或配置中做任何映射，cas-some-property被读取后会自动还原为cas.some.property供 CAS 使用。

结合依赖组成可以推断其底层实现路径：spring-cloud-azure-starter-keyvault-secrets作为属性源（PropertySource）挂入 Spring 环境，模块在读取时完成名称还原，这一行为由该 starter 的通用机制承担，CAS 侧只需保证依赖引入正确即可。

提示：由于名称模式限制，属性名中不应出现下划线_、点号之外的其他特殊字符；如确有必要，建议先重构为合法的[0-9a-zA-Z-]字符集内的名称。

四、配置客户端：通过spring.cloud.azure.keyvault.secret.*控制行为

模块读取行为通过 Spring Cloud Azure 的标准属性前缀spring.cloud.azure.keyvault.secret.*控制。常见配置项（依据所依赖的spring-cloud-azure-starter-keyvault-secrets组件约定）包括：

一个典型的application.yml配置示例：

spring: cloud: azure: keyvault: secret: property-source-enabled: true endpoint: https://cas-config.vault.azure.net/ profile: tenant-id: ${AZURE_TENANT_ID} credential: client-id: ${AZURE_CLIENT_ID} client-secret: ${AZURE_CLIENT_SECRET}

其中AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET建议通过环境变量或 CI/CD 机密注入，避免明文落盘。具体属性清单与默认值请以仓库所锁定的 Spring Cloud Azure7.4.0的官方属性文档为准。

五、两种使用场景：配置服务器与 CAS 独立部署

官方文档特别强调：这些配置模块不只属于 Spring Cloud 配置服务器，也可以原样用于 CAS server overlay 内部。

场景一：配置服务器（推荐）

将cas-server-support-configuration-cloud-azure-keyvault加入配置服务器 overlay，配置服务器即从 Key Vault 拉取配置，再通过标准的/{name}/{profile}/{label}协议提供给 CAS Web 应用（关于配置服务器 overlay 的部署方式，参见 WAR Overlay Initializr）。

场景二：CAS 独立部署直接读取

在 CAS server overlay 中直接引入该模块，即可让 CAS 在独立（standalone）运行模式下直接访问 Azure Key Vault 获取设置。此时各属性源（文件、git、Vault、KeyVault 等）可以并存、混用，共同为 CAS 提供配置。

客户端侧：bootstrap 阶段的注意事项

无论哪种场景，配置服务器的客户端属性（如spring.cloud.config.*）都必须写入 CAS 自身的src/main/resources/bootstrap.properties，因为这部分设置必须在bootstrap 阶段、其余应用配置尚未从配置服务器读取之前先行加载。客户端默认绑定为：

"name" = ${spring.application.name} "profile" = ${spring.profiles.active} "label" = "master"

三者均可通过spring.cloud.config.name/spring.cloud.config.profile/spring.cloud.config.label覆盖；label支持逗号分隔的回退列表（如myfeature,develop），可用于灰度与回滚，详见 Configuration-Management-Reload。

六、验证与排障

配置服务器默认运行在8888端口、上下文路径/casconfigserver，端点以 Basic Auth 保护（默认用户casuser）。引入 KeyVault 模块后，可通过以下方式确认配置是否正确加载。

1. 查看配置服务器对native配置档案的完整视图：

curl -u casuser:Mellon https://config.server.url:8888/casconfigserver/cas/native

2. 在开启 actuator 的前提下，枚举配置服务器当前所有属性源（应能看到 Azure Key Vault 对应的 PropertySource）：

curl -u casuser:Mellon https://config.server.url:8888/casconfigserver/actuator/env

常用排查思路：

• 属性加载失败：核对 Key Vault 密钥名称是否满足^[0-9a-zA-Z-]+$，确认.已全部替换为-；
• 认证失败：核对endpoint、tenant-id、client-id、client-secret四要素，确认服务主体对目标 Key Vault 具有Get/List密钥权限；
• 版本与冲突：若同时使用多个属性源，可通过/actuator/env的优先级顺序判断哪个源覆盖了同名属性；配置服务器的order属性数值越小优先级越高。

七、更多配置源与延伸阅读

Azure KeyVault 只是配置服务器众多属性源之一。仓库还提供了 Amazon S3、Amazon Secret Manager、Amazon SSM、DynamoDb、Etcd、HashiCorp Consul、HashiCorp Vault、JDBC、MongoDb、ZooKeeper 与 GCP Secret Manager 等方案；如需同时从多个仓库拉取配置，可启用多个 profile 并借助order属性设定优先级（详见 Configuration-Server-Management-SpringCloud）。配置服务器还提供overrides机制，可为所有客户端强制注入不可被覆盖的默认值。

八、小结

Spring Cloud Azure KeyVault 模块为 CAS 的配置管理提供了一个安全、集中的云属性源：通过 WAR overlay 依赖 引入、遵循.→-的命名转换规则、以spring.cloud.azure.keyvault.secret.*控制连接，即可让配置服务器或独立 CAS 实例从 Azure Key Vault 加载全部设置。建议在配置服务器中开启 KeyVault 属性源，并结合/actuator/env与健康检查端点持续监控配置加载状态，实现配置与应用的彻底解耦。

• 后端
• 认证鉴权
• 单点登录