1. 项目概述与核心价值

最近在折腾容器化部署，发现镜像仓库（Registry）的选型和运维是个绕不开的话题。无论是个人开发测试，还是团队协作、生产环境发布，一个稳定、高效、安全的私有镜像仓库都是基础设施里的关键一环。网上开源方案不少，但真正要落地，从选型、部署到日常运维，每一步都有不少细节需要注意。今天就来聊聊我最近在用的一个方案，它基于一个名为 mcparmory/registry 的镜像，这个镜像本身是对 Docker 官方 Registry 镜像的一个封装和增强，特别适合那些希望快速搭建一个功能相对完善、配置管理清晰的私有仓库的场景。

简单来说， mcparmory/registry 项目提供了一个“开箱即用”的 Docker Registry 部署方案。它不仅仅是把官方的 registry:2 镜像打个包，更重要的是，它预置了一套我认为比较合理的默认配置，集成了诸如身份认证（通过 Nginx 反向代理和 htpasswd ）、TLS 加密传输等生产环境常用的功能，并且通过环境变量和配置文件的方式，让管理和定制变得非常清晰。对于中小团队或者个人开发者而言，这意味着你不需要从零开始去研究 Nginx 如何与 Registry 配合、如何生成证书、如何配置用户密码，这个项目已经帮你把“最佳实践”的骨架搭好了，你只需要填充一些属于自己环境的具体参数（比如域名、证书路径、用户列表），就能快速获得一个可用的服务。

它的核心价值在于“标准化”和“易用性”。在容器生态里，官方 Registry 镜像提供了最核心的存储和分发 API，但它像一块“裸板”，很多外围功能需要你自己集成。 mcparmory/registry 则像是一个“开发板”，把电源、接口、基础驱动都给你焊好了，你接上显示器（你的域名和证书）就能跑起来。这大大降低了私有仓库的入门和维护门槛，让你能把精力更集中在业务镜像的构建和发布流程上，而不是反复调试基础设施的配置。

2. 核心架构与组件解析

2.1 整体服务栈构成

mcparmory/registry 项目的典型部署架构并不复杂，但每个组件都承担着明确且关键的角色。整个服务栈以 Docker Compose 为核心编排工具，通常包含以下几个核心服务：

1. Registry 服务 ：这是核心，基于 Docker 官方的 registry:2 镜像运行，负责实际的容器镜像的存储、管理和分发。它通过 RESTful API 响应客户端的 docker push 和 docker pull 等命令。
2. Nginx 反向代理 ：这是项目的关键增强点。官方 Registry 支持基本的 HTTP 认证，但在生产环境中，我们通常需要更灵活、更强大的认证和访问控制，以及 TLS 终止。Nginx 在这里扮演了“网关”和“安全卫士”的角色。
   • TLS/SSL 终止 ：所有来自外部的 HTTPS 请求首先到达 Nginx，由 Nginx 完成解密，然后以 HTTP 形式将请求转发给后端的 Registry 服务。这简化了 Registry 本身的配置，并统一了证书管理。
   • 基础认证 ：Nginx 可以配置 auth_basic ，使用 htpasswd 文件来管理用户名和密码。这是实现私有仓库访问控制最直接的方式。
   • 负载均衡与高可用 ：虽然在这个基础配置中不突出，但 Nginx 的架构为未来扩展（如在它后面部署多个 Registry 实例）预留了可能性。
3. 数据持久化卷 ：Registry 存储的镜像数据（Blobs 和 Manifests）以及 Nginx 的认证文件（ htpasswd ）都需要持久化存储，通常通过 Docker Volume 或绑定挂载主机目录来实现，确保服务重启后数据不丢失。

这个架构的优势在于职责分离。Registry 专心做它最擅长的镜像存储和分发；Nginx 处理网络接入、安全和访问控制。这种模式清晰、稳定，也是社区公认的实践。

2.2 关键配置文件剖析

项目的易用性很大程度上体现在其预设的配置模板上。我们主要关注两个文件： docker-compose.yml 和 Nginx 的配置文件（通常是 nginx/registry.conf ）。

docker-compose.yml 解析： 这个文件定义了服务的运行方式。一个典型的片段如下所示：

