看到 unauthorized: authentication required，基本可锁定为凭证问题，常见原因包括未登录、登录地址错误或 ~/.docker/config.json 配置异常；需验证 auth 字段存在且有效，并检查 TLS 证书、insecure-registries 配置及 Kubernetes 中 imagePullSecrets 引用是否正确。
认证失败的头号信号：unauthorized 错误
看到 unauthorized: authentication required，基本可以锁定是凭证问题。这不是网络不通，也不是镜像不存在，而是 docker 守护进程压根没把有效的身份信息发给仓库。常见原因有三个：没登录、登录错了地址、或者 config.json 文件被手动改乱了。
快速验证方式很简单：
docker login your-registry.example.com
输对用户名密码后，Docker 会自动写入 ~/.docker/config.json。别跳过这步，也别用错仓库域名——比如你连的是 reg.corp.internal:5000，却去登录 reg.corp.internal（少端口），就会白登。
配置文件里藏着最隐蔽的坑
~/.docker/config.json 不是“登一次就一劳永逸”的保险柜。它可能被以下几种方式悄悄破坏：
- 手动编辑时多加了一个逗号，导致 JSON 格式错误，Docker 直接忽略整个 auths 区块
- 复制粘贴了别人给的 config.json，里面 auth 字段是 Base64 编码的旧密码，但实际账户已重置
- 公司统一推送了配置模板，却漏掉了你的 registry 域名条目
- 用了 Docker Desktop 和 WSL2 双环境，登录只在其中一个生效，另一个仍无凭据
建议每次拉取失败后，先执行：
cat ~/.docker/config.json | jq '.auths' | grep -i your-registry
确认对应域名下确实有非空的 auth 字段。没有？立刻重登。
自签名证书和 TLS 配置是高频断点
私有仓库用自签证书很常见，但 Docker 默认不认。报错 x509: certificate signed by unknown authority 就是典型症状。光把证书丢进系统信任库（如 /etc/ssl/certs）没用，Docker 有自己的证书目录：
使用 Python 脚本下载 Docker 镜像并打包为 tar 文件。用户说“下载镜像”“拉取镜像”“pull xxx”“帮我下载 nginx 镜像”等时触发。支持 SOCKS5 代理直连（推荐）和国内镜像站加速两种模式。
- 路径必须严格为：/etc/docker/certs.d/your-registry.example.com:5000/ca.crt（注意：带端口才匹配）
- 证书文件名必须叫 ca.crt，不能是 cert.pem 或其他名字
- 改完后必须重启 Docker：sudo systemctl restart docker（Linux）或重启 Docker Desktop（Mac/Win）
如果仓库跑在 HTTP 模式（测试环境），则需在 /etc/docker/daemon.json 中显式启用不安全仓库：
{ "insecure-registries": ["your-registry.example.com:5000"] }
改完同样要重启守护进程。
Kubernetes 场景下容易忽略的关键环节
在集群里拉不到私有镜像，经常不是 Docker 本身的问题，而是 Kubernetes 没拿到凭证：
- Secret 必须创建在 Pod 所在的命名空间里，跨 namespace 不生效
- Pod spec 中 imagePullSecrets 字段必须显式引用 Secret 名，不能只靠 default service account
- Secret 的 docker-server 字段值，必须和镜像 tag 中的 registry 地址完全一致（包括协议、端口、大小写）
- 用 kubectl get secret regcred -o yaml 检查 base64 解码后的 server 地址是否拼写正确
一个真实案例：镜像 tag 是 https://reg.corp/internal/app:v1，但 Secret 里填的是 reg.corp/internal ——少写 https://，拉取直接失败，错误日志还不提示具体原因。
