Keycloak 开源身份认证与访问管理平台部署详解

目标：在 Ubuntu 22.04 上从零到一部署 Keycloak（开源 IAM），完成官方发行版下载解压、JVM 内存管控、启动（开发模式）、curl/CLI 验证与 realm/客户端创建，并沉淀 kc.sh 与 kcadm.sh 速查。本文在 Ubuntu 22.04（Keycloak 26.8.0）真实实测，命令与回显逐行来自实测。

环境信息

系统：Ubuntu 22.04 LTS（x86_64）
软件：Keycloak 26.8.0（Quarkus 3.40.1 运行时）
JDK：OpenJDK 17.0.20.1
安装目录：/opt/keycloak
启动脚本：/opt/keycloak/bin/kc.sh、管理 CLI：/opt/keycloak/bin/kcadm.sh
开发模式端口：http://127.0.0.1:8080
开发模式内置数据库：H2（jdbc:h2）
管理员：admin（示例口令 q1w2e3r4，通过引导环境变量注入）
服务名：keycloak

一、安装 Keycloak

1.1 安装 JDK 依赖

Keycloak 26 需要 JDK 17。

sudo apt update
sudo apt install -y openjdk-17-jre-headless wget
sudo update-alternatives --set java /usr/lib/jvm/java-17-openjdk-amd64/bin/java

验证：

java -version

实测回显：

openjdk version "17.0.20.1" 2026-08-18
OpenJDK Runtime Environment (build 17.0.20.1+1-1-22.04-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.20.1+1-1-22.04-Ubuntu, mixed mode, sharing)

1.2 下载官方 tar.gz 并解压

使用 GitHub Releases 的 keycloak-26.8.0.tar.gz：

cd /opt
sudo wget https://github.com/keycloak/keycloak/releases/download/26.8.0/keycloak-26.8.0.tar.gz
sudo tar xzf keycloak-26.8.0.tar.gz
sudo mv keycloak-26.8.0 keycloak

解压后校验 bin 目录：

ls /opt/keycloak/bin

实测回显：

client
federation-sssd-setup.sh
kc.bat
kc.sh
kcadm.bat
kcadm.sh
kcreg.bat
kcreg.sh

💡 kc.sh/kcadm.sh 是 Linux 主脚本；.bat 为 Windows 版本。keycloak 的版本会持续更新，下载前先查最新 tag：curl -s https://api.github.com/repos/keycloak/keycloak/releases/latest。

⚠️ 首次启动前 Keycloak 需要先执行 build 完成优化（kc.sh build）。start-dev 会自动按需构建，为便于首跑，本文用 start-dev；生产部署见第 2 节 systemd（start）。

二、配置与启动

2.1 引导管理员账号（18+ 版本机制）

Keycloak 26 不再从配置文件读取明文 admin 初始密码，而是通过环境变量引导：

export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD=q1w2e3r4

⚠️ 记录该输出：若不设置上述变量，首次启动会由系统自动生成一个临时 admin 初始密码并打印在控制台，请务必记下用于首次登录。手动设置后请按环境泄漏风险管理该口令。

2.2 限制 JVM 堆内存（专项）

Keycloak 是 Java 进程，kc.sh 通过 JAVA_OPTS_KC_HEAP 控制堆大小，默认环境为 -Xms64m -Xmx512m：

export JAVA_OPTS_KC_HEAP="-Xms256m -Xmx256m"

💡 安装文档要求把 Java 组件堆限制在 256–512MB。如需额外 JVM 参数（如 GC、该组件特有的 System 属性），用 export JAVA_OPTS_APPEND="-Dquarkus.http.port=8081" 这类方式追加。启动脚本中的相关逻辑位于 /opt/keycloak/bin/kc.sh 的 89–134 行（默认堆段在 96–102 行，非零时走 JAVA_OPTS_KC_HEAP already set in environment; overriding default settings）。

2.3 开发模式启动（前台，先验证）