version: '3.8'
services:
  registry:
    image: registry:2
    container_name: my-registry
    restart: unless-stopped
    volumes:
      - ./data/registry:/var/lib/registry
    environment:
      REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /var/lib/registry
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: Registry Realm
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
    networks:
      - registry-net
    depends_on:
      - nginx

  nginx:
    image: nginx:alpine
    container_name: registry-nginx
    restart: unless-stopped
    ports:
      - "5043:443"
    volumes:
      - ./nginx/registry.conf:/etc/nginx/conf.d/default.conf:ro
      - ./auth:/auth:ro
      - ./certs:/certs:ro
      - ./data/nginx/logs:/var/log/nginx
    networks:
      - registry-net

networks:
  registry-net:
    driver: bridge

• 端口映射 ： 5043:443 是关键。它将宿主机的 5043 端口映射到 Nginx 容器的 443 端口。这意味着外部通过 https://your-domain:5043 来访问仓库。使用非标准端口（如5043）是常见的做法，可以避免与主机上其他服务的443端口冲突。
• 卷挂载 ：
  • ./nginx/registry.conf:/etc/nginx/conf.d/default.conf:ro ：将自定义的 Nginx 配置挂载进去，覆盖默认配置。
  • ./auth:/auth:ro 和 ./certs:/certs:ro ：分别挂载认证文件和证书目录。 ro （只读）权限保证了容器的安全性。
  • ./data/registry:/var/lib/registry ：持久化存储镜像数据。
• 环境变量 ：传递给 Registry 容器的环境变量，如 REGISTRY_AUTH_HTPASSWD_PATH ，指明了认证文件的位置。注意，这里路径是容器内的路径（ /auth/htpasswd ），对应宿主机挂载的 ./auth 目录。

Nginx 配置 ( nginx/registry.conf ) 解析： 这个文件是安全与访问控制的核心。

server {
    listen 443 ssl http2;
    server_name registry.your-domain.com;

    ssl_certificate /certs/fullchain.pem;
    ssl_certificate_key /certs/privkey.pem;

    # 推荐的安全强化配置
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
    ssl_prefer_server_ciphers off;

    client_max_body_size 0; # 禁用客户端大小限制，便于推送大镜像
    chunked_transfer_encoding on;

    location / {
        # 基础认证
        auth_basic "Registry Authentication Required";
        auth_basic_user_file /auth/htpasswd;

        # 代理到后端 Registry 服务
        proxy_pass http://registry:5000;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 以下配置对 Docker Client 兼容性很重要
        proxy_read_timeout 900;
        proxy_buffering off;
        proxy_request_buffering off;
    }
}

• server_name ：这里必须改成你实际访问仓库的域名或IP。Docker Client 对证书的校验非常严格，如果这里配置的是域名，那么客户端也必须用相同的域名访问，否则会报证书错误。
• ssl_certificate ：指向挂载的证书文件。通常需要包含完整证书链的 fullchain.pem 和私钥 privkey.pem 。你可以使用 Let‘s Encrypt 的证书，或者生成自签名证书（仅用于测试或内网）。
• client_max_body_size 0; ：这一行至关重要。Docker 镜像可能很大（几个GB），Nginx 默认对客户端请求体大小有限制（通常是1M）。设置为 0 表示禁用这个限制，允许推送任意大小的镜像。
• proxy_pass http://registry:5000; ：注意这里的 registry 是 Docker Compose 中定义的服务名，Docker 的内部 DNS 会将其解析为对应容器的 IP。端口 5000 是 Registry 服务的默认监听端口。
• proxy_buffering off; 和 proxy_request_buffering off; ：这两个配置对于稳定地上传和下载大文件很有帮助，可以避免代理层缓冲带来的内存问题和超时问题。

注意 ： auth_basic 是一种简单有效的认证方式，但它传输的是 Base64 编码的密码，在纯 HTTP 下是明文，因此必须与 HTTPS（TLS）结合使用。这也是为什么这个架构强制要求配置 TLS 的原因。

3. 从零开始部署实操指南

3.1 环境准备与前置条件

在开始之前，你需要准备以下几样东西：

