必码

Appearance

Apereo CAS Overlay 版本迁移实战指南：从 5.3 到 6.6 再到 7.3 的全面演进 ​

作者： 必码 ｜ bima.cc

引言：为什么要写这篇指南 ​

Apereo CAS（Central Authentication Service）作为开源领域最成熟的企业级单点登录解决方案之一，其 Overlay 部署模式为广大开发者提供了高度可定制的 SSO 基础设施。然而，CAS 的版本迭代速度极快，从 5.3.x 到 6.6.x 再到 7.3.x，每一次大版本升级都伴随着 Java 版本、Spring Boot 版本、构建工具链乃至配置范式的根本性变革。根据 Apereo 官方的版本发布节奏，CAS 每年至少发布一个大版本，每个大版本的生命周期通常在 12 到 18 个月之间。这意味着企业如果选择停留在旧版本上，很快就会面临安全补丁缺失和社区支持断裂的风险。

在笔者主导的实际生产项目中，我们完整经历了从 CAS 5.3.16 到 CAS 6.6.15.2 再到 CAS 7.3.4 的三次重大迁移。这三次迁移并非简单的版本号变更，而是涉及依赖管理策略、配置风格、认证架构、安全策略、容器化方案和构建体系的全面重构。每一次迁移都伴随着大量"踩坑"经验，而这些经验在官方文档中往往语焉不详。官方文档通常只告诉你"是什么"和"怎么用"，却很少解释"为什么这样设计"以及"从旧版本迁移时需要注意什么"。本文正是要填补这一信息空白。

在大型企业环境中，CAS 往往是整个身份认证体系的核心枢纽，数十乃至上百个业务系统依赖其提供单点登录服务。任何 CAS 版本的变更都可能导致连锁反应——轻则部分业务系统登录异常，重则整个认证体系瘫痪。因此，CAS 版本迁移绝不是简单的"改版本号、重新构建、部署上线"三步曲，而是一项需要精心规划、充分测试、逐步推进的系统工程。

本文将基于真实项目的构建文件（build.gradle、application.yml、spring-common.xml 等），系统性地梳理三个版本之间的技术差异，深入分析每一次变更背后的设计动机，并提供可操作的迁移指导。所有配置示例均经过脱敏和教学化处理，旨在帮助读者理解迁移的本质而非提供可直接复制的模板。我们的目标不是让读者"照抄配置"，而是让读者"理解原理"，从而能够独立应对未来可能出现的版本迁移挑战。

需要特别说明的是，本文的分析基于 Gradle 构建的 CAS Overlay 项目。虽然 Maven 构建的项目在依赖管理细节上有所不同，但配置风格演进、认证架构变更、安全策略升级等核心内容是完全适用的。

第一章：三个版本的技术栈全景对比 ​

1.1 核心版本矩阵 ​

在深入细节之前，我们先通过一张全景对比表来建立对三个版本技术栈的整体认知：

技术维度CAS 5.3.16CAS 6.6.15.2CAS 7.3.4
Java 版本Java 8 (1.8)Java 11Java 21
Spring Boot2.7.182.7.183.5.6
Gradle7.57.59.1.0
连接池commons-dbcp 1.4commons-dbcp 1.4commons-dbcp2 2.10.0
MyBatis3.5.6 / mybatis-spring 1.3.13.5.6 / mybatis-spring 1.3.13.5.16 / mybatis-spring 3.0.3
依赖管理mavenBom + 手动排除platform() BOM + 全局排除enforcedPlatform() + 零排除
配置风格XML 为主 + 多 propertiesYAML 为主 + 精简 XML纯 YAML + 最小化 XML
SSL 密钥库PKCS12PKCS12JKS
TLS 协议TLSTLSv1.2 + TLSv1.3TLSv1.2 + TLSv1.3
Docker 构建手动 Dockerfile手动 DockerfileJib + Docker Plugin
SBOM无无CycloneDX
OAuth 加密无无AES signing + encryption
基础镜像eclipse-temurin:8-jdkeclipse-temurin:11-jdkazul/zulu-openjdk:21

这张表格揭示了一个关键事实：CAS 5.3 到 6.6 的迁移主要是"温和升级"（Java 8 到 11，Spring Boot 版本不变），而 6.6 到 7.3 则是一次"颠覆性重构"（Java 11 到 21，Spring Boot 2.x 到 3.x，Gradle 7 到 9）。理解这一差异，是制定迁移策略的基础。

从实际项目经验来看，5.3 到 6.6 的迁移工作量大约在 3 到 5 个人天（假设项目自定义扩展较少），而 6.6 到 7.3 的迁移工作量则在 10 到 20 个人天之间，后者几乎是前者的三到四倍。工作量差异的主要来源包括：Jakarta 命名空间的全量替换、MyBatis Spring 模块的大版本升级、OAuth 2.0 配置属性的命名规范变更、以及 Gradle 构建脚本的适配工作。

值得注意的是，这三个版本在 Gradle Wrapper 的版本选择上也体现了保守与激进的平衡。CAS 5.3 和 6.6 都使用 Gradle 7.5，而 CAS 7.3 直接跳到了 Gradle 9.1.0。Gradle 9.x 引入了大量的 API 废弃和移除，这意味着 CAS 7.3 的构建脚本无法在 Gradle 7.x 上运行，反之亦然。这种"一步到位"的版本跳跃虽然增加了短期迁移成本，但避免了长期维护多个 Gradle 版本兼容层的复杂性。

1.2 Java 版本跨越的深层影响 ​

从 Java 8 到 Java 11 的跨越相对平缓。Java 11 作为 LTS 版本，大部分 Java 8 的代码可以无缝迁移。主要的变更集中在模块化系统（JPMS）的影响上——虽然 CAS 本身并未完全模块化，但一些内部 API 的访问限制开始收紧。在 CAS 6.6 的 springboot.gradle 中，我们可以看到大量的 --add-opens 和 --add-exports JVM 参数，这正是为了绕过 JPMS 的强封装：

groovy
// CAS 6.6 springboot.gradle 中的 JVM 参数（教学示例）
def list = []
list.add("--add-opens")
list.add("java.base/java.lang=ALL-UNNAMED")
list.add("--add-opens")
list.add("java.base/java.nio=ALL-UNNAMED")
list.add("--add-opens")
list.add("java.base/sun.nio.ch=ALL-UNNAMED")
// ... 更多 --add-opens 参数

这些参数的存在说明 CAS 6.6 仍然大量依赖 JDK 内部 API。到了 CAS 7.3，虽然 Java 版本跃升至 21，但这些 --add-opens 参数依然存在，表明框架层面的 JPMS 适配仍在进行中。

从 Java 11 到 Java 21 的跨越则影响深远。Java 17 引入了强封装（Strong Encapsulation），默认禁止通过反射访问 JDK 内部 API。Java 21 带来了虚拟线程（Virtual Threads）、记录类（Records）、模式匹配（Pattern Matching）等语言特性。对于 CAS Overlay 项目而言，最直接的影响是：

  1. 编译目标变更：sourceCompatibility 和 targetCompatibility 从 11 变为 21
  2. 基础镜像变更：Docker 基础镜像从 eclipse-temurin:11-jdk 变为 azul/zulu-openjdk:21
  3. JVM 厂商选择：CAS 7.3 引入了 jvmVendor 属性，支持 AMAZON、ADOPTIUM、JETBRAINS 等多种 JVM 供应商

在 gradle.properties 中的配置对比：

properties
# CAS 5.3
sourceCompatibility=1.8
targetCompatibility=1.8
baseDockerImage=eclipse-temurin:8-jdk

# CAS 6.6
sourceCompatibility=11
targetCompatibility=11
baseDockerImage=eclipse-temurin:11-jdk

# CAS 7.3
sourceCompatibility=21
targetCompatibility=21
jvmVendor=AMAZON
baseDockerImage=azul/zulu-openjdk:21

1.3 Spring Boot 版本跃迁的连锁反应 ​

CAS 5.3 和 CAS 6.6 都基于 Spring Boot 2.7.18，这意味着从 5.3 升级到 6.6 时，Spring Boot 层面几乎没有变化。这也是为什么 5.3 到 6.6 的迁移相对容易的根本原因。

然而，CAS 7.3 基于 Spring Boot 3.5.6，这是一次跨越两个大版本的升级。Spring Boot 3.x 带来的核心变更包括：

Jakarta EE 命名空间迁移：这是 Spring Boot 3.x 最具破坏性的变更。所有 javax.* 包名统一迁移为 jakarta.*。对于 CAS Overlay 项目而言，这意味着：

  • javax.servlet.* 变为 jakarta.servlet.*
  • javax.validation.* 变为 jakarta.validation.*
  • javax.persistence.* 变为 jakarta.persistence.*
  • javax.mail 变为 jakarta.mail

在实际项目中，这一变更影响最深远的并非 CAS 框架本身（Apereo 团队已经在框架层面完成了迁移），而是项目自定义的扩展代码。任何直接引用 javax.* 的自定义认证处理器、自定义 Filter、自定义属性解析器都需要逐一修改。

最低 Java 版本要求：Spring Boot 3.x 最低要求 Java 17，这与 CAS 7.3 要求 Java 21 形成了"向上兼容"的关系。

自动配置报告变更：Spring Boot 3.x 对 ConditionEvaluationReport 的输出格式进行了调整，调试自动配置问题时需要适应新的报告结构。在 CAS 项目中，自动配置报告是排查"为什么某个 Bean 没有被创建"问题的核心工具。Spring Boot 3.x 将报告的输出从 /actuator/conditions 端点迁移到了 /actuator/conditions（路径不变），但报告的 JSON 结构进行了重构，增加了 condition 和 message 字段的详细程度。

配置属性迁移：部分 Spring Boot 2.x 的配置属性在 3.x 中被重命名或移除。例如 spring.http.encoding.* 在 Spring Boot 3.x 中被标记为 deprecated，推荐使用 server.servlet.encoding.*。在 CAS 7.3 的 application.yml 中，我们可以看到同时保留了两种写法以确保兼容性，这是一种务实的过渡策略。

Spring Security 配置变更：Spring Boot 3.x 基于 Spring Security 6.x，引入了基于 Lambda 的安全配置 DSL。虽然 CAS 框架内部已经完成了适配，但项目自定义的 Security 配置（如自定义认证过滤器链）需要手动迁移。在 CAS 5.3/6.6 中常见的 WebSecurityConfigurerAdapter 在 Spring Security 6.x 中已被完全移除，需要改用 SecurityFilterChain Bean 的方式声明式配置。

Actuator 端点变更：Spring Boot 3.x 对 Actuator 端点的配置路径进行了调整。在 CAS 5.3 中，端点启用/禁用使用 endpoints.enabled 和 endpoints.sensitive 配置；在 CAS 6.6/7.3 中，改为使用 management.endpoints.enabled-by-default 和 management.endpoint.<name>.enabled 的细粒度控制方式。这一变更在 CAS 6.6 中就已经体现，说明 CAS 团队在 6.6 版本中就已经为未来的 Spring Boot 3.x 迁移做了铺垫。

1.4 Gradle 构建工具的代际更替 ​

Gradle 从 7.5 到 9.1.0 的跨越同样不容忽视。Gradle 8.x 引入了一系列重大变更：

  1. Configuration Cache：Gradle 8.x 对 Configuration Cache 的支持更加严格。在 CAS 7.3 的 build.gradle 中，我们可以看到 Jib 插件与 Configuration Cache 的兼容性处理逻辑：
groovy
// CAS 7.3 build.gradle 中的 Configuration Cache 兼容处理（教学示例）
def configurationCacheRequested = services.get(BuildFeatures)
    .configurationCache.requested.getOrElse(true)

['jibDockerBuild', 'jibBuildTar', 'jib'].each { taskName ->
    getTasksByName(taskName, true).each(it -> {
        it.notCompatibleWithConfigurationCache("Jib is not compatible with configuration cache");
        it.enabled = !configurationCacheRequested
    })
}

这段代码展示了 CAS 7.3 构建脚本的一个精妙设计：当 Configuration Cache 开启时，自动禁用 Jib 相关任务，并输出提示信息告知开发者需要使用 --no-configuration-cache 参数。

  1. Plugin DSL 变更：Gradle 8.x 对 plugins {} DSL 进行了增强，推荐使用 alias 机制管理插件版本。

  2. Task API 变更：Gradle 8.x 推荐使用 tasks.register() 替代 task {}。在 CAS 7.3 的 tasks.gradle 中，我们可以清晰地看到这一变化：

