# 快速开始

本指南帮助你在本机完成一次通过 SparkCR 拉取公共镜像的最短路径。当前站点的镜像仓库入口是 `sparkcr.cn`。

## 准备工作

你需要：

- 一个 [SparkCR 账号](/register)
- 已安装 Docker、containerd 或 Podman 之一

## 选择镜像引用方式

SparkCR 支持两种常见引用方式：

| 模式 | 示例 | 适合场景 |
| --- | --- | --- |
| 路径前缀 | `sparkcr.cn/docker.io/library/hello-world:latest` | 推荐默认使用，命令最统一 |
| 别名入口 | `docker.sparkcr.cn/library/hello-world:latest` | 更接近原生 Registry 写法 |

下方 Docker 快速路径使用别名入口；需要统一不同上游的命令格式时，可以使用路径前缀模式。

## 创建 Access Token

1. [登录 SparkCR 控制台](/login)。
2. 打开 [`Access Token`](/tokens) 页面。
3. 创建一个用于本机或 CI 的访问令牌。
4. 公共镜像拉取只需要默认的 `pull:public` 权限。
5. 私有上游镜像和推送场景稍后再单独创建令牌。
6. 复制令牌明文。明文只展示一次。

后续命令中：

- `<email>` 替换为你的账号邮箱
- `<access-token>` 替换为刚创建的访问令牌
- SparkCR 镜像仓库入口由当前站点提供：`sparkcr.cn`

## Docker 快速路径

Docker 快速路径使用 Docker Hub 的别名入口：`docker.sparkcr.cn`。

配置 Docker Hub mirror：

```json
{
  "registry-mirrors": ["https://docker.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://docker.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
```

（可选）登录 SparkCR：

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

未登录用户也可以拉取公共镜像，但可能受到匿名配额或风控限制。长期使用、CI 或共享出口网络建议登录后使用。用户名填写 SparkCR 账号邮箱，密码填写 Access Token。

拉取第一张镜像：

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

## 验证结果

检查镜像是否已拉取：

```bash
docker image inspect docker.sparkcr.cn/library/hello-world:latest
```

也可以检查 Registry V2 认证挑战：

```bash
curl -i https://docker.sparkcr.cn/v2/
```

未登录时返回 `401 Unauthorized` 是正常现象。关键是响应中应包含 `WWW-Authenticate: Bearer ...`。

## 下一步

- 需要确认不同上游的镜像写法：阅读 [镜像路径速查](registry-reference.md)。
- 需要配置 containerd、Podman 或多个公共镜像仓库：阅读 [Runtime 配置](runtime-config.md)。
- 需要接入 Kubernetes 集群：阅读 [Kubernetes 集群配置](kubernetes.md)。
- 需要在流水线中使用：阅读 [CI/CD 集成](ci-cd.md)。
- 需要拉取或推送私有镜像：阅读 [私有镜像仓库](private-registries.md)。
- 需要理解缓存命中、配额和拉取历史：阅读 [缓存与用量](cache-and-usage.md)。