GitLab个人访问令牌用于DockerHub登录失败求助

问题背景 #

已为GitLab账号开启2FA并创建个人访问令牌，尝试以下三种docker login方式均失败：

$ docker login https://dockerhub.my-site.com:5000/some/path?private_token=<personal-access-token>
$ docker login -u <username> -p <personal-access-token> https://dockerhub.my-site.com:5000/some/path
$ docker login https://dockerhub.my-site.com:5000/some/path

返回统一错误：

login Error Head "https://dockerhub.my-site.com:5000/some/path": unauthorized: HTTP Basic: Access denied. The provided password or token i... 1.3s
Error response from daemon: Head "https://dockerhub.my-site.com:5000/some/path": unauthorized: HTTP Basic: Access denied. The provided password or token is incorrect or your account has 2FA enabled and you must use a personal access token instead of a password. See https://dockerhub.my-site.com:5000/help/user/profile/account/two_factor_authentication#troubleshooting

排查方案 #

• 修正登录地址格式：docker login不需要附加仓库的子路径/some/path，私有仓库的认证端点是根域名+端口。正确命令应为：

  docker login -u <username> -p <personal-access-token> https://dockerhub.my-site.com:5000
  

• 检查个人访问令牌权限：创建GitLab个人访问令牌时，必须勾选read_registry（拉取镜像）和write_registry（推送镜像）权限，权限不足会直接触发认证失败。
• 验证令牌有效性：用curl直接测试仓库API，确认令牌和账号的有效性：

  curl -u <username>:<personal-access-token> https://dockerhub.my-site.com:5000/v2/
  

  若返回401 Unauthorized但提示"authentication required"，说明令牌本身有效但需检查仓库权限；若返回其他错误，需重新生成令牌。
• 清理Docker认证缓存：若之前使用密码登录过，Docker可能缓存了旧的认证信息，导致新令牌无法生效：
  • Linux/macOS：编辑~/.docker/config.json，删除对应仓库的auth条目，或直接删除文件（会清除所有仓库登录记录）
  • Windows：删除C:\Users\<你的用户名>\.docker\config.json文件
• 确认仓库访问权限：确保GitLab账号拥有目标私有仓库的访问权限（如项目开发者、成员角色），无仓库权限即使令牌正确也会被拒绝。

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