让 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 无法访问外链，可 打开说明文档 复制全文粘贴。文档会随站点更新，复制内容可能过期，建议定期检查。
Docker 拉取提示 UNAUTHORIZED（401）怎么办？
本文适用于：
- • Docker 20+ / 24+
- • 使用 sudo 或普通用户执行 docker 命令
- • 遇到 UNAUTHORIZED 身份认证失败错误
- • 需要解决 docker login 与 docker pull 的认证不一致问题
⚠️ 重要提示
这通常是 sudo 与普通用户认证不一致导致的，不是密码错误。
快速诊断：
UNAUTHORIZED 错误 ↓ 是否使用 sudo？ ├─ 是 → 必须使用 sudo docker login └─ 否 → 普通用户 login + pull
✅ 推荐做法
统一使用同一用户身份：要么都用 sudo，要么都不用。推荐：将用户加入 docker 组，避免使用 sudo。
当您在拉取镜像时遇到 UNAUTHORIZED 错误，提示"您无法拉取该镜像，请您使用轩辕镜像用户名密码进行身份验证"，这本质上是身份认证失败问题。
错误示例
问题原因分析
原因 1：sudo 与普通用户认证不一致（最常见）
docker login 的认证信息保存在当前用户的 ~/.docker/config.json 文件中：
- • 如果您使用普通用户执行
docker login，认证信息会保存在该用户的配置文件中 - • 但使用
sudo docker pull时，Docker 会以 root 用户身份运行 - • root 用户的
~/.docker/config.json中没有认证信息，因此会返回 unauthorized 错误
原因 2：账户或密码错误
- • 使用了非轩辕镜像账户（如 GitHub、Docker Hub 或其他账户）
- • 密码输入错误或使用了其他仓库的密码
- • 密码中包含特殊字符导致 shell 解析错误
原因 3：镜像权限问题
- • 该镜像可能是私有的，只有特定账户可以访问
- • 镜像仓库路径区分大小写，确保路径完全正确
解决方案
方案 A：统一用户身份（使用 sudo）
如果您必须使用 sudo 拉取镜像，那么登录时也要使用 sudo：
⚠️ 注意：不要先普通用户登录再用 sudo pull，否则 root 没有认证信息。
方案 B：非 sudo 拉取（推荐）
如果当前用户已经加入 docker 组，可以直接使用普通用户权限：
✅ 这样登录和拉取都是同一个用户，不会出现认证不一致的问题。
方案 C：确认账户密码正确
- • 确认使用的是轩辕镜像专用账户和密码，而不是其他平台的账户
- • 如需重新生成密码，可前往轩辕镜像管理后台操作
- • 密码中如包含特殊字符，建议使用单引号包裹密码，避免 shell 解析错误
- • 确认镜像路径和标签的大小写完全正确
方案 D：验证镜像仓库权限
登录成功后，您可以尝试搜索该镜像以验证权限：
如果能够搜索到，说明您有权限访问该镜像。
💡 总结：
- ✅ 如果使用
sudo pull，也必须使用sudo login - ✅ 如果不使用 sudo，则普通用户
login+pull即可 - ✅ 确认使用的是轩辕镜像账户，并且密码正确无误
- ✅ 确认镜像路径、标签的大小写完全正确
你可能还会遇到：
本文由「轩辕镜像」维护
轩辕镜像 | Docker 镜像高效稳定拉取服务
内容基于轩辕镜像真实用户使用与实测整理