使用 Docker Registry 镜像搭建私有仓库并配置 htpasswd 认证是最轻量可控方案：生成 htpasswd 文件、挂载 config.yml 启动容器，客户端配置 insecure-registries 后登录推送镜像，再通过 API 验证及排查常见错误。
用 Docker 官方 Registry 镜像快速搭建私有仓库，并通过 htpasswd 实现基础用户名密码认证，是最轻量、最可控的方案。
一、拉取并运行带认证的 Registry 容器
Registry 默认不启用认证，需挂载配置文件并指定认证方式。推荐使用 auth: htpasswd 方式，简单可靠。
- 生成 htpasswd 文件（例如创建用户
admin，密码123456）：mkdir -p /opt/registry && htpasswd -Bbn admin 123456 > /opt/registry/htpasswd - 准备配置文件
/opt/registry/config.yml：
version: 0.1
log:
level: info
fields:
service: registry
storage:
delete:
enabled: true
filesystem:
rootdirectory: /var/lib/registry
http:
addr: :5000
headers:
X-Content-Type-Options: [nosniff]
auth:
htpasswd:
realm: basic-realm
path: /etc/registry/htpasswd
- 启动容器（注意挂载配置和 htpasswd 文件）：
docker run -d \<br> --restart=always \<br> --name registry \<br> -v /opt/registry/config.yml:/etc/registry/config.yml \<br> -v /opt/registry/htpasswd:/etc/registry/htpasswd \<br> -v /opt/registry/data:/var/lib/registry \<br> -p 5000:5000 \<br> registry:2
二、客户端登录与推送镜像
本地 Docker 客户端需先登录，才能 push/pull 私有仓库镜像。注意：若 Registry 使用非 HTTPS，默认只允许 localhost 或添加 insecure-registries 配置。
- 修改 Docker daemon 配置（如 Ubuntu 在
/etc/docker/daemon.json）：{ "insecure-registries": ["your-host-ip:5000"] }
修改后执行sudo systemctl restart docker - 登录：
docker login your-host-ip:5000（输入 admin/123456） - 打标签并推送（以 nginx 为例）：
docker tag nginx:alpine your-host-ip:5000/my-nginx<br>docker push your-host-ip:5000/my-nginx
三、验证与常见问题
成功推送后，可通过 API 或浏览器访问 http://your-host-ip:5000/v2/_catalog 查看镜像列表（需认证，可用 curl 带 -u 参数）。
- 401 Unauthorized？检查 htpasswd 路径是否挂载正确、realm 是否匹配、客户端是否已 login
- 404 or “unknown blob”？确认镜像 tag 是否包含完整地址（如
ip:port/repo:tag），且 Registry 存储目录有写权限 - push 报错 “no basic auth credentials”？说明未 login 或 daemon.json 未生效，可执行
docker info | grep -i insecure确认配置加载
四、进阶建议（可选）
生产环境建议补充以下措施提升安全性与可用性：
- 用 Nginx 反向代理 + TLS，替换自签名证书或对接 Let’s Encrypt，彻底避免 insecure-registries 配置
- 将 htpasswd 文件改为定期更新或对接 LDAP（通过外部 auth 服务如 dex + nginx-auth-module）
- 启用垃圾回收：
docker exec registry registry garbage-collect /etc/registry/config.yml，清理未引用的层 - 配合 Prometheus + Grafana 监控 Registry 的请求延迟、存储用量、错误率等指标
