docker中“命名空间不匹配”非原生报错，实指镜像全名（registry/namespace/repository:tag）拼写错误或私有仓库权限不足，导致unauthorized/not found等错误；需核对路径准确性、登录状态、项目权限及registry配置。
命名空间不匹配不是 Docker 原生报错术语，实际中它通常指向两类具体问题：一是镜像名称中组织/仓库路径（即命名空间）拼写错误或权限缺失；二是私有 registry 中项目路径与用户权限不一致，导致拉取时返回 unauthorized 或 not found，但表象类似“命名空间不存在”。这类错误不会直接提示“命名空间不匹配”，而是通过 HTTP 状态码和上下文暴露本质。
确认镜像全名是否准确
镜像名格式为 [registry-host/][namespace/][repository]:[tag]，其中 namespace 通常是组织名、项目名或用户名。常见误写包括大小写错误、下划线/短横混淆、多级路径漏写等。
- 用
docker search验证公开镜像是否存在对应命名空间：docker search --filter is-official=true nginx（查官方镜像）docker search myorg/app-server（查第三方命名空间） - 访问对应 registry 页面手动核对，例如：
→ Docker Hub：https://hub.docker.com/r/myorg/app-server
→ 私有 Harbor：https://reg.example.com/harbor-project/app-server - 注意：Docker Hub 上
library/命名空间是隐式的，docker pull nginx等价于docker pull library/nginx；但私有 registry 没有该默认前缀，必须显式写出完整路径。
检查私有 registry 的项目权限与路径一致性
在 Harbor、Nexus、GitLab Container Registry 等平台中，“命名空间”常对应一个项目（Project），而用户需被授予 pull 权限。即使镜像存在，权限不足也会表现为 unauthorized 或 repository not found。
- 登录后执行
curl -X GET -H "Authorization: Bearer $(cat ~/.docker/config.json | jq -r '.auths.\"your-registry.com\".auth' | base64 -d | cut -d: -f1):$(cat ~/.docker/config.json | jq -r '.auths.\"your-registry.com\".auth' | base64 -d | cut -d: -f2)" https://your-registry.com/v2/测试基础认证是否有效 - 确认你所属的项目（命名空间）是否启用
public拉取，或你是否被加入该项目的成员并分配了guest及以上角色 - 检查镜像 push 时使用的路径是否与 pull 路径完全一致——Harbor 对大小写敏感，且不自动补全路径层级
验证 registry 配置与镜像地址是否匹配
本地配置的镜像源（如 registry-mirrors）只作用于 Docker Hub 默认域名（registry-1.docker.io），对带 host 的自定义 registry 地址无效。若误将私有 registry 地址写进 registry-mirrors，会导致请求被错误转发。
- 运行
docker info | grep -A 5 "Registry Mirrors"，确认镜像源仅用于官方 Hub - 私有 registry 必须使用完整地址拉取：
docker pull reg.example.com/myteam/backend:1.2，不能省略reg.example.com/ - 如需跳过 TLS 校验（测试环境），需在
/etc/docker/daemon.json中明确添加："insecure-registries": ["reg.example.com:5000"]，并重启 docker
查看详细错误日志定位真实原因
Docker 报错信息往往隐藏关键线索。不要只看第一行，用 docker pull 加 -v（verbose）或结合 daemon 日志分析。
- 启用 debug 模式临时观察：
docker --debug pull reg.example.com/myteam/backend:1.2 - 查守护进程日志：
sudo journalctl -u docker.service --since "1 hour ago" | grep -i "myteam\|unauthorized\|not found" - 典型线索举例：
→unauthorized: authentication required→ 缺少 login 或 token 过期
→manifest unknown→ tag 存在但命名空间下无该镜像
→no such host或connection refused→ registry 地址 DNS 或网络不通，而非命名空间问题
