# Docker 配置

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

## 推荐：使用镜像别名

先使用 SparkCR 账号用户名和 [Access Token](/tokens) 登录 Docker Hub 别名入口：

```bash
docker login docker.sparkcr.cn
```

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

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

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

```bash
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。即使已经执行：

```bash
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)](https://github.com/moby/moby/issues/30880)。

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

## 可选：匿名 Transparent Mirror

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

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

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

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

输出应包含：

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

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

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

配置其他 runtime 或多个公共镜像仓库，请阅读 [Runtime 配置](runtime-config.md)。

## 其他镜像仓库

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

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

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

也可以使用 GHCR 别名入口：

```bash
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`。其他镜像仓库的完整写法见 [镜像路径速查](registry-reference.md)。