Docker Registry HTTP API V2 详解
2025-07-06 07:05:11作者：董灵辛Dennis
前言
Docker Registry HTTP API V2 是 Docker 镜像分发协议的核心组件，它为 Docker 引擎提供了镜像分发的能力。本文将深入解析该 API 的设计理念、核心功能和使用方法，帮助开发者更好地理解和使用 Docker Registry。
架构演进
V1 到 V2 的转变
Docker Registry 最初采用 V1 版本的 API，但在实际使用中发现了一些架构上的问题：
- 镜像格式不够自包含，导致安全性问题
- 性能瓶颈明显，特别是在大规模分发场景下
- 带宽利用率不高
- 后端存储容易损坏
V2 版本针对这些问题进行了全面改进，引入了自包含的镜像清单格式，显著提升了安全性、性能和可靠性。
核心特性
1. 命名空间导向的 URI 设计
API 采用清晰的命名空间结构：
/v2/<name>/
其中 <name> 是镜像仓库名称，支持多级路径，如 library/ubuntu。
2. 镜像清单推送/拉取
支持 V2 格式的镜像清单操作，这是镜像分发的核心功能。
3. 可恢复的层推送
网络中断后可以从中断点继续上传，大幅提升大镜像上传的可靠性。
4. 客户端库实现
提供标准化的客户端实现规范。
使用场景
1. 镜像验证
Docker 引擎可以：
- 获取镜像清单
- 验证清单签名
- 下载各层后验证摘要 确保镜像来源可信且未被篡改。
2. 断点续传
上传中断后可以：
- 查询上传进度
- 仅上传剩余部分 特别适合 CI/CD 环境。
3. 层去重
当多个构建产生相同层时：
- 首个上传的层会被存储
- 后续相同层直接引用 节省存储空间和上传时间。
API 设计细节
错误处理
采用标准化的错误响应格式：
{
"errors": [
{
"code": "ERROR_CODE",
"message": "Human-readable message",
"detail": {}
}
]
}
版本检查
通过 /v2/ 端点检查 API 版本支持：
- 200 OK: 支持 V2
- 401 Unauthorized: 需要认证
- 404 Not Found: 不支持 V2
内容摘要
采用内容寻址存储，使用摘要唯一标识内容：
algorithm:hex
如 sha256:6c3c624b58dbb...
摘要头部
响应可能包含 Docker-Content-Digest 头部，客户端应验证内容完整性。
镜像拉取流程
1. 获取镜像清单
请求格式：
GET /v2/<name>/manifests/<reference>
支持通过标签或摘要获取。
2. 验证清单
验证清单签名确保真实性。
3. 拉取镜像层
各层通过摘要获取：
GET /v2/<name>/blobs/<digest>
镜像推送流程
1. 初始化上传
POST /v2/<name>/blobs/uploads/
2. 分块上传
使用 PATCH 方法上传数据块。
3. 完成上传
PUT 请求确认上传完成。
实用功能
跨仓库挂载
可以直接引用其他仓库的已有层，避免重复上传：
POST /v2/<name>/blobs/uploads/?mount=<digest>&from=<other_name>
分页支持
列表类接口支持分页参数：
n: 每页数量last: 上一页最后一项
最佳实践
- 始终验证内容摘要
- 利用断点续传提升可靠性
- 使用跨仓库挂载优化存储
- 合理设置分页参数处理大量数据
总结
Docker Registry HTTP API V2 通过精心设计解决了 V1 版本的诸多问题，提供了更安全、高效和可靠的镜像分发能力。理解其设计理念和核心功能，有助于开发者更好地构建基于 Docker 的应用交付流水线。
