# 容器镜像

面向校内用户的容器 Registry 代理缓存服务。

## 服务范围

本服务仅面向浙江大学校内网络提供，无需登录。

本服务设有白名单，仅放行白名单内的镜像。白名单以**已在国内备案**、提供 `m.daocloud.io` 镜像服务的公开列表 [DaoCloud public-image-mirror 项目的 allows.txt](https://github.com/DaoCloud/public-image-mirror/blob/main/allows.txt) 为参考，来确保所放行的镜像**合规且安全**。如果需要的镜像不在白名单中，可以前往 [DaoCloud/public-image-mirror](https://github.com/DaoCloud/public-image-mirror) 或 [ZJUSCT/mirrors.zju.edu.cn](https://github.com/ZJUSCT/mirrors.zju.edu.cn) 提交 issue 申请添加。

当前提供以下上游 Registry 的代理缓存：

| Registry                     | 代理路径前缀                                      |
| ---------------------------- | ------------------------------------------------- |
| Docker Hub                   | `registry.mirrors.zjusct.io/hub.docker.com/`      |
| GitHub Container Registry    | `registry.mirrors.zjusct.io/ghcr.io/`             |
| Quay                         | `registry.mirrors.zjusct.io/quay.io/`             |
| NVIDIA Container Registry    | `registry.mirrors.zjusct.io/nvcr.io/`             |
| Kubernetes Registry          | `registry.mirrors.zjusct.io/registry.k8s.io/`     |
| GitLab Container Registry    | `registry.mirrors.zjusct.io/registry.gitlab.com/` |
| Amazon ECR Public Gallery    | `registry.mirrors.zjusct.io/public.ecr.aws/`      |
| Microsoft Artifact Registry  | `registry.mirrors.zjusct.io/mcr.microsoft.com/`   |
| Elastic Container Registry   | `registry.mirrors.zjusct.io/docker.elastic.co/`   |
| Google Container Registry    | `registry.mirrors.zjusct.io/gcr.io/`              |
| Kubernetes 旧版 GCR          | `registry.mirrors.zjusct.io/k8s.gcr.io/`          |
| Google US Container Registry | `registry.mirrors.zjusct.io/us.gcr.io/`           |
| LinuxServer.io               | `registry.mirrors.zjusct.io/lscr.io/`             |
| OSGeo Docker Registry        | `registry.mirrors.zjusct.io/docker.osgeo.org/`    |

其中 Docker Hub 的几个别名也有提供，例如 `docker.io`、`registry-1.docker.io`

## 快速使用

将完整原镜像名放在 `registry.mirrors.zjusct.io/` 后面即可，例如：

```console
docker pull registry.mirrors.zjusct.io/ghcr.io/owner/image:tag
docker pull registry.mirrors.zjusct.io/registry.k8s.io/pause:3.10
docker pull registry.mirrors.zjusct.io/quay.io/prometheus/prometheus:latest
```

可用于 Docker、Podman、containerd、Kubernetes、Compose 和其他 OCI 镜像工具：

```yaml
image: registry.mirrors.zjusct.io/hub.docker.com/library/redis:7
```

Docker Hub 的镜像名通常省略 Registry 和官方镜像的 `library/` 命名空间，使用代理时必须补全：

| 原镜像名 | 代理镜像名 |
| --- | --- |
| `ubuntu:24.04` | `registry.mirrors.zjusct.io/hub.docker.com/library/ubuntu:24.04` |
| `library/nginx:stable` | `registry.mirrors.zjusct.io/hub.docker.com/library/nginx:stable` |
| `prom/prometheus:latest` | `registry.mirrors.zjusct.io/hub.docker.com/prom/prometheus:latest` |

规则：没有 Registry 域名时补上 `hub.docker.com/`；只有一个路径段时再补上 `library/`；最后添加 `registry.mirrors.zjusct.io/`。

## 配置客户端

如果只使用 Docker Hub，也可以配置客户端，让原镜像名继续可用。长配置见下方的展开内容。

<details>
<summary>Docker Engine / Docker Desktop</summary>

将以下字段合并到 `/etc/docker/daemon.json`；Docker Desktop 在 **Settings → Docker Engine** 中配置：

```json
{
  "registry-mirrors": ["https://docker.mirrors.zjusct.io"]
}
```

Linux 使用 systemd 时重启 Docker；Rootless Docker 通常使用
`~/.config/docker/daemon.json` 和 `systemctl --user restart docker`。
此配置只代理 Docker Hub，其他 Registry 仍使用上面的完整代理名称。Docker 可能在代理失败时回退到 Docker Hub 直连。
</details>

<details>
<summary>Podman / Buildah / Skopeo</summary>

将以下配置保存为 `/etc/containers/registries.conf.d/99-zju-mirrors.conf`，个人配置可保存到 `~/.config/containers/registries.conf.d/99-zju-mirrors.conf`：

```toml
[[registry]]
prefix = "docker.io"
location = "registry.mirrors.zjusct.io/hub.docker.com"

[[registry]]
prefix = "ghcr.io"
location = "registry.mirrors.zjusct.io/ghcr.io"

[[registry]]
prefix = "quay.io"
location = "registry.mirrors.zjusct.io/quay.io"

[[registry]]
prefix = "registry.k8s.io"
location = "registry.mirrors.zjusct.io/registry.k8s.io"
```

按需为其他已代理 Registry 添加相同的 `prefix` 和 `location` 映射。配置不会修改 Docker daemon 或 Kubernetes 的 containerd。建议使用带 Registry 域名的完整名称：

```console
podman pull docker.io/library/ubuntu:24.04
skopeo inspect docker://registry.k8s.io/pause:3.10
```
</details>

<details>
<summary>containerd（包括 Kubernetes 节点）</summary>

为 Docker Hub 创建 `/etc/containerd/certs.d/docker.io/hosts.toml`：

```toml
server = "https://registry-1.docker.io"

[host."https://docker.mirrors.zjusct.io"]
  capabilities = ["pull", "resolve"]
```

让 CRI 插件读取 `/etc/containerd/certs.d`，在 `/etc/containerd/config.toml` 合并对应版本的配置：

```toml
# containerd 2.x，配置版本 3
[plugins."io.containerd.cri.v1.images".registry]
  config_path = "/etc/containerd/certs.d"

# containerd 1.x，配置版本 2
[plugins."io.containerd.grpc.v1.cri".registry]
  config_path = "/etc/containerd/certs.d"
```

首次修改 `config_path` 后重启 containerd。K3s、RKE2 等发行版请使用其提供的 Registry 配置入口。其他 Registry 使用完整代理名称。
</details>

<details>
<summary>独立 BuildKit / Docker Buildx</summary>

在 `buildkitd.toml` 中配置 Docker Hub：

```toml
[registry."docker.io"]
  mirrors = ["docker.mirrors.zjusct.io"]
```

加载配置并重启 buildkitd；Buildx 的 `docker-container` driver 可这样创建 builder：

```console
docker buildx create --name zju-mirror --driver docker-container --buildkitd-config ./buildkitd.toml --use
docker buildx inspect --bootstrap
```
</details>