1. 一台 Linux 服务器 ：可以是云服务器（如 AWS EC2、腾讯云 CVM）或本地虚拟机。建议使用 Ubuntu 20.04/22.04 LTS 或 CentOS 7/8 等常见发行版。确保有 root 或 sudo 权限。
2. Docker 与 Docker Compose ：这是运行基础。确保已经安装最新稳定版的 Docker Engine 和 Docker Compose Plugin（V2）。可以通过 docker --version 和 docker compose version 来验证。
3. 一个域名（可选但推荐） ：如果你希望从外网访问，最好拥有一个域名，并配置好 DNS 解析，将域名（例如 registry.your-company.com ）指向你的服务器公网 IP。如果仅在内网使用，可以直接使用服务器 IP 地址，但使用自签名证书时，客户端配置会稍麻烦。
4. SSL/TLS 证书 ：
   • 生产环境 ：申请一个正式的证书，例如从 Let‘s Encrypt 免费获取。你可以使用 certbot 工具自动化完成。
   • 测试/内网环境 ：可以生成自签名证书。虽然 Docker 客户端会警告，但可以通过将 CA 证书添加到客户端的信任链来解决。

3.2 逐步部署流程

假设我们的项目目录为 /opt/docker-registry 。

步骤一：获取项目文件 通常，你需要从 mcparmory/registry 项目的代码仓库（如 GitHub）获取 docker-compose.yml 和 nginx/registry.conf 等配置文件模板。你可以直接克隆仓库或下载压缩包。

sudo mkdir -p /opt/docker-registry
cd /opt/docker-registry
# 假设你通过某种方式获得了配置文件，这里以手动创建为例
mkdir -p nginx auth certs data/registry data/nginx/logs

步骤二：配置 Nginx 将上文的 nginx/registry.conf 内容写入 /opt/docker-registry/nginx/registry.conf 。 务必修改 server_name 为你实际的域名或IP 。

步骤三：生成认证文件 使用 htpasswd 命令创建用户。如果系统没有该命令，可以安装 apache2-utils (Ubuntu) 或 httpd-tools (CentOS)。

# 安装工具（Ubuntu/Debian）
sudo apt-get update && sudo apt-get install -y apache2-utils

# 创建第一个用户（用户名为 admin）
sudo htpasswd -Bbc ./auth/htpasswd admin your_strong_password_here
# -B 强制使用 bcrypt 加密（更安全），-c 表示创建新文件。后续添加用户不要再用 -c 参数，否则会覆盖。
# 添加第二个用户
sudo htpasswd -Bb ./auth/htpasswd developer another_password

现在 ./auth/htpasswd 文件里就存储了加密后的用户凭证。

步骤四：准备 SSL 证书

• 使用 Let’s Encrypt (推荐) ：

  # 安装 certbot
  sudo apt-get install -y certbot
  # 申请证书（假设你的域名是 registry.example.com，且80端口可访问）
  sudo certbot certonly --standalone -d registry.example.com
  

  申请成功后，证书通常位于 /etc/letsencrypt/live/registry.example.com/ 。我们需要创建软链接或复制到项目目录：

  sudo ln -s /etc/letsencrypt/live/registry.example.com/fullchain.pem ./certs/
  sudo ln -s /etc/letsencrypt/live/registry.example.com/privkey.pem ./certs/
  

  注意 ：Let‘s Encrypt 证书90天过期，需要设置自动续期。可以将续期和重启服务的命令加入 crontab。

• 生成自签名证书 (测试用) ：

  cd /opt/docker-registry/certs
  # 生成私钥和证书请求
  openssl req -newkey rsa:4096 -nodes -sha256 -keyout privkey.pem -x509 -days 365 -out fullchain.pem -subj "/C=CN/ST=Beijing/L=Beijing/O=MyCompany/CN=registry.local"
  

  这里 -subj 参数中的 CN (Common Name) 必须设置为客户端访问时使用的地址（域名或IP）。例如，如果你打算用 IP 192.168.1.100 访问， CN 就应该是 192.168.1.100 。

步骤五：编写 docker-compose.yml 将前面解析过的 docker-compose.yml 内容写入 /opt/docker-registry/docker-compose.yml 。根据你的路径调整卷挂载，确保指向正确的目录。

步骤六：启动服务

