calverley/keycloak

Keycloak Docker镜像

概述

Keycloak Docker镜像是Keycloak服务器的容器化版本。Keycloak是一款开源的身份和访问管理解决方案，提供用户认证、授权、单点登录(SSO)等功能，适用于保护Web应用和API。

核心功能和特性

• 多数据库支持：兼容H2（嵌入式）、MySQL、PostgreSQL和MariaDB
• 灵活部署：支持独立模式运行，可配置端口映射
• 管理员账户管理：通过环境变量或命令创建管理员账户
• 自定义扩展：支持添加自定义主题和提供者
• 集群发现：可配置JGroups发现协议实现集群部署
• 安全配置：支持TLS/SSL加密和代理地址转发
• 日志管理：可自定义Keycloak和容器的日志级别

使用场景和适用范围

• 开发环境快速搭建身份认证服务
• 生产环境部署企业级身份管理系统
• 集成多种数据库实现数据持久化
• 构建支持单点登录的多应用系统
• 需要自定义主题和认证流程的场景

使用方法和配置说明

基本使用

独立模式启动

bash
docker run jboss/keycloak

暴露到本地

将容器的8080端口映射到本地，以便通过localhost访问：

bash
docker run -p 8080:8080 jboss/keycloak

创建管理员账户

默认情况下未创建管理员账户，需通过环境变量指定初始用户名和密码：

bash
docker run -e KEYCLOAK_USER=<用户名> -e KEYCLOAK_PASSWORD=<密码> jboss/keycloak

也可在运行中的容器上创建账户：

bash
docker exec <容器ID> keycloak/bin/add-user-keycloak.sh -u <用户名> -p <密码>
docker restart <容器ID>

数据库配置

支持H2、MySQL、PostgreSQL和MariaDB，通过DB_VENDOR环境变量指定数据库类型：

• h2：嵌入式H2数据库（默认）
• postgres：PostgreSQL数据库
• mysql：MySQL数据库
• mariadb：MariaDB数据库

若未指定DB_VENDOR，镜像将尝试自动检测数据库（基于网络主机名或特定环境变量）。

通用数据库环境变量

• DB_ADDR：数据库主机名（可选）
• DB_PORT：数据库端口（可选，默认使用数据库默认端口）
• DB_DATABASE：数据库名称（可选，默认keycloak）
• DB_USER：数据库用户名（可选，默认keycloak）
• DB_PASSWORD：数据库密码（可选，默认password）

MySQL示例

1. 创建自定义网络：

bash
docker network create keycloak-network

2. 启动MySQL实例：

bash
docker run --name mysql -d --net keycloak-network \
  -e MYSQL_DATABASE=keycloak \
  -e MYSQL_USER=keycloak \
  -e MYSQL_PASSWORD=password \
  -e MYSQL_ROOT_PASSWORD=root_password \
  mysql

3. 启动Keycloak实例（自动检测MySQL）：

bash
docker run --name keycloak --net keycloak-network jboss/keycloak

若MySQL实例名称非mysql，需指定DB_ADDR环境变量：-e DB_ADDR=<mysql实例名称>

PostgreSQL示例

1. 创建自定义网络：

bash
docker network create keycloak-network

2. 启动PostgreSQL实例：

bash
docker run -d --name postgres --net keycloak-network \
  -e POSTGRES_DB=keycloak \
  -e POSTGRES_USER=keycloak \
  -e POSTGRES_PASSWORD=password \
  postgres

3. 启动Keycloak实例：

bash
docker run --name keycloak --net keycloak-network jboss/keycloak

若PostgreSQL实例名称非postgres，需指定DB_ADDR环境变量

MariaDB示例

1. 创建自定义网络：

bash
docker network create keycloak-network

2. 启动MariaDB实例：

bash
docker run -d --name mariadb --net keycloak-network \
  -e MYSQL_ROOT_PASSWORD=password \
  -e MYSQL_DATABASE=keycloak \
  -e MYSQL_USER=keycloak \
  -e MYSQL_PASSWORD=password \
  mariadb

3. 启动Keycloak实例：

bash
docker run --name keycloak --net keycloak-network jboss/keycloak

若MariaDB实例名称非mariadb，需指定DB_ADDR环境变量

指定JDBC参数

可通过JDBC_PARAMS环境变量配置数据库连接参数：

bash
docker run --name keycloak -e DB_VENDOR=postgres -e JDBC_PARAMS='connectTimeout=30' jboss/keycloak

添加自定义主题

扩展Keycloak镜像，将主题文件添加到/opt/jboss/keycloak/themes目录。

添加自定义提供者

扩展Keycloak镜像，将提供者文件添加到/opt/jboss/keycloak/standalone/deployments/目录。

配置JGroups发现协议

通过环境变量替换默认发现协议：

• JGROUPS_DISCOVERY_PROTOCOL：发现协议名称（如DNS_PING）
• JGROUPS_DISCOVERY_PROPERTIES：协议属性（格式：PROP1=FOO,PROP2=BAR）

示例（使用DNS_PING）：

bash
docker run \
  -e JGROUPS_DISCOVERY_PROTOCOL=DNS_PING \
  -e JGROUPS_DISCOVERY_PROPERTIES=dns_query=keycloak.myproject.svc.cluster.local \
  jboss/keycloak

杂项配置

指定主机名

生产环境建议设置固定主机名：

bash
docker run -e KEYCLOAK_HOSTNAME=keycloak.example.com jboss/keycloak

指定端口

自定义HTTP和HTTPS端口：

bash
docker run -e KEYCLOAK_HTTP_PORT=8081 -e KEYCLOAK_HTTPS_PORT=8443 jboss/keycloak

日志级别配置

• KEYCLOAK_LOGLEVEL：Keycloak日志级别（默认INFO）
• ROOT_LOGLEVEL：容器日志级别（默认INFO）

支持的级别：ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE, WARN

运行时修改日志级别：

bash
# 进入容器
docker exec -it <容器ID> /bin/bash
# 修改根日志级别
./keycloak/bin/jboss-cli.sh --connect --command='/subsystem=logging/root-logger=ROOT:change-root-log-level(level=DEBUG)'
# 修改Keycloak日志级别
./keycloak/bin/jboss-cli.sh --connect --command='/subsystem=logging/logger=org.keycloak:write-attribute(name=level,value=DEBUG)'

启用代理地址转发

在代理服务器后运行时启用：

bash
docker run -e PROXY_ADDRESS_FORWARDING=true jboss/keycloak

配置TLS(SSL)

挂载TLS证书和私钥到/etc/x509/https目录：

• tls.crt：证书文件
• tls.key：私钥文件

示例：

bash
docker run -v /path/to/tls:/etc/x509/https jboss/keycloak

若需配置 Mutual TLS，可挂载CA bundle并设置X509_CA_BUNDLE环境变量指向CA文件。

其他说明

该镜像基于jboss/base-jdk镜像构建，后者在jboss/base镜像基础上添加了OpenJDK分发版。

构建自定义镜像

从GitHub仓库构建

通过构建参数指定GitHub仓库和分支：

bash
docker build --build-arg GIT_REPO=keycloak/keycloak --build-arg GIT_BRANCH=master .

从替代位置下载Keycloak

指定自定义Keycloak分发包地址：

bash
docker build --build-arg KEYCLOAK_DIST=[***] .