企业官网建设流程全解析

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

本文聚焦 Apereo CAS 的配置管理核心——配置服务器（Configuration Server）。随着 CAS 部署从开发、测试一路进入生产环境，如何在不同环境之间安全、可控地管理配置，是每个采用者必须解决的问题。本文基于官方文档，结合仓库源码，完整讲解 CAS 的两种配置消费策略（默认的 Standalone 独立模式与基于 Spring Cloud 的外部化配置服务器）、配置文件的命名与加载顺序、加密安全、热加载（Reload）以及集群部署下的 Spring Cloud Bus 广播机制。读完本文，你将能够独立搭建 CAS 配置体系，并掌握在多环境、多节点场景下管理配置的完整方法论。

配置策略总览：两种配置消费方式

CAS 服务器 Web 应用根据以下两种策略来决定设置（settings）如何被消费：

两种策略的核心差异在于：Standalone 模式把配置文件和 CAS 应用放在一起（或指向本地预定义目录），部署简单但缺乏云端部署所需的部分能力；Spring Cloud 模式则将配置集中托管在一个独立服务中，CAS 应用作为该服务的客户端，在任何环境下都通过同一套抽象接口获取设置。

默认策略：Standalone 独立模式

Standalone 是 CAS 的默认配置模式，表示 CAS不需要连接外部配置服务器，而是在嵌入式standalone mode下运行。开启该选项后，CAS 默认会尝试在一组预定义目录和文件中定位设置，兜底目录通常是/etc/cas/config。

配置文件命名与定位规则

与 Spring Cloud 外部配置服务器类似，Standalone 配置目录的内容同样由(cas|application).(yml|properties)文件组成，用于控制 CAS 行为。该目录可被 CAS 监控，自动拾取变更并刷新应用上下文（详见后文"配置热加载"）。

默认情况下，所有 CAS 设置都由 CAS 服务器 Web 应用内嵌的application.properties文件控制。此外还有一份内嵌的application.yml，允许你把配置直接打包进主 Web 应用而不依赖外部配置文件；如果你偏好 properties 语法，application-standalone.properties还可以覆盖application.properties。外部配置文件中的设置可以覆盖 CAS 提供的默认值。

CAS 配置目录内配置文件的命名遵循以下模式：

• application.(properties|yml|yaml)文件始终被加载（如果存在）。
• 文件名匹配spring.application.name值的properties|yml|yaml文件会被加载（例如cas.properties）。注意：spring.application.name默认是大写CAS，但小写名称同样会被加载。
• 文件名匹配spring.profiles.active值的properties|yml|yaml文件会被加载（例如ldap.properties）。
• 打包 Web 应用之外的 profile 专用应用属性文件（application-{profile}.properties|yml|yaml）。这允许你将设置拆分成多个属性文件，通过把文件名赋给激活 profile 列表来定位它们（例如spring.profiles.active=standalone,testldap,stagingMfa）。

配置文件加载顺序

假设spring.profiles.active=standalone,profile1,profile2，配置文件按以下顺序加载。注意：最后加载的配置文件会覆盖先前加载文件中重复的属性：

1. application.(properties|yml|yaml)
2. （小写）spring.application.name.(properties|yml|yaml)
3. spring.application.name.(properties|yml|yaml)
4. application-standalone.(properties|yml|yaml)
5. standalone.(properties|yml|yaml)
6. application-profile1.(properties|yml|yaml)
7. profile1.(properties|yml|yaml)
8. application-profile2.(properties|yml|yaml)
9. profile2.(properties|yml|yaml)

扩展名处理与类路径覆盖规则

如果存在基名相同但扩展名不同的两个配置文件，它们按properties、yml、yaml、groovy的顺序处理（存在重复属性时，最后处理的文件生效）。这些外部配置文件会覆盖位于 classpath 中的文件（例如 CAS overlay 中最终进入WEB-INF/classes的src/main/resources文件）。但内部文件的加载遵循 Spring Boot 规则，与上述 CAS Standalone 规则不同（例如<profile>.properties不会从 classpath 加载，而application-<profile>.properties会）。

配置源目录

CAS 默认按以下顺序尝试定位设置：

