GitLab CI/CD流水线Docker登录失败问题排查与解决求助

核心排查方向及解决步骤 #

1. 确认CI/CD变量配置正确性 #

• 登录GitLab项目，进入Settings -> CI/CD -> Variables，检查是否配置了正确的仓库认证变量（比如DOCKER_REGISTRY_USER、DOCKER_REGISTRY_PASSWORD）
• 确保变量设置为受保护（针对私有分支/标签）和掩码（避免密码泄露）
• 流水线中引用变量时要保证拼写完全一致，比如标准登录命令：

  docker login $DOCKER_REGISTRY_URL -u $DOCKER_REGISTRY_USER -p $DOCKER_REGISTRY_PASSWORD
  

• 可在流水线中临时添加echo $DOCKER_REGISTRY_USER验证变量是否正常加载（注意不要打印密码）

2. 验证镜像仓库地址一致性 #

• 对比VPS本地登录和CI流水线使用的仓库地址，必须完全匹配（包括端口号，比如registry.example.com和registry.example.com:5000是两个独立地址）
• 在流水线中加入nslookup $DOCKER_REGISTRY_URL命令，确认Runner能正常解析仓库域名
• 如果用IP地址访问，检查Runner主机是否能ping通该IP

3. 检查Runner的网络权限 #

• 若Runner是Docker executor，确认Runner容器/主机的出站规则允许访问仓库端口（默认HTTPS是443，私有仓库可能为5000等）
• 在Runner所在主机执行telnet $DOCKER_REGISTRY_URL 443（替换对应端口），测试网络连通性
• 自托管Runner需检查主机防火墙、安全组是否拦截了仓库访问请求

4. 确认Docker-in-Docker（DinD）配置（若使用DinD） #

• 在.gitlab-ci.yml中正确配置DinD服务：

  services:
    - docker:dind
  

• 添加必要环境变量：

  variables:
    DOCKER_HOST: tcp://docker:2376
    DOCKER_TLS_CERTDIR: "/certs"
  

• 保证Docker客户端版本和DinD服务版本一致，避免兼容性问题（比如都用docker:24.0.6和docker:24.0.6-dind）

5. 处理自签名证书/私有CA问题 #

• 如果镜像仓库用自签名SSL证书，需把证书放到Runner主机的/etc/docker/certs.d/<registry-url>/目录下（比如/etc/docker/certs.d/registry.example.com/ca.crt）
• 若使用DinD，可在流水线中挂载证书到DinD容器，或添加证书信任步骤：

  mkdir -p /etc/docker/certs.d/$DOCKER_REGISTRY_URL
  echo "$REGISTRY_CA_CERT" > /etc/docker/certs.d/$DOCKER_REGISTRY_URL/ca.crt
  

  其中REGISTRY_CA_CERT是存储在CI变量中的证书内容（设为掩码变量）

6. 清理Docker凭证缓存 #

• 在流水线登录命令前添加清理步骤，避免旧凭证冲突：

  docker logout $DOCKER_REGISTRY_URL || true
  docker login $DOCKER_REGISTRY_URL -u $DOCKER_REGISTRY_USER -p $DOCKER_REGISTRY_PASSWORD
  

7. 手动在Runner主机测试登录 #

• 登录到Runner所在的VPS/主机，使用CI变量中的相同用户名和密码执行docker login命令
• 如果这里也失败，说明问题出在Runner主机环境（比如证书、网络、账号权限）；如果成功，再回到CI配置排查变量引用或DinD问题

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