Docker Registry私有仓库搭建实战：内网镜像分发与安全配置

1. 为什么需要私有仓库：Registry的核心价值

1.1 Docker镜像分发的现实困境

先聊一个我在实际项目中反复遇到的问题。Docker Hub虽然是公共镜像仓库的事实标准，但在真实的生产环境里，你很快会发现几个让人头疼的痛点。

第一个痛点是拉取速度。国内网络访问Docker Hub的体验大家都懂，pull一个稍微大点的镜像，比如包含机器学习依赖或者完整中间件的镜像，动辄几个GB，慢的时候一个镜像能拖上半小时。第二个痛点是限流和稳定性。公共仓库有匿名请求限制，企业里几十上百台机器同时做CI构建、批量部署的时候，很容易触发限流，构建直接失败。第三个痛点更致命——合规和审计。在金融、政务等对安全敏感的行业，镜像从公网拉取意味着你把应用供应链的一环交给了外部，一旦镜像被污染或者仓库被攻击，整个生产环境都可能沦陷。

这几个痛点叠加在一起，就引出了一个非常自然的诉求：在你自己掌控的网络环境里，搭建一套属于自己团队的镜像仓库。这正是Docker Registry私有仓库的核心价值——它本质上是一套可以私有化部署的Docker镜像分发服务，让你的团队能够像使用Dijkstra的Git私服一样，用自己的镜像仓库来管理Docker镜像。我见过很多团队在初期用脚本scp镜像tar包，或者直接依赖公共Hub，等规模上来之后再返工，成本很高。如果你正在搭环境、做CI/CD、管理多台服务器，或者身处内网环境，这篇文章值得你看完。

1.2 私有仓库到底解决了什么问题

咱们把需求拆解得更具体一点。搭建一套私有Registry之后，你的工作流会发生几个明显的变化。

一是拉取速度的质变。镜像在局域网内分发，走的是内网带宽，多数情况下能做到秒级拉取，尤其在Kubernetes集群里，节点要拉取相同镜像时，速度差一个数量级。二是版本和权限可控。你的镜像只推送到自己的仓库，谁能拉、谁能推，通过认证和授权完全由自己决定，不再受公共仓库的限流和策略影响。三是供应链安全。你可以对推入仓库的镜像做扫描、签名，确保运行在服务器上的每一个容器镜像都能追溯到来源。

理解Registry在Docker生态中扮演的角色，有个很形象的类比：它就像Docker镜像的Git服务器。Docker命令行工具docker push、docker pull，对标的就是git push、git pull；而Registry这个服务，对标的就是GitLab或者Gitea。理解了这一层，你再看后续所有配置，思路就会特别清晰——你实际上是在“自己托管自己的软件分发中心”。

2. 搭建前的准备与方案选型

2.1 环境确认与Registry版本选择

动手之前，先把环境搞清楚。首选的操作系统是Ubuntu 20.04/22.04 LTS、Debian 11/12或者CentOS Stream 9这类主流Linux发行版。如果你是在Windows或者macOS上做开发测试，用Docker Desktop直接跑Registry容器也行，生产环境务必放在Linux服务器上。

Docker本身必须提前装好。这里不展开Docker安装全过程，但有一个关键点要提：确认Docker daemon正常运行，并且当前用户有权限执行docker命令。你可以快速验证：

bash复制docker version
docker info

如果docker version能正常输出Client和Server两段信息，说明daemon没问题。注意，很多新手只看到Client没看到Server，就以为装好了，这在Docker Desktop里经常出现，记得确认Server部分也在运行。

接下来是Registry方案选型。市面上常见的方案有两类。

第一类是官方Docker Registry镜像（registry:2），轻量、部署简单、专注于核心分发功能，适合中小团队和纯镜像管理场景。第二类是Harbor，基于Registry二次封装，自带Web UI、项目管理、RBAC权限控制、镜像复制、漏洞扫描等功能，适合企业级要求更高的场景。