1. /etc/cas/config
2. /opt/cas/config
3. /var/cas/config

Groovy 配置脚本

CAS 还可以加载 Groovy 脚本来获取设置。该文件预期位于上述匹配目录中，命名为${cas-application-name}.groovy，例如cas.groovy。脚本能够在同一位置组合"按 profile 过滤的条件设置"与"适用于所有环境/所有 profile 的公共设置"，结构类似下面的示例：

// 设置可按 profile 单独过滤 profiles { standalone { cas.some.setting="value" } } // 以下设置适用于所有 profile 和环境 cas.common.setting="value"

要启用对 Apache Groovy 的支持，请参考 Apache Groovy 脚本集成指南。

此外，还可以使用一个专用配置文件，以文件或 classpath 资源的形式直接向 CAS 注入一批属性。这在以下场景特别有用：CAS 裸机部署在云上、没有配置服务器或外部目录，且部署者希望避免覆盖内嵌配置文件。

cas.standalone.* 配置项

Standalone 模式的专用配置由cas.standalone.*系列属性控制。在源码 StandaloneConfigurationProperties.java 中可以看到三个核心字段：

• cas.standalone.configuration-directory：描述 CAS 配置所在目录路径（对应上面的/etc/cas/config等目录）。
• cas.standalone.configuration-file：描述包含 CAS 属性的单一配置文件路径（即"以文件形式直接喂给 CAS 一批属性"的机制）。
• cas.standalone.configuration-security：配置安全设置，用于加密/解密值。这些设置通常通过命令行属性或系统/环境变量传入，因为属性在 bootstrap 阶段就要被读取；放在这里是为了让 CAS 在传入时能够识别其合法性。

从源码看，该类的字段"并不直接被使用"——它们由运行时环境通过 PropertySource Locator 直接访问以引导 CAS 设置。在 CasCoreBaseEnvironmentConfiguration.java 中注册了standaloneConfigurationFilePropertiesSourceLocatorBean，而 StandaloneConfigurationFilePropertiesSourceLocator.java 以Ordered.HIGHEST_PRECEDENCE最高优先级，把独立配置文件包装成CompositePropertySource注入环境。这说明 Standalone 模式下配置文件中的属性具有非常高的生效优先级，能够可靠地覆盖内嵌默认值。

覆盖内置配置的注意事项

官方文档给出了明确警告：不要覆盖或修改内置的application.properties或bootstrap.properties文件，这只会让你的部署变得复杂且脆弱。应尽量遵循 CAS 默认值，通过application.yml、application-standalone.properties覆盖，或使用文档中列出的策略引导 CAS，并尽量让 CAS 定位其自身之外的配置文件。"过早的优化只会导致混乱。"

外部化策略：Spring Cloud 配置服务器

CAS 能够使用外部集中式配置服务器获取状态和设置。配置服务器为 CAS（及其所有客户端）提供了一种非常抽象的方式，从多种来源获取设置：文件系统、git或svn仓库、MongoDb 数据库、Vault 等。这种方案的美妙之处在于：对 CAS Web 应用服务器而言，设置来自哪里并不重要，它完全不知道底层属性源的存在——它只需要与配置服务器通信以定位设置即可。

这同时也是保证配置安全的好策略：配置不会散落在各个部署环境中。配置服务器无需暴露给外部世界，可以安全地藏在防火墙之后，仅允许 CAS Web 应用等授权客户端访问。

部署配置服务器（Overlay）

配置服务器本身与 CAS 类似，可以通过 CAS Initializr（WAR Overlay） 部署，对应模块为org.apereo.cas:cas-server-webapp-config-server（仓库中位于 webapp/cas-server-webapp-config-server）。

除了常规配置策略外，配置服务器自身按以下顺序和机制加载 CAS 设置：

1. 打包 Web 应用之外的 profile 专用应用属性（application-{profile}.properties|yml）
2. 打包在 jar 内部的 profile 专用应用属性（application-{profile}.properties|yml）
3. 打包 jar 之外的应用属性（application.properties|yml）
4. 打包在 jar 内部的应用属性（application.properties|yml）

配置服务器自身的启动配置