groovy
// CAS 6.6 tasks.gradle（旧式 API）
task debug(group: "CAS", description: "...") {
    dependsOn 'build'
    doLast { ... }
}

// CAS 7.3 tasks.gradle（新式 API）
tasks.register('debug', JavaExec) {
    group = "CAS"
    description = "..."
    jvmArgs = ["-server", "-Xmx2048M"]
    debug = true
}
  1. Provider API 的强制使用：Gradle 8.x 强制要求在构建脚本中使用 Provider API（如 project.providers.gradleProperty()）来延迟解析属性值，避免配置阶段的副作用。

1.5 中间件与基础设施库的版本演进 ​

除了核心框架，三个版本在中间件层面的差异同样值得关注：

连接池：commons-dbcp 1.4 到 commons-dbcp2 2.10.0

这是一个容易被忽视但影响深远的变更。commons-dbcp 1.4 是 DBCP 1.x 系列的最终版本，基于 Apache Commons Pool 1.x。而 commons-dbcp2 基于 Commons Pool 2.x，提供了更丰富的连接池管理功能。

在 spring-common.xml 中的配置差异尤为明显：

xml
<!-- CAS 5.3/6.6：commons-dbcp 1.4 的属性命名 -->
<bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource">
    <property name="maxActive" value="10"/>
    <property name="maxIdle" value="10"/>
    <property name="maxWait" value="5000"/>
</bean>

<!-- CAS 7.3：commons-dbcp2 的属性命名 -->
<bean id="dataSource" class="org.apache.commons.dbcp2.BasicDataSource">
    <property name="maxTotal" value="100"/>
    <property name="maxIdle" value="30"/>
    <property name="maxWaitMillis" value="10000"/>
</bean>

关键属性映射关系：

  • maxActive -> maxTotal（语义更准确）
  • maxWait -> maxWaitMillis（单位明确化）
  • removeAbandoned -> removeAbandonedOnBorrow / removeAbandonedOnMaintenance
  • 新增 initialSize、minIdle 的更精细控制

MyBatis：从 1.3.1 到 3.0.3 的跨越

mybatis-spring 从 1.3.1 到 3.0.3 的升级幅度极大。mybatis-spring 3.0.x 要求：

  • 最低 Spring 6.x / Spring Boot 3.x
  • 最低 MyBatis 3.5.13+
  • 全面支持 Jakarta 命名空间
  • 移除了对 Spring 5.x 的兼容

这意味着 mybatis-spring 的版本升级与 Spring Boot 3.x 的升级是强绑定的，不能独立进行。

在实际项目中，mybatis-spring 3.0.3 带来的一个重要变化是 SqlSessionFactoryBean 的初始化流程。在 1.3.1 版本中，SqlSessionFactoryBean 实现了 SpringInitializingBean 接口，初始化时机由 Spring 容器控制；在 3.0.3 版本中，初始化流程经过了重构，增加了对 Spring 6.x Environment 抽象的深度集成。这一变化在大多数情况下是透明的，但如果项目中存在自定义的 SqlSessionFactory 后处理器（例如用于注册自定义 TypeHandler 或 Interceptor），可能需要调整初始化顺序。

另一个容易被忽视的变化是 MapperScannerConfigurer 的行为差异。在 mybatis-spring 1.3.1 中，MapperScannerConfigurer 的 basePackage 属性支持包路径通配符（如 cc.example.cas.*）；在 3.0.3 中，虽然仍然支持通配符，但解析逻辑进行了优化，对于包含多个模块的大型项目，扫描性能有显著提升。

Webjars 前端资源版本演进

三个版本在前端资源依赖方面也体现了技术栈的现代化趋势。CAS 5.3 依赖了大量的 Webjars 资源，包括 jQuery、Bootstrap、AngularJS、Semantic-UI、Knockout.js 等，总计超过 20 个前端库。这些库的版本普遍较旧，部分甚至已经停止维护。CAS 6.6 精简了 Webjars 依赖，移除了 AngularJS 和 Knockout.js 等过时的前端框架。CAS 7.3 进一步现代化，引入了 Material Design Components 和 MDI Icons，同时将 Bootstrap 升级到 5.3.3，jQuery 升级到 3.7.1。

对于需要自定义 CAS 登录页面的项目来说，前端库的版本升级可能影响自定义模板的兼容性。特别是 Bootstrap 从 3.x 到 5.x 的跨越，CSS 类名和 JavaScript API 都发生了重大变化，自定义主题可能需要全面重写。

Pac4j 版本的隐含升级

CAS 的认证协议支持层基于 Pac4j 库。虽然三个版本在 build.gradle 中都声明了 org.pac4j:pac4j-core、org.pac4j:pac4j-http、org.pac4j:pac4j-cas 等依赖（未显式指定版本，由 CAS BOM 管理），但实际解析的 Pac4j 版本在不同 CAS 版本间存在显著差异。CAS 5.3 使用 Pac4j 3.x，CAS 6.6 使用 Pac4j 4.x，CAS 7.3 使用 Pac4j 5.x。Pac4j 的大版本升级同样涉及 Jakarta 命名空间迁移和 API 重构，如果项目中有直接使用 Pac4j API 的自定义代码（如自定义客户端或授权器），需要同步适配。

第二章：依赖管理的演进之路 ​

依赖管理是 CAS Overlay 项目中最容易出问题的环节，也是三个版本之间差异最大的领域之一。

2.1 CAS 5.3：手动排除的"黑暗时代" ​

在 CAS 5.3 时代，依赖管理的核心特征是"大量手动排除"。由于 CAS 5.3 的 BOM 管理不够精细，许多 CAS 模块传递引入了与项目需求冲突的依赖，开发者不得不在每个依赖声明中手动排除。

以下是一个典型的 CAS 5.3 依赖声明片段（教学简化版）：

groovy
// CAS 5.3 build.gradle 依赖声明（教学示例）
dependencies {
    implementation('org.apereo.cas:cas-server-core') {
        exclude group: 'org.springframework.boot', module: 'spring-boot-devtools'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
        exclude group: 'dom4j', module: 'dom4j'
    }

    implementation('org.apereo.cas:cas-server-support-rest-authentication') {
        exclude group: 'org.springframework.boot', module: 'spring-boot-devtools'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-web'
        exclude group: 'org.slf4j', module: 'slf4j-api'
        exclude group: 'org.slf4j', module: 'jul-to-slf4j'
        exclude group: 'dom4j', module: 'dom4j'
    }

    implementation('org.apereo.cas:cas-server-support-oauth') {
        exclude group: 'org.springframework.boot', module: 'spring-boot-devtools'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-slf4j-impl'
        exclude group: 'org.apache.logging.log4j', module: 'log4j-web'
        exclude group: 'org.slf4j', module: 'slf4j-api'
        exclude group: 'org.slf4j', module: 'jul-to-slf4j'
        exclude group: 'dom4j', module: 'dom4j'
    }
    // ... 每个模块都重复类似的排除声明
}

在实际项目中，CAS 5.3 的 build.gradle 包含了超过 30 个 CAS 模块依赖，每个模块平均携带 5-7 个 exclude 声明。这种模式存在严重的问题：

  1. 维护成本极高：新增一个 CAS 模块时，必须手动复制排除列表，遗漏任何一个都可能导致依赖冲突
  2. 排除原因不透明：为什么需要排除 log4j-slf4j-impl？为什么需要排除 dom4j？这些决策的上下文信息完全丢失
  3. 版本锁定困难：CAS 5.3 还需要手动锁定特定版本的传递依赖，例如：
groovy
// CAS 5.3 中需要手动指定 Spring Data Redis 和 Jedis 版本
implementation 'org.springframework.data:spring-data-redis:1.8.23.RELEASE'
implementation 'redis.clients:jedis:2.9.3'

这些版本号的选择并非随意——spring-data-redis:1.8.23.RELEASE 是最后一个与 CAS 5.3 内部使用的 Spring Data 兼容的版本，而 jedis:2.9.3 则是为了避免与 CAS 内部依赖的 Jedis 版本冲突。

此外，CAS 5.3 还需要在 dependencyManagement 块中手动声明大量依赖版本：

groovy
// CAS 5.3 dependencyManagement（教学示例）
dependencyManagement {
    imports {
        mavenBom "org.apereo.cas:cas-server-support-bom:${project['cas.version']}"
        mavenBom 'org.apache.logging.log4j:log4j-bom:2.12.4'
    }
    dependencies {
        dependency 'org.apache.logging.log4j:log4j-core:2.12.4'
        dependency 'commons-beanutils:commons-beanutils:1.9.4'
        dependency 'org.dom4j:dom4j:2.1.3'
        dependency 'com.fasterxml.jackson.core:jackson-databind:2.13.4.2'
        dependency 'org.apache.tomcat.embed:tomcat-embed-core:8.5.32'
        // ... 更多版本声明
    }
}

2.2 CAS 6.6：platform() BOM 带来的秩序 ​

CAS 6.6 在依赖管理方面做出了显著改进，引入了 platform() BOM 导入机制，并使用 configurations.all 全局排除替代了逐模块排除。

groovy
// CAS 6.6 build.gradle 依赖管理（教学示例）
dependencies {
    // 使用 platform() 导入 BOM，版本由 BOM 统一管理
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)
    implementation platform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")

    // CAS 模块依赖——无需手动排除，无需指定版本
    implementation "org.apereo.cas:cas-server-core"
    implementation "org.apereo.cas:cas-server-support-oauth"
    implementation "org.apereo.cas:cas-server-support-redis-ticket-registry"
    // ...
}

// 全局排除配置——一处声明，处处生效
configurations {
    all {
        exclude(group: "cglib", module: "cglib")
        exclude(group: "cglib", module: "cglib-full")
        exclude(group: "org.slf4j", module: "slf4j-log4j12")
        exclude(group: "org.slf4j", module: "slf4j-simple")
        exclude(group: "org.slf4j", module: "jcl-over-slf4j")
        exclude(group: "org.apache.logging.log4j", module: "log4j-to-slf4j")
        exclude(group: "ch.qos.logback", module: "logback-core")
        exclude(group: "ch.qos.logback", module: "logback-classic")
    }
}

对比 CAS 5.3，CAS 6.6 的依赖管理改进体现在三个维度：

维度一：BOM 导入方式的标准化

CAS 5.3 使用 mavenBom 在 dependencyManagement 块中导入，而 CAS 6.6 使用 platform() 直接在 dependencies 块中导入。platform() 是 Gradle 原生的 BOM 支持方式，语义更清晰，且与 Gradle 的依赖解析机制集成更好。

维度二：全局排除的引入

CAS 5.3 需要在每个模块声明中重复 exclude，CAS 6.6 通过 configurations.all 实现了"声明一次，全局生效"。这不仅减少了代码量，更重要的是降低了遗漏排除的风险。

维度三：版本管理的自动化

CAS 6.6 中，CAS 模块的版本完全由 BOM 管理，开发者无需（也不应该）手动指定版本号。BOM 中已经包含了经过兼容性测试的版本组合。

然而，CAS 6.6 的依赖管理仍然存在不足。platform() 是"推荐"版本，而非"强制"版本。如果某个传递依赖引入了与 BOM 冲突的版本，Gradle 的依赖解析仍然可能选择错误的版本。这就是 CAS 7.3 引入 enforcedPlatform() 的原因。

2.3 CAS 7.3：enforcedPlatform() 的强制一致性 ​

CAS 7.3 将 platform() 升级为 enforcedPlatform()，这是一个关键性的变更：

groovy
// CAS 7.3 build.gradle 依赖管理（教学示例）
dependencies {
    // enforcedPlatform() 强制所有依赖使用 BOM 指定的版本
    implementation enforcedPlatform("org.apereo.cas:cas-server-support-bom:${project.'cas.version'}")
    implementation platform(org.springframework.boot.gradle.plugin.SpringBootPlugin.BOM_COORDINATES)

    // CAS 模块依赖——零手动排除
    implementation "org.apereo.cas:cas-server-core"
    implementation "org.apereo.cas:cas-server-support-oauth"
    implementation "org.apereo.cas:cas-server-support-oauth-uma"
    // ...
}

