Keycloak18配置KC_HTTP_RELATIVE_PATH后首页显示Resource not found求助

问题原因 #

Keycloak 17+ 基于 Quarkus 架构重构，移除了旧版（如16.x的Wildfly架构）中自动将根路径（/）重定向到KC_HTTP_RELATIVE_PATH指定路径的默认行为。当配置KC_HTTP_RELATIVE_PATH: /auth后，Keycloak仅响应/auth路径下的请求，根路径/无对应资源处理逻辑，因此返回"Resource not found"。

解决方案 #

方案1：通过Caddy反向代理添加根路径重定向 #

修改Caddy配置，将根路径请求永久重定向到/auth，用户访问https://thing.com/时会自动跳转至https://thing.com/auth，既保留原有依赖路径，又解决首页404问题。

示例Caddyfile配置：

https://thing.com {
    # 根路径重定向到/auth
    redir / /auth permanent
    # 反向代理到Keycloak服务
    reverse_proxy <Keycloak机器IP或容器名>:8080
}

方案2：修复Keycloak健康检查配置 #

当前Docker Compose中的健康检查请求根路径/，会因404导致健康检查失败，需同步修改为检查/auth路径：

healthcheck:
  test: curl -I http://127.0.0.1:8080/auth/
  interval: 30s
  timeout: 10s
  retries: 3

补充说明 #

若无法修改反向代理配置，可通过自定义Keycloak扩展添加根路径重定向过滤器，但该方式复杂度较高，反向代理层面处理是最简洁高效的方案。

内容的提问来源于stack exchange，提问作者JWolfRSA