Docker拉取镜像超时主因是网络不通，应优先配置有效镜像加速器；daemon.json需合法JSON格式、用可用地址（如docker.m.daocloud.io）、重启docker服务；宝塔显示成功但images无镜像属插件缓存问题，需手动验证并刷新；login失败多因凭据未正确写入，应命令行执行docker login并确认config.json含auths字段。
宝塔面板里 docker pull 报错 context deadline exceeded 或 TLS handshake timeout
这是最典型的国内网络环境症状：Docker 默认直连 registry-1.docker.io，但实际请求常卡在 DNS 解析或 TLS 握手阶段，根本连不上。宝塔界面点“拉取镜像”没反应、命令行执行 docker pull 卡住几十秒后报超时，基本可锁定为网络通道问题。
别急着换源或重装，先确认是否真被卡住：
- 执行
curl -v https://registry-1.docker.io/v2/，看是否能完成 TLS 握手并返回 401（说明通了）；如果卡在* Trying 104.18.121.116:443...或直接超时，就是网络层不通 - 执行
nslookup registry-1.docker.io，检查 DNS 是否能正常解析出 IP；若失败，说明 DNS 污染或配置失效
此时改 DNS 或加镜像加速器都有效，但加速器优先级更高——它绕过 DNS 解析和境外直连，直接走国内代理节点。
/etc/docker/daemon.json 配置镜像加速器必须注意的三件事
很多人照抄网上加速地址，粘贴完重启就以为搞定，结果还是拉不动。问题往往出在配置细节上：
-
daemon.json文件必须是合法 JSON：末尾不能有多余逗号，引号必须是英文双引号，数组内每个地址必须用英文逗号分隔 - 加速地址必须可用——截至 2026 年 4 月，已确认失效的包括
https://registry.docker-cn.com（已关闭）、https://hub-mirror.c.163.com（响应缓慢且偶发 503），建议优先使用：https://docker.m.daocloud.io、https://docker.mirrors.ustc.edu.cn、https://docker.nju.edu.cn - 不要堆砌过多地址：超过 5 个镜像源反而会拖慢探测逻辑；宝塔 Docker 插件有时只读取第一个生效地址，所以把最稳的那个放在数组首位
正确写法示例：
{ "registry-mirrors": ["https://docker.m.daocloud.io", "https://docker.mirrors.ustc.edu.cn"] }
写完保存后，务必执行两步：
systemctl daemon-reloadsystemctl restart docker
宝塔面板显示“拉取成功”但 docker images 看不到镜像
这通常不是网络问题，而是宝塔 Docker 插件的缓存刷新机制缺陷。它可能把拉取日志当成成功信号，却没及时同步本地镜像列表。
验证方式很简单：
- 在 SSH 中手动执行
docker pull nginx:alpine，等它输出Status: Downloaded newer image - 立刻运行
docker images | grep nginx，确认镜像确实存在本地 - 再回宝塔面板的“镜像管理”页，点击右上角刷新按钮（不是浏览器 F5），或直接关闭页面重新打开
如果仍不显示，说明插件未监听到 dockerd 的事件通知。此时可临时用宝塔终端执行 docker system prune -f 清理一次状态，再重试拉取——多数情况下能触发插件重载。
登录 Docker Hub 后依然提示 unauthorized: authentication required
这个错误容易误导人以为账号密码错了，其实更可能是认证凭据没落到正确的守护进程上下文里。宝塔面板启动的 Docker 插件，有时会以非交互式方式调用 docker login，导致凭据写入路径异常。
稳妥做法是绕过宝塔界面，全程用命令行操作：
- 先执行
docker logout清掉可能冲突的旧凭据 - 再执行
docker login，输入账号密码（注意：不是邮箱，是 Docker ID） - 验证凭据是否生效：
cat ~/.docker/config.json应该能看到非空的auths字段 - 之后所有
docker pull命令（包括宝塔界面发起的）都会自动携带该凭据
特别注意：如果你用的是 GitHub Container Registry（ghcr.io）或私有仓库，docker login 必须带上域名，例如 docker login ghcr.io，否则凭据不会写入对应 key。
