结合你描述的情况——Keycloak在GitLab CI里能返回根路径的重定向页面，但/auth核心路径报404，且本地自定义镜像完全正常——问题基本可以锁定在GitLab CI环境的启动时序、资源限制或配置细节上，下面是几个优先级较高的排查方向：

1. 先确认Keycloak是否真的启动完成了 #

根路径的重定向页面其实是Tomcat的默认页面，不需要Keycloak核心服务初始化完成就能返回，但/auth是Keycloak的专属上下文，必须等它加载完配置、完成数据库初始化（哪怕是默认的H2）才能正常响应。GitLab CI的job经常会在服务还没就绪时就发起请求，这是这类问题的高发原因。

解决办法：
在你的测试脚本前加一段等待逻辑，轮询/auth路径直到它就绪，比如用这段shell脚本：

# 最多等待5分钟，每隔5秒检查一次
MAX_WAIT=300
WAIT_INTERVAL=5
ELAPSED=0

while [ $ELAPSED -lt $MAX_WAIT ]; do
  # 检查是否能拿到Keycloak的登录页面内容
  if curl -s http://sso:8080/auth | grep -q "Keycloak"; then
    echo "✅ Keycloak服务已就绪"
    break
  fi
  echo "⏳ 等待Keycloak启动... 已等待${ELAPSED}/${MAX_WAIT}秒"
  sleep $WAIT_INTERVAL
  ELAPSED=$((ELAPSED + WAIT_INTERVAL))
done

if [ $ELAPSED -ge $MAX_WAIT ]; then
  echo "❌ Keycloak超时未启动"
  exit 1
fi

2. 检查GitLab Runner的资源是否够 #

Keycloak 10.x版本启动至少需要512MB内存，如果你的GitLab Runner是共享实例或者资源配额设得很低，可能会导致Keycloak初始化到一半就卡住，核心服务无法启动。

解决办法：
在.gitlab-ci.yml里给Keycloak服务加资源限制（需要你的Runner支持Docker资源配额）：

services:
  - docker:dind
  - name: mongo:latest
    alias: mongodb
  - name: jboss/keycloak:10.0.1
    alias: sso
    command: ["-b", "0.0.0.0"]
    resources:
      limits:
        memory: 1024M  # 给足内存
      requests:
        memory: 512M

3. 看看Keycloak的启动日志有没有报错 #

GitLab CI会收集服务容器的日志，你可以在job的日志页面展开Services部分，找到sso容器的日志，看看有没有初始化错误——比如数据库连接失败、配置加载报错这类问题，这些都会导致/auth路径无法正常提供服务。

4. 确认CI里的Keycloak配置和本地一致 #

你提到本地自定义镜像能正常运行，但CI里用的是官方镜像，还没设置那些数据库和管理员用户的环境变量。官方镜像默认用H2数据库，但如果启动时缺少必要配置，可能会导致核心服务初始化失败。

解决办法：
要么直接用你自己的自定义镜像，要么在CI的服务配置里补上环境变量：

services:
  - docker:dind
  - name: mongo:latest
    alias: mongodb
  - name: jboss/keycloak:10.0.1
    alias: sso
    command: ["-b", "0.0.0.0"]
    variables:
      DB_VENDOR: xxx
      DB_DATABASE: xxx
      DB_ADDR: mongodb  # 对应mongo服务的alias
      DB_PORT: 27017
      KEYCLOAK_USER: admin
      KEYCLOAK_PASSWORD: admin

⚠️ 注意：Keycloak官方对MongoDB的支持需要额外安装扩展，10.0.1版本可能默认不支持，如果不确定，先换成默认的H2数据库测试，排除数据库配置的问题。

5. 验证CI环境的网络连通性 #

GitLab Runner的网络模式（比如bridge模式）可能会导致服务之间的DNS解析有延迟，或者通信有临时限制。你可以在job里加个前置步骤，先确认sso主机能正常访问：

before_script:
  - ping -c 3 sso  # 测试连通性
  - nslookup sso    # 测试DNS解析

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