Keycloak 配置参数详解

kc.sh 子命令与 KC_* 环境变量逐参数详解：官方默认值、生效实测回显与生产配置模板。

KeycloakKeycloak2026/10/17

Keycloak 配置参数详解

‍‍​​‌​> 目标：逐参数讲清 Keycloak 26.8.1 的 kc.sh 子命令体系与 KC_* 环境变量（数据库、主机名、HTTP、代理、TLS、管理员引导、可观测七类），每个关键参数均给出官方默认值与真实生效回显，并还原生产模式启动的三步排障实录，全部在 Ubuntu 22.04 服务器实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04（x86_64）
  • Keycloak：26.8.1，安装目录 /opt/keycloak（官方 tar.gz 解压安装，二进制入口 /opt/keycloak/bin/kc.sh）
  • Java：OpenJDK 21.0.12.1+1-LTS（Keycloak 26 要求 JDK 21）
  • 默认端口：8080（HTTP）、8443（HTTPS）、9000（管理与指标接口）
  • 数据目录：/opt/keycloak/data

二、前置条件

2.1 安装与版本确认

Keycloak 26.x 发行物自带优化运行时，无需单独安装应用服务器，只需 JDK 21。官方下载地址形如 https://github.com/keycloak/keycloak/releases/download/26.8.1/keycloak-26.8.1.tar.gz（约 166MB），解压到 /opt/keycloak 后即可使用。确认安装与版本：

/opt/keycloak/bin/kc.sh --version

实测回显：

Keycloak 26.8.1
JVM: 21.0.12.1 (Red Hat, Inc. OpenJDK 64-Bit Server VM 21.0.12.1+1-LTS)
OS: Linux 6.8.0-138-generic amd64

2.2 参数的三种配置途径与优先级

同一参数有三处可配，优先级从高到低为：命令行参数 → 环境变量 → keycloak.conf 配置文件。三者只是书写形态不同，参数本体一致：

途径书写形态示例（HTTP 端口）适用
命令行参数--<小写连字符>kc.sh start --http-port=8081一次性覆盖
环境变量KC_ + 下划线大写KC_HTTP_PORT=8081服务托管、编排文件
配置文件小写连字符键值http-port=8081（conf/keycloak.conf）固定部署

💡 说明：环境变量名规则是 --http-port 去掉两个横线、下划线连接并全大写，即 KC_HTTP_PORT；--db-url 对应 KC_DB_URL。本篇后续每个参数都同时给出两种形态。

三、参数查看与修改方式

3.1 用 --help 查看参数与默认值

查看某个子命令的完整参数与官方默认值（以 start 为例，全文 729 行，此处节选）：

/opt/keycloak/bin/kc.sh start --help

实测回显（节选）：

--db <vendor>        The database vendor. In production mode the default value of 'dev-file' is
                       deprecated, you should explicitly specify the db instead. Possible values
                       are: dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres, tidb.
                       Default: dev-file.
--db-connect-timeout <timeout>
                     Sets the JDBC driver connection timeout and login timeout. May be an ISO 8601
                       duration value, an integer number of seconds, or an integer followed by one
                       of [ms, h, m, s, d]. Default: 10s.

💡 说明：--help 是默认值的唯一权威来源——help 里写 Default: 的就是当前版本真实默认值，不随文档记忆漂移。开发模式（start-dev）与生产模式（start）可用的参数集合不同，分别用 start-dev --help 与 start --help 查看。

3.2 用 show-config 查看当前生效配置

/opt/keycloak/bin/kc.sh show-config

实测回显（节选）：

Current Mode: production
Current Configuration:
        kc.log-console-output =  default (classpath application.properties)
        kc.version =  26.8.1 (SysPropConfigSource)
        kc.log-file =  /opt/keycloak/bin/../data/log/keycloak.log (classpath application.properties)

逐行解读：Current Mode 显示当前按开发/生产哪种模式解析（直接运行 show-config 默认按 production 解析）；每行末尾括号标注该值来自哪个配置源（classpath application.properties 为内置默认、ENV 为环境变量、SysPropConfigSource 为系统属性）。排障时先用它确认"我设置的值到底生效没有"。

四、kc.sh 子命令总览

/opt/keycloak/bin/kc.sh --help

实测回显（节选，命令清单部分）：

Commands:

  build                   Creates a new and optimized server image.
  start                   Start the server.
  start-dev               Start the server in development mode.
  export                  Export data from realms to a file or directory.
  import                  Import data from a directory or a file.
  show-config             Print out the current configuration.
  tools                   Utilities for use and interaction with the server.
    completion            Generate bash/zsh completion script for kc.sh.
    build-password-denylist
                          Pre-compute a Bloom filter for a password denylist.
  bootstrap-admin         Commands for bootstrapping admin access
    user                  Add an admin user with a password
    service               Add an admin service account
  update-compatibility    [Preview] Tool for configuration compatibility.
    check                 Checks if the metadata is compatible with the current
                            configuration. A zero exit code means a rolling
                            update is possible between old and the current
                            metadata.
    metadata              Stores the metadata necessary to determine if a
                            configuration is compatible.

