1. 概述
在本教程中，我们将学习如何通过 Docker Registry API 列出远程仓库中的镜像（Images），并获取某个镜像的标签（Tags）。
这类操作在实际开发和部署中非常有用，例如我们可以查看某个仓库中可用的镜像版本，从而决定使用哪个版本进行部署。
⚠️ 注意：本文面向的是有经验的开发者，因此不会过多解释 Docker 的基础概念。
2. Docker Registry API 简介
Docker Registry 提供了一套 RESTful API，用于与仓库进行交互。这套 API 是 Docker CLI 背后调用的接口，支持诸如拉取（pull）、推送（push）、打标签（tag）等操作。
我们也可以绕过 Docker CLI，直接通过 HTTP 请求调用这些接口来管理镜像。
2.1 API 路径格式
Registry API 的基本路径格式如下：
/<api版本>/<镜像仓库名称>/<资源类型>/<参数>
各部分含义如下：
- API版本：目前主流为
/v2/ - 镜像仓库名：如
nginx、library/ubuntu、company/app等 - 资源类型：如
manifests、blobs、tags/list等 - 参数：可选，用于进一步细化操作，如
latest、sha256:...等
2.2 示例请求
列出 nginx 镜像的 latest 标签的 manifest 信息：
GET /v2/nginx/manifests/latest
3. Docker Registry API V2 使用详解
目前主流使用的是 V2 版本的 Registry API。以下操作以自建仓库 https://my-registry.io 为例，使用 curl 命令进行演示。
3.1 列出所有镜像
使用 /_catalog 接口列出仓库中所有镜像：
curl -X GET https://my-registry.io/v2/_catalog
返回示例：
{
"repositories": ["centos", "ubuntu"]
}
⚠️ 如果启用了认证，需加上 -u 参数传入用户名和密码：
curl -u user:password -X GET https://my-registry.io/v2/_catalog
3.2 分页列出镜像
当镜像数量较多时，可以通过 n=<数量> 参数分页获取：
curl -X GET https://my-registry.io/v2/_catalog?n=1
返回示例：
{
"repositories": ["centos"]
}
要获取下一页，需在请求头中加上 Link 字段，并携带 last 参数：
curl -H 'Link: <https://my-registry.io/v2/_catalog?n=1&last=centos>; rel="next"' \
-X GET "https://my-registry.io/v2/_catalog?n=1&last=centos"
返回示例：
{
"repositories": ["ubuntu"]
}
3.3 获取某个镜像的标签列表
使用 /tags/list 接口获取指定镜像的所有标签：
curl -X GET https://my-registry.io/v2/ubuntu/tags/list
返回示例：
{
"name": "ubuntu",
"tags": ["latest", "16.04"]
}
4. Docker Registry API V1（已弃用）
V1 版本在 Docker 17.06 中被弃用，17.12 中彻底移除。如果你遇到旧版本 Registry，仍可使用 V1 接口。
4.1 列出所有镜像
V1 没有直接列出所有镜像的接口。可以使用 docker search 命令代替：
docker search my-registry.io/centos
如果不指定仓库地址，默认会搜索 Docker Hub。
例如，未指定仓库时搜索 “ubuntu”，输出如下图所示（模拟截图）：
4.2 获取镜像标签
V1 获取标签的接口格式如下：
curl -X GET https://registry.hub.docker.com/v1/repositories/baeldung/mesos-marathon-demo/tags
返回示例：
[
{"layer": "", "name": "32"},
{"layer": "", "name": "33"},
{"layer": "", "name": "34"}
]
每个标签是一个对象，包含 name 和 layer 字段。如果只需要标签名，可以结合 jq 提取：
curl -s GET https://registry.hub.docker.com/v1/repositories/baeldung/mesos-marathon-demo/tags | jq -r '[.[].name]'
输出：
[
"32",
"33",
"34"
]
5. 总结
本文介绍了如何使用 Docker Registry API 的 V2 和 V1 版本，列出远程仓库中的镜像和标签。
✅ V2 版本功能更强大，支持分页、更丰富的资源操作
❌ V1 版本已弃用，不建议用于新项目
⚠️ 注意认证问题，多数私有仓库都需要用户名和密码才能访问
通过这些 API，我们可以实现自动化构建、部署、版本控制等流程，不再依赖 Docker CLI，更加灵活可控。