Docker Hub 镜像加速器使用说明

本服务用于加速拉取 Docker Hub 的公开镜像（例如 nginx:alpine），通过 Nginx 反代并对镜像层（blobs）做缓存。推荐使用 “Mirror 模式”，不要在镜像名里显式写域名。

推荐：Mirror 模式 manifest 短缓存 layer/blob 长缓存

Mirror Host: docker.corpa.me

一、Docker（推荐用法：Mirror 模式）大多数场景

将镜像加速器配置为 Docker 的 registry mirror，然后正常拉取 Docker Hub 镜像即可。

/etc/docker/daemon.json

{
  "registry-mirrors": ["https://docker.corpa.me"]
}

重启 Docker 并验证

sudo systemctl restart docker
docker info | sed -n '/Registry Mirrors/,+5p'

拉取示例

docker pull nginx:alpine-slim
docker pull ubuntu:22.04

说明：
1) “Mirror 模式”下，你仍然使用原始镜像名（如 nginx:alpine），Docker 会自动把 docker.io 的请求走 mirror。
2) 这种方式最兼容，也最不容易触发权限/路径问题。

三、显式写域名拉取（不推荐，但可用）需要了解 path 规则

只有在你明确需要把该服务当作“独立 registry 域名”使用时才建议这么做。注意：Docker Hub 的官方镜像需要补 library/ 前缀。

官方镜像：必须带 library/

docker pull docker.corpa.me/library/nginx:alpine-slim
docker pull docker.corpa.me/library/ubuntu:22.04

为什么会 “requested access to the resource is denied”？
你如果写成 docker.corpa.me/nginx:alpine-slim，上游会按仓库 nginx（而不是 library/nginx）去做鉴权， token scope 不匹配时就可能拒绝访问。Mirror 模式可避免此类问题。

四、Podman / Skopeo / Containerd（简要）

这些工具/运行时通常需要在各自的 registry 配置中声明 docker.io 的 mirror。

Podman（/etc/containers/registries.conf 示例片段）

[[registry]]
prefix = "docker.io"
location = "registry-1.docker.io"

[[registry.mirror]]
location = "docker.corpa.me"
insecure = false

Containerd（/etc/containerd/config.toml 示例片段）

[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
  endpoint = ["https://docker.corpa.me"]

五、常见问题（FAQ）

TLS/证书报错：确保证书链正确、客户端信任 CA；或临时用 HTTP + insecure（不推荐）。
命中率低：小磁盘是预期现象；只有“热点层”会被保留。建议拉取常用基础镜像作为预热。
磁盘担心写爆：建议把缓存目录单独挂载到限额文件系统（loop 镜像或独立分区），实现硬性上限。
权限 denied：优先使用 Mirror 模式；显式域名拉官方镜像要带 library/。