Windows10下htpasswd认证Docker私有仓库登录返回401 Unauthorized错误

数据老陈

2026-10-29

Docker私有仓库配置基础认证后登录返回401的排查方案

认证配置有效性校验

关键矛盾点：正常启用基础认证的registry，不带凭证访问/v2/_catalog接口会返回401要求身份校验。当前可以无密码直接访问该接口，说明认证配置未被容器内的registry进程正确识别，问题根源并非单纯的密码输入错误。
第一步先进入容器核对环境变量：
执行命令 docker exec -it hub.local env 逐一确认以下参数值准确，无多余引号、特殊字符：
- REGISTRY_AUTH=htpasswd
- REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm
- REGISTRY_AUTH_HTPASSWD_PATH=/auth/.htpasswd
- REGISTRY_HTTP_ADDR=0.0.0.0:5000
Windows环境常见配置坑：在CMD/PowerShell执行docker run传递环境变量时，无意义的双引号会被Docker直接作为值的一部分传入容器，比如实际识别到的变量名是"REGISTRY_AUTH（带前置引号）、值是htpasswd"（带后置引号），导致配置完全失效。Windows下启动容器时，仅对带空格的变量值添加双引号，其余参数无需额外加引号，修正后的启动命令参考：
docker run -d -p 5000:5000 --name hub.local -v C:\localHub\registry:/var/lib/registry -v C:\localHub\auth:/auth -e REGISTRY_AUTH=htpasswd -e REGISTRY_AUTH_HTPASSWD_REALM="Registry Realm" -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/.htpasswd -e REGISTRY_HTTP_ADDR=0.0.0.0:5000 registry:2

当前使用的 $apr1$ 开头的哈希是Apache服务常用的apr1 MD5格式，Docker Registry v2的htpasswd认证组件仅支持bcrypt算法生成的哈希值，不兼容apr1、普通MD5、SHA等其他哈希格式，即使文件路径映射完全正确，也会因为算法不匹配返回401错误。
合规认证文件生成方案：无需依赖Windows本地工具或在线生成器，直接通过临时容器生成bcrypt格式的凭证，执行以下命令即可在本地auth目录生成符合要求的.htpasswd文件：
docker run --entrypoint htpasswd httpd:2 -Bbn muskan 你的实际登录密码 > C:\localHub\auth\.htpasswd
合规的文件内容会以muskan:$2y$作为开头，是registry组件唯一能识别的哈希格式。
文件格式注意：确保生成的文件为无BOM的UTF-8编码，行尾符为LF格式，避免Windows默认的CRLF行尾、BOM头被解析为密码哈希的一部分，导致匹配失败。

Docker Registry容器内的服务进程以uid 1001的非root用户运行，Windows版Docker Desktop的卷挂载默认不会自动给容器内进程分配对应文件的读取权限，即使文件路径映射正确，也可能因为权限不足无法读取.htpasswd文件，导致认证逻辑失效。
权限校验方法：执行docker exec -it hub.local cat /auth/.htpasswd，确认可以正常输出文件内容，如果返回Permission denied，需要调整Windows本地auth目录的权限设置，给系统已认证用户组分配读取权限。

内容的提问来源于stack exchange，提问作者Muskan Paliwal