kyberpunk/keycloak

ARM64架构的Keycloak Docker镜像

为ARM设备（如树莓派4）预构建的Keycloak服务器Docker镜像。描述内容基于官方Keycloak镜像：https://hub.docker.com/r/jboss/keycloak%E3%80%82

版本 >= 17.0.0 及 latest 标签请遵循新指南：[*] legacy 标签。**

使用方法

独立模式启动

bash
docker run kyberpunk/keycloak

暴露到本地主机

要在本地访问Keycloak，需映射8080端口：

bash
docker run -p 8080:8080 kyberpunk/keycloak

创建管理员账户

默认未创建管理员用户，无法登录管理控制台。需通过环境变量设置初始用户名和密码：

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

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

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

然后重启容器：

bash
docker restart <容器ID>

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

在上述两个环境变量后添加 _FILE（即 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 kyberpunk/keycloak

导出领域

如需导出已创建/更新的领域，需确保容器已挂载卷。例如，启动Keycloak：

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

执行导出命令（使用 -Djboss.socket.binding.port-offset=100 避免端口冲突）：

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官方文档：导出与导入。

数据库支持

支持H2、MySQL、PostgreSQL、MariaDB、Oracle或Microsoft SQL Server作为数据库。可通过 DB_VENDOR 环境变量指定数据库类型，支持值：

• h2：嵌入式H2数据库
• postgres：PostgreSQL数据库
• mysql：MySQL数据库
• mariadb：MariaDB数据库
• oracle：Oracle数据库
• mssql：Microsoft SQL Server数据库

若未指定 DB_VENDOR，镜像将自动检测：

• 通过 getent hosts 检测默认主机名（postgres、mysql等，需使用用户定义网络）
• 检测数据库特定的 _ADDR 环境变量（如 POSTGRES_ADDR，已弃用）

检测失败时默认使用嵌入式H2数据库。

环境变量

通用数据库配置变量（默认值因数据库而异）：

• DB_ADDR：数据库主机名（可选，PostgreSQL支持逗号分隔的多主机故障转移）
• DB_PORT：数据库端口（可选，默认使用数据库默认端口）
• DB_DATABASE：数据库名称（可选，默认 keycloak）
• DB_SCHEMA：数据库模式名称（可选，PostgreSQL默认 public）
• DB_USER：数据库用户名（可选，默认空）
• DB_USER_FILE：通过文件指定数据库用户名（替代 DB_USER）
• DB_PASSWORD：数据库密码（可选，默认空）
• DB_PASSWORD_FILE：通过文件指定数据库密码（替代 DB_PASSWORD）

MySQL示例

创建用户定义网络

bash
docker network create keycloak-network

启动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

启动Keycloak实例

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

若MySQL实例名称非 mysql，需指定 DB_ADDR 环境变量。

PostgreSQL示例

创建用户定义网络

bash
docker network create keycloak-network

启动PostgreSQL实例

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

启动Keycloak实例

bash
docker run --name keycloak --net keycloak-network kyberpunk/keycloak -e DB_USER=keycloak -e DB_PASSWORD=password

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

MariaDB示例

创建用户定义网络

bash
docker network create keycloak-network

启动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

启动Keycloak实例

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

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

Oracle示例

需提供Oracle JDBC驱动。

下载Oracle JDBC驱动

1. 下载对应Oracle版本的JDBC驱动
2. 重命名文件为 ojdbc.jar

创建用户定义网络

bash
docker network create keycloak-network

启动Oracle实例

bash
docker run -d --name oracle --net keycloak-network -p 1521:1521 carloscastillo/rgt-oracle-xe-11g

启动Keycloak实例

bash
docker run -d --name keycloak --net keycloak-network -p 8080:8080 -v /path/to/jdbc/driver:/opt/jboss/keycloak/modules/system/layers/base/com/oracle/jdbc/main/driver kyberpunk/keycloak

或通过 docker cp 复制驱动：

bash
docker cp ojdbc.jar kyberpunk/keycloak:/opt/jboss/keycloak/modules/system/layers/base/com/oracle/jdbc/main/driver/ojdbc.jar

默认环境配置：

• DB_ADDR: oracle
• DB_PORT: 1521
• DB_DATABASE: XE
• DB_USER: SYSTEM
• DB_PASSWORD: oracle

Microsoft SQL Server示例

创建用户定义网络

bash
docker network create keycloak-network

启动SQL Server实例

bash
docker run -e 'ACCEPT_EULA=Y' -e 'SA_PASSWORD=Password!23' -d --name mssql --net keycloak-network mcr.microsoft.com/mssql/server

创建数据库（SQL Server不支持环境变量创建数据库）：

