简要：本文主要是对镜像结构及 Registry API 使用进行了总结。

API

1、拉取镜像

一个镜像是由 JSON 元数据和独立的层文件组成，而镜像检索的重点就是找到这两部分。

拉取镜像的第一步是取回元数据(manifest)，注册表(registry)相关字段如下：

当获取元数据清单后，客户端必须验证签名保证名称和层的有效性。确认后，客户端将使用摘要(digest)下载层文件(layer)。

1.1、拉取 manifests

GET /v2/<name>/manifests/<reference>

name和reference是定义镜像的必需参数，能够指定唯一镜像，reference可以是 tag 或 digest

返回数据

{
   "schemaVersion": 1,
   "name": <name>,
   "tag": <tag>,
   "architecture": "amd64",
   "fsLayers": [
      {
         "blobSum": "sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4"
      }
   ],
   "history": [<v1 images>],
   "signatures": [<JWS>]
}

客户端应在获取层文件之前验证返回的元数据签名的真实性。

1.1.1、镜像是否存在

HEAD /v2/<name>/manifests/<reference>

name和reference是定义镜像的必需参数，能够指定唯一镜像，reference可以是 tag 或 digest

如果返回 404 表示镜像不存在。如果镜像存在返回 200

HTTP/1.1 200 OK
Content-Length: 9116
Content-Type: application/vnd.docker.distribution.manifest.v1+prettyjws
Docker-Content-Digest: sha256:0f09fdacdca588279f0cb332ed0768daa9ed734c491d5d04b89d215982c2bfac

1.2、拉取层文件

层存储在注册表的 blob 部分中，由摘要键入。 拉取层是通过标准的 http 请求进行的

GET /v2/<name>/blobs/<digest>

对层的访问由存储库中的 name 控制，但是在注册表中由摘要唯一标识。

这个 api 可能会响应 307 重定向到另一个服务去下载层，客户端应要处理重定向。

2、推送镜像

推送镜像和拉取镜像的工作顺序相反。在组装镜像清单后，客户端必须先推送每个层，当层文件完全推送到注册表中，客户端需要上传元数据签名。

2.1、推送层文件

层文件上传需要两步：

• 在注册表服务开始上传，返回 url 进行第二步
• 使用 url 传输实际的数据

上传是用 POST 请求开始，该请求返回可用于推送数据和检查上传状态的 url。

请求头“Location”将用于定位每次请求上传后的位置。

2.1.1、开始上传

POST /v2/<name>/blobs/uploads

请求的参数是将镜像空间链接到层文件

2.1.2、层是否存在

HEAD /v2/<name>/blobs/<digest>

如果指定的层文件的摘要存在，则响应 200，没有 body。

200 OK
Content-Length: <length of blob>
Docker-Content-Digest: <digest>

当收到响应，客户端能知道层已经存在注册表中，不需要进行上传操作

2.1.3、上传层文件

如果 POST 请求成功，响应 202，然后在响应头中会有“Location”指定上传 url

202 Accepted
Location: /v2/<name>/blobs/uploads/<uuid>
Range: bytes=0-<offset>
Content-Length: 0
Docker-Upload-UUID: <uuid>

上传过程用返回的 url 进行，对上传 url 的所有响应，无论是发送数据还是获取状态，都按照这种格式。尽管指定了“Location”标头的 URI 格式，但是客户端应将其视为黑盒，不要自己去组装。如果客户端需要将本地上传状态和远程上传状态关联，应使用Docker-Upload-UUID:标头的内容，在断点重传时，uuid 可以键入最后使用的位置。

2.1.4、上传进度

上传进度是通过头Range标识，虽然不是Range的标准使用方法，仍有很多例子使用。

对于刚刚开始的上传，例如一个 1000 字节的层文件，“Range”标头如下：

Range: bytes=0-0

使用 GET 方法获取上传进度

GET /v2/<name>/blobs/uploads/<uuid>
Host: <registry host>

响应类似，会返回 204

204 No Content
Location: /v2/<name>/blobs/uploads/<uuid>
Range: bytes=0-<offset>
Docker-Upload-UUID: <uuid>

2.1.5、单块上传

单块上传是上传单个块，避免分块复杂性，要执行单块上传，只需将整个 blob 放到提供的 url 中

PUT /v2/<name>/blobs/uploads/<uuid>?digest=<digest>
Content-Length: <size of layer>
Content-Type: application/octet-stream

