keycloak-clustered 镜像文档

镜像概述和主要用途

keycloak-clustered 是基于 quay.io/keycloak/keycloak *** Docker 镜像的扩展版本，通过添加 JDBC_PING 集群发现协议，简化了 Keycloak 集群的部署和配置。该镜像旨在帮助用户快速构建支持分布式会话共享和高可用性的 Keycloak 集群环境，适用于开发测试和生产部署场景。

核心功能和特性

• 继承*功能**：完全保留 Keycloak ***镜像的所有功能和配置选项
• JDBC_PING 协议集成：内置 JDBC_PING 集群发现机制，通过数据库实现节点自动发现
• 多数据库兼容：支持 MySQL、MariaDB、PostgreSQL 等主流关系型数据库作为集群协调存储
• 分布式会话共享：集群节点间自动同步用户会话和缓存数据
• 灵活部署：支持 Docker 容器化部署和虚拟机环境部署，适配开发与生产场景

使用场景和适用范围

• 开发环境：快速搭建本地 Keycloak 集群，验证分布式会话和高可用特性
• 生产环境：构建多节点 Keycloak 集群，提供高可用的身份认证和授权服务
• 企业级应用：需要跨节点会话共享、负载均衡和故障转移的认证系统
• 云环境部署：优化云环境下的集群发现机制，解决传统 UDP 多播在云环境中的限制

支持的标签及 Dockerfile 链接

环境变量配置

基础环境变量

该镜像继承 Keycloak ***镜像的所有环境变量，完整配置可参考 Keycloak ***文档。常用基础变量包括：

镜像特有环境变量

本地构建方法

进入对应版本目录，执行以下命令构建镜像：

bash
docker build -t ivanfranchin/keycloak-clustered:latest .

集群部署指南

前置条件

• 安装 Docker

使用 MySQL 部署集群

1. 创建 Docker 网络

bash
docker network create keycloak-net

2. 启动 MySQL 容器

bash
docker run --rm --name mysql -p 3306:3306 \
  -e MYSQL_DATABASE=keycloak \
  -e MYSQL_USER=keycloak \
  -e MYSQL_PASSWORD=password \
  -e MYSQL_ROOT_PASSWORD=root_password \
  --network keycloak-net \
  mysql:9.1.0

3. 启动 Keycloak 节点 1

bash
docker run --rm --name keycloak-clustered-1 -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e KC_DB=mysql \
  -e KC_DB_URL_HOST=mysql \
  -e KC_DB_URL_DATABASE=keycloak \
  -e KC_DB_USERNAME=keycloak \
  -e KC_DB_PASSWORD=password \
  -e KC_LOG_LEVEL=INFO,org.infinispan:DEBUG,org.jgroups:DEBUG \
  -e JGROUPS_DISCOVERY_EXTERNAL_IP=keycloak-clustered-1 \
  --network keycloak-net \
  ivanfranchin/keycloak-clustered:latest start-dev

4. 启动 Keycloak 节点 2

bash
docker run --rm --name keycloak-clustered-2 -p 8081:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e KC_DB=mysql \
  -e KC_DB_URL_HOST=mysql \
  -e KC_DB_URL_DATABASE=keycloak \
  -e KC_DB_USERNAME=keycloak \
  -e KC_DB_PASSWORD=password \
  -e KC_LOG_LEVEL=INFO,org.infinispan:DEBUG,org.jgroups:DEBUG \
  -e JGROUPS_DISCOVERY_EXTERNAL_IP=keycloak-clustered-2 \
  --network keycloak-net \
  ivanfranchin/keycloak-clustered:latest start-dev

使用 MariaDB 部署集群

1. 创建 Docker 网络

bash
docker network create keycloak-net

2. 启动 MariaDB 容器

bash
docker run --rm --name mariadb -p 3306:3306 \
  -e MARIADB_DATABASE=keycloak \
  -e MARIADB_USER=keycloak \
  -e MARIADB_PASSWORD=password \
  -e MARIADB_ROOT_PASSWORD=root_password \
  --network keycloak-net \
  mariadb:10.11.10

3. 启动 Keycloak 节点 1

bash
docker run --rm --name keycloak-clustered-1 -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e KC_DB=mariadb \
  -e KC_DB_URL_HOST=mariadb \
  -e KC_DB_URL_DATABASE=keycloak \
  -e KC_DB_USERNAME=keycloak \
  -e KC_DB_PASSWORD=password \
  -e KC_LOG_LEVEL=INFO,org.infinispan:DEBUG,org.jgroups:DEBUG \
  -e JGROUPS_DISCOVERY_EXTERNAL_IP=keycloak-clustered-1 \
  --network keycloak-net \
  ivanfranchin/keycloak-clustered:latest start-dev

4. 启动 Keycloak 节点 2