platform() 与 enforcedPlatform() 的核心区别在于版本冲突的处理策略：

  • platform()：当传递依赖引入了不同版本时，Gradle 会按照标准的版本冲突解决策略（通常选择最高版本），BOM 中的版本只是"建议"
  • enforcedPlatform()：当传递依赖引入了不同版本时，Gradle 会强制使用 BOM 中指定的版本，如果无法满足则直接报错

这一变更的意义在于：它从根本上消除了"版本漂移"的风险。在大型项目中，某个间接依赖可能引入了与你预期不同的库版本，导致运行时的 ClassCastException 或 NoSuchMethodError。enforcedPlatform() 在构建阶段就能捕获这类问题。

值得注意的是，CAS 7.3 中 CAS BOM 使用 enforcedPlatform()，而 Spring Boot BOM 仍然使用 platform()。这种不对称的设计是有意为之的——CAS 团队希望严格控制 CAS 生态内部的版本一致性，同时给予 Spring Boot 生态一定的灵活性。这种设计哲学在实际应用中的效果是：CAS 模块之间的版本冲突会在构建时立即暴露，而 Spring Boot 生态的版本冲突则仍然依赖 Gradle 的标准解析策略。对于项目开发者而言，这意味着如果你的自定义代码引入了与 CAS 内部依赖冲突的 Spring Boot 组件，仍然需要手动处理。

2.4 依赖冲突排查实战方法论 ​

在三个版本的迁移过程中，依赖冲突排查是最耗时的工作之一。以下是笔者总结的实战方法论：

步骤一：建立依赖基线

在迁移前，使用 gradle dependencies --configuration runtimeClasspath 导出当前项目的完整依赖树，作为迁移后的对比基线。建议将输出保存到文件中，便于后续的 diff 比较。同时，使用 gradle dependencies --configuration runtimeClasspath > deps-before.txt 命令生成依赖树的文本快照。

步骤二：识别版本差异

迁移后，再次导出依赖树，与基线进行 diff 比较。重点关注：

  • 同一依赖的不同版本（如 mybatis-spring:1.3.1 vs 3.0.3）
  • 新增或消失的传递依赖
  • 被排除的依赖是否仍然存在

在实际操作中，建议编写一个简单的 Shell 脚本来自动化 diff 分析，提取出所有版本发生变化的依赖，生成一份"依赖变更清单"。这份清单将成为后续测试验证的重要依据。

步骤三：使用 Dependency Insight 定位冲突源

bash
# 查看特定依赖的来源
./gradlew dependencyInsight --dependency mybatis-spring --configuration runtimeClasspath

dependencyInsight 任务的输出会显示该依赖的完整解析链路，包括哪个直接依赖引入了它、是否存在版本冲突、最终选择了哪个版本以及选择的原因。这是定位依赖冲突最有效的工具。

步骤四：验证运行时行为

构建成功不等于运行正确。特别需要验证：

  • MyBatis Mapper 接口的代理创建是否正常
  • Redis 连接池的初始化是否成功
  • OAuth 2.0 端点的 Filter 链是否完整
  • Thymeleaf 模板解析是否正常（前端资源版本变更可能导致模板渲染异常）

步骤五：回归测试

依赖变更的最终验证必须通过完整的回归测试来完成。建议至少覆盖以下场景：

  • 基本的用户名密码登录流程
  • OAuth 2.0 授权码流程（获取授权码 -> 获取访问令牌 -> 调用用户信息接口）
  • 单点登出流程（CAS 发出登出请求到所有已注册的 Service）
  • REST API 认证流程
  • 票据过期和自动清理

2.5 依赖管理的隐性成本分析 ​

在实际项目中，依赖管理的成本远不止"修改 build.gradle"这一步。以下是笔者在三次迁移中总结的隐性成本：

编译期成本：依赖变更后，所有引用变更依赖 API 的代码都需要重新编译。在大型项目中，全量编译可能需要 10 到 30 分钟。如果使用 Gradle 的增量编译，后续的编译时间会缩短，但首次编译的开销不可忽视。

测试期成本：依赖变更可能影响测试用例的行为。特别是使用 Mock 框架的测试，如果 Mock 的类签名发生了变化，测试用例会编译失败或运行时异常。

运行期成本：依赖变更可能引入性能差异。例如，commons-dbcp2 相比 commons-dbcp 1.4，连接池的实现机制发生了变化，连接获取和释放的性能特征可能不同。建议在迁移后执行性能基准测试。

安全审计成本：新引入的依赖版本可能存在已知的安全漏洞。建议在迁移后使用 OWASP Dependency-Check 或 Snyk 等工具进行安全扫描。CAS 7.3 引入的 CycloneDX SBOM 为这一步骤提供了标准化的输入。

第三章：配置风格的范式转移 ​

CAS 的配置风格经历了从"XML 为主"到"YAML 为主"再到"纯 YAML"的演进，这一转变不仅是格式上的变化，更是配置哲学的根本性转变。

3.1 CAS 5.3：XML 为主的多文件配置体系 ​

CAS 5.3 的配置体系是最复杂的，涉及多种配置文件的协同工作：

配置文件清单（CAS 5.3）：

  1. application.yml — Spring Boot 主配置
  2. spring-common.xml — 数据源、MyBatis、AOP 事务配置
  3. apereo.properties — CAS 主题资源路径
  4. cas-theme-default.properties — 默认主题 CSS/JS 路径
  5. cas_common_messages.properties — 国际化消息
  6. deployerConfigContext.groovy — CAS 部署上下文（Groovy 脚本）
  7. log4j2.xml — Log4j2 日志配置
  8. generatorConfig.xml — MyBatis Generator 配置
  9. bootstrap.properties — Spring Cloud Bootstrap 配置

在 CAS 5.3 中，spring-common.xml 承担了核心的基础设施配置职责，包括数据源、MyBatis 会话工厂、事务管理和 AOP 切面：

xml
<!-- CAS 5.3 spring-common.xml 教学示例 -->
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:tx="http://www.springframework.org/schema/tx"
       xmlns:aop="http://www.springframework.org/schema/aop">

    <!-- 数据源配置 -->
    <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource"
          destroy-method="close">
        <property name="driverClassName" value="com.mysql.cj.jdbc.Driver"/>
        <property name="url" value="jdbc:mysql://localhost:3306/cas_db"/>
        <property name="username" value="cas_user"/>
        <property name="password" value="encrypted_password"/>
        <property name="maxActive" value="10"/>
        <property name="maxWait" value="5000"/>
    </bean>

    <!-- 全通配事务策略 -->
    <tx:advice id="dao" transaction-manager="ticketTransactionManager">
        <tx:attributes>
            <tx:method name="*" propagation="REQUIRED"/>
        </tx:attributes>
    </tx:advice>

    <!-- AOP 切面配置 -->
    <aop:config>
        <aop:pointcut id="daoMethods"
            expression="execution(* org.apereo.cas.ticket.registry..*.*(..))"/>
        <aop:advisor advice-ref="dao" pointcut-ref="daoMethods"/>
    </aop:config>

    <!-- MyBatis 配置 -->
    <bean id="sqlSessionFactory"
          class="org.mybatis.spring.SqlSessionFactoryBean">
        <property name="configLocation"
                  value="classpath:mybatis/mybatis-config.xml"/>
        <property name="dataSource" ref="dataSource"/>
        <property name="mapperLocations">
            <list>
                <value>classpath:mapper/**/*.xml</value>
            </list>
        </property>
    </bean>

    <!-- Mapper 扫描——扫描整个包 -->
    <bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
        <property name="sqlSessionFactoryBeanName" value="sqlSessionFactory"/>
        <property name="basePackage" value="cc.example.cas"/>
    </bean>
</beans>

CAS 5.3 的 log4j2.xml 也相当复杂，包含了大量的自定义 Logger 配置，用于精细控制不同包的日志级别。该文件定义了控制台、文件滚动、审计日志和性能统计四个 Appender，以及数十个 AsyncLogger 配置。这种粒度的日志控制在 CAS 5.3 中是必要的，因为框架内部各模块的日志输出量差异极大。

3.2 CAS 6.6：YAML 主导的精简过渡 ​

CAS 6.6 在配置风格上做出了重要调整，核心变化包括：

移除的配置文件：

  • apereo.properties — 合并到 application.yml
  • cas-theme-default.properties — 合并到 application.yml
  • cas_common_messages.properties — 使用 CAS 默认的国际化机制

保留但精简的配置文件：

  • spring-common.xml — 精简了事务策略和 Mapper 扫描
  • deployerConfigContext.groovy — 保留但内容未变
  • log4j2.xml — 保留但日志配置开始向 YAML 迁移

新增的配置方式：

  • application.yml 中新增 logging 配置节，开始接管日志配置

CAS 6.6 的 spring-common.xml 相比 5.3 做了三个关键改进：

xml
<!-- CAS 6.6 spring-common.xml 教学示例 -->
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:tx="http://www.springframework.org/schema/tx"
       xmlns:aop="http://www.springframework.org/schema/aop">

    <!-- 数据源配置（结构不变，属性微调） -->
    <bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource"
          destroy-method="close">
        <property name="url" value="jdbc:mysql://localhost:3306/cas_db?serverTimezone=Asia/Shanghai"/>
        <!-- ... -->
    </bean>

    <!-- 改进一：精准化事务策略 -->
    <tx:advice id="dao" transaction-manager="ticketTransactionManager">
        <tx:attributes>
            <tx:method name="save*" propagation="REQUIRED"/>
            <tx:method name="update*" propagation="REQUIRED"/>
            <tx:method name="delete*" propagation="REQUIRED"/>
            <tx:method name="add*" propagation="REQUIRED"/>
            <tx:method name="remove*" propagation="REQUIRED"/>
            <tx:method name="create*" propagation="REQUIRED"/>
            <tx:method name="*" read-only="true" propagation="SUPPORTS"/>
        </tx:attributes>
    </tx:advice>

    <!-- 改进二：Mapper 扫描精准化 -->
    <bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
        <property name="sqlSessionFactoryBeanName" value="sqlSessionFactory"/>
        <property name="basePackage" value="cc.example.cas.dao"/>
        <property name="annotationClass" value="org.apache.ibatis.annotations.Mapper"/>
    </bean>

    <!-- 改进三：事务管理器 ID 统一 -->
    <bean id="ticketTransactionManager"
          class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
        <property name="dataSource" ref="dataSource"/>
    </bean>
    <tx:annotation-driven transaction-manager="ticketTransactionManager"/>
</beans>

这三个改进分别解决了 CAS 5.3 中的三个痛点：

  1. 全通配事务策略：CAS 5.3 中 name="*" + propagation="REQUIRED" 意味着所有方法都在事务中执行，包括只读查询。CAS 6.6 将写操作（save/update/delete/add/remove/create）精确匹配为 REQUIRED，其他方法设为只读的 SUPPORTS，显著降低了数据库锁竞争。

  2. Mapper 扫描范围过大：CAS 5.3 中 basePackage 设置为整个项目包（如 cc.example.cas），这可能导致非 DAO 接口被错误扫描。CAS 6.6 将范围缩小到 cc.example.cas.dao，并增加 annotationClass 过滤，只扫描带有 @Mapper 注解的接口。

  3. 事务管理器 ID 不一致：CAS 5.3 中事务管理器的 ID 是 transactionManager，但 tx:advice 引用的是 ticketTransactionManager。这种不一致在 CAS 6.6 中得到了修正。

3.3 CAS 7.3：纯 YAML 的极简主义 ​

CAS 7.3 将配置精简推向了极致：

移除的配置文件：

  • log4j2.xml — 完全迁移到 YAML 的 logging 配置节
  • deployerConfigContext.groovy — CAS 7.3 不再使用 Groovy 部署描述符
  • generatorConfig.xml — MyBatis Generator 配置移除

保留但大幅精简的 XML：

  • spring-common.xml — 仅保留数据源、MyBatis 和组件扫描

CAS 7.3 的 spring-common.xml 精简到了极致：

