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

如果你使用 DeepSeek、元宝 AI、Copilot、ChatGPT 等 AI 工具，协助配置轩辕镜像、编写 docker pull 命令、修改 Docker Compose 镜像地址、配置镜像加速、排查镜像拉取失败、分析报错日志等问题，请先让 AI 阅读并遵守轩辕镜像的规则文档。

只需在 AI 对话中先发送下面这句话即可：

请先完整阅读并严格遵守以下文档中的全部规则与要求：

https://xuanyuan.cloud/agents.md

在未充分阅读并理解该文档前，不要生成任何命令、配置、修改建议、故障排查方案或技术回答。后续所有输出都必须严格以该文档中的规范为最高优先级执行。

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

拉取镜像提示 TAG_INVALID 或无效标签（400）怎么办？

本文适用于：

• 拉取或推送时出现 HTTP 400 与标签校验失败
• 报错含 TAG_INVALID、无效标签、'None' / 'null'
• CI/CD、脚本或 Helm 模板中镜像 tag 变量未正确赋值
• 标签长度超过 Docker Registry 规定的 128 字符上限

先搞清一点：这是标签字符串本身不合法，与镜像源无关

Registry 在收到拉取或推送请求时，会先校验 tag 格式。若 tag 为空、为 Python/JSON 的 None/null 字面量、含非法字符或超长，会直接返回 400 Bad Request 与 TAG_INVALID，不会进入真正的 manifest 查询阶段。

典型报错示例

docker pull docker.xuanyuan.run/library/nginx:None Error response from daemon: invalid reference format

Error response from daemon: manifest for nginx:null not found: manifest unknown: TAG_INVALID: invalid tag 'null'

unexpected status ... 400 Bad Request TAG_INVALID: tag length exceeds maximum of 128 characters

常见原因

CI/CD 变量为空：Jenkins、GitLab CI、GitHub Actions 中 ${IMAGE_TAG} 未设置，模板展开后变成 :None 或空 tag
脚本语言默认值泄露：Python 中 str(None) → "None"；JSON 中 null 被直接拼进镜像名
错误使用 digest 与 tag：同一引用中同时写 tag 与 @sha256:...，或 tag 部分留空
标签过长：将完整 Git commit 说明、构建 URL 等拼进 tag，超过 Registry 规定的 128 字符 上限
含非法字符：tag 中不宜包含空格、:、@ 等（digest 应使用 repo@sha256:... 形式，而非当作 tag）

处理建议

1）打印实际执行的镜像全名

在 CI 日志或脚本中输出最终镜像引用，确认 tag 部分不是空、None、null：

# 示例：部署前 echo 检查 echo "IMAGE=${IMAGE_NAME}:${IMAGE_TAG}" docker pull "${IMAGE_NAME}:${IMAGE_TAG}"

2）为 tag 设置合理默认值或校验

使用 Git commit 短 SHA（如 abc1234）或语义化版本（v1.2.3），避免裸 latest 以外的空值
在流水线中增加判断：if [ -z "$IMAGE_TAG" ]; then exit 1; fi
Python 拼接前检查：if tag is None: raise ValueError(...)

3）控制 tag 长度与字符集

tag 最长 128 字符；仅使用小写字母、数字、.、_、- 等合法字符。需要固定版本时，优先用 digest 拉取（见 digest 校验说明）。

与相近错误的区分

400 TAG_INVALID：tag 字符串格式非法（空、None、超长等）→ 修脚本/变量
manifest unknown：tag 格式合法，但仓库中不存在该标签 → 核对镜像名与 tag
422 Unknown：上游查询 manifest 时异常 → 按该文排查 Hub 状态与老镜像问题

你可能还会遇到：

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