bash
docker run --rm --name keycloak-clustered-2 -p 8081:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e KC_DB=mariadb \
  -e KC_DB_URL_HOST=mariadb \
  -e KC_DB_URL_DATABASE=keycloak \
  -e KC_DB_USERNAME=keycloak \
  -e KC_DB_PASSWORD=password \
  -e KC_LOG_LEVEL=INFO,org.infinispan:DEBUG,org.jgroups:DEBUG \
  -e JGROUPS_DISCOVERY_EXTERNAL_IP=keycloak-clustered-2 \
  --network keycloak-net \
  ivanfranchin/keycloak-clustered:latest start-dev

使用 PostgreSQL 部署集群

1. 创建 Docker 网络

bash
docker network create keycloak-net

2. 启动 PostgreSQL 容器

bash
docker run --rm --name postgres -p 5432:5432 \
  -e POSTGRES_DB=keycloak \
  -e POSTGRES_USER=keycloak \
  -e POSTGRES_PASSWORD=password \
  --network keycloak-net \
  postgres:17.2

3. 启动 Keycloak 节点 1

bash
docker run --rm --name keycloak-clustered-1 -p 8080:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e KC_DB=postgres \
  -e KC_DB_URL_HOST=postgres \
  -e KC_DB_URL_DATABASE=keycloak \
  -e KC_DB_SCHEMA=myschema \
  -e KC_DB_USERNAME=keycloak \
  -e KC_DB_PASSWORD=password \
  -e KC_LOG_LEVEL=INFO,org.infinispan:DEBUG,org.jgroups:DEBUG \
  -e JGROUPS_DISCOVERY_EXTERNAL_IP=keycloak-clustered-1 \
  --network keycloak-net \
  ivanfranchin/keycloak-clustered:latest start-dev

4. 启动 Keycloak 节点 2

bash
docker run --rm --name keycloak-clustered-2 -p 8081:8080 \
  -e KEYCLOAK_ADMIN=admin \
  -e KEYCLOAK_ADMIN_PASSWORD=admin \
  -e KC_DB=postgres \
  -e KC_DB_URL_HOST=postgres \
  -e KC_DB_URL_DATABASE=keycloak \
  -e KC_DB_SCHEMA=myschema \
  -e KC_DB_USERNAME=keycloak \
  -e KC_DB_PASSWORD=password \
  -e KC_LOG_LEVEL=INFO,org.infinispan:DEBUG,org.jgroups:DEBUG \
  -e JGROUPS_DISCOVERY_EXTERNAL_IP=keycloak-clustered-2 \
  --network keycloak-net \
  ivanfranchin/keycloak-clustered:latest start-dev

使用 Microsoft SQL Server 部署集群

警告：当前该配置存在问题，暂不推荐使用。

集群验证方法

验证会话共享

1. 打开两个不同浏览器（如 Chrome 和 Chrome 无痕模式）
2. 分别访问两个节点：http://localhost:8080 和 http://localhost:8081
3. 使用管理员账号登录（用户名：admin，密码：admin）
4. 左侧菜单点击 Sessions，应显示 admin 用户有 2 个会话

验证数据库集群表

以 MySQL 为例，进入数据库容器查看集群表：

bash
# 进入 MySQL 终端
docker exec -it -e MYSQL_PWD=password mysql mysql -ukeycloak --database keycloak

# 查看 JGROUPSPING 表（集群节点信息）
mysql> SELECT * FROM JGROUPSPING;

集群清理步骤

1. 停止 Keycloak 节点：在对应终端按 Ctrl+C
2. 停止数据库容器：在数据库终端按 Ctrl+\
3. 删除 Docker 网络：

bash
docker network rm keycloak-net

虚拟机环境部署

前置条件

• 安装 VirtualBox 和 Vagrant

部署步骤

1. 克隆仓库并进入根目录
2. 编辑 Vagrantfile 配置数据库类型（可选）
3. 启动虚拟机集群：

bash
vagrant up

虚拟机管理命令

• 暂停虚拟机：vagrant suspend
• 恢复虚拟机：vagrant up
• 停止虚拟机：vagrant halt
• 销毁虚拟机：vagrant destroy -f

重要说明

自 Keycloak 26.1.0 版本起，集群发现默认传输栈已切换为 JDBC-PING，简化了集群配置并提升了云环境兼容性。有关集群部署的详细指南，可参考以下文章：

• 开发环境 Keycloak 集群部署指南
• 生产环境 Keycloak 集群部署指南

参考文章

• 使用 JDBC-PING 的 Keycloak 集群分布式缓存
• 基于 Vagrant 和虚拟机的 Keycloak 集群配置
• 基于 Docker Compose 的 Keycloak 集群配置

作者信息

Ivan Franchin

• LinkedIn
• GitHub
• Medium
• X