bash
docker run -d --name mssql-scripts --net keycloak-network mcr.microsoft.com/mssql-tools /bin/bash -c 'until /opt/mssql-tools/bin/sqlcmd -S mssql -U sa -P "Password!23" -Q "create database Keycloak"; do sleep 5; done'

启动Keycloak实例

bash
docker run --name keycloak --net keycloak-network -p 8080:8080 -e DB_VENDOR=mssql -e DB_USER=sa -e DB_PASSWORD=Password!23 -e DB_ADDR=mssql -e DB_DATABASE=Keycloak -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin kyberpunk/keycloak

指定JDBC参数

可通过 JDBC_PARAMS 环境变量指定JDBC连接参数，例如：

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

各数据库JDBC参数详情：

• PostgreSQL
• MySQL
• MariaDB
• Oracle
• Microsoft SQL Server

添加自定义主题

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

环境变量配置：

• KEYCLOAK_WELCOME_THEME：欢迎页主题（需存在）
• KEYCLOAK_DEFAULT_THEME：全局默认主题（默认 keycloak）

添加自定义提供程序

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

启动时运行自定义脚本

在 /opt/jboss/startup-scripts 目录放置脚本，支持：

• WildFly .cli 脚本（建议使用离线模式，默认使用 standalone-ha.xml 配置）
• 可执行脚本（需 chmod +x）

脚本按字母顺序执行。

通过Dockerfile添加脚本

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

通过卷挂载脚本

bash
docker run -v /some/dir/my-script.cli:/opt/jboss/startup-scripts/my-script.cli kyberpunk/keycloak

使用自定义命令行选项启动

通过 JAVA_OPTS_APPEND 环境变量添加JVM启动参数，例如启用 upload_script 特性：

bash
docker run -e JAVA_OPTS_APPEND="-Dkeycloak.profile.feature.upload_scripts=enabled" kyberpunk/keycloak

集群

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

• JGROUPS_DISCOVERY_PROTOCOL：发现协议名称（如 dns.DNS_PING）
• JGROUPS_DISCOVERY_PROPERTIES：协议属性（格式 PROP1=FOO,PROP2=BAR）
• JGROUPS_DISCOVERY_PROPERTIES_DIRECT：JBoss CLI格式属性（格式 {PROP1=>FOO,PROP2=>BAR}）
• JGROUPS_TRANSPORT_STACK：传输栈（udp 或 tcp，默认 tcp）

注意：JGROUPS_DISCOVERY_PROPERTIES 和 JGROUPS_DISCOVERY_PROPERTIES_DIRECT 不可同时设置。

PING示例（默认）

bash
docker run kyberpunk/keycloak

OpenShift DNS_PING示例

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

分布式缓存所有者

• CACHE_OWNERS_COUNT：分布式缓存所有者数量（默认1）
• CACHE_OWNERS_AUTH_SESSIONS_COUNT：AuthenticationSessions副本数量（默认不复制）

Vault

Kubernetes/OpenShift文件明文Vault

将密钥文件挂载到 $JBOSS_HOME/secrets 目录，用于消费Kubernetes/OpenShift集群密钥。

杂项

指定前端基础URL

bash
docker run -e KEYCLOAK_FRONTEND_URL=https://keycloak.example.com kyberpunk/keycloak

指定日志级别

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

支持级别：ALL、DEBUG、ERROR、FATAL、INFO、OFF、TRACE、WARN。

运行时修改日志级别：

bash
./keycloak/bin/jboss-cli.sh --connect --command='/subsystem=logging/console-handler=CONSOLE:change-log-level(level=DEBUG)'
./keycloak/bin/jboss-cli.sh --connect --command='/subsystem=logging/root-logger=ROOT:change-root-log-level(level=DEBUG)'
./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 kyberpunk/keycloak

设置TLS(SSL)

挂载TLS证书和私钥到 /etc/x509/https 目录（文件名为 tls.crt 和 tls.key）。

添加CA证书：挂载CA文件并设置 X509_CA_BUNDLE 环境变量（空格分隔路径）。

启用指标

通过 KEYCLOAK_STATISTICS 环境变量启用指标（db、http、jgroups 或 all）：

bash
docker run -e KEYCLOAK_STATISTICS=db,http kyberpunk/keycloak

调试

设置环境变量启用Java调试：

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

其他细节

基于 registry.access.redhat.com/ubi8-minimal 基础镜像构建。

从不同来源构建镜像

从GitHub仓库构建

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

从替代位置下载Keycloak

bash
docker build --build-arg KEYCLOAK_DIST=http://172.17.0.1:8000/keycloak-4.1.0.Final-SNAPSHOT.tar.gz .

Docker启动和停止

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