(为什么无法镜像文件夹)

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

API1、拉取镜像

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

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

字段

描述

name

镜像名称

tag

镜像版本

fsLayers

层描述符列表(包括摘要)

signature

元数据签名

当获取元数据清单后,客户端必须验证签名保证名称和层的有效性。确认后,客户端将使用摘要(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 OKContent-Length: 9116Content-Type: application/vnd.docker.distribution.manifest.v1+prettyjwsDocker-Content-Digest: sha256:0f09fdacdca588279f0cb332ed0768daa9ed734c491d5d04b89d215982c2bfac1.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 OKContent-Length: <length of blob>Docker-Content-Digest: <digest>

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

2.1.3、上传层文件

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

202 AcceptedLocation: /v2/<name>/blobs/uploads/<uuid>Range: bytes=0-<offset>Content-Length: 0Docker-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 ContentLocation: /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 CreatedLocation: /v2/<name>/blobs/<digest>Content-Length: 0Docker-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 CreatedLocation: /v2/<name>/blobs/<digest>Content-Length: 0Docker-Content-Digest: <digest>

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

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

202 AcceptedLocation: /v2/<name>/blobs/uploads/<uuid>Range: bytes=0-<offset>Content-Length: 0Docker-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。


电脑