xml
<!-- CAS 7.3 spring-common.xml 教学示例 -->
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:context="http://www.springframework.org/schema/context">

    <!-- 组件扫描 -->
    <context:component-scan base-package="cc.example.cas"/>

    <!-- 数据源（切换到 commons-dbcp2） -->
    <bean id="dataSource" class="org.apache.commons.dbcp2.BasicDataSource"
          destroy-method="close">
        <property name="driverClassName" value="com.mysql.cj.jdbc.Driver"/>
        <property name="url" value="jdbc:mysql://localhost:3306/cas_db"/>
        <property name="username" value="cas_user"/>
        <property name="password" value="encrypted_password"/>
        <property name="initialSize" value="5"/>
        <property name="maxTotal" value="100"/>
        <property name="maxIdle" value="30"/>
        <property name="minIdle" value="5"/>
        <property name="maxWaitMillis" value="10000"/>
    </bean>

    <!-- MyBatis 配置 -->
    <bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
        <property name="dataSource" ref="dataSource"/>
        <property name="configLocation" value="classpath:mybatis/mybatis-config.xml"/>
        <property name="mapperLocations" value="classpath:mapper/**/*.xml"/>
    </bean>

    <bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
        <property name="basePackage" value="cc.example.cas.dao"/>
    </bean>

    <!-- 事务管理（简化为声明式） -->
    <bean id="transactionManager"
          class="org.springframework.jdbc.datasource.DataSourceTransactionManager">
        <property name="dataSource" ref="dataSource"/>
    </bean>
</beans>

对比三个版本的 spring-common.xml，我们可以清晰地看到演进趋势：

配置元素CAS 5.3CAS 6.6CAS 7.3
数据源commons-dbcp 1.4commons-dbcp 1.4commons-dbcp2 2.10.0
AOP 事务切面全通配精准匹配移除（Spring Boot 自动配置）
tx:annotation-driven引用 transactionManager引用 ticketTransactionManager移除
Mapper 扫描全包扫描DAO 包 + @Mapper 注解DAO 包扫描
组件扫描无无context:component-scan
XML Schema6 个命名空间6 个命名空间2 个命名空间

3.4 配置文件数量对比与迁移清单 ​

配置文件CAS 5.3CAS 6.6CAS 7.3
application.yml有有（增强）有（进一步增强）
spring-common.xml有（复杂）有（精简）有（极简）
apereo.properties有移除-
cas-theme-default.properties有移除-
cas_common_messages.properties有移除-
deployerConfigContext.groovy有有移除
log4j2.xml有（复杂）有移除
generatorConfig.xml有有移除
bootstrap.properties有有有

从 9 个配置文件减少到 3 个（不含 messages 国际化文件），CAS 7.3 的配置精简幅度达到了 67%。这不仅降低了维护成本，更重要的是减少了配置分散导致的"配置漂移"风险。

第四章：认证架构的深度重构 ​

认证是 CAS 的核心功能，其架构在三个版本之间经历了显著的重构。

4.1 CAS 5.3/6.6 的认证处理器模式 ​

在 CAS 5.3 和 6.6 中，自定义认证的典型实现模式如下：

java
// CAS 5.3/6.6 自定义认证配置（教学示例）
@Configuration("customAuthenticationConfiguration")
@EnableConfigurationProperties(CasConfigurationProperties.class)
public class CustomAuthenticationConfiguration
        implements AuthenticationEventExecutionPlanConfigurer {

    @Autowired
    private CasConfigurationProperties casProperties;

    @Autowired
    private ServicesManager servicesManager;

    @Bean
    public LoginHandler customLoginHandler() {
        // 构造函数需要传入 ServicesManager
        return new LoginHandler(servicesManager);
    }

    @Override
    public void configureAuthenticationExecutionPlan(
            AuthenticationEventExecutionPlan plan) {
        plan.registerAuthenticationHandler(customLoginHandler());
    }
}

对应的认证处理器实现：

java
// CAS 5.3/6.6 认证处理器（教学示例）
public class LoginHandler extends AbstractPreAndPostProcessingAuthenticationHandler {

    public LoginHandler(ServicesManager servicesManager) {
        super(servicesManager);
    }

    @Override
    public boolean supports(Credential credential) {
        return credential instanceof UsernamePasswordCredential;
    }

    @Override
    protected HandlerResult doAuthentication(Credential credential)
            throws GeneralSecurityException, PreventedException {
        // 自定义认证逻辑
        UsernamePasswordCredential upc = (UsernamePasswordCredential) credential;
        // ... 验证用户名密码
        return createHandlerResult(upc, principal, new ArrayList<>());
    }
}

这种模式的关键特征：

  1. ServicesManager 依赖：认证处理器的构造函数必须接收 ServicesManager 参数，这是因为 CAS 5.3/6.6 的认证处理器需要通过 ServicesManager 获取已注册的服务信息，用于服务级别的认证策略决策。在 CAS 的架构设计中，ServicesManager 是服务注册中心的门面，它管理着所有已注册的 Service 定义（包括 CAS Protocol、SAML、OAuth 2.0 等各种协议的 Service）。认证处理器通过 ServicesManager 可以实现"针对不同 Service 使用不同认证策略"的高级功能。

  2. AuthenticationEventExecutionPlanConfigurer 接口：自定义认证配置类必须实现此接口，并在 configureAuthenticationExecutionPlan 方法中注册认证处理器。这个接口是 CAS 认证架构的核心扩展点——CAS 框架在启动时会收集所有实现了此接口的 @Configuration 类，依次调用其 configureAuthenticationExecutionPlan 方法，将所有认证处理器注册到一个统一的执行计划中。这种设计模式类似于 Spring 的 ImportBeanDefinitionRegistrar，但专门针对认证场景进行了优化。

  3. AbstractPreAndPostProcessingAuthenticationHandler：这是 CAS 提供的认证处理器基类，提供了前置处理（pre-process）和后置处理（post-process）的扩展点。前置处理可以在实际认证之前执行额外的检查（如账号锁定检查、密码过期检查等），后置处理可以在认证成功后执行额外的操作（如记录审计日志、更新最后登录时间等）。在实际项目中，我们经常在后置处理中注入自定义的属性到 Principal 中，以便下游 Service 获取更多的用户信息。

然而，CAS 5.3/6.6 的认证架构也存在一些不足。首先是 ServicesManager 的过度耦合——并非所有认证处理器都需要访问 Service 注册信息，但构造函数强制要求传入。其次是缺乏热刷新能力——修改认证配置后必须重启 CAS 服务才能生效。这些不足在 CAS 7.3 中得到了改进。

4.2 CAS 7.3 的认证架构革新 ​

CAS 7.3 对认证架构进行了深度重构，引入了 CasInitializerConfig 模式：

java
// CAS 7.3 认证初始化配置（教学示例）
@Configuration(value = "casInitializerConfig")
@EnableConfigurationProperties(CasConfigurationProperties.class)
public class CasInitializerConfig {

    @RefreshScope
    @Bean
    public LoginHandler customLoginHandler(
            CasConfigurationProperties casProperties) {
        // 构造函数简化，不再需要 ServicesManager
        return new LoginHandler(casProperties);
    }
}

对应的认证处理器实现也进行了简化：

java
// CAS 7.3 认证处理器（教学示例）
public class LoginHandler extends AbstractPreAndPostProcessingAuthenticationHandler {

    public LoginHandler(CasConfigurationProperties casProperties) {
        super(casProperties);
    }

    @Override
    public boolean supports(Credential credential) {
        return credential instanceof UsernamePasswordCredential;
    }

    @Override
    protected HandlerResult doAuthentication(Credential credential)
            throws GeneralSecurityException, PreventedException {
        // 认证逻辑保持不变
        UsernamePasswordCredential upc = (UsernamePasswordCredential) credential;
        // ... 验证逻辑
        return createHandlerResult(upc, principal, new ArrayList<>());
    }
}

4.3 默认认证处理器的清除策略 ​

CAS 7.3 引入了一个重要的配置变更——默认认证处理器的显式清除。在 application.yml 中：

yaml
# CAS 7.3 显式禁用默认的 accept 用户认证
cas:
  authn:
    accept:
      enabled: false
      users:

在 CAS 5.3/6.6 中，如果不显式配置，CAS 会启用一个默认的 acceptUsersAuthenticationHandler，它接受任何在 cas.authn.accept.users 中配置的用户名/密码对。这虽然方便开发测试，但在生产环境中是一个安全隐患。

CAS 7.3 的做法更加明确：通过 enabled: false 显式禁用默认处理器，然后通过自定义的 CasInitializerConfig 注册项目自己的认证处理器。同时，CAS 7.3 还覆盖了 acceptUsersAuthenticationEventExecutionPlanConfigurer，确保默认处理器不会被自动注册。

4.4 @RefreshScope 热刷新机制的引入 ​

CAS 7.3 在认证配置中引入了 @RefreshScope 注解，这是 CAS 5.3/6.6 中没有的特性。@RefreshScope 是 Spring Cloud Context 提供的注解，它使得被注解的 Bean 在收到 /refresh 事件时会被重新创建。

对于认证处理器而言，这意味着：

  1. 动态配置更新：修改认证相关的配置（如数据源连接信息、密码策略参数等）后，无需重启 CAS 服务，只需触发 /refresh 端点即可生效
  2. 配置验证：可以在不中断现有会话的情况下，验证新的认证配置是否正确
  3. 灰度发布：可以在多节点部署环境中，逐个节点刷新配置，实现认证策略的灰度切换

需要注意的是，@RefreshScope 与 CAS 的 Ticket Registry 存在交互。当认证处理器被刷新时，已有的 TGT（Ticket Granting Ticket）不会失效，但新的认证请求将使用刷新后的处理器。这种设计是合理的——它保证了已登录用户不受配置变更的影响。

在实际使用中，@RefreshScope 需要配合 Spring Cloud Bus 或 Actuator 的 /refresh 端点使用。在 CAS 7.3 的 application.yml 中，Spring Cloud Bus 默认是禁用的（spring.cloud.bus.enabled: false），如果需要使用配置热刷新功能，需要启用 Spring Cloud Bus 并配置消息中间件（如 RabbitMQ 或 Kafka）。对于不使用 Spring Cloud Bus 的项目，可以通过 Actuator 的 /actuator/refresh 端点手动触发刷新。

4.5 认证架构迁移的代码变更清单 ​

从 CAS 5.3/6.6 迁移到 7.3 时，认证相关的代码变更可以归纳为以下清单：

  1. 配置类重构：将 AuthenticationEventExecutionPlanConfigurer 实现类替换为 CasInitializerConfig 风格的配置类
  2. 构造函数简化：将 AbstractPreAndPostProcessingAuthenticationHandler 子类的构造函数参数从 ServicesManager 改为 CasConfigurationProperties
  3. 添加 @RefreshScope：在认证处理器的 @Bean 方法上添加 @RefreshScope 注解
  4. 禁用默认认证：在 application.yml 中添加 cas.authn.accept.enabled: false
  5. 覆盖默认 Bean：确保自定义认证处理器覆盖了 acceptUsersAuthenticationEventExecutionPlanConfigurer

这些变更的总体工作量取决于项目中自定义认证处理器的数量和复杂度。对于只有一个自定义认证处理器的简单项目，迁移工作量大约在 1 到 2 个小时；对于有多个认证处理器、多个属性解析器的复杂项目，迁移工作量可能在 1 到 2 个人天。

第五章：SSL/TLS 安全策略演进 ​

SSL/TLS 配置是 CAS 部署中最基础也最关键的安全配置，三个版本之间的演进体现了安全最佳实践的持续升级。

5.1 CAS 5.3 的 TLS 配置与局限 ​

CAS 5.3 的 SSL 配置相对基础：

yaml
# CAS 5.3 SSL 配置（教学示例）
server:
  ssl:
    enabled: true
    key-store: classpath:etc/ssl/keystore.p12
    key-store-password: changeit
    key-password: changeit
    keyStoreType: PKCS12
    protocol: TLS
    port: 8443

CAS 5.3 的 TLS 配置存在几个安全隐患：

  1. 协议过于宽泛：protocol: TLS 允许 TLS 1.0、TLS 1.1、TLS 1.2 等所有 TLS 版本，而 TLS 1.0 和 1.1 已被证明存在安全漏洞（POODLE、BEAST 等攻击）
  2. TGC secure:false：Ticket Granting Cookie 的 secure 标志被设为 false，意味着 TGC 可以通过非加密的 HTTP 连接传输，存在被中间人攻击截获的风险
  3. 密钥库使用 PKCS12 格式：虽然 PKCS12 本身没有问题，但在某些旧版 JDK 上存在兼容性问题