cd /opt/keycloak/bin
./kc.sh start-dev --http-port 8080

启动关键回显：

Running the server in development mode. DO NOT use this configuration in production.
...
INFO  [org.keycloak.services.resources.KeycloakApplication] (main) Bootstrap completed in 2.657000 seconds
INFO  [io.quarkus] (main) Keycloak 26.8.0 on JVM (powered by Quarkus 3.40.1) started in 8.690s. Listening on: http://localhost:8080
INFO  [io.quarkus] (main) Installed features: [agroal, cdi, hibernate-orm, jdbc-h2, keycloak, narayana-jta, opentelemetry, rest, rest-jackson, smallrye-context-propagation, vertx]

⚠️ start-dev 仅用于开发/测试，使用 H2 内存数据库且不开启 HTTPS，不可用于生产。

2.4 实测确认 JVM 内存生效

另开一个会话，用 ps 抓取真实生效的堆参数：

ps -ef | grep [k]eycloak | grep -oE "\-Xm[sx][0-9]+m" | sort -u

实测回显：

-Xms256m
-Xmx256m

💡 看到 -Xms256m -Xmx256m 即说明 2.2 的内存限制已生效；若仍显示默认的 -Xmx512m，检查 JAVA_OPTS_KC_HEAP 是否在 kc.sh 所在进程前正确导出。

2.5 systemd 托管（生产推荐，start 模式）

编辑 /etc/systemd/system/keycloak.service：

[Unit]
Description=Keycloak Identity and Access Management
After=network-online.target

[Service]
User=root
Environment=KC_BOOTSTRAP_ADMIN_USERNAME=admin
Environment=KC_BOOTSTRAP_ADMIN_PASSWORD=q1w2e3r4
Environment=JAVA_OPTS_KC_HEAP=-Xms256m -Xmx256m
WorkingDirectory=/opt/keycloak
ExecStart=/opt/keycloak/bin/kc.sh start --http-port 8080 --hostname-strict=false
Restart=always

[Install]
WantedBy=multi-user.target

💡 Environment= 每行仅声明一个变量。生产建议改用外部数据库（--db postgres 等）并关闭 --hostname-strict=false 的宽松校验；此处为单机起点配置。

启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable keycloak
sudo systemctl start keycloak

状态确认：

sudo systemctl is-active keycloak

2.6 验证 realm 配置端点（curl）

server 起来后可直接访问 master realm 的配置 JSON：

curl -s http://127.0.0.1:8080/realms/master | head -c 300

实测回显（节选）：

{"realm":"master","public_key":"MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArEuVPxUk...
,"token-service":"http://127.0.0.1:8080/realms/master/protocol/openid-connect",...
"tokens-not-before":0}

检查 HTTP 状态码：

curl -s -o /dev/null -w "HTTP %{http_code}\n" http://127.0.0.1:8080/realms/master

实测回显：

HTTP 200

2.7 校验 OIDC Discovery 端点

很多 IAM 工具（如 OAuth2 Proxy）要依赖该端点：

curl -s http://127.0.0.1:8080/realms/master/.well-known/openid-configuration

实测回显（节选）：

