keycloak

Keycloak 身份认证服务

补充说明

keycloak 提供 OIDC/SAML 单点登录、用户联邦和权限管理。服务端用 kc.sh 启停，管理可用 Admin Console 或 kcadm.sh。

常用示例

kc.sh start-dev
kc.sh start --db=postgres --hostname=auth.example.com
kc.sh build
kc.sh bootstrap-admin user
kc.sh export --dir /backup --realm app
kc.sh import --dir /backup
kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin
kcadm.sh get realms
kcadm.sh create realms -s realm=app -s enabled=true
kcadm.sh create clients -r app -s clientId=web -s enabled=true

常见配置

KC_DB=postgres
KC_DB_URL=jdbc:postgresql://db:5432/keycloak
KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=secret
KC_HOSTNAME=auth.example.com
KC_PROXY_HEADERS=xforwarded
KC_HTTP_ENABLED=true

易错点与排错

start-dev 只适合开发；生产用 start 并配置数据库和 hostname。
反向代理场景要正确设置 hostname/proxy headers，否则登录跳转地址错误。
Admin 账号要在首次启动时创建；忘记后需要恢复流程。
realm 导出/导入要包含用户和密钥时加相应参数，否则迁移后登录失败。
数据库、缓存（Infinispan）和集群配置不一致会导致会话丢失。
TLS、cookie SameSite 和跨域配置影响单点登录。
主题和自定义 SPI 升级后可能不兼容；升级前看版本说明。

相关命令

oauth2-proxy — 反向代理接入
nginx — 前置代理
psql / mysql — 后端数据库

读完自测

合上页面，先回答，再展开对照。

生产环境用 start-dev 有什么问题？
反向代理后登录跳转到错误地址，先查什么？
realm 导出导入后用户数据在但登录失败，可能漏了什么？

答案

它只适合开发，生产要用 start 并配置数据库和 hostname。
hostname 和 proxy headers 是否配置正确。
导出/导入要包含用户和密钥，需要加相应参数。