逐个说明日常使用频率最高的五个子命令：start-dev（开发模式启动，跳过 hostname/TLS 约束，H2 内存/文件库）、start（生产模式启动，强制完整配置）、build（预编译优化运行时，配合 start --optimized 缩短启动时间）、export/import（域数据导出导入，迁移与备份用）。下面给出 export/import 的实测形态。

4.1 export：导出域数据

/opt/keycloak/bin/kc.sh export --dir /tmp/kc-export

实测回显（节选）：

2026-10-17 09:25:40,244 INFO  [org.keycloak.services] (main) KC-SERVICES0033: Full model export requested
2026-10-17 09:25:40,539 INFO  [org.keycloak.exportimport.dir.DirExportProvider] (main) Exporting into directory /tmp/kc-export
2026-10-17 09:25:40,575 INFO  [org.keycloak.exportimport.dir.DirExportProvider] (main) Realm 'quzuo-demo' - data exported
2026-10-17 09:25:40,741 INFO  [org.keycloak.exportimport.dir.DirExportProvider] (main) Realm 'master' - data exported
2026-10-17 09:25:40,782 INFO  [org.keycloak.exportimport.dir.DirExportProvider] (main) Users 0 - 0 exported
2026-10-17 09:25:40,787 INFO  [org.keycloak.services] (main) KC-SERVICES0035: Export finished successfully

导出产物为每域一个 JSON：

-rw-r--r-- 1 keycloak root 86243 Oct 17 09:25 master-realm.json
-rw-r--r-- 1 keycloak root   981 Oct 17 09:25 master-users-0.json
-rw-r--r-- 1 keycloak root 79044 Oct 17 09:25 quzuo-demo-realm.json

4.2 import：启动时导入域数据

把导出的 quzuo-demo-realm.json 放入 <安装目录>/data/import/，启动时追加 --import-realm：

/opt/keycloak/bin/kc.sh start-dev --import-realm

实测回显（节选）：

INFO  [org.keycloak.exportimport.dir.DirImportProvider] (main) Importing from directory /opt/keycloak/bin/../data/import
INFO  [org.keycloak.services] (main) KC-SERVICES0030: Full model import requested. Strategy: IGNORE_EXISTING
INFO  [org.keycloak.exportimport.util.ImportUtils] (main) Realm 'quzuo-demo' imported
INFO  [org.keycloak.services] (main) KC-SERVICES0032: Import finished successfully

💡 说明：导入策略为 IGNORE_EXISTING——同名域已存在时跳过不覆盖，所以该方式适合初始化新环境，不适合更新既有域。

五、核心参数分类详解

5.1 数据库类：KC_DB / KC_DB_URL / KC_DB_USERNAME / KC_DB_PASSWORD

Keycloak 开箱使用 H2 文件库（仅适合开发），生产必须换关系库。--help 实测的官方说明：--db 可选值为 dev-file, dev-mem, mariadb, mssql, mysql, oracle, postgres, tidb，生产模式默认值 dev-file 已废弃、必须显式指定；JDBC 连接超时 --db-connect-timeout 默认 10s。PostgreSQL 形态的环境变量写法：

export KC_DB=postgres
export KC_DB_URL="jdbc:postgresql://localhost:5432/keycloak"
export KC_DB_USERNAME=keycloak
export KC_DB_PASSWORD=q1w2e3r4

💡 技术拓展：KC_DB_URL 与四要素简化写法的取舍——

写法说明适用
仅 KC_DB + KC_DB_USERNAME/PASSWORDKeycloak 按默认规则拼 JDBC URL库名/端口符合默认（keycloak@5432）
显式 KC_DB_URL完整控制主机/端口/库名/连接参数非默认端口、需要 SSL/连接池参数
KC_DB_SCHEMA指定 schema（默认 public）多组件共用一个库时

生产推荐显式 KC_DB_URL，把 ?ssl=true 等连接参数的控制权留在自己手里。

5.2 主机名类：KC_HOSTNAME / KC_HOSTNAME_STRICT（Hostname v2）

26.x 默认启用 Hostname v2。--help 实测原文：--hostname 接受完整 URL 或仅主机名，是服务对外暴露地址的基准（token 的 issuer、前端 URL、回调校验都由它派生）；--hostname-strict 默认 true，禁止从请求头动态推断主机名。生产模式不配 hostname 会被直接拒绝启动：

