GitLab Dependency Proxy拉取镜像报unauthorized认证失败如何解决

算力阿峰

2026-8-29

常见触发原因

访问令牌权限范围配置错误：GitLab 14.10 版本中，Dependency Proxy 写入镜像缓存层需要write_registry权限，仅配置read_registry权限会直接返回认证失败。
登录地址与拉取地址不匹配：手动拼接代理地址、跨群组使用令牌时，凭证和访问的资源所属群组不对应，鉴权不通过。
DinD 服务未正确读取认证配置：原配置未指定Docker配置文件路径，dind服务拉取镜像时读不到之前login生成的认证信息，相当于未登录直接拉取。
自定义令牌变量失效：CI变量被保护规则、掩码规则限制，或者令牌本身过期、被吊销，导致docker login步骤实际未成功，只是没有抛出显性错误。
版本兼容问题：14.10 版本中子群组项目使用根群组Dependency Proxy时，子群组生成的令牌没有根层级代理的访问权限。

排查修复步骤

先验证凭证有效性
在docker login步骤后增加调试命令，确认认证信息确实写入了docker配置：
```
before_script:
  - mkdir -p $HOME/.docker
  - docker login -u $TOKEN_USERNAME -p $TOKEN_PASSWORD $CI_DEPENDENCY_PROXY_SERVER
  # 调试用，确认凭证写入成功，验证完可删除
  - cat $HOME/.docker/config.json | grep $CI_DEPENDENCY_PROXY_SERVER
```
如果grep没有匹配到对应地址的认证段，说明login步骤失败，优先检查TOKEN_USERNAME、TOKEN_PASSWORD两个变量是否在当前流水线作用域内可用，没有被保护规则拦截、没有为空。
校正令牌权限
检查你使用的群组访问令牌，必须同时勾选read_registry、write_registry两个权限范围；如果使用个人访问令牌，要确认令牌所属账号是目标群组的成员，且同样配置了上述两个权限。
更稳妥的方式是直接使用GitLab预定义的Dependency Proxy专用凭证，不需要手动创建令牌，直接替换login命令即可：
```
docker login -u $CI_DEPENDENCY_PROXY_USER -p $CI_DEPENDENCY_PROXY_PASSWORD $CI_DEPENDENCY_PROXY_SERVER
```
这两个变量是GitLab为当前流水线生成的临时凭证，自动匹配当前项目所属群组的代理权限，不会出现令牌过期、权限不足的问题，是官方推荐的标准用法。

修正DinD配置
补充Docker配置路径变量，确保dind服务和作业容器共用同一份认证配置，修改后的完整CI配置参考：

# .gitlab-ci.yml
image: docker:19.03.12

variables:
  DOCKER_HOST: tcp://docker:2375
  DOCKER_TLS_CERTDIR: ""
  # 指定docker配置路径，确保认证信息可被dind读取
  DOCKER_CONFIG: $HOME/.docker

services:
  - docker:19.03.12-dind

build:
  image: docker:19.03.12
  before_script:
    - mkdir -p $DOCKER_CONFIG
    - docker login -u $CI_DEPENDENCY_PROXY_USER -p $CI_DEPENDENCY_PROXY_PASSWORD $CI_DEPENDENCY_PROXY_SERVER
  script:
    - docker pull ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/php:7-fpm-alpine3.15

检查功能开关与权限配置
进入对应群组的管理后台，找到「设置 > 通用 > 权限与项目功能」，确认Dependency Proxy功能处于开启状态；同时检查群组权限规则，确认流水线作业的默认角色（通常为Reporter及以上）有Dependency Proxy的访问权限。如果项目在子群组下，优先使用子群组自身的Dependency Proxy地址拉取镜像，规避14.10版本的跨层级鉴权bug。

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