Gitlab Runner无法拉取Nexus Registry中的Docker镜像

已部署 GitLab、GitLab Runner 和 Nexus 服务器，计划替换独立 Docker Registry 为 Nexus 提供的 Registry。本地 Docker 可正常操作 Nexus Registry，但 GitLab Runner 使用 Nexus 镜像时持续报错，提示no basic auth credentials。

环境与现象 #

• 镜像指定方式对比：

  image: jenkins.intern.de/pipeline-env:latest  # 可正常运行
  # image: nexus.intern.de/docker-group/test/pipeline-env:latest  # 报错
  

• 错误日志：

  Running with gitlab-runner 16.3.0 (8ec04662)
    on debian U7maLHgP, system ID: s_bb2cc94b24c5
  Preparing the "docker" executor
  00:01
  Using Docker executor with image nexus.intern.de/docker-group/test/pipeline-env:latest ...
  Pulling docker image nexus.intern.de/v2/docker-group/test/pipeline-env:latest ...
  WARNING: Failed to pull image with policy "always": Error response from daemon: Head "https://nexus.intern.de/v2/docker-group/test/pipeline-env/manifests/latest": no basic auth credentials (manager.go:237:0s)
  ERROR: Job failed: failed to pull image "nexus.intern.de/docker-group/test/pipeline-env:latest" with specified policies [always]: Error response from daemon: Head "https://nexus.intern.de/v2/docker-group/test/pipeline-env/manifests/latest": no basic auth credentials (manager.go:237:0s)
  

• 本地工作站的 Docker 可正常执行login/pull/push操作访问 Nexus 镜像，但 GitLab Runner 无法拉取。

1. 同步 GitLab Runner 的 Docker 认证凭据 #

本地 Docker 的认证信息存放在~/.docker/config.json中，但 GitLab Runner 运行环境（容器或独立服务）默认不会继承该配置：

• 如果 Runner 以容器方式运行：
  停止并重新启动 Runner，挂载本地 Docker 配置目录：

  docker stop gitlab-runner && docker rm gitlab-runner
  docker run -d --name gitlab-runner --restart always \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /srv/gitlab-runner/config:/etc/gitlab-runner \
    -v $HOME/.docker:/root/.docker \
    gitlab/gitlab-runner:latest
  

• 如果 Runner 以主机服务方式运行：
  将本地用户的认证配置复制到 Runner 运行用户的家目录（比如 Runner 用gitlab-runner用户）：

  cp $HOME/.docker/config.json /home/gitlab-runner/.docker/
  chown gitlab-runner:gitlab-runner /home/gitlab-runner/.docker/config.json
  

2. 修正 Nexus 镜像地址格式 #

Nexus Docker 仓库的正确地址需要包含repository前缀，之前的路径有误：

• 正确镜像地址应为：nexus.intern.de/repository/docker-group/test/pipeline-env:latest
• 原地址缺少repository，导致 Runner 请求错误路径（日志中显示请求/v2/docker-group/...，实际 Nexus 仓库路径为/repository/docker-group/v2/...）

3. 直接在 Runner 配置中添加私有仓库认证（推荐） #

不依赖本地 Docker 配置，直接在 Runner 配置文件中写入 Nexus 认证信息：

1. 编辑 Runner 配置文件（通常为/etc/gitlab-runner/config.toml）
2. 在[[runners]]区块下添加 Docker 认证配置：

   [[runners]]
     name = "debian"
     url = "你的GitLab实例地址"
     token = "你的Runner令牌"
     executor = "docker"
     [runners.docker]
       tls_verify = false
       image = "docker:latest"
       privileged = false
       volumes = ["/cache"]
       pull_policy = "always"
       # 添加Nexus仓库认证
       [[runners.docker.auth_configs]]
         ["nexus.intern.de"]
           username = "Nexus用户名"
           password = "Nexus密码"
           # 若使用自签名证书，需添加证书路径
           # ca_file = "/path/to/nexus-ca.crt"
   

3. 重启 Runner 服务：gitlab-runner restart

4. 检查 Nexus 仓库权限设置 #

• 登录 Nexus 后台，确认docker-group仓库的权限配置：
  • 如果允许匿名拉取，需开启仓库的Allow anonymous pull选项
  • 如果需要认证，确认所用用户拥有nx-repository-view-docker-*-pull角色权限

5. 验证网络与证书有效性 #

• 若 Nexus 使用自签名证书，需在 Runner 所在主机信任该证书：
  将 Nexus CA 证书复制到/etc/docker/certs.d/nexus.intern.de/ca.crt；若 Runner 为容器运行，需将证书挂载到容器内对应路径
• 测试 Runner 主机能否正常访问 Nexus 仓库：

  curl -u 用户名:密码 https://nexus.intern.de/repository/docker-group/v2/_catalog
  

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