ERROR: Failed to start server in (production) mode
ERROR: hostname is not configured; either configure hostname, or set hostname-strict to false

⚠️ 注意：旧版本的 hostname-strict-https 参数在 Hostname v2 下已被取代，不要照抄旧文档；若确需 HTTP 访问，用 5.3 节的 KC_HTTP_ENABLED=true，并确保 TLS 终结在代理层。

5.3 HTTP 与端口：KC_HTTP_ENABLED / KC_HTTP_PORT / KC_HTTP_HOST

--help 实测原文：--http-enabled 生产模式默认 false（"Enabled by default in development mode. Typically not enabled in production unless the server is fronted by a TLS termination proxy"）；--http-port 默认 8080；--http-host 生产模式默认绑定 0.0.0.0。

KC_HTTP_PORT 生效实测（改为 8081 启动后验证监听与访问）：

KC_HTTP_PORT=8081 /opt/keycloak/bin/kc.sh start-dev

实测回显：

2026-10-17 09:20:17,696 INFO  [io.quarkus] (main) Keycloak 26.8.1 on JVM (powered by Quarkus 3.40.1) started in 10.484s. Listening on: http://0.0.0.0:8081

curl -s -o /dev/null -w 'localhost:8081 → HTTP %{http_code}\n' http://localhost:8081/

实测回显：

localhost:8081 → HTTP 302

⚠️ 注意：KC_HTTP_ENABLED=true 只在"HTTPS 由前置代理终结"的部署中开启；裸暴露 HTTP 的生产 Keycloak 会因缺少安全上下文导致部分功能（如跨域 Cookie）异常，启动日志中也会给出 insecure context 警告。

5.4 代理类：KC_PROXY_HEADERS（KC_PROXY 已废弃）

反向代理场景必须让 Keycloak 正确解析 X-Forwarded-*/Forwarded 头，否则生成的 issuer/回调地址会变成代理的内网地址。--help 实测原文：

--proxy-headers <headers>
                     The proxy headers that should be accepted by the server. Misconfiguration
                       might leave the server exposed to security vulnerabilities. Takes precedence
                       over the deprecated proxy option. Possible values are: forwarded, xforwarded.

💡 技术拓展：两种代理头标准对比——

方案头格式采用方
xforwardedX-Forwarded-For/Proto/Host/Port 一组头Nginx/Apache/绝大多数代理（常用）
forwarded单一 Forwarded 头携带全部信息较新代理与网关

旧参数 KC_PROXY（edge/repackage/passthrough 三值）已废弃，被 KC_PROXY_HEADERS 取代；升级部署时务必替换，否则新版本会忽略旧变量。

5.5 TLS 证书：KC_HTTPS_CERTIFICATE_FILE / KC_HTTPS_CERTIFICATE_KEY_FILE

不经过代理直接对外提供 HTTPS 时，配置 PEM 格式证书与私钥：

export KC_HTTPS_CERTIFICATE_FILE=/opt/keycloak/conf/tls/fullchain.pem
export KC_HTTPS_CERTIFICATE_KEY_FILE=/opt/keycloak/conf/tls/privkey.pem

配套参数 --https-certificates-reload-period 默认 1h（证书文件变更后的小时级自动重载，设 -1 关闭）。配好证书后不再需要 KC_HTTP_ENABLED，Keycloak 直接以 HTTPS 监听。

5.6 管理员引导：KC_BOOTSTRAP_ADMIN_USERNAME / KC_BOOTSTRAP_ADMIN_PASSWORD

首启创建 master 域临时管理员的标准方式（环境变量与 --bootstrap-admin-username/--bootstrap-admin-password 等价）：

export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD=q1w2e3r4

--help 实测原文注明该用户"仅在 master realm 创建时生效"（Used only when the master realm is created），此后改这两个变量不会再改密码。不设置这两个变量时实测启动日志中不会出现任何 admin 相关创建记录，首次登录管理台前需用交互式子命令补建：

/opt/keycloak/bin/kc.sh bootstrap-admin user

按提示输入用户名与密码即可（也支持 bootstrap-admin service 创建服务账号形态的管理凭据）。

5.7 可观测：KC_HEALTH_ENABLED / KC_METRICS_ENABLED

两者默认均为 false。开启后 Keycloak 在独立管理端口（默认 9000）暴露 /health 与 /metrics，供负载均衡探活与监控抓取，不占用 8080 业务端口。验证形态：

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:9000/health

💡 说明：健康检查与业务端口分离是 25.x 起的默认设计，负载均衡的健康探测应指向 9000 而非 8080。

六、生产配置模板

6.1 推荐配置（PostgreSQL + 代理终结 TLS，8GB 内存服务器适用）