5.2 CAS 6.6 的协议升级与 remoteip 配置 ​

CAS 6.6 在安全配置方面做出了重要改进：

yaml
# CAS 6.6 SSL 配置（教学示例）
server:
  ssl:
    enabled: true
    key-store: src/main/resources/etc/ssl/thekeystore.p12
    key-store-password: changeit
    key-password: changeit
    key-store-type: PKCS12
    protocol: TLS
    enabled-protocols: TLSv1.2,TLSv1.3
  tomcat:
    remoteip:
      enabled: true
      protocol-header: X-Forwarded-Proto
      port-header: X-Forwarded-Port
      remote-ip-header: X-FORWARDED-FOR
      internal-proxies: 10\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}|192\\.168\\.\\d{1,3}\\.\\d{1,3}|...

CAS 6.6 的关键安全改进：

  1. 显式指定 TLS 版本：通过 enabled-protocols: TLSv1.2,TLSv1.3 禁用了不安全的 TLS 1.0 和 1.1
  2. 新增 remoteip 配置：这是一个在 CAS 5.3 中经常被遗漏但在生产环境中至关重要的配置。当 CAS 部署在反向代理（如 Nginx、HAProxy）之后时，remoteip 配置使得 Tomcat 能够正确识别客户端的真实 IP 地址和协议

remoteip 配置的各个参数含义：

  • enabled: true：启用 RemoteIpValve
  • protocol-header: X-Forwarded-Proto：从哪个 HTTP 头获取原始协议
  • port-header: X-Forwarded-Port：从哪个 HTTP 头获取原始端口
  • remote-ip-header: X-FORWARDED-FOR：从哪个 HTTP 头获取客户端真实 IP
  • internal-proxies：正则表达式匹配可信代理的 IP 范围，防止伪造头攻击

internal-proxies 的正则表达式值得深入分析。CAS 6.6 中使用的正则表达式覆盖了三大私有 IP 地址段：

  • 10.0.0.0/8（A 类私有地址）
  • 192.168.0.0/16（C 类私有地址）
  • 172.16.0.0/12（B 类私有地址）

在实际部署中，如果 CAS 前面有多层反向代理（如 CDN -> Nginx -> CAS），需要确保每一层的代理 IP 都包含在 internal-proxies 中。否则，RemoteIpValve 会将中间代理的 IP 当作客户端真实 IP，导致 IP 限流、地理定位等功能异常。

CAS 7.3 对 internal-proxies 的正则表达式进行了微调，使用了 (?i:[0-9]{1,3}) 替代了 \d{1,3}，增加了对大小写不敏感的匹配。这一变更虽然微小，但体现了 CAS 团队对正则表达式健壮性的持续优化。

5.3 CAS 7.3 的密钥库切换与加密增强 ​

CAS 7.3 在 SSL 配置方面做出了一个出人意料的变更——将密钥库格式从 PKCS12 切换为 JKS：

yaml
# CAS 7.3 SSL 配置（教学示例）
server:
  ssl:
    enabled: true
    key-store: src/main/resources/keystore.jks
    key-store-password: changeit
    key-password: changeit
    key-store-type: JKS
    protocol: TLS
    enabled-protocols: TLSv1.2,TLSv1.3

这一变更的背景是：虽然 PKCS12 是 Java 9+ 推荐的密钥库格式（甚至在 Java 9 中一度将 JKS 标记为 deprecated），但 PKCS12 在某些场景下存在兼容性问题。JKS 作为 Java 原生的密钥库格式，在 JDK 21 上仍然得到完全支持，且与 keytool 工具链的集成更加紧密。

从 CAS 5.3/6.6 的 PKCS12 迁移到 CAS 7.3 的 JKS，需要执行密钥库格式转换：

bash
# 从 PKCS12 转换为 JKS（教学示例）
keytool -importkeystore \
    -srckeystore keystore.p12 -srcstoretype PKCS12 \
    -destkeystore keystore.jks -deststoretype JKS \
    -srcstorepass changeit -deststorepass changeit

需要注意的是，JKS 格式在安全性上略逊于 PKCS12——JKS 使用专有的加密算法，而 PKCS12 使用标准的加密算法。如果安全合规要求使用 PKCS12 格式，可以在 CAS 7.3 中通过修改 key-store-type: PKCS12 来切换回 PKCS12。CAS 7.3 并不强制的使用 JKS，只是默认模板使用了 JKS。

更重要的是，CAS 7.3 引入了 TGC 加密控制：

yaml
# CAS 7.3 TGC 加密配置
cas:
  tgc:
    crypto:
      enabled: false
  webflow:
    crypto:
      enabled: false

在 CAS 5.3/6.6 中，TGC 的加密行为是隐式的——框架内部自行决定是否对 TGC 进行加密。CAS 7.3 将这一行为显式化，通过 cas.tgc.crypto.enabled 和 cas.webflow.crypto.enabled 两个配置项，让运维团队可以根据安全策略自行决定是否启用加密。

5.4 TGC Cookie 安全策略的演进 ​

TGC（Ticket Granting Cookie）是 CAS SSO 机制的核心——用户首次认证成功后，浏览器会收到一个 TGC，后续访问其他 CAS 保护的应用时，浏览器自动携带 TGC 实现无感登录。

三个版本中 TGC 的安全策略演进：

安全维度CAS 5.3CAS 6.6CAS 7.3
secure 标志falsefalse可控（通过 crypto.enabled）
httpOnlytruetruetrue
SameSite未配置未配置未配置
加密隐式隐式显式可控

TGC secure: false 的设置在开发环境中是合理的（方便使用 HTTP 进行调试），但在生产环境中应当设为 true。CAS 7.3 的显式加密控制为生产环境的安全加固提供了更精细的手段。

第六章：OAuth 2.0 集成的架构升级 ​

OAuth 2.0 是 CAS 的重要扩展能力，三个版本在 OAuth 2.0 的实现方式上经历了显著变化。

6.1 CAS 5.3 的自定义 Filter 拦截方案 ​

在 CAS 5.3 中，OAuth 2.0 的集成往往需要自定义 Filter 来拦截特定的端点。这是因为 CAS 5.3 的 OAuth 模块提供的默认行为不一定满足业务需求，开发者需要通过自定义 Filter 来扩展或覆盖默认行为。

典型的实现模式包括：

  1. 自定义 Filter 拦截 /oauth2.0/authorize 端点：在授权码流程中，需要在用户授权前执行额外的业务逻辑（如权限检查、 consent 页面定制等）
  2. 自定义 RequestWrapper：包装 HTTP 请求，修改或补充请求参数
  3. 自定义 /oauth2.0/accessToken 端点处理：在发放访问令牌时执行额外的验证逻辑

这种模式虽然灵活，但存在明显的问题：

  • Filter 的执行顺序难以精确控制
  • 与 CAS 内部的 Filter 链可能产生冲突
  • 调试困难，问题定位链路长
  • 升级 CAS 版本时，Filter 的兼容性容易出问题

此外，CAS 5.3 的 OAuth 2.0 实现在配置层面也存在不足。例如，OAuth 2.0 的访问令牌和刷新令牌没有加密保护，令牌以明文形式存储在票据注册中心中。在 Redis 票据注册中心的情况下，这意味着任何能访问 Redis 的组件都能读取 OAuth 令牌的内容。虽然 Redis 本身提供了网络层面的访问控制，但在共享 Redis 基础设施的环境中，这种"信任边界"的假设可能不成立。

CAS 5.3 的 OAuth 2.0 还缺少对 UMA（User-Managed Access）协议的支持。UMA 是 OAuth 2.0 的重要扩展，允许资源所有者对受保护资源的访问进行精细化的授权管理。在需要实现跨组织资源共享的场景中，UMA 是不可或缺的协议支持。

6.2 CAS 7.3 的条件装配与 UMA 支持 ​

CAS 7.3 引入了 Spring Boot 的条件装配机制来管理 OAuth 2.0 的扩展点：

java
// CAS 7.3 OAuth 扩展（教学示例）
@Configuration
public class CustomOAuthConfiguration {

    @ConditionalOnMissingBean(name = "customOAuthFilter")
    @Bean
    public FilterRegistrationBean<CustomOAuthFilter> customOAuthFilter() {
        FilterRegistrationBean<CustomOAuthFilter> registration =
            new FilterRegistrationBean<>();
        registration.setFilter(new CustomOAuthFilter());
        registration.addUrlPatterns("/oauth2.0/*");
        registration.setOrder(Ordered.HIGHEST_PRECEDENCE + 1);
        return registration;
    }
}

@ConditionalOnMissingBean 注解是关键——它表示"只有当容器中不存在指定名称的 Bean 时，才创建这个 Bean"。这种模式的优势在于：

  1. 可覆盖性：项目可以通过定义同名的 Bean 来覆盖默认实现，无需修改框架代码
  2. 零侵入性：当项目不需要自定义扩展时，框架的默认行为不受任何影响
  3. 可测试性：在测试环境中，可以通过 Mock Bean 来替换真实的 Filter

CAS 7.3 还新增了对 UMA（User-Managed Access）的支持。UMA 是 OAuth 2.0 的一个扩展协议，允许资源所有者精细控制对其资源的访问权限。在依赖层面，CAS 7.3 新增了 cas-server-support-oauth-uma 模块：

groovy
// CAS 7.3 新增 UMA 支持
implementation "org.apereo.cas:cas-server-support-oauth-uma"

6.3 OAuth 2.0 加密配置的新增 ​

CAS 7.3 为 OAuth 2.0 引入了完整的加密配置体系，这是 CAS 5.3/6.6 中完全不具备的能力：

yaml
# CAS 7.3 OAuth 2.0 加密配置（教学示例）
cas:
  authn:
    oauth:
      access-token:
        crypto:
          encryption:
            key: "YOUR_256_BIT_AES_ENCRYPTION_KEY_BASE64_ENCODED"
          signing:
            key: "YOUR_256_BIT_HMAC_SIGNING_KEY_BASE64_ENCODED"
      session-replication:
        cookie:
          crypto:
            signing:
              key: "YOUR_SESSION_SIGNING_KEY"
            encryption:
              key: "YOUR_SESSION_ENCRYPTION_KEY"

这些加密配置的作用：

  • access-token.crypto.encryption.key：用于加密 OAuth 2.0 访问令牌的 AES 密钥（256 位，Base64 编码）
  • access-token.crypto.signing.key：用于签名 OAuth 2.0 访问令牌的 HMAC 密钥（256 位，Base64 编码）
  • session-replication.cookie.crypto：用于加密和签名会话复制 Cookie 的密钥

这些密钥的引入解决了 CAS 5.3/6.6 中 OAuth 2.0 令牌明文存储的安全隐患。在生产环境中，这些密钥应当通过安全的密钥管理服务（如 HashiCorp Vault、AWS KMS）来管理，而非直接写在配置文件中。

6.4 YAML 属性命名规范的变更 ​

CAS 7.3 对 OAuth 2.0 配置属性的命名规范进行了调整，从驼峰命名法（camelCase）转变为连字符命名法（kebab-case）：

yaml
# CAS 5.3/6.6 的驼峰命名
cas:
  authn:
    oauth:
      refreshToken:
        timeToKillInSeconds: 1209600
      code:
        timeToKillInSeconds: 300
        numberOfUses: 1
      accessToken:
        timeToKillInSeconds: 86400
        maxTimeToLiveInSeconds: 43200

# CAS 7.3 的连字符命名
cas:
  authn:
    oauth:
      refresh-token:
        time-to-kill-in-seconds: 1209600
      code:
        time-to-kill-in-seconds: 300
        number-of-uses: 1
      access-token:
        time-to-kill-in-seconds: 86400
        max-time-to-live-in-seconds: 43200

这一变更遵循了 Spring Boot 的配置属性命名最佳实践。Spring Boot 的 relaxed binding 机制虽然在大多数情况下可以同时接受驼峰和连字符形式，但官方推荐使用连字符形式。CAS 7.3 的这一调整使得配置风格与 Spring Boot 生态保持一致。

迁移注意：虽然 Spring Boot 的 relaxed binding 通常能处理这种命名转换，但在某些边缘场景下（如 @Value 注解直接引用属性名、自定义的 ConfigurationProperties 类等），可能需要手动调整属性名。建议在迁移后进行全面的配置验证。

