如何搭建本地 Docker 镜像仓库(完整步骤)
方案简述
本地镜像仓库的核心是 Docker Registry（官方工具）。以下是两种常见方案：
方案 | 特点 | 适用场景 |
基础 Registry | 无需认证，HTTP 明文传输，简单快捷 | 本地开发测试环境 |
安全 Registry | 支持 HTTPS + 用户认证 + 持久化存储 | 生产或内网环境 |
一、基础本地仓库（快速入门）
适用于本地测试，无需 HTTPS 和认证。
步骤：
- 启动 Registry 容器
docker run -d \ -p 5000:5000 \ --name my-registry \ --restart=always \ -v /opt/registry-data:/var/lib/registry \ registry:2- -p 5000:5000：将容器端口映射到宿主机
- -v /opt/registry-data:/var/lib/registry：数据持久化到宿主机
- 配置 Docker 客户端
编辑 /etc/docker/daemon.json（Linux）或 Docker Desktop 设置（Windows/Mac）：
{ "insecure-registries": ["localhost:5000"] }- 重启 Docker 服务
sudo systemctl restart docker- 测试镜像推送/拉取
docker tag nginx:latest localhost:5000/my-nginx:v1- 推送镜像
docker push localhost:5000/my-nginx:v1- 拉取镜像
docker pull localhost:5000/my-nginx:v1- 查看仓库内容
curl http://localhost:5000/v2/_catalog二、安全增强仓库（生产推荐）
添加 HTTPS 加密 + 用户认证 + 持久化存储。
步骤：
- 创建 SSL 证书
mkdir -p certs && openssl req -newkey rsa:4096 -nodes -sha256 \ -keyout certs/domain.key -x509 -days 365 -out certs/domain.crt \ -subj "/CN=myregistry.example.com"注意：替换 myregistry.example.com 为你的仓库域名或 IP
2.创建用户密码文件
mkdir auth docker run --rm httpd:2.4-alpine \ htpasswd -Bbn username password > auth/htpasswd3.启动带认证的 Registry
docker run -d \ -p 5000:5000 \ --name secure-registry \ -v $(pwd)/certs:/certs \ -v $(pwd)/auth:/auth \ -v /opt/registry-data:/var/lib/registry \ -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \ -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \ -e REGISTRY_AUTH=htpasswd \ -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \ -e REGISTRY_AUTH_HTPASSWD_REALM="Registry Realm" \ registry:2- 客户端登录仓库
docker login myregistry.example.com:5000 # 输入 username/password- 使用仓库
docker tag nginx:latest myregistry.example.com:5000/secured-nginx:v1 docker push myregistry.example.com:5000/secured-nginx:v1三、管理仓库内容
查看仓库镜像列表：
curl -X GET -u username:password https://myregistry:5000/v2/_catalog删除镜像（需启用删除功能）：
- 启用删除：启动容器时添加 -e REGISTRY_STORAGE_DELETE_ENABLED=true
- 删除镜像： # 获取镜像的 digest curl -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \ -u user:pass -X GET \ https://registry:5000/v2/<镜像名>/manifests/<版本> # 执行删除（替换 <digest>） curl -u user:pass -X DELETE \ https://registry:5000/v2/<镜像名>/manifests/<digest>
四、可视化界面（可选）
使用开源工具 docker-registry-ui：
docker run -d --name registry-ui \
-p 8080:80 -e REGISTRY_URL=http://myregistry:5000 \
joxit/docker-registry-ui:latest访问 http://localhost:8080 即可浏览仓库内容。
常见问题解决
- 推送时报错 http: server gave HTTP response to HTTPS client
- 原因：客户端未配置不安全的仓库地址
- 解决：在 /etc/docker/daemon.json 中添加 insecure-registries（参考步骤一）
- 认证失败
- 检查 htpasswd 文件权限是否为可读
- 确保启动时正确挂载了 -v $(pwd)/auth:/auth
- 删除镜像后磁盘空间未释放
- 执行垃圾回收： docker exec secure-registry registry garbage-collect /etc/docker/registry/config.yml
总结
组件 | 作用 | 关键配置项 |
registry:2 | 核心仓库服务 | 端口映射、数据卷、环境变量 |
certs/ | 存放 TLS 证书 | REGISTRY_HTTP_TLS_CERTIFICATE/KEY |
auth/ | 存放用户密码文件 | REGISTRY_AUTH* 相关参数 |
/opt/registry-data | 持久化存储镜像数据 | 宿主机目录挂载 |
根据实际需求选择基础版或安全增强版，轻松实现本地 Docker 镜像管理！