keycloak 26+ 必须用 jdk 21、通过 kc.sh build 注册 postgresql 驱动、配置 keycloak.conf（非 standalone.xml），并预设 keycloak_admin 环境变量才能启动成功。
Keycloak 在 Linux 上能直接跑，但默认用 H2 内存数据库，生产环境必须换 PostgreSQL 或 MySQL，否则服务一重启用户/配置全丢。
怎么选安装方式：zip 包 vs Docker
如果你要快速验证、本地开发，docker-compose 最省事；如果要部署到生产服务器（比如 CentOS 7/8、Ubuntu 22.04），推荐解压 zip 包手动配置——可控性强，日志路径、JVM 参数、模块加载都一目了然。
- 用
docker-compose：适合已有 Docker 环境、不打算深度定制 JDBC 驱动或安全策略的场景；注意官方镜像quay.io/keycloak/keycloak:26.3.4已弃用start-dev模式，必须用start启动并显式指定数据库参数 - 用 zip 包：下载地址是
https://github.com/keycloak/keycloak/releases/download/26.3.4/keycloak-26.3.4.zip；解压后目录结构固定，KEYCLOAK_HOME就是解压后的根目录，所有配置都在standalone/configuration/下 - 别用旧版脚本思维去套新版：Keycloak 26+ 已全面转向 Quarkus 运行时，
standalone.xml不再生效，改用conf/keycloak.conf或环境变量控制
换 PostgreSQL 数据库的关键三步
默认 H2 只能用于测试。换 PostgreSQL 不是改个 URL 就完事，漏掉任何一步都会报 WFLYCTL0013: Operation ("add") failed 或启动卡在 “Waiting for services”。
- 把
postgresql-42.7.3.jar放进providers/目录（不是lib/），然后执行./kc.sh build注册驱动；这步跳过会导致找不到 JDBC 类 - 在
conf/keycloak.conf里写死连接参数：db=postgres、db-url=jdbc:postgresql://127.0.0.1:5432/keycloak、db-username=keycloak、db-password=yourpass - PostgreSQL 必须提前建库并启用
pg_trgm和btree_gin扩展：CREATE EXTENSION IF NOT EXISTS pg_trgm;和CREATE EXTENSION IF NOT EXISTS btree_gin;，否则用户搜索、角色同步会失败
启动失败常见错误和对应检查点
启动时黑屏、无日志、或报 Failed to start service org.wildfly.undertow，大概率是端口、权限或 JVM 配置问题。
-
Address already in use: bind：检查http-port是否被占用，默认是8080；临时改端口加参数--http-port=8180 - Java 版本不对：Keycloak 26.3.4 强制要求 JDK 21，
java -version输出必须含21.；OpenJDK 17 或 22 都会启动失败 - 文件权限问题：Linux 下如果用
root解压再切到普通用户运行，data/和providers/目录可能因属主不一致导致初始化失败；建议全程用同一用户操作 - 没执行
./kc.sh build：换了数据库驱动或加了自定义 provider 后，必须重新构建，否则新配置不加载
管理员账号首次登录进不去？
不是密码错，而是 Keycloak 26+ 默认禁用了基于表单的管理控制台登录，只允许通过 CLI 或环境变量预设管理员。
- 启动前必须设置两个环境变量：
KEYCLOAK_ADMIN=admin和KEYCLOAK_ADMIN_PASSWORD=yourpass - 或者用命令初始化：
./kc.sh start --auto-build --hostname-strict=false --admin-username=admin --admin-password=admin - 浏览器访问地址已变：不再是
http://localhost:8080/auth，而是http://localhost:8080（/auth路径已移除） - 如果看到白屏或 404，检查
kc.sh是否成功输出Admin console listening on http://...，没这句说明服务根本没起来
最易被忽略的是：Keycloak 26+ 的配置体系彻底重构，standalone.xml、domain.xml 全部失效，所有配置必须走 keycloak.conf 或环境变量；沿用老教程改 XML 文件，只会让服务静默失败。