如果你是个人开发者、小团队，或者只想给CI/CD提供个私有镜像源，官方Registry完全够用，本文以registry:2为例。如果需要完整的企业级功能，Harbor也值得单独写一篇，这里先不展开。

2.2 网络、存储与安全的前置规划

在敲第一条命令之前，我建议你花五分钟做一张小规划表，能省去后面不少返工时间。

网络方面，Registry默认监听5000端口，如果生产环境要对外提供服务，建议规划好域名和端口。直接用IP+端口在公司内网用没问题，但如果要走TLS证书（强烈建议），那就需要你有一个能解析到该服务器的域名，因为正规CA签发的证书是绑定域名的。当然，自签证书也行，就是客户端配置麻烦点，后面会详细讲。

存储方面，Registry默认把镜像数据存放在容器的/var/lib/registry目录，这是个数据卷。千万别图省事不挂载，否则容器一删数据就全没了，这个坑我亲自踩过。合理做法是挂载到宿主机独立目录，有条件的话挂到单独的数据盘或NAS上。

安全方面有两个选项必须提前想清楚：第一，是不是只在可信内网使用？如果不是，那必须配置TLS和基础认证，绝对不能裸奔。第二，有没有多团队隔离需求？有的话，建议直接上Harbor或者做多租户规划，避免后续迁移。我的建议是——即便是内网使用，也至少把TLS和认证配好，因为生产环境的容器里通常藏着数据库密码、API密钥等敏感信息，镜像一旦被拿到，风险极高。

3. Registry私有仓库快速搭建实操

3.1 使用官方镜像一键启动Registry

基础版搭建其实简单到令人发指，一条命令就能跑起来：

bash复制docker run -d \
  --name registry \
  -p 5000:5000 \
  -v /opt/registry/data:/var/lib/registry \
  --restart=always \
  registry:2

逐项说明一下参数含义，命令说清楚比背下来更重要。

-d表示后台运行。--name registry指定容器名，方便后续管理。关键在-p 5000:5000，把容器的5000端口映射到宿主机5000端口，Registry默认就在这个端口上提供服务。接着-v /opt/registry/data:/var/lib/registry做数据持久化，这个是整个命令里最不能省略的参数，把容器内部镜像存储目录挂载到宿主机指定目录，容器销毁重建镜像数据依然在。--restart=always让Docker守护进程在容器异常退出或宿主机重启后自动拉起来，生产环境下必须加。

等几秒钟让容器启动，然后验证一下服务是否正常：

bash复制curl http://localhost:5000/v2/

如果输出一个空JSON对象{}，恭喜你，Registry已经跑起来了。这个/v2/端点其实是Registry的API入口，能响应就说明服务在正常工作。不放心的话可以看容器日志：

bash复制docker logs registry

会看到一条类似于“listening on [::]:5000”的日志，说明一切正常。

到这里，一个最小可用的私有仓库就搭好了。是不是比想象中简单？但先别急着庆祝，直接用这个配置执行push大概率会报错，因为Docker默认走HTTPS访问仓库，而我们的Registry还只有HTTP。下面来解决这个核心问题。

3.2 客户端配置HTTP访问与insecure-registries

先明白这个问题的根源。Docker daemon与Registry通信时，默认使用HTTPS协议。我们的Registry现在只是裸HTTP服务，daemon会拒绝连接。要让daemon放行某个HTTP仓库，需要把它加入insecure-registries列表。注意，这个列表是在Docker daemon的配置里配置，不是容器里，也不是环境变量。

以Linux环境为例，编辑/etc/docker/daemon.json文件：

json复制{
  "insecure-registries": ["192.168.1.100:5000"]
}

把192.168.1.100换成你的Registry服务器实际IP。如果文件里已有其他配置项，比如镜像源，需要合并而不是覆盖，别把已有配置弄丢了。修改后重启Docker使配置生效：

bash复制systemctl restart docker

这里有个容易踩的细节：重启Docker daemon会中断当前所有容器的运行，如果服务器上有正在跑的重要容器，最好挑维护窗口操作，或者用docker update先更新容器的restart策略。

配置完之后，验证一下连通性：

