如何部署可供团队推送和拉取镜像的Docker私有镜像仓库?

发布人:A5数据发布时间:2026-11-04 10:05阅读量:69

要让团队能够安全地推送和拉取镜像,最小可用方案可以只使用一台 Linux 服务器、Docker Engine、Docker Compose、Registry 容器、TLS 证书和基础认证。本文按 Ubuntu Server 22.04/24.04 说明,使用 Docker Distribution Registry 作为仓库服务,直接监听服务器的 5000 端口,不额外引入数据库或 Nginx。

部署完成后,团队成员通过类似 registry.example.com:5000/team/app:1.0 的镜像地址执行登录、推送和拉取。示例中的域名、IP 地址、用户名和密码均需替换为实际值。

一、准备条件

1.1 服务器和网络要求

建议准备以下环境:

项目示例要求
操作系统Ubuntu Server 22.04 或 24.04
计算资源2 vCPU、4 GB 内存作为小规模团队的起步配置
存储空间至少预留 50 GB,可根据镜像数量和层大小扩展
软件Docker Engine、Docker Compose Plugin
域名registry.example.com
网络域名解析到仓库服务器,客户端能够访问 TCP 5000
证书与仓库域名匹配的 TLS 证书

Registry 采用内容寻址存储,相同镜像层通常只保存一份,但不同项目、版本和基础镜像仍会持续占用磁盘。存储空间不要只按当前镜像大小规划,应为后续版本和临时上传预留余量。

本文使用以下示例变量:

  • 仓库域名:registry.example.com
  • 仓库端口:5000
  • 仓库目录:/srv/registry
  • 管理员账号:teamadmin
  • 示例镜像:team/hello-world:1.0

如果服务器使用云平台,还需要在安全组中允许团队来源地址访问 TCP 5000。不要直接对公网开放不必要的端口。

A5idc数据在中国香港、美国、日本等地提供物理服务器,不同产品系列覆盖 NVMe、SSD 及大容量 HDD 存储,并提供多种带宽与线路选择。这些计算、存储和网络资源可用于运行团队 Docker 私有镜像仓库、保存镜像数据,并支持分布在不同地区的团队成员推送和拉取镜像。

1.2 检查系统和端口

先确认系统版本、架构和 5000 端口是否已经被占用:

cat /etc/os-release
uname -m
sudo ss -lntp | grep ':5000' || true

预期结果是系统为 Ubuntu 22.04 或 24.04,架构通常为 x86_64 或 aarch64,并且没有其他程序监听 5000 端口。

如果已经有服务使用 5000 端口,应先确认其用途,再决定更换 Registry 端口或停止冲突服务。不要直接结束未知进程。

1.3 配置 DNS 和 TLS

将 registry.example.com 的 A 记录解析到仓库服务器公网或内网 IP。使用公共受信任机构签发的证书时,证书的域名必须包含 registry.example.com,并且服务端应使用完整证书链。

如果只是内部测试,也可以创建自签名证书。自签名证书不会自动被 Docker 客户端信任,需要在每一台客户端上安装信任证书。生产或跨网络团队使用时,优先采用客户端已信任的证书链。

二、安装 Docker Engine 和 Compose

以下命令适用于 Ubuntu。安装过程会添加 Docker 软件源,并安装 Docker Engine、容器运行时、Buildx 和 Compose Plugin。

sudo apt-get update
sudo apt-get install -y ca-certificates curl openssl apache2-utils

sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

sudo systemctl enable --now docker

安装后检查版本:

sudo docker version
sudo docker compose version
sudo systemctl is-active docker

预期结果中,Docker 服务状态为 active,并能看到 Docker Compose 版本。如果软件源无法找到 docker-ce,先检查系统版本和软件源中的发行版代号,不要随意混用其他 Ubuntu 版本的软件源。

如果希望普通用户不使用 sudo 执行 Docker 命令,可以将其加入 docker 用户组。但该用户组拥有近似 root 的主机控制权限,适用于明确受信任的实施账号,不建议无条件给所有团队成员配置。

三、创建仓库目录和认证文件

3.1 创建持久化目录

Registry 容器本身可以删除和重建,镜像数据、认证文件和证书必须放在主机目录中持久化保存:

sudo mkdir -p /srv/registry/{data,auth,certs}
sudo chmod 750 /srv/registry/data
sudo chmod 700 /srv/registry/auth /srv/registry/certs

验证目录:

