ikaruswill/keycloak

Keycloak Docker镜像

概述和主要用途

Keycloak Docker镜像是Keycloak服务器的容器化版本，支持arm64和amd64多架构。Keycloak是开源身份和访问管理解决方案，提供单点登录、OAuth 2.0、OpenID Connect等功能，用于保护各类应用的身份认证与授权。

核心功能和特性

• 多架构支持（arm64和amd64）
• 完整的身份认证与授权管理
• 支持多种数据库（H2、MySQL、PostgreSQL、MariaDB、Oracle、SQL Server）
• 领域导入/导出功能
• 自定义主题和提供程序扩展
• 集群部署与缓存复制
• 环境变量配置（含敏感信息文件注入）
• TLS/SSL配置与代理地址转发支持

使用场景和适用范围

适用于企业内部系统、SaaS应用、移动应用后端等需要身份认证和授权管理的场景，支持开发、测试和生产环境的单机或集群部署。

使用方法和配置说明

基本用法

以独立模式启动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> /opt/jboss/keycloak/bin/add-user-keycloak.sh -u <用户名> -p <密码>
docker restart <容器ID>

通过文件提供用户名和密码

使用KEYCLOAK_USER_FILE和KEYCLOAK_PASSWORD_FILE环境变量从文件读取敏感信息，适用于Docker Swarm等环境的密钥管理。

导入领域

创建管理员并导入领域配置：

bash
docker run -e KEYCLOAK_USER=<用户名> -e KEYCLOAK_PASSWORD=<密码> \
  -e KEYCLOAK_IMPORT=/tmp/example-realm.json -v /tmp/example-realm.json:/tmp/example-realm.json jboss/keycloak

导出领域

需挂载卷以保存导出文件，启动容器：

bash
docker run -d -p 8180:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin \
  -v $(pwd):/tmp --name kc jboss/keycloak

执行导出命令（端口偏移避免冲突）：

bash
docker exec -it kc /opt/jboss/keycloak/bin/standalone.sh \
  -Djboss.socket.binding.port-offset=100 -Dkeycloak.migration.action=export \
  -Dkeycloak.migration.provider=singleFile \
  -Dkeycloak.migration.realmName=my_realm \
  -Dkeycloak.migration.usersExportStrategy=REALM_FILE \
  -Dkeycloak.migration.file=/tmp/my_realm.json

更多导出选项见Keycloak官方文档。

数据库配置

支持多种数据库，通过DB_VENDOR指定类型（h2/postgres/mysql/mariadb/oracle/mssql），未指定时自动检测。

通用环境变量

• DB_ADDR：数据库主机名（PostgreSQL支持逗号分隔的多主机）
• DB_PORT：数据库端口（默认取决于数据库类型）
• DB_DATABASE：数据库名称（默认keycloak）
• DB_SCHEMA：数据库模式（PostgreSQL默认public）
• DB_USER/DB_USER_FILE：数据库用户
• DB_PASSWORD/DB_PASSWORD_FILE：数据库密码

数据库示例

MySQL：

bash
docker network create keycloak-network
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
docker run --name keycloak --net keycloak-network jboss/keycloak

PostgreSQL：

bash
docker network create keycloak-network
docker run -d --name postgres --net keycloak-network -e POSTGRES_DB=keycloak -e POSTGRES_USER=keycloak -e POSTGRES_PASSWORD=password postgres
docker run --name keycloak --net keycloak-network jboss/keycloak -e DB_USER=keycloak -e DB_PASSWORD=password

Oracle（需提供JDBC驱动）：

bash
docker network create keycloak-network
docker run -d --name oracle --net keycloak-network -p 1521:1521 carloscastillo/rgt-oracle-xe-11g
docker run -d --name keycloak --net keycloak-network -p 8080:8080 -v /path/to/ojdbc.jar:/opt/jboss/keycloak/modules/system/layers/base/com/oracle/jdbc/main/driver/ojdbc.jar jboss/keycloak

指定JDBC参数

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

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

自定义主题与提供程序

• 主题：扩展镜像，将主题文件添加至/opt/jboss/keycloak/themes，通过KEYCLOAK_WELCOME_THEME和KEYCLOAK_DEFAULT_THEME设置
• 提供程序：扩展镜像，将提供程序文件添加至/opt/jboss/keycloak/standalone/deployments/

启动自定义脚本

将.cli脚本或可执行文件放入/opt/jboss/startup-scripts目录，按字母顺序执行：

dockerfile
FROM keycloak
COPY custom-scripts/ /opt/jboss/startup-scripts/

集群配置

通过环境变量配置集群发现协议：

• JGROUPS_DISCOVERY_PROTOCOL：协议名称（如dns.DNS_PING）
• JGROUPS_DISCOVERY_PROPERTIES：协议属性（PROP1=FOO,PROP2=BAR）
• JGROUPS_TRANSPORT_STACK：传输栈（udp/tcp，默认tcp）

OpenShift示例：

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

杂项配置

• 前端URL：KEYCLOAK_FRONTEND_URL设置固定前端基础URL
• 日志级别：KEYCLOAK_LOGLEVEL（Keycloak日志）和ROOT_LOGLEVEL（容器日志），支持DEBUG/INFO/WARN等
• 代理转发：PROXY_ADDRESS_FORWARDING=true启用代理环境支持
• TLS配置：挂载/etc/x509/https目录（含tls.crt和tls.key）自动配置HTTPS
• 指标：KEYCLOAK_STATISTICS=db,http启用数据库和HTTP指标

调试

启用Java调试：

bash
docker run -e DEBUG=true -e DEBUG_PORT='*:8787' -p 8080:8080 -p '8787:8787' jboss/keycloak

构建镜像

从GitHub仓库构建：

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

从自定义地址下载分发版：

bash
docker build --build-arg KEYCLOAK_DIST=http://example.com/keycloak.tar.gz .

Docker启停

支持docker start和docker stop，配置变更需创建新容器。