bash复制curl http://192.168.1.100:5000/v2/

返回{}就说明从客户端到Registry的网络链路、daemon到Registry的HTTPS豁免都已经生效。至此，基础版可用仓库就真正就绪了。

4. 镜像推送与拉取的完整实操

4.1 给镜像打上私仓标签并推送

Registry能跑起来是一回事，能推送镜像才算真正用它干活。先说清楚一件事：Docker镜像的tag本质上是“仓库地址/镜像名:版本号”这个组合。当你执行docker pull mysql:8.0，完整含义其实是“从Docker Hub的library/mysql仓库拉取8.0标签”。如果你要让某个镜像进私有仓库，就必须把它“重命名”为私有仓库地址开头的tag。

假设你本机现在有mysql:8.0这个镜像，用docker images确认一下。然后给它打标签：

bash复制docker tag mysql:8.0 192.168.1.100:5000/mysql:8.0

这个命令不会复制镜，也不会下载新东西，只是在本地镜像列表里添加一个引用别名。接着推送：

bash复制docker push 192.168.1.100:5000/mysql:8.0

推送成功后，Registry内部就存储了这个镜像的图层数据。你会看到输出末尾有一行类似于latest: digest: sha256:xxx size: xxx的信息，这表示镜像的清单（manifest）已经上传成功。

再验证一下仓库里到底有什么，调用Registry的API：

bash复制curl http://192.168.1.100:5000/v2/_catalog

正常情况下会返回类似{"repositories":["mysql"]}的JSON。想看某个仓库的所有标签，执行：

bash复制curl http://192.168.1.100:5000/v2/mysql/tags/list

返回{"name":"mysql","tags":["8.0"]}。通过这两个API，你可以快速检查仓库状态，排障时非常有用。

4.2 拉取镜像与内网分发流程

推送到了私仓，其他机器怎么拉？假设你要在另一台服务器上部署，确保它的Docker daemon也配置了insecure-registries，然后直接拉：

bash复制docker pull 192.168.1.100:5000/mysql:8.0

如果你在推送那台机器上验证，先删掉本地镜像再拉，避免触发本地缓存：

bash复制docker rmi 192.168.1.100:5000/mysql:8.0
docker pull 192.168.1.100:5000/mysql:8.0

在内网环境下，这个拉取速度会让你觉得幸福，可能几秒钟就完成了。这背后其实是一个分层的复用机制：Docker只会下载本机没有的镜像层，网络环境好时，分发效率天然很高。

实际使用中，我见过不少团队把Registry作为构建流水线的一部分：CI里构建完镜像，push到私仓；部署阶段从私仓pull并运行。整套流程跑通之后，就跟用公共Hub一样顺手，但速度和安全性完全是两回事。

5. 生产级私有仓库进阶配置

5.1 配置TLS证书，告别HTTP裸奔

前面用insecure-registries的方式打开HTTP访问，适合测试和内网低安全要求的场景，但生产环境强烈不建议。HTTP传输镜像数据是明文，镜像内容相当于在网络里裸奔，任何人只要在网络链路上就能窃取甚至篡改。配置TLS证书后，客户端与Registry之间的通信变成加密通道，同时Docker daemon不再需要insecure-registries配置，更加安全规范。

TLS证书有两种来源：正规CA签发的证书，和自签证书。有域名的话，用Let's Encrypt这类免费正规CA签发即可，步骤大家都比较熟，这里主要说自签证书的流程。

首先在Registry服务器上生成私钥和自签证书。用openssl一次性生成：

bash复制mkdir -p /opt/registry/certs

openssl req \
  -newkey rsa:2048 \
  -nodes \
  -keyout /opt/registry/certs/domain.key \
  -x509 \
  -days 365 \
  -out /opt/registry/certs/domain.crt \
  -subj "/CN=192.168.1.100"

注意，如果直接用IP访问，CN字段填IP；如果用域名，填域名。然后重启一个带证书挂载的Registry容器：