<Layer Binary Data>

digest参数必须要在 PUT 请求中使用

2.1.6、分块上传

要执行一个块的上传，客户端可以指定Range并且只包含层的Range部分

PATCH /v2/<name>/blobs/uploads/<uuid>
Content-Length: <size of chunk>
Content-Range: <start of range>-<end of range>
Content-Type: application/octet-stream

<Layer Chunk Binary Data>

除了服务器必须按顺序接受之外，没有强制性执行块的拆分。服务器可以强制限制块的最小块，如果服务器不能接收块，会返回 416。

如果收到 416，客户端应从“最后一个有效范围”恢复上传，在此情况下返回 416：

• 无效的请求头Content-Range
• 乱序块：下一个块的范围必须在前一个响应的“最后一个有效范围”之后立即开始

如果块被成功接收，会返回 202

2.1.7、完成上传

为了保证上传完整性，客户端在上传 url 提交一个带有摘要参数的 PUT 请求，如果未提供，则不认为上传完成。

PUT /v2/<name>/blobs/uploads/<uuid>?digest=<digest>
Content-Length: <size of chunk>
Content-Range: <start of range>-<end of range>
Content-Type: application/octet-stream

<Last Layer Chunk Binary Data>

可选的，如果所有块都已上传，则可以发送带有 digest 参数和 0 长度的 body 的 PUT 请求以验证完成上传。

当最后一个块被接收，层校验完毕，客户端会收到 201 响应

201 Created
Location: /v2/<name>/blobs/<digest>
Content-Length: 0
Docker-Content-Digest: <digest>

Location会包含可访问的层 url，Docker-Content-Digest返回上传的 blob 摘要。

2.1.8、取消上传

DELETE /v2/<name>/blobs/uploads/<uuid>

发出此请求后，上传的 uuid 将不再有效，注册服务器将转储所有中间数据。虽然上传未完成会超时，但是如果客户端遇到致命错误仍可发出 http 请求，则应发出此请求。

2.1.9、跨存储库挂载

可以从客户端具有读取访问权限的另一个存储库安装 blob，从而无需上传注册表已知的 blob。 要发出 blob 挂载而不是上传，应按以下格式发出 POST 请求

POST /v2/<name>/blobs/uploads/?mount=<digest>&from=<repository name>
Content-Length: 0

如果 blob 成功被挂载，客户端会收到响应 201

201 Created
Location: /v2/<name>/blobs/<digest>
Content-Length: 0
Docker-Content-Digest: <digest>

Location将包含用于访问已经接收层文件的注册表 URI，Docker-Content-Digest返回上传的 blob 的摘要。

如果由于无效的存储库或摘要导致挂载失败，则注册表会回退到标准上传行为，并返回 202

202 Accepted
Location: /v2/<name>/blobs/uploads/<uuid>
Range: bytes=0-<offset>
Content-Length: 0
Docker-Upload-UUID: <uuid>

2.2、删除层文件

DELETE /v2/<name>/blobs/<digest>

如果存储库存在并且成功被删除，会响应 202，如果已经被删除或不存在，会响应 404。

如果删除注册表(registry)中清单(manifest)引用的层，则无法解析完整的镜像

2.3、推送镜像元数据

所有层文件已经上传，客户端能够上传镜像元数据了。

PUT /v2/`<name>`/manifests/`<reference>`
    Content-Type: `<manifest media type>`

    {
       "name":`<name>`,
       "tag": `<tag>`,
       "fsLayers": [
          {
             "blobSum": `<digest>`
          },
          ...
        ]
       ],
       "history": `<v1 images>`,
       "signature": `<JWS>`,
       ...
    }

如果上传出现问题，会响应 4xxx。如果在注册表中层文件不存在，会返回BLOB_UNKNOWN错误

{
        "errors:" [{
                "code": "BLOB_UNKNOWN",
                "message": "blob unknown to registry",
                "detail": {
                    "digest":`<digest>`
                }
            },
            ...
        ]
    }

3、小结

pull 分为两个步骤，第一步拉取清单 manifest，然后再根据清单中的 layers 拉取层文件。

push 分为两步，第一步会先去推送层文件 layer，会判断仓库中是否存在，是否需要分块上传，所有层文件上传完成之后，再去上传清单 manifest。