keycloak 26+ 在 linux 上必须使用 jdk 21、执行 ./kc.sh build 构建运行时配置、设置 kc_hostname_strict=false 和 kc_proxy=edge，并避免 postgresql 密码含 url 特殊字符，否则无法访问管理后台或获取 token。
Keycloak 在 Linux 上能跑起来不难，但直接解压 zip 或拉 latest 镜像就启动，十有八九进不了管理后台、拿不到 token、重启丢数据——这不是装错了，是新版（26+）默认行为和旧教程严重脱节。
Keycloak 26+ 必须用 JDK 21，且不能跳过 kc.sh build
旧版靠 standalone.sh 启动、改 standalone.xml 就行，26+ 全面转向 Quarkus，JVM 和配置体系全换。java -version 输出不含 21，服务直接静默失败；没执行 ./kc.sh build，哪怕数据库参数全对，也会卡在 “Waiting for services”。
- JDK 必须是 OpenJDK 21（不是 17、22），安装后验证：
java -version | grep 21 - 下载 zip 包后，cd 进解压目录，先设环境变量：
export KEYCLOAK_ADMIN=admin && export KEYCLOAK_ADMIN_PASSWORD=Admin1234 - 再执行构建：
./kc.sh build --db=postgres --hostname=localhost --proxy=edge（这步生成运行时配置，不可省） - 构建成功后才能
./kc.sh start，否则报WFLYCTL0013: Operation ("add") failed
Docker 启动必须显式设 KC_HOSTNAME_STRICT=false 和 KC_PROXY=edge
用 docker run 或 docker-compose 跑，不加这两项，从浏览器访问 http://your-ip:8080 就是 400 Bad Request 或空白页，控制台提示 Invalid parameter: redirect_uri——Keycloak 生成跳转地址时用了容器内 localhost，而不是你实际访问的 IP/域名。
在 Linux 上通过 Docker 运行 OpenClaw，并使用 Tailscale 实现远程访问。⚠️ 涉及 sudo、Docker、Tailscale和凭证挂载——请先查阅安全章节...
-
KC_HOSTNAME_STRICT=false关闭 Host 头严格校验（默认 true） -
KC_PROXY=edge告诉 Keycloak 它前面有反向代理（如 Nginx），否则 HTTPS 重定向会拼错协议和端口 - 如果走公网域名，还要加
KC_HOSTNAME=your-domain.com，否则登录后跳回http://localhost:8080 - 别用
start-dev：26+ 官方镜像已弃用该模式，必须用start并带数据库参数
PostgreSQL 密码含 @ 或 / 会导致 JDBC URL 解析失败
连接 PostgreSQL 时，KC_DB_URL=jdbc:postgresql://host:5432/db?currentSchema=public 看似没问题，但如果 KC_DB_PASSWORD 是 pass@word/123，JDBC 解析器会把 @ 当作 URL 分隔符，报 Malformed database URL，服务起不来。
- 密码避开
@、/、:、?这类 URL 特殊字符 - 若必须用，需 URL 编码：把
@换成%40，/换成%2F - 数据库里提前执行：
CREATE EXTENSION IF NOT EXISTS pg_trgm;和CREATE EXTENSION IF NOT EXISTS btree_gin;，否则用户搜索、角色同步功能异常 - PostgreSQL 用户必须有
CREATEDB权限，Keycloak 初始化要自动建 schema 和表
Client ID 和 Redirect URIs 填错，前端永远拿不到 token
Realm 创建完，进 Clients 页面配应用，填错三项中的任意一个，OIDC 授权流程就在 redirect_uri 校验环节失败，返回 400，前端收不到 code，更拿不到 token。
-
Client ID必须全小写、无下划线、无点号：hr-web可以，HR.Web或hr_web会导致 OIDC 发现文档（.well-known/openid-configuration）返回 404 -
Valid Redirect URIs必须精确匹配前端发起授权请求的回调地址，协议、域名、端口、路径、末尾斜杠缺一不可：http://localhost:3000/login/callback/正确，http://localhost:3000/login/callback（少 /）或https://localhost:3000/（协议/路径不符）都会被拒 -
Access Type选confidential（服务端应用）还是public（SPA、移动端）要和前端调用方式一致，混用会导致 client_secret 校验失败
最常被忽略的其实是 kc.sh build 这一步——它不像启动命令那样显眼，但没它，所有后续配置都白搭；还有就是 PostgreSQL 密码里的特殊字符，看着合法，实则让整个 JDBC 连接链路在解析阶段就断掉。
