Keycloak 企业实操：三副本、私有管理接口与恢复

验证：未记录

适用版本: 未记录
验证范围: 尚未登记验证记录。

路径：三节点 Kubernetes、Keycloak 26.x 已批准补丁、私网高可用 PostgreSQL、内部 TLS（传输层安全）入口。使用普通 Deployment 管理固定镜像，避免安装 Operator（控制器）但未交付其生命周期。若组织采用官方 Operator，二选一管理，不能同时协调本篇 Deployment。

1. 数据库与优化镜像#

先按 PostgreSQL 生产实操或托管 SQL 建独立 keycloak 数据库与角色，仅拥有本库 schema。Keycloak 启动会涉及 schema 迁移及锁，不能随意移除必须的数据库权限；高风险升级按第 5 节停止混跑。

cp -R static/examples/keycloak-production /tmp/keycloak-work
cd /tmp/keycloak-work
export KEYCLOAK_IMAGE='quay.io/keycloak/keycloak@sha256:REPLACE_APPROVED_26_X_DIGEST'
docker build --build-arg KEYCLOAK_IMAGE="$KEYCLOAK_IMAGE" -t REPLACE_PRIVATE_REGISTRY/keycloak:CHANGE_ID .
# 扫描、签名、推送，解析实际 digest，填入 workload.yaml。

Dockerfile 在构建时固定 postgres、health、metrics；运行用 start --optimized，不能用 start-dev。26.x 默认 jdbc-ping（数据库发现）形成缓存集群；网络策略允许实际缓存端口，不依赖已弃用的 Kubernetes 发现栈。缓存集群说明

2. 下发秘密和证书#

创建权限 600 的 /secure/keycloak-db.env：KC_DB_URL 使用 jdbc:postgresql://DB_HOST:5432/keycloak?sslmode=verify-full&sslrootcert=/run/dbca/ca.pem，同时包含 KC_DB_USERNAME、KC_DB_PASSWORD。证书 CA 必须与数据库主机名匹配。

kubectl create namespace keycloak --dry-run=client -o yaml | kubectl apply -f -
kubectl -n keycloak create secret generic keycloak-db --from-env-file=/secure/keycloak-db.env
kubectl -n keycloak create secret tls keycloak-tls --cert=/secure/sso-chain.pem --key=/secure/sso-key.pem
kubectl -n keycloak create configmap keycloak-db-ca --from-file=ca.pem=/secure/db-ca.pem

首次初始化额外把 KC_BOOTSTRAP_ADMIN_USERNAME、KC_BOOTSTRAP_ADMIN_PASSWORD 放入受控 Secret；登录后建立永久企业管理员、MFA（多因素认证）和应急流程，移除 bootstrap 环境项、删除临时管理员并滚动重启。移除变量本身不会删除已创建账户。

3. 部署与管理面隔离#

替换 workload.yaml 的镜像、数据库 CIDR 与真实 sso 域名；至少三节点容量足够，数据库连接预算至少 3×20 加 surge/运维预留。

kubectl apply --dry-run=server -f workload.yaml
kubectl apply -f workload.yaml
kubectl -n keycloak rollout status deployment/keycloak --timeout=15m
kubectl -n keycloak get pods -o wide
kubectl -n keycloak port-forward service/keycloak-management 9000:9000 --address=127.0.0.1
# 新终端：
curl --fail http://127.0.0.1:9000/health/ready
curl --fail http://127.0.0.1:9000/metrics

内部入口使用 TLS passthrough 或验证后端证书的再加密，业务 Service 只发布 443；9000 只供私有探针/监控。文档未配置代理头信任，因此不要在公网边缘接受任意 X-Forwarded-* 后直接启用 proxy-headers。接入邮件、LDAP、外部身份源时追加其精确出口和证书，不能把全网放通当默认。

4. 身份与故障验收#

在管理台创建 enterprise-lab realm、合成测试用户、public OIDC（OpenID Connect）客户端；启用 Authorization Code + PKCE（授权码与证明密钥），只允许实际测试回调 URL，关闭隐式流和密码直授。
客户端完成登录、刷新、退出；验证 issuer/audience/签名、错误回调拒绝、非授权角色拒绝，不只请求 discovery 页面。
通过同一内部域名持续执行登录/刷新，逐个重建一个 Keycloak Pod；观察缓存集群成员、登录错误和延迟。随机关闭两个 Pod 不受 PDB 保护，须单独评估容量和会话影响。
从不可信 namespace 访问 9000/7800 应失败；业务域名 /health/ready、/metrics 不应暴露管理数据。

5. 备份、恢复与升级#

备份 PostgreSQL 和外部配置/证书/秘密版本；realm JSON export 不包含完整用户密码、会话与所有数据库状态，不能替代数据库恢复。先停止测试写入/登录，记录用户数、realm、client、角色映射，再对数据库做已验证的物理备份/PITR（时间点恢复）。

恢复至独立数据库，复制本篇清单为 keycloak-restore namespace、独立域名/证书及秘密；禁用真实 SMTP、外部 webhook、生产 LDAP 写回。相同镜像启动后，以合成用户验证密码、MFA、角色、客户端登录及退出，核对配置数量。恢复环境不得使用生产入口或生产写凭据。

升级先在恢复环境用目标镜像执行 schema 迁移与全流程验收。只有官方明确支持的更新组合才滚动混跑；否则维护窗口停全部旧副本，备份并更新镜像后逐步启动。迁移后失败不能只 rollout undo：旧版本可能不兼容新 schema，需恢复数据库和匹配镜像到独立环境，再受控切入口。

验收包含数据库切换期间登录/刷新行为、备份恢复耗时、证书轮换和临时管理员撤销。完成后删除独立恢复实例/namespace 与临时回调配置，保留恢复证据；原数据库与永久身份不在清理范围。

Keycloak 数据库、管理接口。