sudo find /srv/registry -maxdepth 1 -type d -printf '%M %u:%g %p\n'

预期能够看到 data、auth 和 certs 三个目录。认证文件和私钥目录应限制访问范围,避免被普通用户读取。

3.2 生成 Registry 内部密钥

Registry 使用内部 HTTP Secret 处理部分请求状态。将其写入权限受限的 .env 文件:

sudo sh -c 'printf "REGISTRY_HTTP_SECRET=%s\n" "$(openssl rand -hex 32)" > /srv/registry/.env'
sudo chmod 600 /srv/registry/.env

这条命令会生成随机密钥,不要将 .env 文件提交到代码仓库或发布到公共目录。

3.3 创建基础认证账号

使用 htpasswd 创建 bcrypt 格式的认证文件:

sudo htpasswd -B -c /srv/registry/auth/htpasswd teamadmin

命令会交互式要求输入两次密码。-c 表示创建并覆盖文件,只能在首次创建账号时使用。之后新增账号时不要再使用 -c:

sudo htpasswd -B /srv/registry/auth/htpasswd teamdev

验证文件是否存在:

sudo ls -l /srv/registry/auth/htpasswd
sudo awk -F: '{print $1}' /srv/registry/auth/htpasswd

预期能看到账号名称,但不要把认证文件内容直接打印或发送到聊天工具中。若重新执行带 -c 的命令,原有账号会被覆盖,执行前应先备份认证文件。

四、配置 TLS 证书

4.1 使用已有证书

如果已经获得与仓库域名匹配的证书,将证书链和私钥复制到 Registry 目录。以下路径仅为示例:

sudo install -m 0644 /path/to/fullchain.pem \
  /srv/registry/certs/domain.crt

sudo install -m 0600 /path/to/privkey.pem \
  /srv/registry/certs/domain.key

domain.crt 应包含服务端证书和必要的中间证书链,domain.key 为对应私钥。若证书与私钥不匹配,容器启动时会报 TLS 加载错误。

4.2 测试环境生成自签名证书

如果当前只是隔离测试环境,可以生成一张包含正确域名的自签名证书:

sudo openssl req -newkey rsa:4096 -nodes -sha256 \
  -keyout /srv/registry/certs/domain.key \
  -x509 -days 365 \
  -out /srv/registry/certs/domain.crt \
  -subj "/CN=registry.example.com" \
  -addext "subjectAltName=DNS:registry.example.com"

sudo chmod 600 /srv/registry/certs/domain.key
sudo chmod 644 /srv/registry/certs/domain.crt

验证证书中的域名:

sudo openssl x509 \
  -in /srv/registry/certs/domain.crt \
  -noout -subject -issuer -dates -ext subjectAltName

输出中的 subjectAltName 应包含 DNS:registry.example.com。客户端访问时必须使用这个域名,不能改成未写入证书的 IP 地址,否则会出现证书名称不匹配。

五、编写 Compose 配置并启动

5.1 创建 Compose 文件

进入部署目录:

cd /srv/registry

创建 compose.yaml:

services:
  registry:
    image: registry:2.8.3
    container_name: private-registry
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY: /var/lib/registry
      REGISTRY_HTTP_ADDR: 0.0.0.0:5000
      REGISTRY_HTTP_SECRET: ${REGISTRY_HTTP_SECRET}
      REGISTRY_HTTP_TLS_CERTIFICATE: /certs/domain.crt
      REGISTRY_HTTP_TLS_KEY: /certs/domain.key
      REGISTRY_AUTH: htpasswd
      REGISTRY_AUTH_HTPASSWD_REALM: "Registry Realm"
      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd
    volumes:
      - /srv/registry//var/lib/registry
      - /srv/registry/auth:/auth:ro
      - /srv/registry/certs:/certs:ro

配置中的三个挂载点分别负责镜像数据、认证文件和 TLS 文件。认证文件和证书以只读方式挂载,减少容器内误修改的可能。

两台团队 Docker 客户端通过 HTTPS 访问同一台 Linux 服务器的 registry.example.com:5000;服务器内为 Registr

启动前先检查 Compose 配置能否被解析:

sudo docker compose config > /dev/null && echo "compose 配置有效"

预期输出:

compose 配置有效

如果提示 REGISTRY_HTTP_SECRET 未设置,通常是执行目录不在 /srv/registry,或者 .env 文件权限和路径不正确。

5.2 启动容器

在 /srv/registry 目录执行:

