FAQ 与故障排查

快速判断

no basic auth credentials

runtime 没有保存对应 host 的登录信息，或登录 host 与镜像引用 host 不一致。

路径前缀模式：

docker login sparkcr.net
docker pull sparkcr.net/docker.io/library/hello-world:latest

别名入口：

docker login docker.sparkcr.net
docker pull docker.sparkcr.net/library/hello-world:latest

unauthorized: authentication required

检查：

1. Access Token 是否复制完整。
2. Token 是否已撤销或过期。
3. 用户名是否填写 SparkCR 账号用户名。
4. runtime 是否把凭据写到了正确的配置目录。

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

已登录但 docker pull nginx 仍按匿名流量计费

如果 Docker 通过 /etc/docker/daemon.json 的 registry-mirrors 透明拉取 Docker Hub 短镜像名，docker pull nginx 的逻辑 registry 仍是 Docker Hub。Docker 不会可靠地把为 SparkCR mirror 保存的登录凭据发送到 SparkCR 的 token 请求，因此即使已经登录，该请求也会按匿名 IP 配额处理。

需要使用登录用户配额或账号权益时，请改为使用 SparkCR 镜像别名：

docker login docker.sparkcr.net
docker pull docker.sparkcr.net/library/nginx:latest

429 Too Many Requests

收到 429 时：

1. 登录后重试，避免走匿名 IP 配额。
2. 检查 控制台 中的今日用量。
3. 降低 CI 并发拉取。
4. 查看 缓存与用量，确认是否存在大量冷拉取或并发拉取。

响应中的 X-RateLimit-* 头可用于判断剩余额度和重置时间。

Docker Hub 官方镜像怎么写

Docker Hub 官方镜像需要补 library/：

docker pull sparkcr.net/docker.io/library/hello-world:latest

不要写成：

docker pull sparkcr.net/docker.io/hello-world:latest

更多镜像仓库写法见 镜像路径速查。

私有镜像仓库拉取或推送失败

优先检查：

• 是否已经在 Private Registries 页面创建私有镜像仓库。
• 镜像路径是否使用页面生成的镜像地址。
• Access Token 是否包含 pull:private 或 push。
• 私有镜像仓库是否允许当前操作。
• 原始仓库账号是否对目标仓库有拉取或推送权限。

CI 中登录成功但构建仍失败

优先检查：

• docker login 和 docker build 是否在同一个 job 中执行。
• SPARKCR_REGISTRY 是否包含正确路径前缀。
• Dockerfile 中的基础镜像是否已经改写为 SparkCR 路径。
• 并发 job 是否触发配额限制。

首次拉取为什么仍然慢

首次请求通常需要从原始镜像仓库下载内容。后续请求在所需内容已有缓存时可能更快。更多细节见 缓存与用量。