Docker Registry 与镜像分发

1. Registry 模型

Registry 存储 OCI blob、manifest 和 tag。Repository 是逻辑仓库，tag 是可移动引用，digest 是内容标识。

docker pull registry.example.internal/team/api:2026.08.12
docker image inspect \
  registry.example.internal/team/api:2026.08.12 \
  --format '{{json .RepoDigests}}'

生产审计和回滚以 digest 为准。

2. 登录

交互：

docker login registry.example.internal
docker logout registry.example.internal

CI：

printf '%s' "$REGISTRY_TOKEN" \
  | docker login registry.example.internal \
      --username "$REGISTRY_USER" \
      --password-stdin

不要使用 --password value，它可能进入 shell history 和进程参数。优先使用短期、仓库级、只读/只写分离的 token。

Docker credential store：

{
  "credsStore": "osxkeychain"
}

没有 helper 时，~/.docker/config.json 可能存放可逆编码认证数据，必须限制权限且不能提交。

3. 推送

docker tag team-api:build-1042 \
  registry.example.internal/team/api:git-a1b2c3d

docker push registry.example.internal/team/api:git-a1b2c3d

推送后获取 digest：

docker image inspect \
  registry.example.internal/team/api:git-a1b2c3d \
  --format '{{json .RepoDigests}}'

多平台构建直接 push：

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.internal/team/api:git-a1b2c3d \
  --sbom=true \
  --provenance=mode=max \
  --push .

4. 标签策略

推荐同时维护：

• git-<full-or-sufficient-sha>：唯一构建；
• v1.8.3：发布版本；
• release-2026.08.12.1：团队发布编号；
• uat/stable：可选浮动别名，仅用于发现。

Registry 支持时对发布 tag 开启 immutable，防止覆盖。浮动别名不能作为唯一部署凭据。

5. 环境提升

正确的 dev → UAT → prod 是提升同一 digest，而不是每个环境重建：

source commit
  -> build once
  -> scan/test/sign
  -> approve digest
  -> UAT uses digest
  -> production uses same digest

若重新构建，即使源码相同，基础镜像、依赖源和时间戳也可能产生不同产物。

6. TLS 与私有 CA

私有 Registry 必须优先使用 HTTPS。Linux Engine 信任自建 CA 的常见目录：

/etc/docker/certs.d/registry.example.internal/ca.crt

安装后重启/重载并测试：

curl -sS -o /dev/null -w '%{http_code}\n' \
  https://registry.example.internal/v2/
docker login registry.example.internal

未认证探测通常返回 200 或 401；两者都说明 TLS/HTTP 已连通，随后再用 docker login 验证认证。

不要把私库加入 insecure-registries 作为长期解决方案；它会削弱传输和身份验证。

7. 最小自建 Registry 示例

仅用于受控测试：

docker run -d \
  --name registry \
  --restart unless-stopped \
  -p 127.0.0.1:5000:5000 \
  --mount type=volume,src=registry-data,dst=/var/lib/registry \
  registry:3

生产还必须具备：

• TLS、认证、授权与审计；
• 高可用和后端对象存储；
• quota、retention 与垃圾回收；
• 备份恢复；
• 漏洞扫描和签名策略；
• 监控、告警和升级计划。

8. 删除与垃圾回收

删除 tag/manifest 与释放 blob 存储不是一回事；共享 layer 可能仍被其他 manifest 使用。Registry GC 是服务端维护操作。

危险： 在 Registry 正在写入时运行不兼容的垃圾回收可能破坏内容。严格遵循对应产品版本文档、先备份并安排维护窗口。

9. 镜像签名与策略

推荐流程：

1. 构建并推送；
2. 获取 digest；
3. 生成 SBOM/provenance；
4. 扫描并执行策略；
5. 使用组织批准的密钥或 keyless 身份签名 digest；
6. 部署端验证签名、来源和环境策略。

签名 tag 不可靠，因为 tag 可移动；签名对象应是 digest。

10. 访问控制

• 开发者通常只有指定 namespace 的 push 权限。
• 生产部署身份只需 pull。
• CI token 按 repository 和动作最小授权。
• 管理员 token 不用于日常流水线。
• 机器人账号有所有者、轮换周期和撤销流程。
• 认证失败、tag 覆盖和删除操作进入审计。

11. 常见故障

docker login registry.example.internal
curl -v https://registry.example.internal/v2/
docker buildx imagetools inspect IMAGE
docker info | sed -n '/Registry Mirrors/,+8p'

错误	常见原因
x509: certificate signed by unknown authority	CA 未放到 daemon 信任目录、证书链不完整
unauthorized	token 过期、scope 不足、仓库名错误
manifest unknown	tag/digest 不存在或被清理
blob unknown	Registry 存储/GC/复制异常
push retry/timeout	代理、MTU、反向代理 body/timeout 限制
no matching manifest	没有目标平台变体

12. 官方参考

• Registry deployment
• Docker Hub repositories
• Registry API
• Image tags

补充实践：阿里云docker 镜像仓库

来源：jekyall_blog；原记录日期：Tue Jan 01 2019 12:48:54 GMT+0800 (中国标准时间)。以下保留来源案例的环境和版本范围。

阿里云 docker 镜像仓库

1. 登录阿里云Docker Registry
$ sudo docker login --username=hypeyhyper registry.cn-hangzhou.aliyuncs.com
用于登录的用户名为阿里云账号全名，密码为开通服务时设置的密码。

您可以在访问凭证页面修改凭证密码。

2. 从Registry中拉取镜像
$ sudo docker pull registry.cn-hangzhou.aliyuncs.com/chaochengli/tcpserverandcluster:[镜像版本号]
3. 将镜像推送到Registry
$ sudo docker login --username=hypeyhyper registry.cn-hangzhou.aliyuncs.com
$ sudo docker tag [ImageId] registry.cn-hangzhou.aliyuncs.com/chaochengli/tcpserverandcluster:[镜像版本号]
$ sudo docker push registry.cn-hangzhou.aliyuncs.com/chaochengli/tcpserverandcluster:[镜像版本号]
请根据实际镜像信息替换示例中的[ImageId]和[镜像版本号]参数。

4. 选择合适的镜像仓库地址
从ECS推送镜像时，可以选择使用镜像仓库内网地址。推送速度将得到提升并且将不会损耗您的公网流量。

如果您使用的机器位于VPC网络，请使用 registry-vpc.cn-hangzhou.aliyuncs.com 作为Registry的域名登录，并作为镜像命名空间前缀。
5. 示例
使用"docker tag"命令重命名镜像，并将它通过专有网络地址推送至Registry。

$ sudo docker images
REPOSITORY                                                         TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
registry.aliyuncs.com/acs/agent                                    0.7-dfb6816         37bb9c63c8b2        7 days ago          37.89 MB
$ sudo docker tag 37bb9c63c8b2 registry-vpc.cn-hangzhou.aliyuncs.com/acs/agent:0.7-dfb6816
使用"docker images"命令找到镜像，将该镜像名称中的域名部分变更为Registry专有网络地址。

$ sudo docker push registry-vpc.cn-hangzhou.aliyuncs.com/acs/agent:0.7-dfb6816

参考地址