Keycloak（v24）在Azure Container Apps启动失败，求助排查思路

• 检查镜像基础环境兼容性：Keycloak 24官方镜像已从旧版OpenJDK基础镜像切换为Eclipse Temurin，底层操作系统换成了Red Hat UBI。确认Azure Container Apps的运行环境是否支持该基础镜像，排查是否存在系统依赖库缺失的情况。

• 核对启动命令参数：Keycloak从16到24版本的启动参数格式有大幅调整，旧版以-D开头的系统参数，新版大多改为--开头的CLI参数。比如旧版的-Dkeycloak.profile.feature.upload_scripts=enabled，新版需替换为--features=upload-scripts。检查你的启动命令是否完全适配24版本的语法规则。

• 调整资源配额：Keycloak 24对CPU和内存的需求远高于16版本，Azure Container Apps默认的资源配额（如0.5核CPU、512M内存）可能不足以支撑启动。尝试将CPU调至1核、内存调至1G以上，重新部署测试。

• 补全新版本必填环境变量：Keycloak 24强制要求设置KC_BOOTSTRAP_ADMIN_USERNAME和KC_BOOTSTRAP_ADMIN_PASSWORD两个环境变量，旧版本无此强制要求。另外KC_HOSTNAME也是新版启动的关键参数，必须指定符合ACA访问规则的主机名，否则会启动失败。

• 排查镜像拉取问题：避免使用latest标签，改用具体版本tag（如quay.io/keycloak/keycloak:24.0.0），防止ACA拉取到不兼容的镜像变体。同时触发一次重新部署，让ACA重新拉取镜像，排除缓存导致的镜像损坏问题。

• 深挖系统日志细节：在Log Analytics中执行精确查询，获取更详细的错误信息：

  ContainerAppConsoleLogs_CL
  | where ContainerName_s == "key"
  | where Log_s contains "ContainerCreateFailure"
  | project TimeGenerated, Log_s, ContainerInstanceId_g
  

  查看是否存在镜像拉取超时、权限不足、端口冲突等具体提示。

• 本地镜像验证：用Docker在本地完全复刻ACA的配置运行Keycloak 24：

  docker run -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin -e KC_HOSTNAME=localhost -p 8080:8080 quay.io/keycloak/keycloak:24.0.0 start-dev
  

  如果本地也启动失败，直接定位为配置问题；如果本地正常，再排查ACA的环境限制（如网络策略、私有镜像仓库权限等）。

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