在实际项目中，除了属性命名变更，CAS 7.3 的 OAuth 2.0 还引入了一些新的配置项。例如 cas.authn.oauth.session-replication.cookie.crypto 配置节，用于控制会话复制 Cookie 的加密和签名行为。这些新配置项在 CAS 5.3/6.6 中不存在，如果直接使用旧版本的 application.yml 启动 CAS 7.3，这些配置项会使用默认值。建议在迁移时显式配置这些安全相关的属性，避免使用默认值带来的安全风险。

6.5 OAuth 2.0 迁移的端到端验证清单 ​

OAuth 2.0 的迁移验证比基本登录流程更为复杂，因为涉及多个端点和多种令牌类型的交互。以下是建议的端到端验证清单：

  1. 授权码流程：访问 /oauth2.0/authorize 获取授权码 -> 使用授权码访问 /oauth2.0/accessToken 获取访问令牌 -> 使用访问令牌访问 /oauth2.0/profile 获取用户信息
  2. 刷新令牌流程：使用刷新令牌访问 /oauth2.0/accessToken（grant_type=refresh_token）获取新的访问令牌
  3. 资源所有者密码凭证流程：直接使用用户名密码访问 /oauth2.0/accessToken（grant_type=password）获取访问令牌
  4. 令牌加密验证：检查 Redis 中存储的令牌是否已加密（对比迁移前后的存储格式）
  5. 令牌有效期验证：验证授权码、访问令牌、刷新令牌的有效期是否符合配置预期

第七章：Docker 容器化的演进之路 ​

容器化部署是现代应用交付的标准方式，CAS Overlay 项目的 Docker 构建策略在三个版本之间经历了从手动到自动化的演进。

7.1 CAS 5.3/6.6 的手动多阶段构建 ​

CAS 5.3 和 6.6 使用几乎相同的手动多阶段 Dockerfile：

dockerfile
# CAS 5.3/6.6 Dockerfile 教学示例
# 阶段1：构建
FROM gradle:7.5-jdk8 AS builder
WORKDIR /app

RUN mkdir -p ~/.gradle \
    && echo "org.gradle.daemon=false" >> ~/.gradle/gradle.properties \
    && echo "org.gradle.configureondemand=true" >> ~/.gradle/gradle.properties

COPY . .

RUN chmod 750 ./gradlew \
    && ./gradlew clean bootJar -x test --parallel --no-daemon

