企业级实战：手把手打造生产可用的高可用 Keycloak 集群（附避坑指南）-脚本在线

AI智能体脚本智能办公脚本自动化游戏脚本浏览器自动化脚本服务器脚本

企业级实战：手把手打造生产可用的高可用 Keycloak 集群（附避坑指南）

作者：互联网

2026-03-24

AI模型库

在现代微服务架构和云原生应用中，统一、安全的身份认证与授权（Identity and Access Management, IAM）是基石。Keycloak 作为一款开源的、功能强大的 IAM 解决方案，凭借其灵活的协议支持（如 OpenID Connect, SAML）、用户友好的管理控制台和可扩展的架构，正被越来越多的企业采纳。

然而，将 Keycloak 从开发环境推向生产环境，绝非简单的单机部署。生产环境要求高可用性（High Availability）、可伸缩性（Scalability）和数据持久性（Data Persistence）。单点故障（SPOF）是生产系统的天敌。今天，我将分享如何部署一套真正生产级别的、高可用的 Keycloak 集群。

1. 架构设计：高可用的核心要素

生产级的 Keycloak 集群部署，核心在于消除单点故障，并确保会话状态的共享。我们采用以下架构：

多实例集群 (Keycloak Cluster): 部署至少两个 Keycloak 实例，通过负载均衡器（如 Nginx, HAProxy）对外提供服务，实现流量分发和故障转移。

外部数据库 (External Database): Keycloak 的用户、客户端、角色等核心数据必须存储在外部高可用数据库中（如 PostgreSQL, MySQL），而非默认的嵌入式 H2 数据库。这是实现数据持久化的关键。

分布式会话管理 (Distributed Session): Keycloak 实例间的会话状态（如用户登录状态）需要共享。我们利用 Infinispan 作为分布式缓存层，通过 JGroups 实现节点间的通信和状态同步。Keycloak 支持将 Infinispan 配置为外部集群模式，这是实现无共享（share-nothing）架构和会话高可用的核心。

反向代理与 TLS 终止: 使用 Nginx 或 HAProxy 作为反向代理，处理 HTTPS 请求，并将流量转发到后端的 Keycloak 实例。

2. 部署实践：关键步骤与配置

整体架构：总共用4台服务器构建。两台服务器部署keycloak，两台服务器部署haproxy负载均衡到keycloak。以下是一个基于 Docker Compose 的简化示例，展示核心组件的编排。

(1) 部署高可用postgresql集群，这里不做演示。

(2) 生成keycloak使用的证书

# 创建目录
sudo mkdir -p /app/keycloak/certs 
sudo chown -R ops. /app/keycloak
cd /app/keycloak/certs/

# ca证书
openssl req -newkey rsa:2048 -x509 -nodes -keyout ca.key -out ca.crt -days 3650 -subj "/CN=CA"

# 服务证书
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr -subj "/C=CN/O=jiaxzeng/CN=keycloak.jiaxzeng.com"
openssl x509 -req -CA ca.crt -CAkey ca.key -in server.csr -out server.crt -CAcreateserial -days 3650 -extfile <(printf "subjectAltName=IP:127.0.0.1,IP:172.139.x.x,IP:172.139.x.x,IP:172.139.x.x,IP:172.139.x.x,IP:172.139.x.x,IP:172.139.x.x,DNS:localhost,DNS:keycloak.jiaxzeng.com")1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.

Tip：IP地址需要有keycloak和负载均衡以及VIP地址。

(3) pg数据库创建好数据库

$ createuser -h 172.139.x.x -p 9999 -U postgres -W sso -P
Enter password for new role: 
Enter it again: 
Password: 

$ createdb -h 172.139.x.x -p 9999 -O sso -U postgres -W keycloak
Password:1.
2.
3.
4.
5.
6.
7.

(4) 部署keycloak集群(两台主机部署)

services:
  keycloak:
    container_name: keycloak
    image: quay.io/keycloak/keycloak:26.4
    environment:
      # 登录keycloak账密
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
      # 数据库配置
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://172.139.x.x:9999/keycloak?serverTimeznotallow=Asia/Shanghai
      KC_DB_USERNAME: sso
      KC_DB_PASSWORD: xxx
      # https配置
      KC_HTTPS_CERTIFICATE_FILE: /tmp/ssl/server.crt
      KC_HTTPS_CERTIFICATE_KEY_FILE: /tmp/ssl/server.key
      # http配置
      KC_HOSTNAME_STRICT: "false"
      KC_PROXY_HEADERS: forwarded
      # http配置
      KC_HTTP_ENABLED: "true"
      KC_HTTP_PORT: 18080
      KC_PROXY_TRUSTED_ADDRESSES: "172.139.x.x,172.139.x.x"
      # metrics和监控检查
      KC_HTTP_MANAGEMENT_PORT: 19000
      KC_HEALTH_ENABLED: "true"
      KC_METRICS_ENABLED: "true"
      # Java启动参数
      JAVA_OPTS_APPEND: '-Djgroups.bind.address=172.139.x.x'
    volumes:
    - ./certs:/tmp/ssl
    command: ["start"]
    network_mode: host1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.

Tip：

上述只需要修改JAVA_OPTS_APPEND参数的地址信息，改成本机IP地址
KC_PROXY_TRUSTED_ADDRESSES配置负载均衡IP地址

(5) keycloak配置ssl reqest为none

进入Configure -> Realm settings -> General，Require SSL选择为None -> Save

Tip：任意一台主机，但是必须通过https端口访问。

3. Haproxy反向代理配置

(1) ssl终止的证书

$ cd /app/keycloak/certs
$ cat server.key server.crt | tee keycloak.pem >/dev/null 
$ scp keycloak.pem 172.139.x.x:/etc/haproxy/certs1.
2.
3.

(2) haproxy配置

frontend keycloak_frontend
  bind *:18443 ssl crt /usr/local/etc/haproxy/certs/keycloak.pem
  mode http
  # keycloak需要的请求头
  http-request set-header Forwarded "for=%[src];host=%[req.hdr(host)];proto=https"
  # 暴露所需url
  acl is_public path_beg /realms/ /resources/
  use_backend  keycloak_server if is_public

backend keycloak_server
  mode http
  server kc01 172.139.x.x:18080 maxconn 32 check
  server kc02 172.139.x.x:18080  maxconn 32 check1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.