如何将Keycloak会话存储从本地缓存切换至数据库并保留现有会话信息

前置准备 #

• 先备份当前Keycloak全量数据，包括Infinispan缓存持久化文件、现有运行配置，避免操作异常导致数据丢失
• 提前部署好可用的PostgreSQL实例，创建专属Keycloak的数据库和账号，确认网络连通性正常

步骤1：持久化现有会话数据 #

你当前cache-owners.cli内的配置仅设置了分布式缓存的副本数，默认会话数据仅存在Infinispan内存中，首先需要先将会话数据持久化到临时存储避免丢失：

• 临时修改Keycloak启动配置，开启Infinispan会话缓存的文件持久化，配置示例如下（添加到你的cli配置文件末尾即可）：

/subsystem=infinispan/cache-container=keycloak/distributed-cache=clientSessions/file-store=file:add(path="client-sessions", relative-to="jboss.server.data.dir")
/subsystem=infinispan/cache-container=keycloak/distributed-cache=offlineClientSessions/file-store=file:add(path="offline-client-sessions", relative-to="jboss.server.data.dir")

• 重启Keycloak实例，等待所有会话数据落地到本地文件存储后再关闭实例

步骤2：配置PostgreSQL数据源 #

• 将PostgreSQL JDBC驱动放到Keycloak的providers目录
• 新增cli配置片段配置PostgreSQL数据源，替换原有本地存储配置：

# 注册JDBC驱动
/subsystem=datasources/jdbc-driver=postgresql:add(driver-name=postgresql, driver-module-name=org.postgresql, driver-class-name=org.postgresql.Driver)
# 新增数据源
/subsystem=datasources/data-source=KeycloakPostgresDS:add(
    jndi-name=java:jboss/datasources/KeycloakDS,
    connection-url=jdbc:postgresql://<你的PostgreSQL服务地址>:5432/<Keycloak数据库名>,
    driver-name=postgresql,
    user-name=<数据库访问账号>,
    password=<数据库访问密码>,
    valid-connection-checker-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker,
    exception-sorter-class-name=org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
)

• 替换存储配置，将Keycloak默认存储切换为JDBC（PostgreSQL），同时保留Infinispan作为会话缓存层：

/subsystem=keycloak-server/spi=connectionsJpa/provider=default:write-attribute(name=properties.dataSource, value="java:jboss/datasources/KeycloakDS")
/subsystem=keycloak-server/spi=userSessions/provider=infinispan:write-attribute(name=properties.cacheOwners, value=${env.CACHE_OWNERS_COUNT:1})

你原有cache-owners.cli里的两行配置不需要删除，原有会话缓存副本配置依然生效，仅底层持久化源会切换为PostgreSQL

步骤3：数据迁移与验证 #

• 启动Keycloak实例，系统会自动在PostgreSQL中创建所需表结构
• 执行会话数据验证：通过Keycloak管理控制台的会话页面，确认现有会话全部可见，也可以直接查询PostgreSQL中的client_session、offline_client_session表验证数据完整性
• 待验证所有数据正常后，可删除之前临时添加的Infinispan文件持久化配置

内容的提问来源于stack exchange，提问作者Mikhail