# 兜底：确保 JAR 文件正确复制
RUN mkdir -p /app/cas \
    && first_jar=$(ls /app/build/libs/*.jar | head -n 1) \
    && cp "$first_jar" /app/cas/cas.jar

# 阶段2：运行
FROM azul/zulu-openjdk:8 AS runner
WORKDIR /docker/cas/jar

RUN mkdir -p /etc/cas/config /etc/cas/services /etc/cas/saml \
    && chmod -R 777 /etc/cas

COPY src/main/resources/etc/ssl/keystore.jks /etc/cas/thekeystore
COPY src/main/resources/services /etc/cas/services
COPY --from=builder /app/cas/cas.jar /docker/cas/jar/
COPY src/main/jib/docker/entrypoint.sh /docker/entrypoint.sh

RUN chmod +x /docker/entrypoint.sh
ENV PATH $PATH:$JAVA_HOME/bin:/docker/cas/jar

EXPOSE 80 443 8080 8443 8444 8761 8888 5000
ENTRYPOINT ["/docker/entrypoint.sh"]

这种手动 Dockerfile 的工作方式存在几个问题：

  1. 构建耦合：Docker 构建过程与 Gradle 构建过程耦合在一起，无法利用 Gradle 的增量构建和缓存机制
  2. 镜像体积：虽然使用了多阶段构建，但运行时镜像中仍然包含了一些不必要的文件
  3. 构建效率：每次 Docker 构建都需要重新下载依赖，即使代码没有变化
  4. 平台限制：手动 Dockerfile 难以支持多平台（amd64/arm64）构建

CAS 6.6 的 Dockerfile 与 5.3 几乎完全相同，唯一的差异是基础镜像从 gradle:7.5-jdk8 变为 gradle:7.5-jdk11，运行时镜像从 azul/zulu-openjdk:8 变为 azul/zulu-openjdk:11。CAS 6.6 的 Dockerfile 还新增了时区设置（ENV TZ=Asia/Shanghai），这是一个看似微小但在生产环境中非常重要的改进——日志时间戳、票据过期时间、审计记录时间等都依赖于正确的时区设置。如果时区不正确，可能导致票据提前过期或审计记录的时间线混乱。

手动 Dockerfile 的另一个隐患是构建上下文过大。COPY . . 会将整个项目目录（包括 .gradle 缓存、build 输出、.git 历史等）复制到构建容器中，导致构建上下文可能达到数百 MB 甚至 GB 级别。虽然 Docker 的构建缓存机制可以缓解这一问题，但在 CI/CD 环境中，每次构建都需要传输完整的构建上下文，严重拖慢构建速度。建议在项目根目录添加 .dockerignore 文件，排除不必要的文件和目录。

7.2 CAS 7.3 的 Jib 插件集成 ​

CAS 7.3 引入了 Google 的 Jib 插件，彻底改变了 Docker 镜像的构建方式：

groovy
// CAS 7.3 Jib 配置（教学示例）
jib {
    from {
        image = project.baseDockerImage
        platforms {
            imagePlatforms.each {
                def given = it.split(":")
                platform {
                    architecture = given[0]
                    os = given[1]
                }
            }
        }
    }
    to {
        image = "${project.'containerImageOrg'}/${project.'containerImageName'}:${project.version}"
        credHelper = "osxkeychain"
        tags = [project.version]
    }
    container {
        creationTime = "USE_CURRENT_TIMESTAMP"
        entrypoint = ['/docker/entrypoint.sh']
        ports = ['80', '443', '8080', '8443', '8444', '8761', '8888', '5000']
        labels = [version:project.version, name:project.name]
        workingDirectory = '/docker/cas/war'
    }
    extraDirectories {
        paths {
            path { from = file('src/main/jib') }
            path { from = file('etc/cas'); into = '/etc/cas' }
            path { from = file("build/libs"); into = "/docker/cas/war" }
        }
        permissions = [
            '/docker/entrypoint.sh': '755'
        ]
    }
}

Jib 相比手动 Dockerfile 的优势：

  1. 无需 Docker 守护进程：Jib 直接构建 OCI 镜像并推送到镜像仓库，不需要本地安装 Docker
  2. 层缓存优化：Jib 自动将依赖、资源、类文件分层，只有变化的层才会被重建
  3. 可重复构建：相同输入始终产生相同镜像，不受构建环境差异影响
  4. 安全性：不需要 Docker 特权，减少了构建管道的安全攻击面

CAS 7.3 同时保留了手动 Dockerfile 和 Jib 两种构建方式，开发者可以根据场景选择：

  • 本地开发调试：使用手动 Dockerfile（更直观）
  • CI/CD 管道：使用 Jib（更高效、更安全）
  • 多平台发布：使用 Jib（原生支持）

7.3 CycloneDX SBOM 与供应链安全 ​

CAS 7.3 引入了 CycloneDX 插件，用于生成 SBOM（Software Bill of Materials）：

groovy
// CAS 7.3 CycloneDX 配置
apply plugin: "org.cyclonedx.bom"

// bootJar 依赖 cyclonedxBom
bootJar {
    dependsOn cyclonedxBom
}

SBOM 是软件供应链安全的基础设施。它记录了软件中包含的所有组件及其版本、许可证、依赖关系等信息。在以下场景中，SBOM 至关重要：

  1. 安全漏洞扫描：当某个依赖被报告存在 CVE 漏洞时，可以通过 SBOM 快速确定哪些项目受影响
  2. 许可证合规：通过 SBOM 自动检查项目中是否引入了不兼容的开源许可证
  3. 供应链审计：满足行业监管对软件成分透明度的要求

CycloneDX 是 OWASP 推荐的 SBOM 标准，被广泛支持。CAS 7.3 在构建时自动生成 CycloneDX 格式的 SBOM 文件，并将其打包到最终的 JAR 中。

7.4 多平台镜像构建 ​

CAS 7.3 的 Jib 配置支持多平台镜像构建：

properties
# gradle.properties
dockerImagePlatform=amd64:linux,arm64:linux
groovy
// build.gradle 中的多平台配置
def imagePlatforms = project.dockerImagePlatform.split(",")
jib {
    from {
        platforms {
            imagePlatforms.each {
                def given = it.split(":")
                platform {
                    architecture = given[0]
                    os = given[1]
                }
            }
        }
    }
}

这一配置使得单次构建即可生成支持多种 CPU 架构的 Docker 镜像，满足了 ARM 服务器（如 AWS Graviton、Apple Silicon）日益增长的需求。在 CAS 5.3/6.6 中，要实现多平台构建需要使用 docker buildx 配合 QEMU 模拟，构建效率和可靠性都远不如 Jib。

第八章：Gradle 构建体系的增强 ​

Gradle 构建脚本是 CAS Overlay 项目的"骨架"，三个版本在构建体系上的演进体现了工程化成熟度的持续提升。

8.1 springboot.gradle 的职责拆分 ​

从 CAS 6.6 开始，构建脚本被拆分为多个独立的 Gradle 文件，其中 springboot.gradle 专门负责 Spring Boot 相关的构建配置：

groovy
// springboot.gradle 核心职责（教学示例）
// 1. 定义 bootRun 的 classpath 和 JVM 参数
bootRun {
    classpath = configurations.bootRunConfig
        + sourceSets.main.compileClasspath
        + sourceSets.main.runtimeClasspath
    jvmArgs = [
        "-XX:TieredStopAtLevel=1",
        "-Xverify:none",
        "--add-modules", "java.se",
        "--add-opens", "java.base/java.lang=ALL-UNNAMED",
        // ... 更多 JVM 参数
    ]
}

// 2. 配置 bootJar 的输出格式
bootJar {
    archiveFileName = "cas.jar"
    entryCompression = ZipEntryCompression.STORED
    launchScript()  // 生成可执行启动脚本
}

CAS 7.3 的 springboot.gradle 在 6.6 的基础上增加了 CycloneDX 集成：

groovy
// CAS 7.3 springboot.gradle 新增内容
def wireOverlayDependency = { Task t ->
    ["processTestResources", "compileJava", "compileGraalJava"]
        .collect { tasks.findByName(it) }
        .findAll { it != null }
        .each { t.dependsOn(it) }
}
tasks.named("cyclonedxBom").configure { wireOverlayDependency(delegate) }
tasks.named("cyclonedxDirectBom").configure { wireOverlayDependency(delegate) }

bootJar {
    dependsOn cyclonedxBom  // 确保 SBOM 在 JAR 打包前生成
}

8.2 tasks.gradle 的实用工具集 ​

tasks.gradle 提供了一系列实用任务，是 CAS Overlay 项目的"瑞士军刀"。以下是几个关键任务的解析：

createKeystore 任务：自动化生成 TLS 密钥库

groovy
// tasks.gradle 中的 createKeystore 任务（教学示例）
task createKeystore(group: "CAS", description: "Create CAS keystore") {
    doFirst {
        exec {
            commandLine "keytool", "-genkeypair", "-alias", "cas",
                "-keyalg", "RSA",
                "-keypass", "changeit", "-storepass", "changeit",
                "-keystore", keystorePath,
                "-dname", dn, "-ext", "SAN=${subjectAltName}",
                "-storetype", storeType
        }
        exec {
            commandLine "keytool", "-exportcert", "-alias", "cas",
                "-storepass", "changeit", "-keystore", keystorePath,
                "-file", serverCert
        }
    }
}

exportConfigMetadata 任务：导出 CAS 配置元数据

这个任务利用 CAS 的 CasConfigurationMetadataCatalog API，导出所有可用的配置属性及其描述、类型、默认值等信息。对于理解 CAS 的配置体系极其有用：

groovy
// tasks.gradle 中的 exportConfigMetadata 任务（教学示例）
task exportConfigMetadata(group: "CAS", description: "Export collection of CAS properties") {
    doLast {
        file.withWriter('utf-8') { writer ->
            def props = CasConfigurationMetadataCatalog.query(
                ConfigurationMetadataCatalogQuery.builder()
                    .queryType(queryType)
                    .build())
                .properties()
            props.each { property ->
                writer.writeLine("# ${property.name}: ${property.defaultValue}")
                writer.writeLine("# Type: ${property.type}")
                writer.writeLine("# Module: ${property.module}")
            }
        }
    }
}

listTemplateViews 任务：列出所有可用的 Thymeleaf 模板视图

这个任务通过解压 CAS 的 cas-server-support-thymeleaf 和 cas-server-webapp-resources JAR 包，提取所有 HTML 模板文件路径。对于需要自定义 CAS 登录页面的开发者来说，这是不可或缺的工具。

CAS 7.3 新增的 duct 任务：票据注册中心功能测试

groovy
// CAS 7.3 tasks.gradle 新增的 duct 任务（教学示例）
task duct(group: "CAS", description: "Test ticket registry functionality") {
    doLast {
        // 1. 从 CAS Server 1 获取 TGT
        def connection = new URL("${casServerPrefix1}/v1/tickets").openConnection()
        connection.setRequestMethod("POST")
        connection.setDoOutput(true)
        connection.getOutputStream().write("username=${username}&password=${password}".getBytes("UTF-8"))

        // 2. 从 CAS Server 2 获取 ST（验证分布式票据共享）
        connection = new URL("${casServerPrefix2}/v1/tickets/${tgt}").openConnection()
        connection.setRequestMethod("POST")
        connection.getOutputStream().write("service=${service}".getBytes("UTF-8"))

        // 3. 在 CAS Server 1 验证 ST（验证跨节点票据验证）
        connection = new URL("${casServerPrefix1}/p3/serviceValidate?service=${service}&ticket=${st}&format=json").openConnection()
    }
}

这个任务专门用于测试分布式部署场景下的票据注册中心功能。它通过在两个不同的 CAS 节点之间执行 TGT 获取、ST 获取和 ST 验证的完整流程，验证 Redis 票据注册中心的跨节点共享能力。

duct 任务的名称来源于 HVAC（暖通空调）系统中的"管道"概念，寓意为 CAS 的票据流转管道进行压力测试。这个任务支持多种配置参数：

  • duct.service：用于测试的 Service URL（默认为 https://apereo.github.io）
  • duct.cas.*：CAS 服务节点的地址列表（支持多节点）
  • duct.username / duct.password：测试用的用户名和密码
  • duct.duration：测试持续时间（秒）
  • duct.count：测试执行次数

在实际项目中，duct 任务是验证 Redis 票据注册中心配置正确性的最有效工具。特别是在从 CAS 5.3/6.6 迁移到 7.3 后，Redis 配置结构发生了变化（详见第九章），使用 duct 任务可以在不启动完整应用的情况下快速验证票据注册中心的功能。

createTheme 任务：自动化创建 CAS 主题目录结构

这个任务根据指定的主题名称，自动创建完整的主题目录结构，包括 CSS、JavaScript、图片和 Thymeleaf 模板目录。对于需要深度定制 CAS 登录页面的项目来说，这个任务可以省去大量手动创建目录的工作。

8.3 CAS 7.3 新增的构建插件生态 ​

CAS 7.3 在构建插件层面引入了三个重要的新插件：

Foojay Plugin（gradleFoojayPluginVersion=1.0.0）

Foojay Plugin 是 Gradle 官方推荐的 JDK 分发管理插件。它的核心功能是：当本地找不到匹配的 JDK 版本时，自动从 Foojay 仓库下载对应的 JDK 发行版。

groovy
// CAS 7.3 中的 Foojay 配置（教学示例）
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(project.targetCompatibility)
        // Foojay Plugin 会在本地找不到 JDK 21 时自动下载
    }
}

在 CAS 7.3 的 build.gradle 中，我们可以看到 Foojay Plugin 的间接使用——通过 jvmVendor 属性指定 JVM 供应商（如 AMAZON、ADOPTIUM），Foojay Plugin 会自动下载对应供应商的 JDK 21 发行版。

Jib Plugin（jibVersion=3.5.3）

Jib 插件在 CAS 7.3 中从 3.4.0 升级到 3.5.3，新增了对 Configuration Cache 的兼容性处理。

CycloneDX Plugin（gradleCyclonePluginVersion=3.2.0）

CycloneDX 插件用于生成 SBOM，已在第七章详细讨论。

8.4 Java Toolchain 的跨版本兼容方案 ​

CAS 7.3 的 Java Toolchain 配置是三个版本中最完善的：

groovy
// CAS 7.3 Java Toolchain 配置（教学示例）
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(project.targetCompatibility)

        def chosenJvmVendor = null
        if (project.jvmVendor != null) {
            try {
                // 优先尝试 Gradle 8.x 枚举写法
                chosenJvmVendor = JvmVendorSpec."${project.jvmVendor?.toUpperCase()}"
            } catch (MissingPropertyException e) {
                // 回退到 Gradle 7.x of() 方法
                try {
                    chosenJvmVendor = JvmVendorSpec.of(project.jvmVendor?.toUpperCase())
                } catch (MissingMethodException ex) {
                    // 最终回退到系统 JDK
                }
            }
        }
        if (chosenJvmVendor != null) {
            vendor = chosenJvmVendor
        }
    }
}

这段代码展示了 CAS 7.3 构建脚本的一个精妙设计——Gradle 版本兼容性处理。由于 JvmVendorSpec 的 API 在 Gradle 7.x 和 8.x 之间发生了变化（从 of() 方法变为枚举常量），这段代码通过 try-catch 链实现了向后兼容。这意味着同一个 build.gradle 可以在 Gradle 7.x 和 8.x 上运行，而不会因为 API 变更而构建失败。

第九章：迁移踩坑实录与解决方案 ​

本章记录了在实际迁移过程中遇到的具体问题和解决方案，这些都是官方文档中难以找到的"实战经验"。

9.1 踩坑一：commons-dbcp 到 commons-dbcp2 的属性映射断裂 ​

问题描述：从 CAS 6.6 升级到 7.3 后，应用启动时数据源初始化失败，报错信息为 Invalid property 'maxActive' for class BasicDataSource。

根本原因：commons-dbcp 1.4 的 BasicDataSource（包名 org.apache.commons.dbcp）和 commons-dbcp2 的 BasicDataSource（包名 org.apache.commons.dbcp2）虽然类名相同，但属性名存在差异。maxActive 在 dbcp2 中被重命名为 maxTotal，maxWait 被重命名为 maxWaitMillis。

解决方案：在 spring-common.xml 中逐一修改属性名：

commons-dbcp 1.4 属性commons-dbcp2 属性
maxActivemaxTotal
maxIdlemaxIdle（不变）
maxWaitmaxWaitMillis
initialSizeinitialSize（不变）
minIdleminIdle（不变）
removeAbandonedremoveAbandonedOnBorrow
removeAbandonedTimeoutremoveAbandonedOnBorrow + removeAbandonedTimeout
testWhileIdletestWhileIdle（不变）
validationQueryvalidationQuery（不变）

经验教训：在升级连接池版本时，不能仅修改 Gradle 依赖声明，必须同步检查所有引用连接池属性的配置文件（XML、YAML、Properties）。

9.2 踩坑二：MyBatis Spring 模块版本不兼容 ​

问题描述：升级到 CAS 7.3 后，MyBatis Mapper 接口的代理创建失败，报错信息为 org.mybatis.spring.mapper.MapperFactoryBean 无法初始化。

根本原因：mybatis-spring 3.0.3 要求 Spring 6.x 环境，且内部使用了 jakarta.persistence 包名。如果项目中存在对 javax.persistence 的引用，会导致类型不匹配。

解决方案：

  1. 确认 mybatis-spring 版本与 Spring Boot 版本的对应关系：
    • mybatis-spring 1.3.x -> Spring 5.x
    • mybatis-spring 2.x -> Spring 5.x（过渡版本）
    • mybatis-spring 3.0.x -> Spring 6.x
  2. 检查项目中是否有直接引用 javax.persistence 的代码，替换为 jakarta.persistence
  3. 检查 mybatis-config.xml 中是否有引用旧版 MyBatis 特性的配置

经验教训：mybatis-spring 的版本升级必须与 Spring Boot 大版本升级同步进行，不能独立升级。

9.3 踩坑三：Spring Boot 3.x 的 Jakarta 命名空间迁移 ​

问题描述：CAS 7.3 启动时，自定义的 Filter 和 Servlet 初始化失败，报 ClassNotFoundException: javax.servlet.Filter。

根本原因：Spring Boot 3.x 全面迁移到 Jakarta EE 9+，javax.servlet.* 包名变为 jakarta.servlet.*。CAS 框架本身已完成迁移，但项目自定义代码中的 javax.* 引用未同步更新。

解决方案：全局搜索项目中所有 javax.servlet、javax.validation、javax.persistence、javax.annotation 引用，替换为对应的 jakarta.* 包名。可以使用 IDE 的全局替换功能，但需要注意：

  • javax.mail 在某些上下文中仍然是 javax.mail（Jakarta Mail 的 Maven 坐标是 com.sun.mail:jakarta.mail，但包名是 jakarta.mail）
  • javax.xml.bind 在 CAS 7.3 中需要替换为 jakarta.xml.bind
  • javax.security 不需要替换（不属于 Jakarta EE 范畴）

经验教训：在开始迁移前，先使用 grep -r "javax\." src/ 全面排查 javax 引用，建立迁移清单。

9.4 踩坑四：CAS 7.3 中 OAuth 配置属性的驼峰转连字符 ​

问题描述：迁移到 CAS 7.3 后，OAuth 2.0 的授权码有效期配置不生效，授权码仍然使用默认的 30 秒有效期。

根本原因：CAS 7.3 的配置属性命名从驼峰形式（timeToKillInSeconds）转变为连字符形式（time-to-kill-in-seconds）。虽然 Spring Boot 的 relaxed binding 理论上应该兼容两种形式，但在 CAS 7.3 的某些 ConfigurationProperties 绑定场景中，只有连字符形式才能正确生效。

解决方案：将所有 OAuth 相关的驼峰属性名替换为连字符形式：

yaml
# 修改前（CAS 5.3/6.6 风格）
cas.authn.oauth.refreshToken.timeToKillInSeconds: 1209600

# 修改后（CAS 7.3 风格）
cas.authn.oauth.refresh-token.time-to-kill-in-seconds: 1209600

经验教训：迁移后必须逐一验证每个配置项是否生效，不能假设 Spring Boot 的 relaxed binding 能处理所有情况。

9.5 踩坑五：Redis 票据注册中心配置结构变更 ​

问题描述：CAS 7.3 启动后，Redis 票据注册中心无法连接，报 Unable to connect to Redis。

根本原因：CAS 7.3 对 Redis 票据注册中心的配置结构进行了重组。CAS 5.3/6.6 中的 cas.ticket.registry.redis 配置在 CAS 7.3 中被重新组织，部分属性被移除或重命名。

解决方案：对比三个版本的 Redis 配置结构：

yaml
# CAS 5.3 Redis 配置
cas:
  ticket:
    registry:
      redis:
        host: 192.168.1.30
        port: 6379
        timeout: 2000
        database: 0
        pool:
          max-active: 20
          max-idle: 10
          min-idle: 5

# CAS 7.3 Redis 配置
cas:
  ticket:
    registry:
      redis:
        enabled: true
        host: 192.168.1.30
        port: 6379
        database: 0
        password:
        timeout: PT10S  # 注意：使用 Duration 格式
        useSsl: false
        pool:
          enabled: true
          max-active: 8
          max-wait: -1
          max-idle: 8
          min-idle: 0

关键差异：

  1. CAS 7.3 新增 enabled: true 显式开关
  2. timeout 从毫秒数值变为 ISO-8601 Duration 格式（PT10S 表示 10 秒）
  3. 连接池配置新增 enabled 开关
  4. 新增 useSsl 和 enableRedisSearch 配置项

经验教训：CAS 大版本升级时，配置结构的变更往往是最容易被忽视的。建议使用 exportConfigMetadata 任务导出新版本的完整配置元数据，与旧配置进行逐一对比。

9.6 踩坑六：Jib 与 Gradle Configuration Cache 的兼容性问题 ​

问题描述：在 CAS 7.3 中执行 ./gradlew jibDockerBuild 时报错 Jib is not compatible with configuration cache。

根本原因：Jib 插件（截至 3.5.3 版本）不支持 Gradle 的 Configuration Cache 功能。当 org.gradle.unsafe.configuration-cache 被设为 true 时，Jib 任务会被自动禁用。

解决方案：CAS 7.3 的 build.gradle 中已经包含了兼容性处理代码。如果需要使用 Jib 构建 Docker 镜像，在命令行添加 --no-configuration-cache 参数：

bash
./gradlew jibDockerBuild --no-configuration-cache

或者，在 gradle.properties 中将 org.gradle.unsafe.configuration-cache 设为 false。

经验教训：在使用 Gradle 新特性（如 Configuration Cache）时，需要提前验证所有插件（特别是第三方插件）的兼容性。

第十章：迁移决策矩阵与最佳实践 ​

10.1 是否值得迁移的评估框架 ​

在决定是否进行 CAS 版本迁移之前，建议从以下维度进行评估：

安全维度（高优先级）

  • 当前版本是否仍在接受安全补丁？CAS 5.3.x 已停止维护，不再接收安全更新
  • 当前版本是否存在已知的安全漏洞？
  • 合规要求是否强制要求使用特定版本？

技术维度（中优先级）

  • 当前 Java 版本是否即将停止免费支持？
  • 是否需要 Spring Boot 3.x 的新特性（如原生镜像支持、Observability 增强）？
  • 是否需要 OAuth 2.0 的加密能力？
  • 是否需要多平台 Docker 镜像？

成本维度（中优先级）

  • 自定义扩展代码的迁移工作量有多大？
  • 测试覆盖是否充分？
  • 团队对新版本是否熟悉？

建议：

  • 如果当前使用 CAS 5.3.x，强烈建议尽快迁移到 7.3.x（跳过 6.6.x），因为 5.3 已停止维护
  • 如果当前使用 CAS 6.6.x，可以在安全补丁覆盖期内继续使用，但建议规划向 7.3.x 的迁移
  • 如果是新项目，直接从 7.3.x 开始

10.2 推荐的迁移路径 ​

路径一：5.3 -> 7.3 直接迁移（推荐）

对于 CAS 5.3 用户，建议直接迁移到 7.3，而非先升级到 6.6。原因：

  • 5.3 到 6.6 的迁移工作量与 5.3 到 7.3 相差不大（核心工作都是 Java 版本升级和依赖调整）
  • 6.6 也即将停止维护，中间多一次迁移反而增加总成本
  • 7.3 的 enforcedPlatform() 和 Jib 等新特性可以显著降低长期维护成本

路径二：6.6 -> 7.3 渐进迁移

对于 CAS 6.6 用户，建议采用渐进式迁移：

  1. 先在测试环境搭建 CAS 7.3 基础框架
  2. 逐步迁移自定义认证处理器（注意构造函数签名变更）
  3. 逐步迁移自定义 OAuth 扩展（使用 @ConditionalOnMissingBean）
  4. 迁移配置文件（驼峰转连字符、Redis 配置结构调整）
  5. 切换构建工具链（Gradle 7.5 -> 9.1.0）
  6. 验证 Docker 镜像构建（Jib 替代手动 Dockerfile）

10.3 生产环境迁移 Checklist ​

以下是在生产环境中执行 CAS 版本迁移的完整检查清单：

迁移前

  • [ ] 完整备份当前 CAS 配置和数据库
  • [ ] 在测试环境完成迁移验证
  • [ ] 准备回滚方案（保留旧版本的 Docker 镜像和配置）
  • [ ] 通知所有接入 CAS 的应用团队
  • [ ] 确认所有已注册的 Service 定义在新版本中兼容
  • [ ] 执行性能基准测试（对比迁移前后的 TPS、响应时间）

迁移中

  • [ ] 在维护窗口期执行迁移
  • [ ] 先迁移 Redis 票据存储（确保跨版本兼容）
  • [ ] 按节点逐步升级（灰度发布）
  • [ ] 每升级一个节点，执行完整的 SSO 流程测试
  • [ ] 监控错误日志和性能指标

迁移后

  • [ ] 验证所有已注册 Service 的 SSO 登录/登出
  • [ ] 验证 OAuth 2.0 授权码流程
  • [ ] 验证 REST API 认证
  • [ ] 验证票据过期和清理机制
  • [ ] 执行安全扫描（检查新引入的依赖是否存在已知漏洞）
  • [ ] 更新运维文档和应急预案

10.4 回滚策略设计 ​

版本迁移必须准备回滚策略。基于 CAS 的架构特点，建议采用以下回滚策略：

策略一：票据不兼容回滚

CAS 的票据（TGT、ST、PT）在不同版本之间可能不兼容。如果从 7.3 回滚到 6.6，已有的 TGT 将失效，所有用户需要重新登录。这种票据不兼容性源于 CAS 内部票据序列化格式的版本差异。每个 CAS 大版本都可能引入新的票据属性或修改现有属性的序列化方式，导致跨版本的票据反序列化失败。

策略二：Redis 清理回滚

在回滚前，清理 Redis 中的所有 CAS 票据数据，确保旧版本不会尝试解析新版本的票据格式。可以使用以下命令清理 Redis 中的 CAS 票据（教学示例）：

bash
# 清理 Redis 中的 CAS 票据（教学示例，请根据实际 key pattern 调整）
redis-cli --scan --pattern "CAS_TICKET:*" | xargs redis-cli DEL
redis-cli --scan --pattern "CAS_GRANTING_TICKET:*" | xargs redis-cli DEL

需要注意的是，如果 Redis 实例同时被其他应用使用，清理操作必须精确匹配 CAS 的 key pattern，避免误删其他应用的数据。建议在生产环境中使用独立的 Redis 实例或数据库来存储 CAS 票据，以降低操作风险。

策略三：蓝绿部署回滚

如果使用 Kubernetes 等容器编排平台，可以通过蓝绿部署实现快速回滚：

  1. 绿环境运行 CAS 7.3
  2. 蓝环境运行 CAS 6.6（保持待命状态）
  3. 回滚时，将流量切回蓝环境
  4. 清理 Redis 票据数据

蓝绿部署的优势在于回滚速度极快（通常在秒级），但成本也更高（需要双倍的计算资源）。对于关键业务系统，建议在迁移窗口期间保持蓝绿双环境运行至少 24 小时，确保有充足的回滚时间窗口。

策略四：金丝雀发布

对于大型部署环境，建议采用金丝雀发布策略：

  1. 先将 5% 的流量切换到 CAS 7.3 节点
  2. 观察 1 到 2 小时，监控错误率、响应时间和用户反馈
  3. 如果指标正常，逐步增加流量比例（10% -> 25% -> 50% -> 100%）
  4. 如果发现异常，立即将流量切回旧版本

金丝雀发布的关键在于监控指标的选取。建议重点监控以下指标：

  • CAS 登录成功率（目标 > 99.9%）
  • 平均登录响应时间（目标 < 500ms）
  • OAuth 2.0 授权码获取成功率
  • 票据注册中心的读写延迟
  • JVM 内存使用率和 GC 频率

总结与展望 ​

通过对 CAS Overlay 从 5.3 到 6.6 再到 7.3 的全面演进分析，我们可以提炼出以下关键洞察：

依赖管理是迁移的核心战场。从手动排除到 platform() 再到 enforcedPlatform()，CAS 的依赖管理策略日趋成熟。对于大型项目而言，enforcedPlatform() 带来的版本一致性保障是弥足珍贵的。在实际项目中，依赖冲突往往是最难排查的问题——它不会在编译期报错，而是在运行时以 ClassNotFoundException、NoSuchMethodError、ClassCastException 等形式突然出现。enforcedPlatform() 将这类问题从运行时提前到了构建时，极大地降低了线上故障的风险。

配置风格的演进反映了"约定优于配置"理念的深化。从 9 个配置文件减少到 3 个，不仅是文件数量的减少，更是配置复杂度的系统性降低。纯 YAML 配合 Spring Boot 的自动配置机制，使得 CAS Overlay 的维护成本大幅降低。然而，配置精简也带来了新的挑战——开发者需要更深入地理解 Spring Boot 的自动配置机制，才能在出现配置问题时快速定位根因。CAS 7.3 提供的 exportConfigMetadata 任务是理解配置体系的有力工具，建议每位 CAS 开发者都熟悉其使用方法。

安全是版本升级的第一驱动力。TLS 协议升级、TGC 加密控制、OAuth 2.0 令牌加密——这些安全增强是推动版本升级的最重要理由。对于仍在使用 CAS 5.3 的团队，安全补丁的缺失应当成为迁移的直接触发因素。在当前网络安全形势日益严峻的背景下，使用一个不再接收安全补丁的认证系统，无异于在企业的安全防线中留下一个已知的大洞。

构建工具链的现代化是长期效率投资。Jib 插件、CycloneDX SBOM、Foojay Toolchain——这些构建层面的增强虽然不直接影响运行时行为，但它们显著提升了构建效率、供应链安全性和跨环境一致性。特别是在 CI/CD 管道中，Jib 的层缓存优化可以将镜像构建时间从分钟级降低到秒级，这对于频繁部署的敏捷开发团队来说是实实在在的效率提升。

认证架构的演进体现了"解耦"的设计哲学。从 ServicesManager 的强制依赖到 CasConfigurationProperties 的可选注入，从缺乏热刷新到 @RefreshScope 的引入，CAS 的认证架构在保持向后兼容的同时，逐步降低了扩展的门槛。这种渐进式的架构演进，对于需要长期维护的 CAS Overlay 项目来说，是最理想的升级路径。

迁移的本质是"理解差异，而非照搬配置"。本文花了大量篇幅分析每个变更背后的设计动机，而非简单地列出"改什么、怎么改"。这是因为，CAS 的版本迭代速度极快，今天从 5.3 迁移到 7.3 的经验，明天可能需要适配从 7.3 到 8.x 的迁移。只有理解了变更的设计动机，才能在面对未来的版本迁移时，具备独立分析和解决问题的能力。

展望未来，CAS 的演进趋势可能会围绕以下方向展开：

  1. GraalVM 原生镜像支持：Spring Boot 3.x 已经提供了对 GraalVM Native Image 的初步支持，CAS 未来可能会提供原生镜像的官方支持，将启动时间从秒级降低到毫秒级。这对于需要快速扩缩容的云原生部署场景尤为重要。

  2. 可观测性增强：Micrometer Tracing 和 OpenTelemetry 的深度集成，使得 CAS 的分布式追踪能力进一步增强。在微服务架构中，CAS 作为认证网关，其可观测性对于全链路问题排查至关重要。

  3. Passkey/WebAuthn 集成：随着无密码认证的普及，CAS 可能会提供更完善的 Passkey 支持。Apple、Google、Microsoft 已经在各自平台上推出了 Passkey 功能，CAS 作为企业级 SSO 解决方案，需要紧跟这一趋势。

  4. AI 辅助认证：基于行为分析的风险自适应认证可能会成为 CAS 的标准功能。通过分析用户的登录时间、地理位置、设备指纹等多维特征，动态调整认证强度（如要求二次验证），在安全性和用户体验之间取得平衡。

  5. 多租户架构增强：随着 SaaS 模式的普及，CAS 可能会提供更完善的多租户支持，允许不同的租户使用不同的认证策略、品牌主题和服务注册。

无论 CAS 如何演进，理解其版本间的差异和迁移路径，对于每一位企业级 SSO 架构师而言，都是不可或缺的核心能力。希望本文能为正在或即将进行 CAS 版本迁移的团队提供有价值的参考。

在结束本文之前，笔者想强调一点：版本迁移不是目的，而是手段。真正的目标是构建一个安全、稳定、可维护的企业级 SSO 基础设施。在迁移过程中，不要盲目追求最新版本，而要基于自身的业务需求、技术能力和资源约束，选择最合适的版本和迁移时机。技术选型的核心原则永远是"适合的才是最好的"。

版权声明： 本文为必码（bima.cc）原创技术文章，仅供学习交流。

本文内容基于实际项目源码解析整理，代码示例均为教学简化版本，仅供学习参考。

文档内容提取自项目源码与配置文件，如需获取完整项目代码，请访问 bima.cc。

© 2024-至今 北京必码科技工作室 bima.cc