1. 为什么私有镜像库不是"可选项"而是"必选项"
很多团队在容器化初期都是直接使用公共镜像仓库，拉个基础镜像、推个业务镜像，看起来一切都很顺畅。但只要团队规模超过三五个人，或者项目进入需要多环境部署的阶段，公共仓库的短板就会集中暴露出来。我第一次意识到这个问题，是在一个内部服务频繁迭代的项目里——每次构建都要从公共仓库拉取基础镜像，网络抖动导致构建失败的概率高得离谱，更别提镜像层被反复下载浪费的带宽和时间。
私有镜像库解决的第一个问题就是速度与稳定性。把镜像存在内网服务器上，拉取走的是局域网带宽，延迟从几百毫秒降到个位数毫秒，构建流水线的成功率肉眼可见地提升。第二个问题是可控性：公共仓库的镜像可能被删除、被覆盖，甚至被投毒，而私有库里的每一个镜像都是你自己推上去的，标签怎么打、什么时候清理，完全由你说了算。第三个问题是安全边界：内部业务镜像包含代码、配置甚至密钥，推到公共仓库等于把家底亮给所有人看，私有库天然把访问控制在团队内部。
Docker Registry 就是官方提供的最轻量的私有镜像库实现。它本身就是一个容器镜像，跑起来只需要一条命令，没有复杂的依赖，也不需要额外的数据库（默认使用本地文件系统存储）。对于中小团队来说，它足够用；对于大团队来说，它也是理解镜像仓库工作原理的最佳起点。这篇文章我会从零开始，把 Registry 的搭建、配置、认证、日常运维和踩坑经验完整讲一遍，所有步骤都经过实际验证，你可以直接照着操作。
提示：本文面向已经会用 Docker 基本命令、但对镜像仓库内部机制不太熟悉的读者。如果你连
docker push都没用过，建议先花半小时熟悉镜像的拉取和推送流程，再来看这篇。
2. Registry 的部署方式与存储后端选型
2.1 三种部署形态的取舍
Registry 的部署方式大致有三种：单容器直接运行、Docker Compose 编排、集成到编排系统。单容器方式最简单，适合快速验证和极小规模使用；Compose 方式能同时管理 Registry 和认证服务，适合正式环境；集成到编排系统则适合已经有成熟容器平台的团队。
我个人的建议是：先用单容器跑通，再用 Compose 固化配置。原因很简单，单容器方式能让你最快看到效果，建立信心；而 Compose 方式把配置、认证、存储挂载都写进文件，方便版本管理和迁移。直接上编排系统反而容易在初期被各种概念绕晕。
单容器启动的命令长这样：
docker run -d \ --name registry \ -p 5000:5000 \ -v /data/registry:/var/lib/registry \ --restart=always \ registry:2这条命令做了四件事：后台运行、把容器 5000 端口映射到宿主机、把镜像数据挂载到宿主机/data/registry目录、设置自动重启。挂载这一步非常关键，如果不挂载，容器一删镜像全丢，这是新手最容易踩的坑。
2.2 存储后端的选择逻辑
Registry 默认使用本地文件系统存储镜像，这对大多数场景已经够用。但如果你有以下需求，就需要考虑其他存储后端：
| 存储后端 | 适用场景 | 优点 | 缺点 |
|---|---|---|---|
| 本地文件系统 | 单机、小规模 | 零配置、性能好 | 无法多节点共享 |
| S3 兼容对象存储 | 多节点、大规模 | 可扩展、高可用 | 需要额外服务 |
| 云厂商对象存储 | 云上部署 | 托管、省心 | 有费用、依赖厂商 |
本地文件系统的性能其实相当不错，因为镜像层就是一堆文件，读写直接走磁盘。我实测过，在普通机械硬盘上推送一个 500MB 的镜像大约需要 8 到 12 秒，换成 SSD 能降到 3 秒左右。如果你的团队只有十几个人、镜像总量在几百 GB 以内，本地存储完全够用，没必要为了"看起来更专业"去上对象存储。
注意：本地文件系统存储的 Registry 只能单节点运行，因为多个节点无法共享同一份文件。如果你需要高可用，必须换对象存储后端，这是架构层面的限制，不是配置能解决的。
2.3 配置文件的结构与关键字段
Registry 的配置文件是一个 YAML 文件，默认路径是/etc/docker/registry/config.yml。单容器运行时可以通过挂载覆盖它。一个典型的配置长这样：
version: 0.1 log: level: info formatter: text storage: filesystem: rootdirectory: /var/lib/registry delete: enabled: true http: addr: :5000 headers: X-Content-Type-Options: [nosniff] health: storagedriver: enabled: true interval: 10s threshold: 3这里有几个字段值得展开说。storage.delete.enabled默认是false，意味着你推送的镜像标签即使删了，底层数据也不会被回收，磁盘会一直涨。把它设为true之后，才能通过 API 真正删除镜像数据。http.headers里的X-Content-Type-Options是一个安全头，防止浏览器对响应内容做 MIME 类型嗅探，虽然 Registry 主要给 Docker 客户端用，但加上没坏处。health段配置了存储驱动的健康检查，每 10 秒检查一次，连续 3 次失败就标记为不健康，配合编排系统的健康探针很有用。
3. 让 Registry 支持 HTTPS 与基础认证
3.1 为什么必须上 HTTPS
Docker 客户端默认只信任 HTTPS 的镜像仓库。如果你用 HTTP 访问 Registry，客户端会直接报错，除非在客户端的daemon.json里把该地址加入insecure-registries列表。但insecure-registries是一个"临时方案"，它意味着你的镜像传输是明文的，任何能抓包的人都能看到镜像内容，包括可能存在的敏感配置。
正式环境必须上 HTTPS。最省事的做法是用自签名证书，虽然浏览器会警告，但 Docker 客户端可以通过把 CA 证书放到/etc/docker/certs.d/<registry域名>/目录下来信任它。如果你有内部 CA，用内部 CA 签发更规范。
生成自签名证书的命令：
mkdir -p /certs openssl req -newkey rsa:4096 -nodes -sha256 \ -keyout /certs/registry.key \ -x509 -days 3650 \ -out /certs/registry.crt \ -subj "/C=CN/ST=Beijing/L=Beijing/O=Internal/CN=registry.internal"这里-days 3650表示证书有效期 10 年，内部使用足够。-subj里的CN必须和客户端访问 Registry 时用的域名一致，否则证书校验会失败。比如你用registry.internal访问，CN 就得是registry.internal，用 IP 访问就得把 IP 写进 SAN 扩展里，这一点后面踩坑部分会详细说。
3.2 用 htpasswd 做基础认证
光有 HTTPS 还不够，Registry 默认没有任何认证，任何人都能推拉镜像。最轻量的认证方案是 HTTP Basic Auth，用htpasswd生成密码文件。
docker run --rm --entrypoint htpasswd \ httpd:2 -Bbn myuser mypassword > /auth/htpasswd这条命令用httpd镜像里的htpasswd工具生成一个 bcrypt 加密的密码条目。-B表示用 bcrypt，-b表示从命令行读密码，-n表示输出到标准输出。生成的htpasswd文件里是一行用户名:哈希值的内容。
然后修改 Registry 配置，加上认证段：
auth: htpasswd: realm: basic-realm path: /auth/htpasswdrealm是认证域的名称，客户端在提示输入密码时会显示这个字符串，随便起一个有意义的名字就行。path指向挂载进容器的密码文件路径。
3.3 完整的 Compose 编排文件
把 HTTPS 和认证整合起来，用 Compose 管理最清晰：
version: '3' services: registry: image: registry:2 container_name: registry restart: always ports: - "5000:5000" environment: REGISTRY_AUTH: htpasswd REGISTRY_AUTH_HTPASSWD_REALM: basic-realm REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd REGISTRY_HTTP_TLS_CERTIFICATE: /certs/registry.crt REGISTRY_HTTP_TLS_KEY: /certs/registry.key volumes: - /data/registry:/var/lib/registry - /auth:/auth - /certs:/certs这里用环境变量覆盖配置，比挂载整个配置文件更灵活，因为环境变量优先级更高，改起来也方便。REGISTRY_HTTP_TLS_CERTIFICATE和REGISTRY_HTTP_TLS_KEY分别指向证书和私钥，Registry 启动时会自动加载并启用 HTTPS。
启动之后，用curl -k https://registry.internal:5000/v2/测试，如果返回{}就说明服务正常。-k是跳过证书校验，因为自签名证书 curl 默认不信任。
4. 客户端配置与镜像推拉全流程
4.1 让 Docker 客户端信任自签名证书
服务端配好了 HTTPS，客户端还得信任证书。Docker 客户端会从/etc/docker/certs.d/<registry地址>/目录下读取 CA 证书。注意这里的<registry地址>必须和你在docker push时用的地址完全一致，包括端口号。
mkdir -p /etc/docker/certs.d/registry.internal:5000 cp /certs/registry.crt /etc/docker/certs.d/registry.internal:5000/ca.crt文件名必须是ca.crt，这是 Docker 的硬性约定。放好之后不需要重启 Docker 服务，客户端在连接时会自动读取。如果你用的是内部 CA 签发的证书，把 CA 的根证书放进去；如果是自签名证书，证书本身就是 CA，直接放进去即可。
4.2 登录、打标签、推送的完整链路
客户端配置好之后，操作流程就三步：登录、打标签、推送。
docker login registry.internal:5000 docker tag myapp:latest registry.internal:5000/team/myapp:v1.0.0 docker push registry.internal:5000/team/myapp:v1.0.0docker login会提示输入用户名密码，登录成功后凭据会保存在~/.docker/config.json里。docker tag的作用是给本地镜像起一个"带仓库地址的别名"，Docker 根据这个别名决定推送到哪里。team/myapp是仓库路径，v1.0.0是标签，这种命名方式方便按团队和项目组织镜像。
拉取镜像同样简单：
docker pull registry.internal:5000/team/myapp:v1.0.04.3 镜像命名规范与标签策略
镜像命名看起来是小事，但团队协作中命名混乱会带来很大麻烦。我建议采用<registry地址>/<团队或项目>/<服务名>:<标签>的三段式结构。标签策略上，永远不要只用latest，因为latest会被覆盖，无法追溯。推荐同时打多个标签：
docker tag myapp:latest registry.internal:5000/team/myapp:v1.0.0 docker tag myapp:latest registry.internal:5000/team/myapp:20240115-abc1234 docker push registry.internal:5000/team/myapp:v1.0.0 docker push registry.internal:5000/team/myapp:20240115-abc1234v1.0.0是语义化版本，方便人读；20240115-abc1234是日期加提交哈希，方便追溯。两个标签指向同一个镜像层，不会额外占用存储空间，因为 Registry 按内容寻址，相同内容只存一份。
提示：
docker push时如果只推了一个标签，另一个标签不会自动推送。必须显式推送每个标签，或者用docker push --all-tags推送所有标签。
5. 日常运维：清理、备份与监控
5.1 镜像删除的正确姿势
Registry 的删除分两步：先删标签，再回收数据。直接删标签只是让标签不可见，底层数据还在。要真正释放空间，需要开启删除功能并执行垃圾回收。
删除标签的 API 调用：
# 获取镜像的 digest curl -u myuser:mypassword -k \ https://registry.internal:5000/v2/team/myapp/manifests/v1.0.0 \ -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \ -I | grep Docker-Content-Digest # 用 digest 删除 curl -u myuser:mypassword -k -X DELETE \ https://registry.internal:5000/v2/team/myapp/manifests/<digest>这里必须用 digest 而不是标签来删除，因为标签可以被重新指向，digest 才是内容的唯一标识。-I表示只取响应头，Docker-Content-Digest头里就是 digest 值。
删完之后，在 Registry 容器里执行垃圾回收：
docker exec registry registry garbage-collect /etc/docker/registry/config.yml垃圾回收会扫描所有镜像层，把没有被任何 manifest 引用的层删掉。这个过程会遍历整个存储目录，镜像多的时候可能跑几分钟，建议在低峰期执行。
5.2 数据备份的两种思路
备份 Registry 数据有两种思路：冷备份和热备份。冷备份是停掉 Registry 容器，直接打包/data/registry目录，简单可靠但服务会中断。热备份是不停服务，用rsync增量同步数据目录，但可能因为同步过程中有写入导致数据不一致。
我的做法是：日常用 rsync 做增量同步到备用机，每周做一次冷备份。rsync 命令：
rsync -avz --delete /data/registry/ backup-host:/backup/registry/--delete表示删除目标端多余的文件，保持两边一致。注意这个操作有风险，如果源目录被误删，目标端也会跟着删，所以建议加--backup参数保留被删文件的副本。
5.3 监控指标与告警项
Registry 暴露了 Prometheus 格式的指标，在配置里开启：
metrics: enabled: true path: /metrics开启后访问https://registry.internal:5000/metrics就能看到指标。重点关注的几个：
| 指标名 | 含义 | 告警阈值建议 |
|---|---|---|
| registry_storage_filesystem_bytes | 存储占用字节数 | 超过磁盘 80% |
| registry_http_requests_total | 请求总数 | 突增或突降 |
| registry_http_request_duration_seconds | 请求耗时 | P99 超过 2 秒 |
存储占用是最关键的指标，因为 Registry 不会自动清理，磁盘满了服务就挂了。我建议设置两个阈值：80% 时告警提醒清理，90% 时紧急告警。请求耗时的突增往往意味着存储后端出了问题，比如磁盘 IO 瓶颈。
6. 那些让我熬夜排查的坑
6.1 证书 CN 与访问地址不一致
这个坑我踩过两次。第一次是用 IP 访问 Registry，但证书的 CN 是域名，Docker 客户端报x509: certificate is valid for registry.internal, not 192.168.1.100。第二次是加了端口号，证书里没包含端口信息，又报错。
解决办法是生成证书时把 IP 和域名都写进 SAN 扩展：
openssl req -newkey rsa:4096 -nodes -sha256 \ -keyout /certs/registry.key \ -x509 -days 3650 \ -out /certs/registry.crt \ -subj "/CN=registry.internal" \ -addext "subjectAltName=DNS:registry.internal,IP:192.168.1.100"-addext是 OpenSSL 1.1.1 以上版本才支持的参数，如果你的版本较老，需要用配置文件的方式。加上 SAN 之后，无论用域名还是 IP 访问，证书校验都能通过。
6.2 磁盘写满导致服务不可用
Registry 对磁盘写满的容错很差。磁盘一满，推送直接失败，而且日志里可能只报一个模糊的 IO 错误。更麻烦的是，如果垃圾回收过程中磁盘满了，可能留下不一致的中间状态。
预防措施有三个：设置磁盘配额、配置监控告警、定期清理。磁盘配额可以用文件系统的 quota 功能，或者简单点，把 Registry 数据目录单独挂一个分区。监控告警前面说了，这里重点说定期清理。
我写了一个清理脚本，每周跑一次，删除 30 天前的临时标签：
#!/bin/bash REGISTRY="registry.internal:5000" USER="myuser" PASS="mypassword" REPOS=$(curl -s -u $USER:$PASS -k https://$REGISTRY/v2/_catalog | jq -r '.repositories[]') for repo in $REPOS; do TAGS=$(curl -s -u $USER:$PASS -k https://$REGISTRY/v2/$repo/tags/list | jq -r '.tags[]') for tag in $TAGS; do if [[ $tag == tmp-* ]]; then DIGEST=$(curl -s -u $USER:$PASS -k -I \ https://$REGISTRY/v2/$repo/manifests/$tag \ -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \ | grep -i docker-content-digest | awk '{print $2}' | tr -d '\r') curl -s -u $USER:$PASS -k -X DELETE https://$REGISTRY/v2/$repo/manifests/$DIGEST fi done done这个脚本依赖jq解析 JSON，删除所有以tmp-开头的标签。你可以根据自己的标签规范调整匹配规则。跑完脚本后再执行垃圾回收，磁盘空间就释放了。
6.3 并发推送时的 500 错误
在高并发推送场景下，Registry 偶尔会返回 500 错误。排查后发现是文件系统层面的竞争：多个推送同时写同一个 blob 的临时文件，导致冲突。这个问题在 Registry 2.7 之后的版本有所改善，但没完全消除。
缓解办法有两个：客户端重试和限制并发。客户端重试可以在 CI 流水线里配置，比如推送失败后等 5 秒重试，最多重试 3 次。限制并发则是在流水线层面控制，不要让太多构建任务同时推送。
for i in 1 2 3; do docker push registry.internal:5000/team/myapp:v1.0.0 && break echo "推送失败，5 秒后重试..." sleep 5 done这个简单的重试逻辑能解决大部分偶发的 500 错误。如果重试三次还失败，那大概率不是并发问题，需要查 Registry 日志。
6.4 垃圾回收期间的服务中断
垃圾回收会遍历整个存储目录，期间如果有推送请求进来，可能因为文件被锁定而失败。Registry 官方文档建议在垃圾回收前把服务设为只读，但配置起来比较麻烦。
我的做法是：在低峰期执行垃圾回收，并提前在团队群里通知。如果团队有跨时区成员，就选一个大多数人不在工作的时间。另外，垃圾回收不要频繁执行，每月一次足够，频繁执行反而增加风险。
注意：垃圾回收是不可逆操作，执行前务必确认备份是最新的。我见过有人垃圾回收跑到一半磁盘满了，结果部分镜像层被删、部分没删，整个仓库处于不一致状态，最后只能从备份恢复。
7. 从单机到多节点的演进思路
单机 Registry 跑稳之后，如果团队规模扩大或者对可用性要求提高，就需要考虑多节点方案。多节点的核心问题是存储共享：多个 Registry 实例必须访问同一份镜像数据，否则推送到 A 节点的镜像在 B 节点拉不到。
最直接的方案是换 S3 兼容的对象存储。Registry 原生支持 S3 协议，配置里把storage段换成：
storage: s3: accesskey: <access-key> secretkey: <secret-key> region: us-east-1 bucket: my-registry-bucket rootdirectory: /registry这样多个 Registry 实例可以同时读写同一个 bucket，前面挂一个负载均衡器分发请求，就实现了水平扩展。对象存储的另一个好处是自带冗余，不用担心单块磁盘损坏。
如果不想引入对象存储，也可以用 NFS 共享文件系统。但 NFS 的性能和稳定性不如对象存储，尤其是在高并发场景下，NFS 的锁机制容易成为瓶颈。我实测过，NFS 后端的 Registry 在 10 个并发推送时就会出现明显的延迟抖动，而对象存储后端在 50 个并发下依然平稳。
演进过程中还有一个容易被忽略的点：认证的统一。单机时用 htpasswd 文件没问题，多节点时每个节点都要同步这个文件，改密码就得改所有节点。这时候应该换成集中式认证，比如对接 LDAP 或者 OAuth2。Registry 支持通过auth.token配置对接外部认证服务，具体配置涉及签发密钥和验证逻辑，篇幅所限这里不展开，但思路是让认证从 Registry 中剥离出去，交给专门的认证服务处理。
最后分享一个我在实际运维中总结的小技巧：给 Registry 的存储目录单独挂一块盘，并设置磁盘使用率告警。这样即使清理不及时，也能在磁盘写满之前收到告警，有时间从容处理。镜像仓库这种基础设施，出问题时往往影响整个团队的交付效率，提前做好监控比事后救火划算得多。
