Keycloak 26（Docker本地部署）健康检查功能异常求助

• 确认健康检查端点路径
  Keycloak 17+（Quarkus 发行版）的健康检查端点默认挂载在管理上下文路径下，并非根路径。当KC_MANAGEMENT_ENABLED=true时，正确的健康检查URL应为：

curl http://localhost:8080/admin/realms/master/management/health

细分状态检查可访问：

# 存活状态检查
curl http://localhost:8080/admin/realms/master/management/health/live
# 就绪状态检查
curl http://localhost:8080/admin/realms/master/management/health/ready

• 验证启动参数是否生效
  进入容器查看Keycloak实际启动参数，确认健康检查相关配置已被加载：

docker exec <你的Keycloak容器ID> ps aux | grep keycloak

若参数未出现，检查Docker环境变量传递是否正确——docker run需用-e指定变量，docker-compose需在environment节点下配置，避免拼写错误（Keycloak环境变量为全大写+下划线格式）。

• 检查配置文件生成情况
  查看容器内的Keycloak配置文件，确认健康检查扩展已启用：

# Quarkus发行版默认配置路径
docker exec <容器ID> cat /opt/keycloak/conf/keycloak.conf | grep -E "(health|management)"

若输出无相关配置，说明启动参数未被正确解析，需排查参数拼写或启动命令格式问题。

• 验证端口映射与容器状态
  确认Docker端口映射正确，避免端口冲突：

docker ps | grep keycloak

检查PORTS列是否为0.0.0.0:8080->8080/tcp，同时确保容器处于Up状态。

• 最简启动命令测试
  暂时移除自定义参数，用官方最简命令启动测试：

docker run -p 8080:8080 quay.io/keycloak/keycloak:26.0.0 start-dev --health-enabled=true --management-enabled=true

若此时健康检查正常，说明之前的参数组合存在冲突（例如KC_HTTP_RELATIVE_PATH=/可能干扰管理路径解析）。

• 查看启动日志定位问题
  检查容器启动日志，确认健康检查扩展是否成功加载：

docker logs <容器ID> | grep -i health

若日志中出现Health check endpoints enabled类信息，说明扩展已加载，问题集中在路径访问；若无相关日志，说明健康检查未被正确启用。

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