配置服务器的行为和配置由其自己的src/main/resources/bootstrap.properties文件控制。仓库中的 bootstrap.properties 展示了默认形态：

spring.application.name=casconfigserver spring.profiles.active=native spring.cloud.config.server.native.search-locations=file:///etc/cas/config # spring.profiles.active=default # spring.cloud.config.server.git.uri=https://github.com/repoName/config # spring.cloud.config.server.git.uri=file://${user.home}/config spring.cloud.config.server.encrypt.enabled=true encrypt.key-store.location=file:///etc/cas/casconfigserver.jks encrypt.key-store.password=changeit encrypt.key-store.alias=cas encrypt.key-store.secret=changeit

默认情况下，配置服务器运行在嵌入式 Apache Tomcat 中，端口8888，上下文路径/casconfigserver，端点由基本认证保护，默认凭据为casuser与在src/main/resources/application.properties中定义的自动生成密码。仓库中的 application.properties 进一步证实了这些默认值：server.port=8888、server.servlet.context-path=/casconfigserver、spring.security.user.name=casuser（密码Mellon以注释形式给出示例）、management.endpoints.web.exposure.include=env,info,health。此外，默认运行在nativeprofile 下（见下文"Native 来源"）。

配置服务器暴露的端点

配置服务器暴露以下受保护的端点：

部署好配置服务器后，假设用于保护配置服务器的凭据与下面示例一致，你可以通过如下命令观察设置集合：

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

假设配置中已启用 actuator 端点，你还可以观察为配置服务器提供设置的所有属性源集合：

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

需要记住：actuator 端点通常以/actuator为前缀。

此外，CAS 还提供health、casConfig等 actuator 端点，以及refresh、configServerHealthIndicator健康指示器，用于监控配置服务器自身状态。

客户端（CAS Web 应用）接入配置

要让 CAS 服务器 Web 应用（或任何其他客户端）与配置服务器通信，需要在 CAS 自己的src/main/resources/bootstrap.properties中配置以下设置。把 CAS Web 应用配置为配置服务器客户端的属性，必须在 bootstrap 阶段、其余配置从配置服务器读取之前被读取，因此只能放在bootstrap.properties中。

核心属性前缀为spring.cloud.config.*（如spring.cloud.config.uri、spring.cloud.config.name、spring.cloud.config.profile、spring.cloud.config.label）。配置服务器以/{name}/{profile}/{label}的路径向应用提供属性源，客户端应用中的默认绑定如下：

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

三者都可以通过设置spring.cloud.config.*（其中*为name、profile或label）来覆盖。label可用于回滚到配置的先前版本：在默认 Config Server 实现中，它可以是 git 标签、分支名或提交 ID。label 也可以作为逗号分隔的列表提供，此时列表中的各项会按顺序逐一尝试，直到某个成功为止。这在开发功能分支时非常有用——例如你希望配置 label 与你的分支对齐，但又希望它是可选的（如spring.cloud.config.label=myfeature,develop）。

配置来源（Sources）与配置 profile

存在多种配置 profile 决定配置服务器如何检索属性和设置：

• Default（git/svn）
• Native（本地文件系统）
• REST
• Amazon S3
• Amazon Secret Manager
• Amazon SSM
• Azure KeyVault
• DynamoDb
• Etcd
• HashiCorp Consul
• HashiCorp Vault
• JDBC
• MongoDb
• ZooKeeper
• GCP Secret Manager

以最常用的两种为例：

Native 来源（配置服务器的默认模式）：配置服务器默认从外部位置/etc/cas/config加载cas.(properties|yml)文件。该位置会被服务器持续监控以检测外部变更；此目录只需存在即可，不需要特殊权限或结构，但目录内配置文件名需要匹配spring.application.name（即cas.properties）。如需使用额外配置文件，其形式必须为application-<profile>.(properties|yml)；application.(properties|yml)默认会被包含。profile 专用文件可通过bootstrap.properties中的spring.profiles.include激活：

spring.profiles.active=native spring.cloud.config.server.native.search-locations=file:///etc/cas/config spring.profiles.include=profile1,profile2

外部位置托管的一个.properties文件示例如下（同样可以换成cas.yml承载变更）：

cas.server.name=...

