该错误源于 Docker 客户端未发送凭证，主因是 config.json 中 registry 地址与 pull 地址不一致、auth 条目缺失或 TLS 证书不受信；需确保登录地址、pull 前缀、config 键名三者完全匹配，并检查 Harbor 权限配置。
docker login 报错 unauthorized: authentication required
这是私有仓库认证失败最典型的提示，不是网络不通，也不是镜像不存在，而是 Docker 客户端根本没把凭证发过去。常见原因是 ~/.docker/config.json 里没写对 registry 地址，或者用了 IP + 端口但没在 config 中显式声明该 registry 的 auth 条目。
- 确保
docker login命令里指定的地址和后续docker pull时用的 registry 前缀完全一致，比如登录时用docker login my-registry.example.com:5000，拉取时就必须用my-registry.example.com:5000/myapp，不能省略端口或换成 IP - 检查
~/.docker/config.json，确认对应 registry 的auths字段下有正确 base64 编码的username:password，且 key 是完整地址（含端口） - 如果私有仓库启用了 TLS 但证书不被系统信任，Docker 会静默跳过认证——此时需先手动把 CA 证书加到
/etc/docker/certs.d/{registry-host}:{port}/ca.crt
使用 docker pull 时提示 no basic auth credentials
这个错误说明 Docker 找到了 registry 地址，也查了 config.json，但没匹配到对应的 auth 条目。本质是“地址字符串不一致”导致的键值查找失败。
- 运行
cat ~/.docker/config.json | jq '.auths'（需装jq），看返回对象的 key 是什么，比如是"https://myreg.example.com"，但你 pull 时用的是http://myreg.example.com，协议不同就匹配不上 - 某些私有仓库（如 Harbor）要求带协议前缀登录：
docker login https://my-harbor.example.com，而另一些（如本地 registry:2）默认走 HTTP，必须用docker login my-reg:5000（无协议） - 如果用脚本批量登录多个 registry，注意
docker login默认会覆盖config.json中已有条目，建议用docker-credential-pass或手动拼 config
CI/CD 流水线中 docker pull 失败，但本地能通
CI 环境通常没有交互式终端，docker login 可能根本没执行，或者凭据存在别的路径（比如 GitLab CI 的 DIND 模式下，Docker daemon 和 client 不共享 config.json）。
- 不要依赖“之前登录过”，每次 job 都应显式调用
docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY - 在 Kubernetes Pod 或 DIND 场景下，
~/.docker/config.json是容器内的路径，宿主机上的凭据不会自动透传；可用volumeMounts挂载，或用docker build --secret配合RUN --mount=type=secret绕过 config 文件 - 某些 CI 平台（如 GitHub Actions）对
docker login的密码字段敏感，若密码含特殊字符（如$、@），需用单引号包裹或 URL 编码，否则 shell 展开后 auth 字符串损坏
Harbor 私有仓库返回 forbidden: repository not found 却已登录
这不是认证问题，而是权限粒度问题：用户通过了 registry 级认证，但没被授予该 namespace 或 project 下的 pull 权限。Harbor 的权限模型比基础 registry 更细。
- 登录 Harbor Web UI，确认目标项目（project）的成员列表里，当前用户角色至少是
guest（只读）或更高 - 检查项目是否设为
private，且用户不在成员中；公开项目（public）才允许未登录拉取 - 如果用 robot account，注意其 token 有效期和权限范围——创建时勾选了
pull才行，且只能拉它所属项目的镜像，不能跨 project
cat ~/.docker/config.json 看凭证存哪了，再比对 docker pull 的地址字符串，最后去仓库后台查权限，顺序不能乱。 