cd /opt/docker-registry
sudo docker compose up -d

使用 docker compose ps 查看服务状态， docker compose logs -f 查看实时日志，确认没有错误。

步骤七：客户端配置与测试 现在，从另一台安装了 Docker 的机器上测试。

1. 登录仓库 ：

   docker login registry.example.com:5043
   # 或使用 IP
   docker login 192.168.1.100:5043
   

   输入之前在 htpasswd 中设置的用户名和密码。

2. 标记并推送镜像 ：

   # 拉取一个测试镜像
   docker pull alpine:latest
   # 重新标记，指向你的私有仓库
   docker tag alpine:latest registry.example.com:5043/my-alpine:latest
   # 推送
   docker push registry.example.com:5043/my-alpine:latest
   

3. 从仓库拉取镜像 ：

   # 可以先删除本地镜像
   docker rmi registry.example.com:5043/my-alpine:latest
   # 再从私有仓库拉取
   docker pull registry.example.com:5043/my-alpine:latest
   

如果以上步骤都成功，说明你的私有镜像仓库已经搭建完成并正常工作。

实操心得 ：在第一次推送大镜像时，很容易因为 Nginx 超时设置或客户端配置问题失败。除了前面提到的 proxy_read_timeout 和缓冲设置，在 Docker 客户端也可以调整 --max-concurrent-uploads 等参数。如果遇到问题，多看 Nginx 和 Registry 容器的日志 ( docker compose logs nginx registry )，那里通常有明确的错误信息。

4. 高级配置与运维管理

4.1 存储后端配置与优化

默认配置使用本地文件系统存储（ /var/lib/registry ），这对于小规模使用或测试是没问题的。但在生产环境，尤其是镜像数量多、体积大时，你需要考虑更可靠、可扩展的存储后端。Docker Registry 支持多种存储驱动。

切换到云存储（以 AWS S3 为例）： 修改 docker-compose.yml 中 registry 服务的 environment 部分：

environment:
  REGISTRY_STORAGE: s3
  REGISTRY_STORAGE_S3_ACCESSKEY: your_aws_access_key
  REGISTRY_STORAGE_S3_SECRETKEY: your_aws_secret_key
  REGISTRY_STORAGE_S3_REGION: us-east-1
  REGISTRY_STORAGE_S3_BUCKET: my-docker-registry
  REGISTRY_STORAGE_S3_ROOTDIRECTORY: /registry # S3 bucket 内的路径
  REGISTRY_STORAGE_CACHE_BLOBDESCRIPTOR: inmemory
  # 可选：使用 S3 的加速端点或自定义端点（用于兼容其他S3协议对象存储）
  # REGISTRY_STORAGE_S3_REGIONENDPOINT: s3.amazonaws.com
  # REGISTRY_STORAGE_S3_ENCRYPT: true
  # REGISTRY_STORAGE_S3_SECURE: true

同时，可以移除之前挂载的本地 ./data/registry 卷。使用 S3 的好处是存储几乎无限扩展，并且天然具备高可用性和持久性。成本需要根据存储量和访问频率进行评估。

使用阿里云 OSS、腾讯云 COS 等兼容 S3 协议的对象存储： 配置大同小异，关键是正确设置 REGISTRY_STORAGE_S3_REGIONENDPOINT 。例如对于阿里云 OSS：

environment:
  REGISTRY_STORAGE: s3
  REGISTRY_STORAGE_S3_ACCESSKEY: your_ali_access_key_id
  REGISTRY_STORAGE_S3_SECRETKEY: your_ali_access_key_secret
  REGISTRY_STORAGE_S3_REGION: oss-cn-hangzhou # 填写 bucket 所在区域
  REGISTRY_STORAGE_S3_BUCKET: my-docker-registry-bucket
  REGISTRY_STORAGE_S3_REGIONENDPOINT: oss-cn-hangzhou.aliyuncs.com # 端点
  REGISTRY_STORAGE_S3_ENCRYPT: false # 根据是否需要服务端加密设置
  REGISTRY_STORAGE_S3_SECURE: true # 使用 HTTPS

