Docker / K8s 镜像拉取失败排查：专属加速域名与白名单配置思路

本文记录一个团队环境里的镜像拉取排查思路。问题不是单个 docker pull 慢，而是 Docker Hub、GHCR、Quay、GCR、K8s、NVIDIA 等多个镜像源混在一起后，CI/CD 和 K8s 节点缺少统一、可控、可定位的镜像入口。

1. 问题现象

常见报错和现象：

bash 复制代码

docker pull nginx:alpine
# timeout / 429 / connection reset / manifest request failed

Kubernetes 里可能看到：

bash 复制代码

kubectl get pods -A | grep ImagePullBackOff
kubectl describe pod <pod-name> -n <namespace>

Kubernetes 官方文档说明，ImagePullBackOff 表示容器无法启动，因为 Kubernetes 无法拉取容器镜像；BackOff 表示 kubelet 会以递增延迟继续重试。也就是说，镜像拉取失败会直接阻塞发布链路。

2. 先区分镜像来源

不要把所有镜像都当成 Docker Hub。实际项目里常见来源如下：

来源	示例	常见场景
Docker Hub	`nginx:alpine`、`node:20-alpine`	基础镜像、Web 服务
GHCR	`ghcr.io/linuxserver/webtop`	自托管服务、开源工具
Quay	`quay.io/prometheus/prometheus`	监控、云原生组件
GCR	`gcr.io/...`	Google 生态组件
K8s	`registry.k8s.io/pause`	Kubernetes 系统组件
NVIDIA	`nvcr.io/nvidia/cuda`	GPU / CUDA 环境

Docker Hub 官方文档也明确区分不同用户类型的拉取限制：匿名用户按 IPv4 地址或 IPv6 /64 子网计算，Personal 用户也有 6 小时维度限制，付费团队和企业账号则有不同策略。共享出口 IP、CI/CD、多人开发环境都更容易撞到这类边界。

3. 公共加速入口的局限

公共镜像加速适合个人开发机快速恢复，但团队环境会多几个问题：

没法清楚知道哪个源在高频拉取。
CI、K8s、NAS、测试机可能各配各的。
共享出口 IP 出问题时，排查缺少白名单边界。
临时环境开了入口后，容易忘记收回。
多源镜像映射趋势不可见，后续容量和规则难治理。

因此，团队更需要"专属加速域名 + 源站映射 + 白名单治理"的组合。

4. 专属加速域名配置示例

以毫秒镜像专属域名为例，公开文档中确认支持 docker.io、gcr.io、ghcr.io、registry.k8s.io、nvcr.io、quay.io、mcr.microsoft.com、docker.elastic.co 等源。

图中可以看到，新增专属域名时先选择镜像原始来源，再设置域名后缀和有效期。排查时这点很重要：docker.io、ghcr.io、quay.io、registry.k8s.io 不要混成同一个问题。

按源拆分后，可以这样验证：

bash 复制代码

# Docker Hub
docker pull docker-team.d.1ms.run/nginx:alpine

# GHCR
docker pull ghcr-team.d.1ms.run/linuxserver/webtop

# Quay
docker pull quay-team.d.1ms.run/prometheus/prometheus

# Kubernetes 官方源
docker pull k8s-team.d.1ms.run/pause:3.9

# NVIDIA NGC
docker pull nvcr-team.d.1ms.run/nvidia/cuda:12.4.1-runtime-ubuntu22.04

如果是 CI/CD，建议写进变量：

yaml 复制代码

variables:
  DOCKER_REGISTRY: "docker-team.d.1ms.run"
  GHCR_REGISTRY: "ghcr-team.d.1ms.run"

build:
  script:
    - docker pull ${DOCKER_REGISTRY}/node:20-alpine
    - docker pull ${DOCKER_REGISTRY}/nginx:alpine

5. 白名单和有效期建议

专属加速域名的重点不是"域名好不好记"，而是可治理。

建议规则：

CI/CD 出口 IP 固定时，纳入白名单。
K8s 节点池出口单独记录，避免和办公网混用。
临时测试机使用指定有效期，不默认长期开放。
多源镜像按前缀拆分，方便后续查询和统计。
定期观察镜像源映射趋势，找出高频源和异常源。

6. Kubernetes 注意点

K8s 场景还要检查 imagePullPolicy：

yaml 复制代码

containers:
  - name: app
    image: docker-team.d.1ms.run/nginx:alpine
    imagePullPolicy: IfNotPresent

如果使用 :latest 或 imagePullPolicy: Always，kubelet 会更频繁地访问镜像仓库。新节点扩容、镜像缓存缺失、源站不可达都会放大问题。

7. 总结

团队镜像拉取失败，不应该只靠"换一个公共镜像源"解决。更稳的做法是：

先区分 Docker Hub、GHCR、Quay、GCR、K8s、NVIDIA 等源。
用专属加速域名统一入口。
用白名单控制出口边界。
用前缀查询和源站映射趋势做后续治理。

毫秒镜像专属域名适合放在这层：既能服务镜像拉取，又能让团队把源站映射、有效期和白名单纳入统一管理。