视觉算法环境 Docker 镜像拉取失败排查

一、问题现象

这次复现一个智能驾驶视觉算法环境，第一步不是跑模型，而是拉容器：

bash 复制代码

docker compose pull

结果 perception-api、ros-bag-runner、metrics 都停在 Pulling，最后出现：

text 复制代码

context deadline exceeded

这时业务代码还没执行，摄像头数据也没进入管线。问题发生在镜像拉取阶段。

二、环境里有哪些镜像

视觉算法环境不是一个镜像，通常会拆成几类：

服务	作用	排查重点
CUDA runtime	GPU 运行环境	CUDA 版本是否固定
PyTorch	模型推理/评测	是否匹配 CUDA
ROS2	数据回放/消息通信	镜像是否能稳定拉取
OpenCV/FFmpeg	视频处理	基础镜像体积较大
Prometheus	指标采集	Quay 类镜像
pause/CoreDNS	K8s 基础组件	新节点是否有缓存

如果只处理 Docker Hub，NVIDIA、Quay、K8s 组件仍然可能在部署时卡住。

三、按来源逐条验证

先不要改算法代码，先验证镜像来源：

bash 复制代码

docker pull docker.1ms.run/osrf/ros:humble-desktop
docker pull docker.1ms.run/pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime
docker pull nvcr.1ms.run/nvidia/cuda:12.4.1-runtime-ubuntu22.04
docker pull quay.1ms.run/prometheus/prometheus:v2.54.1
docker pull k8s.1ms.run/pause:3.9

如果某一类镜像拉取失败，先处理对应来源，不要直接排查模型逻辑。

四、compose 配置示例

毫秒镜像（1ms.run）适合处理这种多源镜像入口统一问题。示例：

yaml 复制代码

services:
  ros-bag-runner:
    image: docker.1ms.run/osrf/ros:humble-desktop
    volumes:
      - ./bags:/data/bags

  infer-worker:
    image: docker.1ms.run/pytorch/pytorch:2.5.1-cuda12.4-cudnn9-runtime
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: ["gpu"]

  cuda-check:
    image: nvcr.1ms.run/nvidia/cuda:12.4.1-runtime-ubuntu22.04
    command: ["nvidia-smi"]

  metrics:
    image: quay.1ms.run/prometheus/prometheus:v2.54.1

执行：

bash 复制代码

docker compose pull
docker compose up -d

五、K8s 节点预拉

如果环境要上 Kubernetes，新节点建议先预拉：

bash 复制代码

crictl pull k8s.1ms.run/pause:3.9
crictl pull k8s.1ms.run/coredns/coredns:v1.10.1
crictl pull nvcr.1ms.run/nvidia/cuda:12.4.1-runtime-ubuntu22.04
crictl pull quay.1ms.run/prometheus/prometheus:v2.54.1

如果这里失败，后面很可能看到：

text 复制代码

ImagePullBackOff

先解决节点镜像链路，再排查 Pod 配置。

六、排查顺序

建议顺序：

固定镜像 tag。
列出 compose / Helm 中所有镜像。
按 Docker Hub、NVIDIA、Quay、K8s 分组。
使用 docker.1ms.run、nvcr.1ms.run、quay.1ms.run、k8s.1ms.run 做预检。
docker compose pull 通过后再启动服务。
K8s 新节点提前做 crictl pull。
容器正常后再看 CUDA、显存、模型文件和数据路径。

七、总结

智能驾驶视觉算法环境部署时，镜像拉取失败会被误判成算法问题。

把多源镜像入口提前统一，能先排除 Docker Hub、NVIDIA、Quay、K8s 等来源带来的不确定性。毫秒镜像适合放在这个预检步骤里，先让容器环境稳定，再进入模型和业务排查。