sudo docker compose up -d

首次启动可能需要下载 Registry 镜像。检查容器状态:

sudo docker compose ps

预期状态类似:

NAME              IMAGE          COMMAND                  SERVICE    STATUS
private-registry  registry:2.8.3 "/entrypoint.sh /etc…"  registry   Up

查看启动日志:

sudo docker compose logs --tail=50 registry

正常情况下不会出现证书加载失败、认证文件不存在或存储目录不可写等错误。

5.3 验证 Registry API

使用已签发证书时,可以直接执行:

curl --user teamadmin \
  https://registry.example.com:5000/v2/

终端会要求输入密码。成功时通常返回:

{}

使用自签名证书时,测试命令需要指定证书:

curl --cacert /srv/registry/certs/domain.crt \
  --user teamadmin \
  https://registry.example.com:5000/v2/

返回 HTTP 200 和 {},表示域名解析、TCP 连接、TLS 握手、认证和 Registry API 均已基本可用。不要把 curl -k 的成功结果作为正式验证依据;它会跳过证书校验,只适合临时定位 TLS 问题。

六、配置客户端并完成首次推送和拉取

6.1 让 Docker 客户端信任证书

使用公共受信任证书时,通常不需要额外配置。使用自签名证书或内部 CA 证书时,需要在每台 Docker 客户端上安装 CA 证书。

在客户端执行:

sudo mkdir -p /etc/docker/certs.d/registry.example.com:5000

sudo install -m 0644 /path/to/ca.crt \
  /etc/docker/certs.d/registry.example.com:5000/ca.crt

如果使用本文生成的自签名证书,可以将服务器上的证书复制到客户端,再执行:

sudo install -m 0644 /path/to/domain.crt \
  /etc/docker/certs.d/registry.example.com:5000/ca.crt

修改 Docker 信任目录后,重启 Docker 服务会影响该客户端上运行的容器,需确认业务允许短暂中断:

sudo systemctl restart docker

验证客户端能够访问仓库:

docker login registry.example.com:5000

输入 teamadmin 和对应密码后,预期结果为:

Login Succeeded

登录地址必须包含端口 5000。证书目录名称也必须严格使用 registry.example.com:5000,不能省略端口或改成其他主机名。

6.2 推送一个测试镜像

先获取一个用于验证的公开基础镜像,再改成私有仓库地址:

docker pull hello-world:latest

docker tag hello-world:latest \
  registry.example.com:5000/team/hello-world:1.0

docker push registry.example.com:5000/team/hello-world:1.0

推送成功时会看到多个 layer 的上传进度,最后出现类似以下结果:

1.0: digest: sha256:... size: ...

其中的摘要由实际镜像内容决定,不应手工填写或固定判断。

6.3 在另一台客户端拉取

在另一台已经配置证书信任的 Docker 客户端上执行:

docker login registry.example.com:5000
docker pull registry.example.com:5000/team/hello-world:1.0
docker image inspect registry.example.com:5000/team/hello-world:1.0

能够完成拉取并返回镜像元数据,说明仓库已经具备团队推送和拉取能力。

也可以通过 API 查看仓库目录:

curl --cacert /path/to/ca.crt \
  --user teamadmin \
  https://registry.example.com:5000/v2/_catalog

示例返回可能类似:

{"repositories":["team/hello-world"]}

基础认证只负责确认用户身份,不提供按项目划分的细粒度权限。在这套最小配置中,认证文件中的账号通常都可以访问同一个 Registry 内的镜像。如果团队需要不同项目之间的推送权限隔离,应在后续引入支持权限策略的认证或仓库管理方案,不要误以为 team/ 路径本身就是权限边界。

七、常见异常和处理方式

7.1 connection refused 或连接超时

先在服务器上确认容器和监听端口:

从客户端连接失败开始,依次检查容器状态、服务器 5000 端口监听和本机与外部客户端的访问差异;各分支指向正文对应的检查对象

sudo docker compose ps
sudo ss -lntp | grep ':5000'
  • 容器不是 Up:查看 sudo docker compose logs registry。
  • 服务器未监听 5000:重点检查 Compose 配置、证书和认证文件路径。
  • 服务器已监听但外部超时:检查云安全组、主机防火墙、DNS 解析和客户端网络。
  • 服务器本机可以访问、客户端不能访问:通常是网络策略或防火墙未允许客户端来源地址。

如果使用 UFW,只允许明确的团队网段访问示例端口:

