# Runtime 配置

运行时配置决定镜像拉取是否经过 SparkCR。当前站点的镜像仓库入口是 `sparkcr.cn`。

## 镜像路径约定

路径前缀模式使用 `REGISTRY/upstream/repository:tag`，别名入口使用 `alias.REGISTRY/repository:tag`。不同上游的完整写法见 [镜像路径速查](registry-reference.md)。

## Docker

Docker 的 `registry-mirrors` 只接受 registry host。路径前缀模式下配置为 SparkCR 主域名：

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

也可以用 `jq` 快速写入：

```bash
sudo test -f /etc/docker/daemon.json || echo '{}' | sudo tee /etc/docker/daemon.json >/dev/null
sudo jq '."registry-mirrors" = ["https://sparkcr.cn"]' /etc/docker/daemon.json | sudo tee /etc/docker/daemon.json.tmp >/dev/null
sudo mv /etc/docker/daemon.json.tmp /etc/docker/daemon.json
```

重启 Docker：

```bash
sudo systemctl restart docker
```

登录并拉取 Docker Hub 官方镜像：

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

别名入口：

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

## containerd

containerd 推荐使用 `certs.d` hosts 配置。

路径前缀模式：

```bash
sudo mkdir -p /etc/containerd/certs.d/docker.io
sudo tee /etc/containerd/certs.d/docker.io/hosts.toml >/dev/null <<'EOF'
server = "https://docker.io"

[host."https://sparkcr.cn/docker.io"]
  capabilities = ["pull", "resolve"]
EOF
sudo systemctl restart containerd
```

验证：

```bash
sudo ctr images pull --hosts-dir /etc/containerd/certs.d docker.io/library/hello-world:latest
```

使用别名入口时，把 host 改为 `docker.sparkcr.cn`。

## Podman

Podman 使用 containers/image 的 `registries.conf`。

写入 `/etc/containers/registries.conf.d/sparkcr.conf`：

```toml
[[registry]]
prefix = "docker.io"
location = "docker.io"

[[registry.mirror]]
location = "sparkcr.cn/docker.io"
insecure = false
```

登录并拉取：

```bash
podman login sparkcr.cn
podman pull docker.io/library/hello-world:latest
```

别名入口：

```toml
[[registry]]
prefix = "docker.io"
location = "docker.io"

[[registry.mirror]]
location = "docker.sparkcr.cn"
insecure = false
```

## CRI-O

CRI-O 与 Podman 使用同一套 `registries.conf` 格式。

写入 `/etc/containers/registries.conf.d/sparkcr.conf`：

```toml
[[registry]]
prefix = "docker.io"
location = "docker.io"

[[registry.mirror]]
location = "sparkcr.cn/docker.io"
insecure = false
```

重启 CRI-O：

```bash
sudo systemctl restart crio
```

验证：

```bash
sudo crictl pull docker.io/library/hello-world:latest
```

## 多上游配置

containerd 每个上游需要一个 `certs.d/<registry>/hosts.toml`。例如 `registry.k8s.io`：

```bash
sudo mkdir -p /etc/containerd/certs.d/registry.k8s.io
sudo tee /etc/containerd/certs.d/registry.k8s.io/hosts.toml >/dev/null <<'EOF'
server = "https://registry.k8s.io"

[host."https://sparkcr.cn/registry.k8s.io"]
  capabilities = ["pull", "resolve"]
EOF
sudo systemctl restart containerd
```

Podman 和 CRI-O 对每个上游追加一个 `[[registry]]` 块：

```toml
[[registry]]
prefix = "registry.k8s.io"
location = "registry.k8s.io"

[[registry.mirror]]
location = "sparkcr.cn/registry.k8s.io"
insecure = false
```

## 认证

SparkCR 使用 Access Token 作为运行时登录密码：

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

用户名填写 SparkCR 账号邮箱，密码填写 [Access Token](/tokens)。公共镜像加速使用 `pull:public` 即可；私有上游拉取需要 `pull:private`；私有上游推送需要 `push`。

匿名拉取可用，但会按客户端 IP 使用匿名配额。

## 常见检查

配置后仍直连上游时，优先检查：

- 配置文件路径是否正确
- runtime 服务是否已重启
- 镜像引用是否包含正确上游
- 登录 host 是否和镜像引用 host 一致