{"issuer":"http://127.0.0.1:8080/realms/master","authorization_endpoint":"http://127.0.0.1:8080/realms/master/protocol/openid-connect/auth","token_endpoint":"http://127.0.0.1:8080/realms/master/protocol/openid-connect/token","introspection_endpoint":"http://127.0.0.1:8080/realms/master/protocol/openid-connect/token/introspect","userinfo_endpoint":"http://127.0.0.1:8080/realms/master/protocol/openi...

三、管理 CLI（kcadm.sh）实测

3.1 登录（配置凭据）

cd /opt/keycloak/bin
export KC_BOOTSTRAP_ADMIN_USERNAME=admin KC_BOOTSTRAP_ADMIN_PASSWORD=q1w2e3r4
./kcadm.sh config credentials --server http://127.0.0.1:8080 --realm master --user admin --password q1w2e3r4

实测回显：

Logging into http://127.0.0.1:8080 as user admin of realm master

3.2 创建 realm

./kcadm.sh create realms -s realm=myrealm -s enabled=true

实测回显：

Created new realm with id 'myrealm'

3.3 列出所有 realm

./kcadm.sh get realms | grep -E "\"realm\" :"

实测回显：

  "realm" : "master",
  "realm" : "myrealm",

3.4 查看服务端信息

./kcadm.sh get serverinfo

实测回显（节选，含系统信息小节头）：

  "systemInfo" : {

3.5 在 realm 下创建公开客户端

./kcadm.sh create clients -r myrealm -s clientId=myapp -s publicClient=true -s directAccessGrantsEnabled=true -i

实测回显（整型客户端 ID）：

47549e52-6208-46c8-8680-289322ce6e0f

💡 -i 使命令直接打印新客户端的 ID；上面的 UUID 是实测产生值，每次部署都不同，属于系统级生成，按需记录。

四、kc.sh / kcadm.sh 命令速查

4.1 kc.sh 版本与帮助

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

实测回显：

Keycloak 26.8.0
JVM: 17.0.20.1 (Ubuntu OpenJDK 64-Bit Server VM 17.0.20.1+1-1-22.04-Ubuntu)
OS: Linux 6.8.0-138-generic amd64

help 中的核心子命令：

命令	用途
`kc.sh build`	构建优化后的运行时镜像（可离线）
`kc.sh start`	生产模式启动
`kc.sh start-dev`	开发模式启动（本文实测）
`kc.sh export`	导出 realm 数据到文件/目录
`kc.sh import`	从文件/目录导入
`kc.sh show-config`	打印当前生效配置
`kc.sh bootstrap-admin user`	引导添加管理员用户/服务账号

4.2 kcadm.sh 常用子命令

命令	用途
`config credentials --server http://127.0.0.1:8080 --realm master`	建立登录凭据（先做）
`get <资源>`	查询（如 `get realms`、`get serverinfo`）
`create <资源> -s 属性=值`	创建（realm、client、user 等）
`update <资源> -s 属性=值`	更新
`delete <资源>`	删除
`get users -r <realm>`	查某 realm 用户

五、常见问题

Unrecognized option: --http-port 启动失败：kc.sh 无此参数时换 --http-port 8080 对应写成 --http-port（26.x）或 --http-host+--http-port；也可直接加 -D 形式。启动失败常见于版本间参数名变化，用 kc.sh start --help 核对。
H2 数据库存储在 /opt/keycloak/data/（start-dev 为内存库，重启即清空业务数据）；生产必须接外部数据库。
admin 密码记不住：通过 kcadm.sh bootstrap-admin 或重设环境变量后重启 Keycloak 可复位；绝不要把明文口令写进提交到仓库的配置。
JVM 未按预期缩小堆：确认 JAVA_OPTS_KC_HEAP 在启动 kc.sh 的 shell 里已导出，并复核 2.4 的 ps -ef 输出；必要时用 JAVA_OPTS_APPEND 强制追加。
8080 端口被占用：改用 --http-port 8081 并同步 systemd 的 ExecStart 与 curl 验证地址。

六、卸载

sudo systemctl stop keycloak
sudo systemctl disable keycloak
sudo rm -f /etc/systemd/system/keycloak.service
sudo rm -rf /opt/keycloak /opt/keycloak-26.8.0.tar.gz /opt/keycloak/data
sudo apt purge -y openjdk-17-jre-headless

💡 如需保留 H2 业务数据，先导出（kc.sh export）或保留 /opt/keycloak/data 再卸载。卸载后再执行 sudo systemctl daemon-reload。

参考链接

Keycloak 官方：https://www.keycloak.org/
Keycloak 26 文档：https://www.keycloak.org/docs/latest/
GitHub Releases：https://github.com/keycloak/keycloak/releases