如何部署可供团队推送和拉取镜像的Docker私有镜像仓库?
要让团队能够安全地推送和拉取镜像,最小可用方案可以只使用一台 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 文件。认证文件和证书以只读方式挂载,减少容器内误修改的可能。

启动前先检查 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 或连接超时
先在服务器上确认容器和监听端口:

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



