Golang实现Docker镜像推送拉取方法

Go 语言需借助 containers/image 库或手动调用 registry v2 HTTP API 实现镜像推送/拉取；前者稳定、纯用户态、需显式处理认证与镜像路径，后者需自行管理 token、blob 上传、manifest 校验等细节。

Go 语言本身不直接提供 Docker 镜像推送/拉取能力，docker 命令背后的镜像分发逻辑由 containerd 和 registry API 实现；用 Go 实现需调用官方 SDK 或封装 HTTP 请求，而非调用 CLI。

用 containers/image 库实现镜像推送与拉取

这是目前最稳定、被 podman 和 buildah 使用的 Go 实现库，支持 OCI 和 Docker registry 协议。它不依赖 dockerd 或 containerd 进程，纯用户态操作。

• 需显式处理认证：从 ~/.docker/config.json 读取或手动构造 authConfig
• 镜像名必须含 registry 地址（如 quay.io/libpod/alpine:latest），不能只写 alpine:latest
• 拉取后得到的是 *image.Image，需自己解包到目录或转为 tar 流；推送前需确保是 types.SystemContext 可识别的源类型（如 dir:/path、docker-archive:/file.tar）

package main

import (
	"context"
	"fmt"
	"github.com/containers/image/v5/copy"
	"github.com/containers/image/v5/directory"
	"github.com/containers/image/v5/image"
	"github.com/containers/image/v5/manifest"
	"github.com/containers/image/v5/signature"
	"github.com/containers/image/v5/transports"
	"github.com/containers/image/v5/types"
)

func main() {
	sys := &types.SystemContext{
		DockerAuthConfig: &types.DockerAuthConfig{
			Username: "myuser",
			Password: "mypass",
		},
	}

	srcRef, err := transports.ParseImageName("docker-archive:/tmp/alpine.tar")
	if err != nil {
		panic(err)
	}
	dstRef, err := transports.ParseImageName("docker://quay.io/myuser/alpine:dev")
	if err != nil {
		panic(err)
	}

	options := copy.Options{
		ReportWriter:   nil,
		SourceCtx:      sys,
		DestinationCtx: sys,
	}

	if _, err = copy.Image(context.Background(), srcRef, dstRef, options); err != nil {
		panic(err)
	}
	fmt.Println("push done")
}

手动调用 registry v2 HTTP API 的关键点

绕过 SDK 直接发 HTTP 请求适合轻量集成或调试，但要自己处理 token 认证、blob 上传分块、manifest 校验等细节。

• 首次请求 GET /v2/ 返回 401 时，从 WWW-Authenticate 头提取 realm 和 scope，再向该 realm 发起 GET 获取 token
• 上传 layer 时必须先 POST /v2//blobs/uploads/ 获取 upload UUID，再 PUT 到对应 URL（带 ?digest=sha256:xxx）
• 推送 manifest 前，所有 layer 必须已存在 registry 中，否则会返回 MANIFEST_BLOB_UNKNOWN
• Accept 请求头必须包含 application/vnd.docker.distribution.manifest.v2+json，否则可能拿到旧版 schema1（已被多数 registry 拒绝）

常见失败错误与定位方式

实际编码中多数问题出在认证或路径解析上，而非逻辑本身。

• error copying image to the remote destination: Error determining manifest MIME type for docker://...：说明 dstRef 解析失败，检查是否漏了 docker:// 前缀或 registry 域名拼写错误
• unauthorized: authentication required：不是密码错，而是 SystemContext.DockerAuthConfig 未设置，或 config.json 路径不对（默认读 $HOME/.docker/config.json）
• failed to get destination image: pinging container registry ... failed：网络不通，或 registry 不支持 HTTPS（需设 sys.DockerInsecureSkipTLSVerify = true）
• 拉取后无法运行：image.Image 默认只加载 manifest 和 config，layer 内容需显式调用 image.Manifest() + image.ConfigInfo() + image.LayerInfos() 分别获取并下载

真正难的不是“怎么推”，而是理解 registry 协议中 blob、manifest、config 三者的依赖顺序和校验规则——漏掉一次 digest 计算或 header 设置，就卡在 400 错误里查半天。