Apereo CAS 数据库驱动（JDBC Drivers）配置指南：内置驱动支持、JPA 实现与手动扩展

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

Apereo CAS 的绝大多数数据库功能模块（如 JPA Ticket Registry、JDBC 认证、审计存储等）会自动携带并加载对应的 JDBC 驱动，但在某些构建与部署场景下，你仍需要显式引入 JDBC 驱动模块，或为不受内置支持的数据源手动添加驱动。本文基于 JDBC-Drivers.md 展开，结合当前仓库中cas-server-support-jdbc-drivers模块的构建脚本与源码实现，系统讲解 CAS 内置支持的数据库驱动清单、各数据库对应的 Hibernate 方言、Hibernate / EclipseLink 两套 JPA 实现的选用，以及驱动注销与 GraalVM 原生镜像相关的底层机制。读完本文，你将能够准确判断何时需要引入驱动模块、如何在 Gradle 构建中补充自定义数据库驱动，并理解 CAS 处理 JDBC 驱动生命周期的内部原理。

何时需要显式引入 JDBC 驱动模块

文档明确指出：在大多数情况下，CAS 会自动处理数据库驱动，无需额外配置。这是因为各个功能模块（例如cas-server-support-jpa-ticket-registry、cas-server-support-jdbc-authentication等）在声明依赖时已经将对应的驱动作为传递依赖一并引入。只有在以下进阶场景中，你才需要手动把cas-server-support-jdbc-drivers模块加入 CAS Overlay 构建：

• 构建环境中依赖解析被裁剪、传递依赖未生效；
• 需要使用内置支持之外的其他数据库驱动；
• 进行定制化开发，需要直接控制驱动类的加载路径。

该模块的定位在 build.gradle 中有明确描述："Bundles common JDBC drivers so database-backed CAS features can connect to supported databases"（打包通用 JDBC 驱动，使数据库相关的 CAS 功能能够连接受支持的数据库）。其依赖声明非常精简：

dependencies { api project(":api:cas-server-core-api") runtimeOnly libraries.databasedrivers }

值得注意的是，驱动依赖采用runtimeOnly作用域，即驱动只参与运行期类路径，不会污染编译期 API；同时模块还依赖了 cas-server-core-api，这是所有 CAS 核心 API 的基础模块。

内置驱动包：databasedrivers依赖清单

runtimeOnly libraries.databasedrivers引用的依赖集合定义在 gradle/dependencies.gradle 中，它聚合了 CAS 自动支持的数据库驱动：

从这份依赖清单可以看出，内置驱动集合实际上比文档表格中列出的数据库范围更广（例如额外包含了 YugabyteDB 驱动以及 Hibernate 社区方言库），这为接入了上述驱动但官方文档未单独成节的数据库（如 YugabyteDB、SQLite 等）提供了运行期支撑。

JPA 实现：Hibernate 与 EclipseLink 二选一

CAS 的 JPA 持久化层提供两套实现，由 CAS 根据构建中包含的模块自动选择，通常无需显式配置，文档中列出的模块信息主要服务于需要定制开发的进阶场景。

Hibernate ORM

Hibernate ORM 是 Java 生态最流行的对象关系映射（ORM）框架，负责将面向对象的领域模型映射到关系型数据库。对应的 CAS 模块为cas-server-support-jpa-hibernate，该模块在仓库中实现了完整的 Hibernate 接入，核心源码包括：

• CasHibernateJpaAutoConfiguration：Spring Boot 自动配置入口，负责装配 Hibernate 的EntityManagerFactory相关 Bean；
• CasHibernateJpaBeanFactory 与 CasHibernatePersistenceProvider：JPA 持久化提供者的 CAS 定制实现；
• CasHibernatePhysicalNamingStrategy：统一物理命名策略，保证表名/列名在不同数据库方言下行为一致。

对应的单元测试位于 CasHibernateJpaBeanFactoryTests 等测试文件中，可用于验证 JPA Bean 工厂的装配行为。

EclipseLink

EclipseLink 是 Eclipse Foundation 维护的开源 Eclipse 持久化服务项目，提供面向数据库、Web 服务、对象 XML 映射以及企业信息系统等多种数据服务的可扩展框架。对应的 CAS 模块为cas-server-support-jpa-eclipselink，核心实现包括：

• CasEclipseLinkJpaAutoConfiguration：EclipseLink 的自动配置入口；
• CasEclipseLinkJpaBeanFactory：面向 EclipseLink 的 JPA Bean 工厂实现。

两套实现互斥，CAS 会根据构建中实际包含的模块决定启用哪一套；同时包含两个模块时，自动配置机制会依据条件注解做出取舍。具体选型应结合部署环境对 ORM 的依赖约束来决定。

自动支持的数据库驱动与方言速查表

以下驱动由 CAS 自动支持，无需手动加入构建；所有未列出的其他数据库驱动都必须手动添加到构建配置中。方言（Dialect）用于告知 Hibernate 目标数据库的 SQL 语法特性，CAS 在持久化配置中会自动选择合适的方言。

H2

可用驱动：

1. org.h2.Driver

HSQLDB

可用驱动：

1. org.hsqldb.jdbcDriver

Oracle

可用驱动：

1. oracle.jdbc.driver.OracleDriver

MySQL

可用驱动：

1. com.mysql.jdbc.Driver
2. com.mysql.cj.jdbc.Driver

