Keycloak/PostgreSQL恢复后数据未同步问题排查

1. 先核对恢复操作的准确性 #

• 你备份生成的是dump_all.sql，但恢复时执行的是cat backup_26012024.sql | psql -U username -d local-db，确认这两个文件是同一个备份吗？文件名不一致等于没恢复正确的备份数据。
• 恢复命令执行后有没有检查输出？比如是否出现权限报错、表结构不匹配等问题——虽然你看到user_entity有数据，但可能部分关联表（比如用户组关联表user_group_membership）没恢复成功。
• 确认恢复时是否覆盖了旧数据：pg_dumpall -c会生成带删除语句的备份，但如果恢复前没清空目标数据库，可能新旧数据混杂，导致Keycloak读取异常。

2. 清除Keycloak缓存 #

Keycloak默认会缓存用户、组等核心数据，即使数据库更新，缓存未失效就会显示旧内容：

• 直接清除缓存：进入Keycloak容器执行命令（需先登录admin）：

  docker exec -it <keycloak容器名> bash
  # 登录admin账户
  kcadm.sh config credentials --server http://localhost:8080/auth --realm master --user <admin用户名> --password <admin密码>
  # 清除用户和组缓存
  kcadm.sh clear-cache --user
  kcadm.sh clear-cache --group
  

• 检查本地缓存卷：如果Docker Compose给Keycloak配置了本地数据卷（比如./keycloak-data:/opt/keycloak/data），容器删除后卷里的旧缓存还会保留。需要彻底清理卷后重启：

  docker compose down -v
  # 重新恢复数据库后再启动
  docker compose up -d
  

3. 验证数据库连接配置 #

检查Docker Compose中Keycloak的数据库连接参数：

• 确认数据库地址是否用了PostgreSQL容器名（比如postgres），而不是localhost（容器内的localhost指向自身，无法连接到PostgreSQL容器）。
• 核对数据库名、用户名、密码是否和备份时的一致，避免Keycloak连接到了其他数据库实例。

4. 查看Keycloak启动日志 #

启动后检查日志，排查数据库加载或缓存初始化异常：

docker logs <keycloak容器名>

重点看是否有Failed to connect to database、Cache initialization failed这类报错，这类问题会导致Keycloak无法读取新恢复的数据库数据。

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