Docker 配置

Docker 用户推荐直接使用 Docker Hub 镜像别名 docker.sparkcr.cn 作为镜像引用 host。这样 docker login 的凭据会用于 SparkCR 的认证交换，请求能够按登录用户使用配额和对应权益。

推荐：使用镜像别名

先使用 SparkCR 账号用户名和 Access Token 登录 Docker Hub 别名入口：

docker login docker.sparkcr.cn

拉取 Docker Hub 官方镜像时保留 library/ 命名空间：

docker pull docker.sparkcr.cn/library/hello-world:latest
docker pull docker.sparkcr.cn/library/nginx:latest

公共镜像加速使用 pull:public 权限即可。也可以使用路径前缀入口完成可认证拉取：

docker login sparkcr.cn
docker pull sparkcr.cn/docker.io/library/nginx:latest

registry-mirrors 的认证限制

Docker Engine 的 registry-mirrors 会透明代理 docker pull nginx 这类 Docker Hub 短镜像名，但该请求的逻辑 registry 仍然是 Docker Hub。即使已经执行：

docker login docker.sparkcr.cn

Docker 在 transparent mirror 拉取时也不会可靠地把为 SparkCR mirror 保存的凭据带到 SparkCR 的 token 请求。SparkCR 收不到 Basic Auth 时只能签发匿名 token，因此会出现：

• 即使已经登录 SparkCR，短镜像名拉取仍会被视为匿名请求。
• 请求计入匿名 IP 配额，而不是登录用户配额。
• CI 或共享出口网络更容易触发匿名限流。

该行为可参阅 Moby 项目问题记录：Docker is not passing auth informations when pulling from a mirror registry (moby/moby#30880)。

因此，需要使用登录用户配额或账号权益时，不要依赖 registry-mirrors；请使用上一节中的 SparkCR 镜像别名。

可选：匿名 Transparent Mirror

如果只需要让 Docker Hub 短镜像名经过 SparkCR，并接受更容易触发风控或限流的风险，可以写入 /etc/docker/daemon.json：

{
  "registry-mirrors": ["https://docker.sparkcr.cn"]
}

重启 Docker 并确认配置已加载：

sudo systemctl restart docker
docker info | grep -i "mirrors" -A 3

输出应包含：

 Registry Mirrors:
  https://docker.sparkcr.cn/

此时可以使用短镜像名，但拉取按匿名请求统计：

docker pull hello-world:latest
docker image inspect hello-world:latest

配置其他 runtime 或多个公共镜像仓库，请阅读 Runtime 配置。

其他镜像仓库

registry-mirrors 不会接管 GHCR、Quay 等其他镜像仓库。直接拉取 ghcr.io/astral-sh/uv:latest 会访问 GHCR，而不会经过 SparkCR。

要通过 SparkCR 拉取 GHCR 镜像，请使用包含原始仓库域名的完整路径：

docker login sparkcr.cn
docker pull sparkcr.cn/ghcr.io/astral-sh/uv:latest

也可以使用 GHCR 别名入口：

docker login ghcr.sparkcr.cn
docker pull ghcr.sparkcr.cn/astral-sh/uv:latest

使用别名入口时，每个入口都是不同的 registry host，需要分别执行 docker login。例如 Docker Hub 登录到 docker.sparkcr.cn，GHCR 登录到 ghcr.sparkcr.cn。其他镜像仓库的完整写法见 镜像路径速查。