sudo ufw allow from 203.0.113.0/24 to any port 5000 proto tcp
sudo ufw status

203.0.113.0/24 是文档示例网段,实际执行时必须替换为已批准的来源网段。执行防火墙调整前确认 SSH 管理端口已有允许规则,避免锁死服务器。撤销该规则:

sudo ufw delete allow from 203.0.113.0/24 to any port 5000 proto tcp

7.2 x509: certificate signed by unknown authority

这表示客户端不信任签发证书的 CA,常见原因包括:

  • 使用自签名证书但没有配置 /etc/docker/certs.d/registry.example.com:5000/ca.crt。
  • CA 文件复制错误或权限不允许 Docker 读取。
  • 使用了错误的仓库域名或端口。
  • 服务端未提供完整证书链。

修复后重启 Docker 客户端服务,再重新执行 docker login。不要为了绕过问题而把仓库加入不安全 Registry 列表,这会降低传输和认证安全性。

7.3 unauthorized: authentication required

检查登录地址是否与推送地址完全一致:

docker info
docker logout registry.example.com:5000
docker login registry.example.com:5000

服务端检查认证文件:

sudo ls -l /srv/registry/auth/htpasswd
sudo docker compose logs --tail=100 registry

如果曾经执行过 htpasswd -c,可能已经覆盖了原账号。重新创建账号前,先备份认证文件,再确认密码输入没有多余空格。

7.4 manifest unknown 或找不到镜像

Registry 区分仓库名称和标签。以下地址并不等价:

registry.example.com:5000/team/app:1.0
registry.example.com:5000/team/app:latest
registry.example.com:5000/app:1.0

推送和拉取必须使用完全相同的仓库路径与标签。可以先列出本地镜像:

docker image ls

再重新执行 docker tag 和 docker push。

7.5 推送过程中出现存储错误

检查数据目录所在磁盘和容器日志:

df -h /srv/registry/data
sudo docker compose logs --tail=100 registry

如果磁盘已满,先停止继续推送,扩容或清理经过确认的无关数据。不要直接删除 Registry 的 blobs、repositories 等内部目录,否则可能造成已上传镜像不可用。

八、部署完成后的验收项

首次部署可以按以下顺序验收:

  • docker 服务已启用,docker compose version 能正常返回。
  • private-registry 容器状态为 Up,重启策略为 unless-stopped。
  • /srv/registry/data、auth、certs 目录均已创建。
  • TLS 证书域名包含 registry.example.com,私钥权限未开放给普通用户。
  • https://registry.example.com:5000/v2/ 能返回 HTTP 200 和 {}。
  • docker login registry.example.com:5000 返回 Login Succeeded。
  • 一台客户端能够推送 team/hello-world:1.0。
  • 另一台客户端能够登录并拉取同一镜像。
  • /srv/registry/data 所在磁盘有足够剩余空间。
  • 云安全组和主机防火墙只开放必要的客户端来源。

九、回滚和恢复检查

首次部署出现配置错误时,优先回滚配置,不要立即删除镜像数据。

停止服务但保留数据:

cd /srv/registry
sudo docker compose down

该命令会停止并删除容器和 Compose 网络,但不会删除 /srv/registry/data 下的镜像数据。

在修改认证、证书或 Compose 文件前,可以先备份配置:

sudo tar -czf /srv/registry-config-$(date +%F-%H%M).tgz \
  -C /srv/registry compose.yaml .env auth certs

如果需要进行完整迁移或数据级回滚,应先停止 Registry,再备份数据目录:

cd /srv/registry
sudo docker compose down

sudo tar -czf /srv/registry-full-$(date +%F-%H%M).tgz \
  -C /srv/registry data auth certs compose.yaml .env

恢复时先确认备份文件可读,再恢复到 /srv/registry,检查证书、认证文件和 Compose 配置,最后重新启动:

sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=50 registry

如果只是清理一次失败的初始部署,建议先改名保留数据目录,而不是直接删除:

sudo mv /srv/registry/data \
  /srv/registry/data.failed-$(date +%F-%H%M)

sudo mkdir -p /srv/registry/data
sudo chmod 750 /srv/registry/data

只有在确认仓库中没有需要保留的镜像、并且已经完成备份后,才考虑删除旧目录。完成回滚后,应重新执行 API 访问、登录、测试推送和跨客户端拉取四项检查,确认服务状态、认证、TLS 和数据读写均恢复正常。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/7458.html

相关推荐