缓存与用量
理解 SparkCR 的缓存命中、冷启动、预热、配额和拉取历史。
缓存与用量
SparkCR 是 pull-through cache。首次请求通常需要回源，后续请求会逐步命中 Manifest 缓存和 Blob 缓存。Dashboard、History 和响应头可以帮助判断当前请求是否走到了缓存。
缓存状态
拉取历史和响应头中的缓存状态通常有这些含义：
| 状态 | 含义 |
|---|---|
HIT | 命中缓存。 |
MISS | 首次回源或缓存中没有该对象。 |
EXPIRED | 缓存已过期，已重新验证或回源。 |
BYPASS | 未缓存，直接流式代理。 |
Manifest 通常比 Blob 更早命中。Blob 首次 miss 时会流式返回给客户端，并在满足大小、完整请求和缓存水位等条件时写入持久化缓存。
为什么第一次拉取较慢
第一次拉取一张镜像时，SparkCR 需要访问公共镜像仓库获取 manifest 和 layer blob。这个过程受上游网络、上游限流、镜像大小和当前缓存水位影响。
后续拉取可能更快，原因包括：
- Manifest 已在缓存中。
- 热 blob 已提升到持久化缓存。
- 命中缓存后可减少公共镜像仓库请求。
- 配置了交付策略时，已缓存 blob 可走更合适的下载路径。
预热
平台可对常用镜像启用预热。预热会提前拉取配置中的 manifest，减少首次解析镜像标签的延迟。
预热的边界：
- 预热主要写入 Manifest 缓存。
- 不会主动下载镜像的全部 blob layer。
- 不会为预热请求记录用户 Pull History。
- 不会扣减用户配额。
如果某张镜像已经在预热列表中，但首次拉取仍有 blob miss，这是正常现象。
配额与限流
SparkCR 会按匿名 IP、登录用户、来源组和套餐等维度应用配额。匿名拉取可用，但共享出口 IP 的 CI、NAT 或集群更容易触发匿名配额。
建议：
- 长期使用时登录 SparkCR 镜像仓库。
- CI 为每个项目或 runner 创建独立 Access Token。
- 公共镜像只授予
pull:public。 - 私有镜像按需授予
pull:private和push。 - 降低同一时间的大规模并发冷拉取。
收到 429 Too Many Requests 时，检查 控制台 中的今日用量和响应里的 X-RateLimit-* 头。
查看用量
在控制台中优先查看：
| 页面 | 用途 |
|---|---|
| Dashboard | 当前配额、总请求、流量和缓存命中率。 |
| History | 最近拉取记录、上游、镜像、状态码、缓存状态和字节数。 |
| Private Registries | 私有上游的拉取和推送用量。 |
排查问题时保留这些信息：
- 完整镜像引用。
- runtime 类型和版本。
- SparkCR 访问模式：路径前缀或别名入口。
- HTTP 状态码和错误信息。
X-SparkCR-Cache、X-RateLimit-*响应头。- 对应的 Pull History 或私有上游用量记录。