说明：com.mysql.jdbc.Driver为 MySQL Connector/J 旧版驱动类名，com.mysql.cj.jdbc.Driver为 8.x 系列的新版驱动类名。实际使用中以 Connector/J 版本为准，CAS 会自动识别。

PostgreSQL

可用驱动：

1. org.postgresql.Driver

MariaDB

可用驱动：

1. org.mariadb.jdbc.Driver

Microsoft SQL Server

可用驱动：

1. net.sourceforge.jtds.jdbc.Driver
2. com.microsoft.sqlserver.jdbc.SQLServerDriver

说明：SQL Server 同时内置了 jTDS（net.sourceforge.jtds.jdbc.Driver）与微软官方驱动（com.microsoft.sqlserver.jdbc.SQLServerDriver）两条驱动路径，二者对应不同的 JDBC URL 格式，选择时需与连接串保持一致。

手动添加其他数据库驱动

对于不在上表之列的数据库，需要手动将驱动加入构建配置。以 Gradle 构建的 CAS Overlay 为例，典型做法是在build.gradle中为对应模块补充运行时依赖，例如：

dependencies { // 其他 CAS 模块依赖... implementation "org.example:example-jdbc-driver:1.2.3" }

同时需要在 CAS 配置文件中通过cas.jdbc或对应功能模块的数据源属性指定驱动类名（driverClass）与 JDBC URL。驱动类名的取值以厂商驱动文档为准，CAS 不会对其做额外限制，只要驱动类存在于运行期类路径即可被 JDBCDriverManager或连接池加载。

驱动生命周期管理：容器重启时的自动注销

JDBC 4.0 引入了驱动的自动注册机制：当驱动类被加载时，会自动向java.sql.DriverManager注册自己。在 Servlet 容器（如 Tomcat）中，如果应用使用了自己的 ClassLoader 加载驱动，那么在应用停止（重新部署、热更新）时，若这些驱动未被注销，DriverManager会继续持有对应用 ClassLoader 的引用，从而造成类加载器内存泄漏。

CAS 通过 JdbcServletContextListener 解决这一问题。该监听器使用@WebListener注解注册，实现了ServletContextListener，在contextDestroyed回调中执行如下逻辑：

1. 遍历DriverManager.getDrivers()获取当前已注册的全部驱动；
2. 对每一个驱动，检查其getClass().getClassLoader()是否与当前线程的上下文类加载器（即应用自身的 ClassLoader）一致；
3. 若一致，则调用DriverManager.deregisterDriver(driver)将其注销；否则跳过，避免误注销由容器或其他应用加载的驱动；
4. 注销过程中的异常会被记录为 WARNING 级别的日志，不影响容器关闭流程。

源码注释中还特别提到：在contextDestroyed阶段 Slf4j 日志框架可能已经关闭，因此该监听器刻意使用 JDK 自带的java.util.logging.Logger记录日志。该实现自 CAS 6.2.0 引入（见类上的@since 6.2.0），相关行为由 JdbcServletContextListenerTests 覆盖验证。

GraalVM 原生镜像下的驱动反射注册

CAS 7.x 支持以 GraalVM Native Image 方式构建运行。原生镜像在构建期执行静态分析，无法在运行期动态反射加载 JDBC 驱动类，因此必须提前向RuntimeHints注册反射信息。CAS 通过 JdbcDriversRuntimeHints（自 7.0.0 引入）完成这一工作：

• 为com.mysql、net.sourceforge、org.h2、org.mariadb、org.postgresql、org.apache.ignite、org.sqlite、org.hsqldb、oracle.jdbc、com.microsoft这些包下所有java.sql.Driver的子类注册反射提示；
• 额外注册oracle.jdbc.logging.annotations.Feature、org.hsqldb.dbinfo.DatabaseInformationFull、org.hsqldb.dbinfo.DatabaseInformation等类型的反射提示；
• 注册 HSQLDB 的资源包与资源文件（org/hsqldb/resources/*.sql、*.properties等）；
• 为javax.sql.DataSource及其子类注册反射提示，覆盖数据源类型的动态加载需求。

该注册逻辑由 JdbcDriversRuntimeHintsTests 进行验证。如果要在原生镜像模式下引入自定义驱动，需要在应用自身的 RuntimeHints 注册器中补充对应的反射提示。

配置验证与常见问题排查

• 确认驱动已加载：启用 CAS 的调试日志（org.apereo.cas相关 Logger 调至 DEBUG），观察数据源初始化日志中是否出现目标驱动类名；若出现ClassNotFoundException/No suitable driver found，说明驱动未进入运行期类路径。
• 驱动类与 URL 前缀匹配：JDBC URL 前缀（如jdbc:mysql:、jdbc:postgresql:、jdbc:sqlserver:、jdbc:jtds:sqlserver:）必须与驱动支持的协议一致，否则DriverManager无法匹配驱动。
• 容器内存泄漏告警：若容器日志中出现驱动未注销的告警，请确认应用基于cas-server-support-jdbc-drivers构建，使 JdbcServletContextListener 随应用部署生效。
• 方言选择异常：若 Hibernate 方言与数据库版本不匹配，可参照上文方言表显式指定；对内置驱动未覆盖的数据库，databasedrivers中的hibernate-community-dialects提供了社区方言支持。

综上，CAS 的 JDBC 驱动策略可以概括为：内置驱动开箱即用，外部驱动手动补充，驱动生命周期由监听器兜底，原生镜像由运行时提示护航。理解 JDBC-Drivers.md 中这张驱动/方言清单及其背后的模块实现，就能在各类数据库接入场景中快速定位问题、完成配置。

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