私有Docker Registry认证失败 凭据正确仍被拒绝故障排查

核心故障原因 #

该问题最常见的诱因是启动容器时的auth目录挂载配置错误，导致容器内无法读取到宿主机上生成的有效htpasswd文件。
Docker 命令行的卷挂载有严格的识别规则：

• 宿主机路径以/开头（绝对路径）、或以.//../开头（显式相对路径）时，才会被识别为绑定挂载，直接映射宿主机对应目录的真实文件到容器内
• 宿主机路径不带路径前缀（比如你命令中写的auth:/auth）时，Docker会将其识别为自身管理的命名卷，首次启动时会初始化一个空的存储卷挂载到容器的/auth路径，完全不会读取你在宿主机home目录下创建的./auth/htpasswd文件。

你在服务端日志中看到的认证失败记录，是Registry开启htpasswd认证后读取不到有效凭据文件时的默认行为——所有请求无论携带什么凭据，都会被直接拒绝，和你提交的密码正确与否没有关系。

修复步骤 #

1. 清理当前异常运行的Registry容器

sudo docker stop registry
sudo docker rm registry

2. 回到你最初创建auth目录的home路径，启动容器时将auth目录的挂载参数改为明确的绑定挂载格式，推荐直接写绝对路径避免路径解析歧义：如果你的auth目录在当前用户home路径下，就将挂载参数替换为/home/你的实际用户名/auth:/auth，如果要使用相对路径则必须写为./auth:/auth。
   修正后的完整启动命令参考：

sudo docker run -d --restart=always --name registry \
-v "/home/你的实际用户名/auth:/auth" \
-e "REGISTRY_AUTH=htpasswd" \
-e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
-e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
-v "/etc/letsencrypt/:/certs/" \
-e REGISTRY_HTTP_ADDR=0.0.0.0:443 \
-e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/live/domain.ext/cert.pem \
-e REGISTRY_HTTP_TLS_KEY=/certs/live/domain.ext/privkey.pem \
-p 443:443 \
registry:2

3. 容器启动后先进入容器校验htpasswd文件是否正常映射：

sudo docker exec registry cat /auth/htpasswd

如果输出内容和你宿主机上~/auth/htpasswd的文件内容完全一致，再执行docker login 你的域名测试认证即可正常通过。

补充排查项（修正挂载后仍异常时检查） #

• 调整宿主机auth目录权限，避免容器内进程无读权限：执行chmod -R 755 ~/auth给所有用户分配目录和文件的读权限
• 检查htpasswd文件内容，不要存在多余空行、BOM头，用户名不要包含大写字母、特殊符号，避免Registry的htpasswd解析模块识别异常
• 目前httpd:2镜像用-B参数生成的bcrypt哈希和最新版registry:2完全兼容，不需要调整哈希算法参数。

内容的提问来源于stack exchange，提问作者Diane M