Keycloak 生产环境避坑指南——从单实例到高可用集群

Thu, 09 Jul 2026 21:00:00 +0800

Keycloak 的开发环境只需 docker run，但生产环境远没有这么简单。本文整理了我们在多个项目中踩过的 7 个坑，每个都有可复制的配置。

如果你还不熟悉 Keycloak 的基本概念（Realm、Client、Identity Provider），建议先阅读 Keycloak 完全指南。

坑 1：默认 H2 数据库

Keycloak 默认使用 H2 嵌入式数据库。开发环境没问题，生产环境绝对不能碰。

症状：重启后所有 Realm 配置消失、并发写入时数据损坏、无法做数据库级别备份。

解决方案：

# docker-compose.yml
keycloak:
 image: quay.io/keycloak/keycloak:26.1
 environment:
 KC_DB: postgres
 KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
 KC_DB_USERNAME: keycloak
 KC_DB_PASSWORD: <secure-password>
 depends_on:
 postgres:
 condition: service_healthy

教训：生产环境第一天就切到 PostgreSQL。H2 → PostgreSQL 的迁移比想象中痛苦（用户密码哈希格式不同、自定义 SPI 数据表结构不兼容）。

坑 2：会话不共享——多实例的噩梦

Keycloak 26.x 默认使用 Infinispan 做分布式缓存，但单播发现模式（PING）在生产环境中不可靠。

症状：登录后刷新页面回到登录页、不同 Pod 之间 Session 不共享、偶尔出现 user session not found 错误。

High Availability on XLabs

Keycloak 生产环境避坑指南——从单实例到高可用集群

坑 1：默认 H2 数据库

坑 2：会话不共享——多实例的噩梦