bash复制docker run -d \
  --name registry \
  -p 5000:5000 \
  -v /opt/registry/data:/var/lib/registry \
  -v /opt/registry/certs:/certs \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  --restart=always \
  registry:2

启动后测试一下HTTPS是否生效：

bash复制curl -k https://192.168.1.100:5000/v2/

-k参数是忽略证书验证，只测TLS握手是否正常。有输出说明Registry已经在HTTPS上提供服务了。

接下来说客户端侧。如果是正规CA签发的证书，客户端什么都不用额外配置，直接用https://地址就行。如果是自签证书，客户端需要信任这个证书。这时候你在客户端机器上执行docker login，大概率会遇到证书校验失败。解决办法是把domain.crt拷到客户端，加入系统信任库。Debian/Ubuntu系统：

bash复制cp domain.crt /usr/local/share/ca-certificates/
update-ca-certificates

CentOS系统：

bash复制cp domain.crt /etc/pki/ca-trust/source/anchors/
update-ca-trust

更新完证书信任之后，再重启Docker daemon，整套链路就通了。另外提醒一下，即使自签证书，也不要把insecure-registries和TLS证书同时混用，否则Docker可能有多余的告警。

5.2 配置访问认证：htpasswd与docker login

TLS解决的是“传输加密”问题，谁还能不能推拉镜像取决于有没有认证。私有仓库不希望任何人都能以docker pull的方式拿到团队内部镜像，所以一定要加认证。

Registry官方支持基于htpasswd的Basic Auth认证方式。先在宿主机上用htpasswd生成账户密码文件：

bash复制mkdir -p /opt/registry/auth
docker run --rm --entrypoint htpasswd registry:2 -Bbn admin YourStrongPassword > /opt/registry/auth/htpasswd

说明一下这条命令的含义：registry:2镜像里内置了htpasswd工具，我们用--entrypoint参数绕过默认启动命令，直接执行它在宿主机生成密码文件。-b表示命令行直接给密码，-n表示输出到标准输出而不是文件，-B表示使用bcrypt算法加密，bcrypt算法的强度比普通MD5要好很多。生成的文件包含一行类似admin:$2y$05$...的内容。

然后启动带认证的Registry容器：

bash复制docker run -d \
  --name registry \
  -p 5000:5000 \
  -v /opt/registry/data:/var/lib/registry \
  -v /opt/registry/certs:/certs \
  -v /opt/registry/auth:/auth \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/domain.key \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  --restart=always \
  registry:2

启动后，如果你不认证直接访问API，会返回401。此时在客户端执行登录：

bash复制docker login 192.168.1.100:5000

输入之前设置的用户名密码，成功后会提示“Login Succeeded”，并且Docker会在本地~/.docker/config.json里保存认证信息，后续的push和pull会自动携带凭证。

这是整个Registry安全配置里最折磨人的一步，我刚开始配置的时候来回改各种参数，最后发现核心其实就三件事：certificate路径、key路径、auth指向的htpasswd路径。把这三点检查对，基本就不会有问题。

5.3 数据持久化、存储驱动与垃圾回收

私有仓库运行时间一长，镜像越推越多，磁盘占用会直线上升。尤其在你经常改tag重新推送的情况下，Registry内部的存储会积累很多“废弃”的镜像层。这里要澄清一个容易误解的点：Docker push同一个镜像名但新tag时，旧的图层并不会被马上清理，需要手动触发垃圾回收（GC）。

Registry的存储目录结构默认是/var/lib/registry/docker/registry/v2，里面按blobs和repositories组织数据。随着镜像数量增长，这里会占用大量磁盘空间。为了巡检方便，你可以主动看下宿主机的磁盘占用：

bash复制du -sh /opt/registry/data

如果发现占用很大，先别急着清理——回收是有讲究的。正确步骤是先用Registry自带的GC工具，注意必须先停止registry容器再执行，不然可能出问题：

bash复制docker exec registry bin/registry garbage-collect /etc/docker/registry/config.yml

输出类似“Blob purge complete”这样。看到这种信息说明空间已释放。如果你执行完发现有些镜像不能用了，那多半是操作前后镜像正在被使用，或者动了不该动的文件。GC是危险操作，建议在低峰期执行，并且先做目录快照备份。