Default 来源（git/svn）：Spring Cloud 配置服务器能够处理托管 CAS 配置的git或svn仓库。此类仓库既可以位于部署本地，也可以以 GitHub/Bitbucket 等形式位于云端；访问云端仓库可以是用户名/密码形式，也可以走 SSH（前提是 CAS 部署环境配置了相应密钥，这与平时通过 SSH 访问 git 仓库并无差别）。仓库可使用 YAML 和 properties 两种语法承载配置，默认 profile 通过spring.profiles.active=default激活。

在以上所有策略中，官方强烈建议：只保留和维护你的部署真正需要的属性，完全没有必要把全部 CAS 设置拷贝到外部位置——外部配置位置或仓库中定义的设置能够覆盖 CAS 提供的默认值。

组合来源（Composite Sources）

某些场景下你可能希望从多个环境仓库拉取配置数据，只需在配置服务器的 application properties 或 YAML 文件中启用多个 profile 即可。例如，同时从 Git 仓库和 SVN 仓库拉取配置数据：

spring: profiles: active: git, svn cloud: config: server: svn: uri: file:///path/to/svn/repo order: 2 git: uri: file:///path/to/git/repo order: 1

除了为每个仓库指定 URI，你还可以指定order属性：order允许你为所有仓库指定优先级顺序，数值越小优先级越高。仓库的优先级顺序将有助于解决多个仓库包含相同属性值时可能产生的冲突。

属性覆盖（Property Overrides）

配置服务器还有一个"overrides（覆盖）"特性，允许运维人员向所有应用提供配置属性，且应用无法通过常规变更事件和钩子意外修改这些属性。声明方式是把一组名称-值对加入spring.cloud.config.server.overrides，例如：

spring: cloud: config: server: overrides: foo: bar

这将使 CAS 服务器（作为配置服务器的客户端）独立于其自身配置地读取到foo=bar。

配置安全：加密敏感设置

CAS 支持多种方式对敏感配置进行加密保护。配置安全与加密/解密策略不仅适用于单个设置项，也可能适用于由特定设置定义的资源文件内容。CAS 提供以下加密策略：

详细内容参见 Configuration-Properties-Security 指南。值得注意的是，配置服务器默认开启了加密支持（spring.cloud.config.server.encrypt.enabled=true），并使用位于/etc/cas/casconfigserver.jks的 JKS 密钥库（见上文 bootstrap.properties），/encrypt与/decrypt端点正是为此提供服务的。

配置热加载：Reload 机制

CAS Spring Cloud 配置服务器能够通过前文所述的 profile 消费属性和设置，并持续自动监控底层属性源的变化，但它没有办法把这些变更广播给自己的客户端（如 CAS 服务器本身）——CAS 服务器扮演"配置服务器的客户端"角色，期望收到变更通知后静默重载配置。

因此，为了广播这类change事件，CAS 提供了多个管理端点允许采用者按需刷新配置。也就是说：采用者修改某个 CAS 设置后，向 CAS 提交刷新请求即可。所有受外部变更影响的 CAS 内部组件都会静默重载，设置立即生效，完全无需容器重启或 CAS 重新部署。

官方文档特别强调：大多数（甚至可以说全部）CAS 设置都是可重载的候选对象，整个 CAS Web 应用（包含所有模块与所有相关设置）都可以被完整、彻底地重载。CAS 应用上下文及包含所有 Spring 组件和 Bean 定义的运行时环境，可通过以下管理端点重载：features、refresh、busenv、butshotdown、bus-refresh、busrefresh、serviceregistry。

如果使用 Standalone 配置 profile 控制设置且禁用 Spring Cloud 配置服务器，CAS 可能会开始自动监视该 profile 指示的配置文件，并自动重载运行时应用上下文的状态。该支持需要在 WAR overlay 中引入依赖org.apereo.cas:cas-server-core-events-configuration。

