这次是在一台轻量服务器上恢复测试环境，服务本身不复杂：一个 Nginx、一个 Redis，再加一个浏览器自动化容器。

问题出在第一步：

```bash
docker compose pull
```

前两个小镜像偶尔能下来，后面的镜像层经常卡住，最后报：

```text
TLS handshake timeout
context deadline exceeded
```

一开始我以为是 Docker 版本问题，升级之后没有变化。后来才发现，机器上虽然配置了 `registry-mirrors`，但配置时间比较久，里面有些地址已经不适合继续作为主源使用。

这篇只记录这次排查过程，不放第三方服务入口。实际环境里把下面的占位地址替换成自己团队已经确认过的镜像源即可。

## 环境

| 项目 | 内容 |
|---|---|
| 机器 | 2C4G 轻量服务器 |
| 系统 | Ubuntu 22.04 |
| Docker | 27.x |
| 运行方式 | Docker Compose |
| 故障现象 | 拉取镜像超时、部分镜像层长时间无进度 |

先确认 Docker 配置：

```bash
cat /etc/docker/daemon.json
docker info | grep -A 10 "Registry Mirrors"
```

这里要注意，`docker info` 里能看到镜像源，不代表项目里的所有镜像都会通过它成功拉取。它主要影响 Docker Hub 相关镜像；如果项目里还有其他上游来源，要单独判断。

## 第一步：先把镜像来源拆开

我先看 compose 文件：

```bash
grep -n "image:" docker-compose.yml
```

项目里大概分成三类：

| 类型 | 例子 | 处理方式 |
|---|---|---|
| 基础服务镜像 | `nginx`、`redis` | 先检查 `registry-mirrors` |
| 浏览器自动化镜像 | `playwright` 相关镜像 | 单独确认上游来源 |
| 监控或辅助组件 | `prometheus` 等 | 单独做拉取预检 |

这一步很关键。以前我只测一个 `nginx:alpine`，能拉下来就以为环境没问题。实际项目里只要有一个镜像来自不同上游，`docker compose pull` 还是会卡住。

## 第二步：先验证基础镜像

我先用小镜像确认 Docker 本身没有问题：

```bash
docker pull nginx:alpine
docker pull redis:7-alpine
docker pull postgres:16-alpine
```

如果这些都失败，优先检查：

- 服务器 DNS。
- 出口网络。
- `/etc/docker/daemon.json` 是否是合法 JSON。
- Docker 是否已经重启。
- 当前镜像源是否还能正常返回镜像层。

重启 Docker：

```bash
sudo systemctl daemon-reload
sudo systemctl restart docker
```

## 第三步：替换为团队已验证入口

这一步我不建议在文章里复制一堆网上找来的公共地址。公共源状态会变，直接贴到服务器上也不好排查。

我的做法是只保留团队已经验证过的入口。例如：

```json
{
  "registry-mirrors": [
    "团队已验证镜像源地址"
  ]
}
```

实际填写时再按 Docker 要求补全协议和域名；发布记录里不放具体第三方地址。

如果是云上内网机器，也可以优先使用云厂商提供的内网镜像能力；如果是公网轻量服务器，就用自己确认可用的公网入口。重点不是地址越多越好，而是能复现、能维护、出问题能定位。

配置后再验证：

```bash
docker info | grep -A 10 "Registry Mirrors"
docker pull nginx:alpine
docker pull redis:7-alpine
```

## 第四步：compose 项目单独预检

基础镜像通过后，再回到项目：

```bash
docker compose config | grep "image:"
docker compose pull
```

如果只想定位是哪一个镜像慢，可以逐个拉：

```bash
docker pull <image-a>
docker pull <image-b>
docker pull <image-c>
```

我这次就是在逐个拉取时发现，基础服务没问题，卡住的是其中一个非 Docker Hub 来源的镜像。把它替换为团队内部已经缓存过的镜像后，`docker compose pull` 才稳定下来。

## 第五步：错误类型要分开看

这几个错误不要混在一起处理：

| 错误 | 优先判断 |
|---|---|
| `manifest unknown` | 镜像名或 tag 写错 |
| `unauthorized` | 私有镜像未登录或权限不足 |
| `TLS handshake timeout` | 网络链路、DNS 或镜像源响应慢 |
| `context deadline exceeded` | 镜像层下载超时 |
| `no such host` | DNS 解析或代理配置问题 |

如果是私有镜像，先登录：

```bash
docker login <registry-host>
docker pull <private-image>
```

如果是公开镜像，先用小镜像排除 Docker 本身问题，再检查对应上游来源，不要一上来就改一长串镜像源。

## 第六步：我最后保留的检查清单

这次处理完后，我给测试机留了一个简单清单：

```bash
docker info | grep -A 10 "Registry Mirrors"
docker pull nginx:alpine
docker pull redis:7-alpine
docker compose config | grep "image:"
docker compose pull
```

如果要放到 CI 前置检查里，可以只保留团队项目真实会用到的镜像，不需要测一堆和项目无关的镜像。

## 小结

这次问题不是应用代码，也不是 Docker Compose 写法，而是镜像来源没有分清。

我的经验是：

1. 先看 `docker-compose.yml` 里到底有多少种镜像来源。
2. 不只测 `hello-world` 或 `nginx:alpine`。
3. 公共镜像源不要堆太多，保留可维护、可复现的入口。
4. 固定生产镜像最好进入内部仓库或缓存仓库。
5. 遇到超时先逐个拉取定位，不要直接整机重装。

这样处理后，后面再遇到 `docker compose pull` 超时，至少能快速判断是网络、镜像源、权限，还是镜像名本身的问题。

这次是在一台轻量服务器上恢复测试环境，服务本身不复杂：一个 Nginx、一个 Redis，再加一个浏览器自动化容器。

轻量服务器 docker pull 超时排查记录

这次是在一台轻量服务器上装测试环境，docker pull nginx:alpine 一开始能拉，后面换到项目镜像就开始超时。

云计算

运维

开发工具

解决Docker镜像拉取超时问题：排查发现服务器registry-mirrors配置过时，导致部分镜像层下载失败。通过分类检查镜像来源、更新有效镜像源、逐个测试镜像拉取，最终定位到非DockerHub来源的镜像问题。建议保留已验证镜像源，避免堆砌无效地址，并建立镜像预检清单。

服务器

容器

Docker

Redis

JSON

2026年中大促 | AI 领航 智绘未来

4核4G3M云服务器 新用户低至38元/年！

lighthouse

热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

轻量服务器 docker pull 超时排查记录-腾讯云开发者社区-腾讯云

轻量服务器 docker pull 超时排查记录

轻量服务器 docker pull 超时排查记录

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