# 缓存与用量

首次拉取通常需要从原始镜像仓库下载内容，后续拉取可能因已有缓存而更快。[Dashboard](/dashboard)、[History](/history) 和响应头可以帮助你判断拉取是否命中缓存。

## 缓存状态

拉取历史和响应头中的缓存状态通常有这些含义：

| 状态 | 含义 |
| --- | --- |
| `HIT` | 命中缓存。 |
| `MISS` | 本次内容尚未缓存。 |
| `EXPIRED` | 已有缓存需要更新。 |
| `BYPASS` | 本次未使用缓存。 |

同一张镜像包含多个文件，不同文件可能显示不同的缓存状态。因此，即使部分请求已经命中缓存，整个镜像拉取仍可能需要等待下载。

## 为什么第一次拉取较慢

第一次拉取一张镜像时，SparkCR 需要访问原始镜像仓库获取内容。这个过程受网络、原始仓库限流和镜像大小影响。

后续拉取可能更快，原因包括：

- 所需内容已经在缓存中。
- 命中缓存后减少了对原始镜像仓库的请求。

## 配额与限流

SparkCR 会根据是否登录、账号套餐和访问网络应用配额或限制。匿名拉取可用，但共享出口 IP 的 CI、NAT 或集群更容易触发匿名配额。

建议：

- 长期使用时登录 SparkCR 镜像仓库。
- CI 为每个项目或 runner 创建独立 [Access Token](/tokens)。
- 公共镜像只授予 `pull:public`。
- 私有镜像按需授予 `pull:private` 和 `push`。
- 降低同一时间的大规模并发冷拉取。

收到 `429 Too Many Requests` 时，检查 [控制台](/dashboard) 中的今日用量和响应里的 `X-RateLimit-*` 头。

## 查看用量

在控制台中优先查看：

| 页面 | 用途 |
| --- | --- |
| [Dashboard](/dashboard) | 当前配额、总请求、流量和缓存命中率。 |
| [History](/history) | 最近拉取记录、来源仓库、镜像、状态码、缓存状态和字节数。 |
| [Private Registries](/settings/private-registries) | 私有镜像仓库的拉取和推送用量。 |

排查问题时保留这些信息：

- 完整镜像引用。
- runtime 类型和版本。
- SparkCR 访问模式：路径前缀或别名入口。
- HTTP 状态码和错误信息。
- `X-SparkCR-Cache`、`X-RateLimit-*` 响应头。
- 对应的拉取历史或私有镜像仓库用量记录。