注意事项 ：使用云存储时，一定要注意权限管理（IAM Policy 或 Bucket Policy），确保 Registry 服务只有必要的读写权限，遵循最小权限原则。同时，开启存储桶的版本控制或生命周期规则可能有助于误操作恢复或成本控制，但需谨慎评估，因为 Registry 的垃圾回收机制与对象存储生命周期可能存在交互。

4.2 认证与授权进阶

auth_basic 简单易用，但在多团队、复杂权限管理的场景下可能力不从心。你可以考虑集成更强大的认证系统。

方案一：集成第三方认证（Token 认证） Registry 支持通过 Token 服务进行认证。你需要部署一个符合 OAuth2 或 Docker Registry v2 认证协议的认证服务器（如 docker/distribution 项目自带的 registry:2 镜像也支持配置外部的 token 认证）。这通常涉及修改 Nginx 配置，将认证请求转发给认证服务器，并在 Registry 配置中指定 token 相关的环境变量。这种方案可以实现复杂的用户组、项目空间权限控制。

方案二：使用商业或开源仓库管理平台 如果你需要更全面的功能，如 Web UI、镜像扫描、安全策略、复制同步等，可以考虑直接部署 Harbor 或 GitLab Container Registry。它们内置了完整的用户权限管理体系。 mcparmory/registry 这种轻量级方案更适合作为基础服务，或者在你已经有统一认证中心（如 LDAP/AD）时，通过 Nginx 的 auth_request 模块或 Lua 脚本进行集成。

对于当前方案的一个实用增强：IP 白名单 有时我们希望对某些可信网络（如公司内网）免除认证。可以在 Nginx 配置中增加 satisfy any 指令结合 allow/deny 规则。

location / {
    satisfy any; # 满足任一条件即可

    # 内网 IP 段直接放行
    allow 10.0.0.0/8;
    allow 172.16.0.0/12;
    allow 192.168.0.0/16;
    deny all; # 其他所有 IP 拒绝

    # 非白名单 IP 需要认证
    auth_basic "Registry Authentication Required";
    auth_basic_user_file /auth/htpasswd;

    proxy_pass http://registry:5000;
    # ... 其他 proxy 设置
}

4.3 监控、日志与垃圾回收

监控： 一个健康的仓库需要被监控。你可以从几个层面入手：

1. 容器健康 ：使用 docker compose ps 查看状态，结合 Prometheus 等监控系统收集容器资源使用情况（CPU、内存）。
2. 服务健康 ：Registry 提供了 /healthz 端点，Nginx 也有 stub_status 模块或可以检查 / 。可以定期用 curl 或监控系统探测。
3. 业务指标 ：Registry 支持将指标导出给 Prometheus。通过环境变量 REGISTRY_HTTP_DEBUG_PROMETHEUS_ENABLED: true 开启，然后访问 /metrics 端点即可获取推送、拉取次数，存储空间使用量等指标。

日志： 默认的日志输出到容器标准输出（stdout）。通过 Docker Compose 的 logging 配置，可以方便地接入 ELK（Elasticsearch, Logstash, Kibana）或 Loki 等日志聚合系统。例如，使用 json-file 驱动并限制日志大小：

services:
  registry:
    # ... 其他配置
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

在生产环境中，将日志集中管理便于问题排查和安全审计。

垃圾回收： 镜像被多次推送、覆盖或删除后，Registry 底层存储中会产生一些不再被任何 Manifest 引用的“孤岛”数据层（Blobs），占用磁盘空间。需要定期执行垃圾回收。

1. 首先，在 Registry 配置中启用删除功能（默认是开启的）。
2. 停止 Registry 服务（或将其设置为只读模式，避免在 GC 期间写入）。
3. 执行垃圾回收命令：

   docker compose exec registry bin/registry garbage-collect /etc/docker/registry/config.yml
   

   可以加上 -m 参数来实际删除数据，不加则是模拟运行（dry-run）。 务必先做模拟运行，确认要删除的内容 。
4. 对于使用文件系统后端的，GC 后会释放空间。对于云存储后端，GC 会标记或删除对应的对象，但云存储的计费可能有延迟，且需注意云存储本身的删除费用（如有）。

