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/获取 upload UUID，再/blobs/uploads/ PUT到对应 URL（带?digest=sha256:xxx） - 推送 manifest 前，所有 layer 必须已存在 registry 中，否则会返回
MANIFEST_BLOB_UNKNOWN -
Accept请求头必须包含application/vnd.docker.distribution.manifest.v2+json，否则可能拿到旧版 schema1（已被多数 registry 拒绝）
常见失败错误与定位方式
实际编码中多数问题出在认证或路径解析上，而非逻辑本身。
立即学习“go语言免费学习笔记（深入）”；
-
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 错误里查半天。