写入 /opt/keycloak/conf/keycloak.conf（等价的环境变量形态见右侧注释）：

# 数据库（等价 KC_DB / KC_DB_URL / KC_DB_USERNAME / KC_DB_PASSWORD）
db=postgres
db-url=jdbc:postgresql://localhost:5432/keycloak
db-username=keycloak
db-password=q1w2e3r4
# 主机名（等价 KC_HOSTNAME）
hostname=sso.quzuo.net
# HTTPS 证书（等价 KC_HTTPS_CERTIFICATE_FILE / KC_HTTPS_CERTIFICATE_KEY_FILE）
https-certificate-file=/opt/keycloak/conf/tls/fullchain.pem
https-certificate-key-file=/opt/keycloak/conf/tls/privkey.pem
# 健康检查（等价 KC_HEALTH_ENABLED / KC_METRICS_ENABLED）
health-enabled=true
metrics-enabled=true

适用场景：单机或主备形态、PostgreSQL 独立部署、前端有 Nginx/负载均衡终结 TLS；磁盘预留 20GB 以上（日志 + 库空间另计）。

6.2 生产启动三步排障实录

生产模式启动对配置完整性有硬校验，以下三步是真实排障路径，读者按报错逐层补配置即可：

第 1 步：只给数据库配置启动 → 报缺 HTTPS 证书或 http-enabled。

WARNING: With HTTPS not enabled, `proxy-headers` unset, and `hostname-strict=false`, the server is running in an insecure context. ...
Key material not provided to setup HTTPS. Please configure your keys/certificates, or if HTTPS access is not needed see the `http-enabled` option. If you meant to start the server in development mode, see the `start-dev` command.

第 2 步：加了 KC_HTTP_ENABLED=true 但未配 hostname → 报 hostname 缺失。

ERROR: Failed to start server in (production) mode
ERROR: hostname is not configured; either configure hostname, or set hostname-strict to false

第 3 步：补齐 KC_HOSTNAME 后启动成功。

2026-10-17 09:15:45,276 INFO  [io.quarkus] (main) Keycloak 26.8.1 on JVM (powered by Quarkus 3.40.1) started in 15.919s. Listening on: http://0.0.0.0:8080

curl -s -o /dev/null -w 'HTTP %{http_code}\n' http://localhost:8080/realms/master/.well-known/openid-configuration

实测回显：

HTTP 200

6.3 build + --optimized：生产启动提速

start 默认每次启动前自动执行一次 build 校验配置变更；固定配置的机器可预先 build 一次，之后用 --optimized 跳过该步骤显著缩短启动时间。build 实测：

KC_DB=postgres KC_DB_URL='jdbc:postgresql://db:5432/keycloak' \
KC_DB_USERNAME=keycloak KC_DB_PASSWORD=q1w2e3r4 \
/opt/keycloak/bin/kc.sh build

实测回显：

Server configuration updated and persisted. Run the following command to review the configuration:

        kc.sh show-config

之后启动：

/opt/keycloak/bin/kc.sh start --optimized

--help 实测原文同时提醒：build 之后若再改配置，需重新 build，否则新配置不会生效——这是 --optimized 唯一的坑。

七、常见问题

Q1：启动直接报 hostname is not configured？ 见 6.2 第 2 步实录。生产模式必须配置 KC_HOSTNAME（或显式 hostname-strict=false，不推荐），它同时决定 token issuer 与前端地址，不要留空。

Q2：报 Key material not provided to setup HTTPS？ 生产模式默认要求 TLS：要么配 5.5 节的证书，要么确认 TLS 由前置代理终结并显式设置 KC_HTTP_ENABLED=true（6.2 第 1 步实录）。开发验证环境直接用 start-dev。

Q3：设置了 KC_BOOTSTRAP_ADMIN_ 但没生效？* 该变量只在 master 域首次创建时起作用（5.6 节 help 原文）。库中已有 master 域后要重置管理员密码，走 Admin API 的 reset-password 或 kc.sh bootstrap-admin user 交互命令。

Q4：改了参数但不生效？ 按优先级排查：命令行参数 > 环境变量 > keycloak.conf；再确认是否用了 --optimized 启动（改配置后必须重新 kc.sh build）；最后用 kc.sh show-config 直接查看生效值与其来源（3.2 节）。

Q5：start 与 start-dev 的行为差异记不住？ 记两条硬边界：start-dev 默认开 HTTP、免 hostname、免证书、H2 存储；start 全部反向硬校验（hostname、HTTPS 或 http-enabled、必须指定真实数据库）。任何"生产可跑但 dev 跑不起来"的问题基本都是 dev 少了管理凭据变量（5.6）。

八、参考链接