1 配置红帽构建的Keycloak
1.1 KeyCloak的配置
1.1.1 配置加载顺序
– 加载命令行参数，例如“–db-url=cliValue”
– 加载环境变量，例如“KC_DB_URL=envVarValue”
– 加载用户创建配置中定义的选项
– 加载配置文件“conf/keycloak.conf”，例如“db-url=confFileValue”
– 加载用户创建的Java KeyStore文件中定义的敏感选项，例如“kc.db-url=keystoreValue”
注：以上加载顺序，越靠前级别越高，例如命令参数优选于环境变量
1.1.2 配置格式
– 命令行格式，“–<key-with-dashes>=<value>”或者“-<abbreviation>=<value>”
– 环境变量格式，大写格式“KC_<key_with_underscores>=<value>”
– 配置文件格式，“<key-with-dashes>=<value>”
– KeyStore配置文件格式，“kc.<key-with-dashes><value>”
1.1.3 配置范例
#命令行参数 bin/kc.[sh|bat] start --db-url-host=mykeycloakdb #环境变量 export KC_DB_URL_HOST=mykeycloakdb #conf/keycloak.conf db-url-host=mykeycloakdb
1.1.4 环境变量的格式
bin/kc.[sh|bat] start --help
另外，你可以显式指定配置文件，
bin/kc.[sh|bat] --config-file=/path/to/myconfig.conf start
1.1.5 命令行参数的格式
db-url-host=${MY_DB_HOST}
另外，防止变量无法解析，你可以指定回退值，
db-url-host=${MY_DB_HOST:mydb}
1.1.6 使用Java KeyStore文件设置敏感选项
keytool -importpass -alias kc.db-password -keystore keystore.p12 -storepass keystorepass -storetype PKCS12 -v
需要注意的是，
– 执行命令后根据提示输入“kc.db-password”的设置值
– 值“kc.db-password”将使用“PBE”加密算法存储到“keystore.p12”中
然后，启动命令按如下方式调用，
bin/kc.[sh|bat] start --config-keystore=/path/to/keystore.p12 --config-keystore-password=storepass --config-keystore-type=PKCS12
1.1.7 raw Quarkus属性的格式
– Quarkus的属性可弥补红帽构建的Keycloak配置中缺少的特定行为或功能
– Quarkus的属性不受红帽的Keycloak支持
– 在“conf”目录中创建“quarkus.properties”
– 配置文件“quarkus.properties”中定义必要的属性
– 使用“[-cf|–config-file]”命令行参数引入“quarkus.properties”文件
详细请参阅文档，
https://quarkus.io/guides/all-config
https://github.com/keycloak/keycloak/blob/main/quarkus/runtime/pom.xml#L17
1.2 Keyclock启动方式
1.2.1 Keyclock启动命令
– 开发模式启动
– 生产模式启动
命令范例如下，
bin/kc.[sh|bat] start-dev bin/kc.[sh|bat] start
注：
– 如果且少设置，生产模式不会启动红帽构建的Keycloak并向你提示错误
– 生产模式需要设置主机名，并启动时使用HTTPS/TLS设置
生产模式的构建步骤请参阅，
https://docs.redhat.com/zh-cn/documentation/red_hat_build_of_keycloak/22.0/html-single/server_guide/index#configuration-production-
1.2.2 开发者模式的默认设置
– HTTP启动用
– 禁用严格的主机名解析
– 缓存设置为local（不用于高可用性的分布式缓存机制）
– 禁用主题缓存和模板缓存
1.2.3 生产模式的默认设置
– HTTP被禁用，因为传输层安全（HTTPS）至关重要
– 主机名配置是预期的
– 预期为HTTPS/TLS配置
– 默认情况下配置文件“conf/keycloak.conf”会被注解掉
1.3 创建Keycloak管理员
– Web Frontend创建Admin
– 环境变量创建,范例“KEYCLOAK_ADMIN=”和“KEYCLOAK_ADMIN_PASSWORD=”
注：管理员创建后才能使用“kcadm.[sh|bat]”工具
1.4 部署红帽显式构建Keycloak的步骤
1.4.1 执行显式构建
bin/kc.[sh|bat] build <build-options>
其他的构建选项，
https://docs.redhat.com/zh-cn/documentation/red_hat_build_of_keycloak/22.0/html-single/server_guide/index#all-config-
获取build的命令行帮助，
bin/kc.[sh|bat] build --help
构建范例，
bin/kc.[sh|bat] build --db=postgres
1.4.2 启动显式构建的Keycloak
bin/kc.[sh|bat] start --optimized <configuration-options>
1.4.2 部署显式构建的Keycloak范例步骤
Step1,使用 build 命令为 PostgreSQL 数据库供应商设置构建选项
bin/kc.[sh|bat] build --db=postgres
Step2,在“conf/keycloak.conf”文件中设置postgres的运行时配置选项。
db-url-host=keycloak-postgres db-username=keycloak db-password=change_me hostname=mykeycloak.acme.com https-certificate-file
Step3,使用优化参数启动服务器
bin/kc.[sh|bat] start --optimized
2 最佳实践
2.1 安装前的准备
2.1.1 准备KeyCloak的开发构建环境
2.1.2 准备数据库
然后，你需要使用如下命令创建KeyCloak所需的数据库，
mysql -uroot -p create database keycloak character set utf8; grant all privileges on keycloak.* to 'keycloak'@'localhost' identified by 'keycloakpwd'; grant all privileges on keycloak.* to 'keycloak'@'127.0.0.1' identified by 'keycloakpwd'; flush privileges;
2.2 配置KeyCloak
2.2.1 创建KeyCloak配置文件
cp vim /etc/keycloak/keycloak.conf vim /etc/keycloak/keycloak.conf.default vim /etc/keycloak/keycloak.conf
配置修改如下，
# Basic settings for running in production. Change accordingly before deploying the server. # Database db = mariadb db-username = keycloak db-password = keycloakpwd db-url = jdbc:mariadb://localhost:3306/keycloak?characterEncoding=UTF-8 # Observability health-enabled = true metrics-enabled = true # HTTP https-certificate-file = /etc/keycloak/wildcard.cmdschool.org.crt https-certificate-key-file = /etc/keycloak/wildcard.cmdschool.org.key # The proxy address forwarding mode if the server is behind a reverse proxy. #proxy = reencrypt # Uncomment to enable proxy forwarding mode # Do not attach route to cookies and rely on the session affinity capabilities from reverse proxy #spi-sticky-session-encoder-infinispan-should-attach-route = false # Uncomment to disable route attachment to cookies # Hostname for the Keycloak server. hostname = websso.cmdschool.org hostname-strict-backchannel = true hostname-admin = rhbk01.cmdschool.org # Logging configuration log = console,file log-level = INFO,org.hibernate:debug,org.hibernate.hql.internal.ast:info log-file = /var/log/keycloak/keycloak.log log-file-size = 10MB log-file-count = 20
需要注意的是，配置文件涉及如下证书，
/etc/keycloak/wildcard.cmdschool.org.crt /etc/keycloak/wildcard.cmdschool.org.key
证书可到腾讯云申请，详细请查阅下文，此处不再详述，
https://cloud.tencent.com/product/ssl
根据配置的需求，你可能需要手动创建日志目录，并设置相应的权限，
mkdir -p /var/log/keycloak/ chown keycloak:keycloak /var/log/keycloak/
2.2.2 构建KeyCloak生产环境
sudo -u keycloak bash -c '/opt/keycloak/rhbk-22.0.13/bin/kc.sh build --db=mariadb'
2.2.3 测试KeyCloak启动
sudo -u keycloak bash -c 'export KEYCLOAK_ADMIN=admin;export KEYCLOAK_ADMIN_PASSWORD=adminpwd;/opt/keycloak/rhbk-22.0.13/bin/kc.sh start'
命令行解析如下，
– 使用“export”生命环境变量“KEYCLOAK_ADMIN=admin”和“KEYCLOAK_ADMIN_PASSWORD=adminpwd”
– 使用命令行“/opt/keycloak/rhbk-22.0.13/bin/kc.sh start”启动服务
如果遇到如下错误提示，可以不予理会，下次启动实例数据表准备好将不会再提示，
2025-07-16 04:42:17,247 WARN [org.mariadb.jdbc.message.server.ErrorPacket] (main) Error: 1146-42S02: Table 'keycloak.MIGRATION_MODEL' doesn't exist 2025-07-16 04:42:19,392 WARN [org.mariadb.jdbc.message.server.ErrorPacket] (main) Error: 1146-42S02: Table 'keycloak.DATABASECHANGELOG' doesn't exist
当你看到如下提示，
2025-07-16 04:50:48,115 INFO [io.quarkus] (main) Keycloak 22.0.13.redhat-00001 on JVM (powered by Quarkus 3.2.12.Final-redhat-00001) started in 6.459s. Listening on: https://0.0.0.0:8443
你可能需要执行如下命令允许该端口被访问，
firewall-cmd --permanent --add-port 8443/tcp firewall-cmd --reload firewall-cmd --list-all
2.2.4 创建服务控制脚本
vim /etc/systemd/system/keycloak.service
加入如下配置，
[Unit] Description=Redhat build of Keycloak (RHBK) Requires=network.target After=syslog.target network.target [Service] Type=simple User=keycloak Group=keycloak WorkingDirectory=/opt/keycloak/rhbk-22.0.13 Environment="KEYCLOAK_ADMIN=admin" Environment="KEYCLOAK_ADMIN_PASSWORD=adminpwd" ExecStart=/usr/bin/bash -c '/opt/keycloak/rhbk-22.0.13/bin/kc.sh start' Restart=on-failure StandardOutput=journal LimitNOFILE=102642 [Install] WantedBy=multi-user.target
配置创建后，你需要使用如下命令重载服务使配置生效，
systemctl daemon-reload
测试服务启动并设置自动运行，
systemctl start keycloak.service systemctl enable keycloak.service
如果遇到启动异常，请使用如下命令查看日志，
tail -f /var/log/keycloak/keycloak.log journalctl -u keycloak.service -b
2.2.5 测试KeyCloak服务
客户端访问需要名称解析(DNS)的支持，测试环境需要访问KeyCloak的电脑客户端，可使用如下命令设置测试环境，
echo 'rhbk01.cmdschool.org' >> /etc/hosts echo 'websso.cmdschool.org' >> /etc/hosts
然后，在浏览器使用如下连接测试，
https://rhbk01.cmdschool.org:8443/
另外，如下连接支持查看健康状态(由配置参数health-enabled开启)，
https://rhbk01.cmdschool.org:8443/health
https://rhbk01.cmdschool.org:8443/health/live
https://rhbk01.cmdschool.org:8443/health/ready
另外，如下页面支持查询公开的指标(由配置参数metrics-enabled开启)，
https://rhbk01.cmdschool.org:8443/metrics
参阅文档
=================
RHBK配置文档
——————–
https://docs.redhat.com/en/documentation/red_hat_build_of_keycloak/22.0/html-single/server_guide/index
KeyCloak配置文档
———————-
https://www.keycloak.org/server/configuration
反向代理设置
———–
https://docs.redhat.com/zh-cn/documentation/red_hat_build_of_keycloak/22.0/html-single/server_guide/index#reverseproxy-
集群数据库锁设置
—————
https://docs.redhat.com/zh-cn/documentation/red_hat_build_of_keycloak/22.0/html-single/server_guide/index#db-changing-database-locking-timeout-in-a-cluster-configuration
没有评论