身份认证失败（UNAUTHORIZED）错误

本文适用于：

• Docker 20+ / 24+
• 使用 sudo 或普通用户执行 docker 命令
• 遇到 UNAUTHORIZED 身份认证失败错误
• 需要解决 docker login 与 docker pull 的认证不一致问题

⚠️ 重要提示

这通常是 sudo 与普通用户认证不一致导致的，不是密码错误。

快速诊断：

UNAUTHORIZED 错误
  ↓
是否使用 sudo？
  ├─ 是 → 必须使用 sudo docker login
  └─ 否 → 普通用户 login + pull

✅ 推荐做法

统一使用同一用户身份：要么都用 sudo，要么都不用。推荐：将用户加入 docker 组，避免使用 sudo。

当您在拉取镜像时遇到 UNAUTHORIZED 错误，提示"您无法拉取该镜像，请您使用轩辕镜像用户名密码进行身份验证"，这本质上是身份认证失败问题。

错误示例

Error response from daemon: Head "https://docker.xuanyuan.run/v2/homeassistant/home-assistant/manifests/latest": unauthorized: {"errors":[{"code":"UNAUTHORIZED","message":"您无法拉取该镜像，请您使用轩辕镜像用户名密码进行身份验证。","detail":[{"Type":"repository","Name":"library/*","Action":"pull"}]}]}

问题原因分析

原因 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 docker login -u 您的账户 -p '您的密码' docker.xuanyuan.run

sudo docker pull docker.xuanyuan.run/镜像名:标签

⚠️ 注意：不要先普通用户登录再用 sudo pull，否则 root 没有认证信息。

方案 B：非 sudo 拉取（推荐）

如果当前用户已经加入 docker 组，可以直接使用普通用户权限：

docker login -u 您的账户 -p '您的密码' docker.xuanyuan.run

docker pull docker.xuanyuan.run/镜像名:标签

✅ 这样登录和拉取都是同一个用户，不会出现认证不一致的问题。

方案 C：确认账户密码正确

• 确认使用的是轩辕镜像专用账户和密码，而不是其他平台的账户
• 如需重新生成密码，可前往轩辕镜像管理后台操作
• 密码中如包含特殊字符，建议使用单引号包裹密码，避免 shell 解析错误
• 确认镜像路径和标签的大小写完全正确

方案 D：验证镜像仓库权限

登录成功后，您可以尝试搜索该镜像以验证权限：

docker search docker.xuanyuan.run/镜像名

如果能够搜索到，说明您有权限访问该镜像。

💡 总结：

✅ 如果使用 sudo pull，也必须使用 sudo login
✅ 如果不使用 sudo，则普通用户 login + pull 即可
✅ 确认使用的是轩辕镜像账户，并且密码正确无误
✅ 确认镜像路径、标签的大小写完全正确

你可能还会遇到：

本文由「xuanyuan.cloud」维护
专注国内 Docker / 镜像 / Registry 网络问题
内容基于真实用户环境与实测