Keycloak升级过程中健康检查路径配置问题解析

问题背景

在Keycloak从24.0.3版本升级到26.1.4版本的过程中，用户遇到了Pod持续重启的问题。通过分析发现，这是由于健康检查路径配置不当导致的。本文将详细解析这一问题及其解决方案。

问题现象

升级后的Keycloak Pod处于CrashLoopBackOff状态，具体表现为：

• 启动探针(Startup Probe)失败
• 健康检查端点返回404错误
• 日志显示服务已正常启动，但健康检查无法通过

根本原因分析

问题的核心在于Keycloak 26.1.4版本中HTTP相对路径(KC_HTTP_RELATIVE_PATH)的配置行为发生了变化：

1. 用户配置了KC_HTTP_RELATIVE_PATH=/auth，这会导致所有端点(包括管理接口)都添加此前缀
2. 但健康检查探针配置中仍使用原始路径/health/started，而非完整路径/auth/health/started
3. 这种不匹配导致探针无法访问正确的健康检查端点

解决方案

针对这一问题，有两种可行的解决方案：

方案一：更新探针配置路径

修改Kubernetes部署配置中的健康检查路径，添加/auth前缀：

startupProbe:
  httpGet:
    path: /auth/health/started
    port: 9000
    scheme: HTTPS

方案二：使用独立的管理接口路径配置

如果希望管理接口保持原始路径，可以专门配置管理接口的相对路径：

KC_HTTP_MANAGEMENT_RELATIVE_PATH=/

这样主接口使用/auth前缀，而管理接口(包括健康检查)保持原始路径。

配置建议

对于Keycloak的健康检查配置，建议注意以下几点：

1. 明确区分主接口和管理接口的路径配置
2. 确保Kubernetes探针路径与Keycloak实际路径一致
3. 测试时可以直接通过curl验证端点可访问性
4. 注意HTTPS证书验证问题，必要时可添加-k参数跳过验证

版本升级注意事项

从Keycloak 24.x升级到26.x时，需要特别注意：

1. 健康检查机制的变化
2. 路径处理逻辑的变更
3. 管理接口的默认行为差异
4. 建议在升级前充分测试配置兼容性

通过正确理解路径配置机制并相应调整探针设置，可以确保Keycloak在升级后能够正常启动和运行。