重要提醒 ：垃圾回收是一个需要谨慎操作的过程，最好在业务低峰期进行，并确保有完整的备份。对于生产环境，建议将 GC 过程脚本化、自动化，并纳入日常运维计划。

5. 常见问题与故障排查实录

在实际部署和运维过程中，你几乎一定会遇到下面这些问题。我把它们和解决方法整理出来，希望能帮你少走弯路。

5.1 证书相关问题

问题1： docker login 或 docker push 时报错 x509: certificate signed by unknown authority

• 原因 ：客户端不信任服务器使用的 SSL 证书。常见于使用自签名证书，或者证书链不完整。
• 排查与解决 ：
  • 检查证书匹配 ：确保 Nginx 配置中 ssl_certificate 指向的证书文件，其 CN (Common Name) 或 SAN (Subject Alternative Name) 包含客户端访问时使用的地址（域名或IP）。可以用命令检查： openssl x509 -in fullchain.pem -text -noout | grep -A1 "Subject Alternative Name" 。
  • 客户端信任证书 ：
    • 对于自签名证书 ：将生成自签名证书时创建的 CA 证书（或 fullchain.pem 文件本身）复制到 Docker 客户端机器的信任目录。对于 Linux，通常是 /etc/docker/certs.d/<registry_host:port>/ca.crt 。例如，对于 registry.example.com:5043 ，需要创建目录 /etc/docker/certs.d/registry.example.com:5043/ ，并将 ca.crt 放入。然后重启 Docker 服务。
    • 对于 Let‘s Encrypt 等公共证书 ：一般不需要此步骤。如果仍报错，检查服务器防火墙是否开放了5043端口，以及域名解析是否正确。

问题2： x509: certificate is valid for xxx, not yyy

• 原因 ：证书是为域名 xxx 签发的，但客户端尝试用 yyy （可能是IP或其他域名）访问。
• 解决 ：统一访问地址。要么让客户端使用证书中指定的域名访问，要么重新生成一个包含正确域名/IP的证书。

5.2 认证与权限问题

问题3： docker login 成功，但 docker push 时返回 403 Forbidden 或 unauthorized: authentication required

• 原因 ：这通常不是登录失败，而是推送的镜像命名空间（Repository）对相应用户没有写权限。Docker Registry v2 的权限模型比较基础， auth_basic 本身不区分用户对哪个仓库有权限。
• 排查 ：
  1. 检查 Nginx 错误日志： docker compose logs nginx | grep -i "403\|401" 。
  2. 确认你推送的镜像名称格式正确： <registry-host>:<port>/<project-or-username>/<image-name>:<tag> 。对于简单的 auth_basic ，任何已登录用户理论上可以推送到任何路径。但某些 Registry 配置或 Nginx 规则可能会做限制。
• 解决 ：如果确实需要严格的仓库级权限，需要考虑升级到 Harbor 或配置更复杂的 Token 认证服务。

问题4： docker login 一直失败，提示 Incorrect username or password

• 排查 ：
  1. 确认 htpasswd 文件路径在 Nginx 容器内可读，且挂载正确。
  2. 检查 htpasswd 文件内容： cat auth/htpasswd 。确保密码是加密的（以 $2y$ , $apr1$ 等开头）。
  3. 确认创建用户时使用了 -B (bcrypt) 选项。某些旧的 htpasswd 工具默认使用不安全的加密方式，可能不被 Nginx 的当前版本支持。
  4. 尝试用 htpasswd -vb auth/htpasswd username 验证密码。

5.3 网络与性能问题

问题5：推送大镜像时超时失败，日志显示 context canceled 或 read tcp ... i/o timeout

• 原因 ：网络慢或代理超时设置太短。
• 解决 ：
  1. 调整 Nginx 超时 ：在 Nginx 配置的 location / 块中，增加超时设置：

     proxy_connect_timeout 300;
     proxy_send_timeout 300;
     proxy_read_timeout 300;
     send_timeout 300;
     

  2. 调整 Docker 客户端设置 ：在客户端机器的 Docker 配置文件（如 /etc/docker/daemon.json ）中，增加：

     {
       "max-concurrent-uploads": 3,
       "max-download-attempts": 5,
       "shutdown-timeout": 30
     }
     

     然后重启 Docker 服务。
  3. 检查防火墙与网络 ：确保服务器防火墙（如 ufw , firewalld ）和云服务商的安全组规则开放了5043端口。