需要理解@RefreshScope的边界：Spring 应用上下文无法刷新在初始化/启动时被排除（或按条件激活/创建）的 Bean，因为根本没有可刷新的对象。刷新请求和标记为@RefreshScope的 Bean 只在应用上下文层级中存在可刷新的 Bean 引用时才会生效；在启动过程中被跳过的 Bean 或配置类永远不会可刷新，因为它们不会在刷新请求时被重新创建。换句话说，刷新请求在"某个已有设置的值从 A 变成 B"的场景下效果最佳；如果一开始就没有 A，或者 A 被移除，刷新请求与重载策略就可能力不从心。

集群部署：Spring Cloud Bus 广播

在分布式部署中，CAS 使用Spring Cloud Bus管理配置。Spring Cloud Bus 通过轻量级消息代理将分布式系统的各个节点连接起来，可用来广播状态变更（例如配置变更）或其他管理指令。总线支持向所有监听节点发送消息，广播的事件会尝试更新、刷新并重载每个 CAS 服务器应用的配置。

如果 CAS 节点没有共享配置属性的中心位置（即每个节点都持有设置副本），那么你对某个节点所做的任何更改都必须复制并同步到所有节点并持久化到磁盘——上述广播机制只作用于运行时和正在运行的 CAS 实例。理想做法是：将 CAS 设置维护在共享的（git）仓库中（甚至是一个私有仓库），在一处变更后广播到所有节点，从而彻底消除跨磁盘和跨 CAS 节点同步变更的需要。

消息代理策略

以下策略可用于将分布式部署的 CAS 节点连接至轻量级消息代理，以广播状态变更（如配置变更）或其他管理指令：

相关配置属性前缀为spring.cloud.bus.*，总线事件传输由上述组件之一处理。Spring Cloud 提供的相关 actuator 端点包括：features、refresh、busenv、bus-refresh、busrefresh、busshutdown、serviceregistry。

故障排查

如需排查总线问题，可修改日志配置文件增加以下 Logger 以开启调试日志：

<Logger name="org.springframework.cloud.bus" level="debug" additivity="false"> <AppenderRef ref="casConsole"/> <AppenderRef ref="casFile"/> </Logger>

属性优先级与编码注意事项

无论使用上述哪种策略，CAS 都允许你将配置外部化，从而在不同环境下使用同一个 CAS 实例。你可以使用 properties 文件、YAML 文件、环境变量和命令行参数来实现外部化。CAS 使用一个特别设计的顺序来保证值的合理覆盖，传递给 CAS Web 应用的属性按以下顺序生效：

1. 命令行参数，以--开头（例如--server.port=9000）
2. SPRING_APPLICATION_JSON中的属性（内嵌在环境变量/系统属性中的 JSON）
3. 来自java:comp/env的 JNDI 属性
4. 配置服务器和 profile 指示的配置文件（即application.properties|yml）
5. 操作系统环境变量
6. Java 系统属性

YAML 还是 Properties？CAS 配置在以下任何策略中都同时支持 YAML 和 Properties 语法，通常用哪种语法并不重要——但当属性值是 Unicode 字符串时就有区别了：Spring 使用ISO-8859-1编码加载 properties 文件，而 YAML 文件以 UTF-8 编码加载。因此，如果需要设置 Unicode 值，请使用 YAML 配置文件。

此外，为便于排查配置，可通过 actuator 端点configProps、env、beans、conditions观察实际生效的配置；启动时 CAS 会显示 banner 和诊断信息，可用系统属性-DCAS_BANNER_SKIP=true跳过；启动事件跟踪（-DCAS_APP_STARTUP）支持default（无操作）、buffering（内存缓存事件并经startup端点暴露）、jfr（写入 Java Flight Recorder 会话）三种模式，详见 Configuration-Management。

小结

CAS 的配置管理围绕"策略选择"展开：默认的 Standalone 模式以本地目录（/etc/cas/config、/opt/cas/config、/var/cas/config）和严格的加载顺序保证了开箱即用的配置体验；Spring Cloud 配置服务器模式则把配置集中托管，支持 git/svn、MongoDb、Vault、云厂商密钥管理等十余种来源，并借助/encrypt、/decrypt端点保障敏感信息安全。在此基础上，CAS 通过管理端点实现配置热加载，通过 Spring Cloud Bus（AMQP / Kafka）在集群节点间广播变更。掌握这两条主线，你就能在多环境、多节点的生产部署中游刃有余地管理 CAS 配置。

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