另外，存储驱动选择也影响长期使用。Registry支持filesystem、s3、azure等存储驱动。中小团队用默认的filesystem就够，数据量大、要求高可用再上S3对象存储。生产推荐把Registry目录挂到RAID磁盘或者分布式存储上，省得后面搬迁。

5.4 可视化界面：从命令行到网页管理

纯命令行管理Repository的体验，久了确实比较枯燥。尤其团队里多个项目、多个环境、多个人推送时，没有一个Web界面来查看镜像列表和标签信息，沟通会很不方便。

这里推荐一个轻量级的方案：docker-registry-ui，它本身是一个独立的Web服务，通过环境变量指向Registry的地址即可。示例启动命令：

bash复制docker run -d \
  --name registry-ui \
  -p 8080:80 \
  -e REGISTRY_URL=http://192.168.1.100:5000 \
  --restart=always \
  joxit/docker-registry-ui:latest

启动后浏览器访问http://192.168.1.100:8080，就能看到仓库里的镜像列表，支持查看标签和删除镜像。UI界面很简洁，适合个人和小团队使用。

如果团队规模大、组织架构复杂，建议直接上Harbor。Harbor的定位是企业级镜像仓库，自带角色权限、项目隔离、镜像复制、漏洞扫描，功能比Registry完整很多。它也是Firefox在容器镜像分发这块的常用解决方案之一。不过Harbor部署重量级一点，对服务器配置要求更高，后续有机会单独展开。

6. 常见问题排查与避坑实录

6.1 问题速查表

我把日常运维里高频出现的几个问题整理成一个表，方便你对照排查：

6.2 我亲历的坑：自签证书过期与GC误删

最后分享两个我实际踩过的教训。

第一个是自签证书过期。我曾在测试环境用openssl生成了365天有效期的自签证书，用得很愉快，然后某天所有客户端突然推拉失败。排查了半天，才发现是证书到期了。从那以后我养成了两个习惯：证书快到期前提前生成新证书替换；把证书有效期直接拉长到10年，毕竟内网证书泄露风险相对可控。自签证书的过期时间设置，推荐用-days 3650。

第二个是GC操作。有一回我在镜像还在大量推送的高峰期执行了garbage-collect，过程中Registry一直报错，最后有几个正在使用的镜像出现了“manifest unknown”的异常。经历过那次之后，我再也不在高峰期碰GC了，每次操作前先备份整个/opt/registry/data目录，操作完马上验证关键镜像能否正常pull。

还有一个容易被忽视的坑是文件权限。Registry容器运行用户是root，但如果你用非root用户管理挂载目录，可能因为权限问题导致容器无法读写存储目录。解决办法是确保挂载目录对容器用户可读写，简单暴力的做法是chmod -R 777，条件是只在内网可信环境使用。生产环境建议按系统规范指定UID:GID，和容器内用户保持一致。

6.3 日常维护建议

最后给三条维护建议，帮你少走弯路。

第一，定期备份。Registry的数据目录就是全部镜像元数据加图层，定期备份这个目录就够了。镜像多的时候，全量备份耗时长占用空间大，可以考虑结合存储快照方案。

第二，监控磁盘和仓库健康状态。服务器上挂个磁盘监控，超过80%就告警，会比等推镜像失败再处理从容很多。Registry自身也有/metrics接口暴露Prometheus格式的监控指标，接入现有监控体系也不算麻烦。

第三，建立镜像命名规范。比如统一格式为registry域名/分类/项目名:tag，避免大家乱命名导致仓库混乱。用久了你会发现，命名规范往往比一堆高级功能更能提升团队协作效率。

我自己在实际使用中的体会是，Registry这套东西真正用顺之后，你会觉得它像基础设施一样不起眼，却又无比重要。团队里所有容器的交付都走它，一旦挂了，CI和部署全部停摆。所以这套仓库看似简单，但值得认真对待。配置一次之后，长期受益。