让 AI 帮你使用轩辕镜像？ · 展开查看说明

如果你用 DeepSeek、元宝AI、Copilot 等 AI 代为编写轩辕镜像的 docker pull、修改 compose 镜像地址，或排查拉取失败等问题，请让 AI 先读规则再动手，只要在 AI 对话里直接发送下面这句话即可：

生成 docker pull、修改 compose 的 image，或排查拉取失败前，请先阅读并严格遵守 https://xuanyuan.cloud/agents.md 中的规则。

国内用户首推元宝 AI、DeepSeek 的深度思考模式，不推荐豆包 AI；Cursor 等编辑器可在对话 @ 该链接，或加入 User Rules。若 AI 无法访问外链，可打开说明文档复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。

docker pull 出现 422 Unknown 怎么办？

本文适用于：

• 拉取时出现 unexpected status from HEAD request ... 422 Unknown
• 报错为泛化的 422，且没有明确的 schema 1、manifest unknown 等关键字
• 已在 Docker Hub 确认镜像存在，但经加速域名拉取仍失败
• 需与「Schema 1 已废弃」和「manifest unknown」区分

422 Unknown 是什么？

代理向 Docker Hub（或对应上游仓库）查询 manifest 时，上游返回了 HTTP 500 等异常响应，且无法明确判断是「镜像不存在」还是「镜像格式过老（Schema 1）」，因此返回 422 Unknown，避免误报 404 让用户以为只是 tag 写错。

典型报错示例

docker pull docker.xuanyuan.run/library/php:5.4.39-fpm Error response from daemon: unexpected status from HEAD request to https://docker.xuanyuan.run/v2/library/php/manifests/5.4.39-fpm: 422 Unknown

域名可能是你的专属加速地址；422 Unknown 是代理层对上游异常的统一封装，需结合镜像本身进一步判断。

常见原因（按概率）

原因	说明
镜像版本极老	如 `php:5.4.39-fpm`，上游返回 500 但未命中 Schema v1 的明确识别规则 → 参考 Schema 1 已废弃
镜像不存在，但上游异常	Docker Hub 偶发返回 500 而非标准 404，代理无法断定 → 核对 tag 后稍后重试
Docker Hub 临时故障	上游短暂不稳定，同一镜像过几分钟可能恢复
私有 / 受限镜像	需登录或权限不足的镜像，上游可能返回非标准错误而非 404

建议排查顺序

422 Unknown
  ↓
到 Docker Hub 确认镜像名、标签是否存在
  ↓ 标签很老（2017 年前后）
参考 Schema 1 文档，换较新版本
  ↓ 标签正常、较新
等待 5～10 分钟后重试
  ↓ 仍失败
提交工单（附完整 pull 命令与报错）

1）先到 Docker Hub 核对镜像与标签

在浏览器打开对应仓库页面，确认标签是否存在、最后更新时间是否很早。也可在本站搜索镜像名辅助确认（见站内搜不到镜像）。

2）若是老版本镜像 → 换新版或自行导入

详见 Manifest Schema 1 已废弃。换镜像源无法解决格式过老的问题。

3）若确认镜像正常 → 等待后重试

Docker Hub 或网络链路偶发异常时，等待 5～10 分钟 后再次执行相同的 docker pull。避免脚本在短时间内高频重试同一失败标签（可能触发 429 限流）。

4）仍失败 → 提交工单

通过工单反馈，请附上：完整 docker pull 命令、完整终端报错、docker version 输出，以及已在 Hub 确认标签存在的截图或链接。

注意：客户端过旧导致的协议问题，通常表现为 406 或 410，而不是 422。若报错含 OCI index 字样，请参考 406 OCI index 客户端过旧。

你可能还会遇到：

本文由「轩辕镜像」维护
轩辕镜像 | Docker 镜像高效稳定拉取服务
内容基于轩辕镜像真实用户使用与实测整理