问题6： docker pull 速度很慢

• 原因 ：可能因为镜像层很大，或者网络带宽不足。
• 解决 ：
  1. 考虑在 Registry 前端部署一个缓存代理（如 registry:2 镜像本身可以作为缓存），或者使用 Nginx 的缓存功能缓存镜像层。
  2. 如果使用云存储后端，确保 Registry 服务器与对象存储之间的网络带宽和延迟是可接受的。有时将 Registry 部署在离存储更近的区域会有帮助。

5.4 存储与空间问题

问题7：服务器磁盘空间不足

• 原因 ：镜像仓库积累了太多镜像和未清理的垃圾数据。
• 解决 ：
  1. 定期清理 ：建立镜像清理策略。可以写脚本调用 Registry API 删除不再需要的镜像标签，然后执行垃圾回收。
  2. 使用存储配额 ：如果是文件系统，可以使用操作系统级的磁盘配额。如果是云存储，设置 Bucket 的生命周期规则，自动清理过期的删除标记（注意与 Registry GC 的协调）。
  3. 迁移存储 ：如前所述，迁移到云存储，利用其无限扩展的能力。

问题8：执行垃圾回收（GC）后，磁盘空间未释放

• 原因 ：在容器内删除文件，并不会立即释放宿主机的磁盘空间，因为 Docker 使用的存储驱动（如 overlay2 ）可能还存在引用。
• 解决 ：
  1. 停止所有使用该存储目录的容器。
  2. 在宿主机上，进入 Registry 的数据卷目录，手动检查大小。
  3. 可以考虑使用 docker system prune -a --volumes （ 危险！会清理所有未使用的容器、镜像、卷和网络 ）来彻底清理，或者重启 Docker 服务有时也能释放一些空间。最根本的方法是规划好存储，使用独立的磁盘或卷，并定期维护。

5.5 服务可用性问题

问题9：服务重启后，客户端无法访问

• 排查步骤 ：
  1. docker compose ps ：确认所有服务（ registry 和 nginx ）状态都是 Up 。
  2. docker compose logs --tail=50 nginx registry ：查看最近日志有无错误。
  3. curl -k -v https://localhost:5043/v2/ ：在服务器本机测试， -k 忽略证书错误。应该返回 {} 或 401 Unauthorized （如果有认证）。如果连不上，检查 Nginx 是否监听5043端口： netstat -tlnp | grep 5043 。
  4. 检查防火墙和云安全组。
  5. 检查域名解析是否正常。

问题10：如何备份和恢复整个仓库？

• 备份 ：
  1. 文件系统后端 ：直接备份挂载的卷目录（如 ./data/registry ）。在备份期间，最好停止 Registry 服务或将其设置为只读模式，以保证数据一致性。
  2. 云存储后端 ：利用对象存储提供的跨区域复制、版本控制或快照功能。或者使用云厂商的备份服务。
  3. 配置与认证 ：别忘了备份 docker-compose.yml , nginx/ 配置， auth/htpasswd 和 certs/ 目录。
• 恢复 ：
  1. 在新环境安装好 Docker 和 Docker Compose。
  2. 将备份的整个项目目录（包含 data , auth , certs , nginx 等）还原。
  3. 检查并修改 docker-compose.yml 和 Nginx 配置中的路径、域名等，确保符合新环境。
  4. 运行 docker compose up -d 。

最后，关于这个 mcparmory/registry 方案，我个人最深的体会是：它完美地诠释了“基础设施即代码”和“约定大于配置”的理念。它没有试图做一个大而全的管理平台，而是聚焦于解决私有 Registry 部署中最繁琐、最容易出错的那部分——安全配置和网络接入。它给你一个坚实、可预测的起点，剩下的存储扩展、监控、备份等高级功能，你可以根据自己团队的规模和需求，在这个清晰的架构上从容地添加。这种“做减法”的设计，对于追求效率和可控性的运维和开发者来说，往往比一个看似功能齐全但黑盒复杂的系统更有价值。如果你刚开始建设容器化基础设施，从这个方案入手，会是一个非常稳健的选择。