最可靠方式是使用 github.com/docker/go-docker 客户端调用 Docker Daemon HTTP API；需显式指定API版本、正确配置传输层与上下文、注意权限及流处理。
直接调用 Docker Daemon 的 HTTP API 是最可靠的方式
Go 官方不提供“Docker SDK”，github.com/docker/docker 仓库里的代码是 daemon 实现，不是客户端库。真正稳定、被广泛使用的客户端是 github.com/docker/go-docker（原 docker/engine-api），它封装了 Docker Daemon 的 HTTP API。别试图自己拼 URL + http.Client，除非你明确要绕过认证或调试底层行为。
关键点：
- Docker Daemon 默认监听
unix:///var/run/docker.sock（Linux/macOS）或tcp://127.0.0.1:2376（启用 TLS 的 Windows） - Go 客户端必须与 daemon 的 API 版本兼容；建议显式指定版本，如
"v1.41"，避免默认值随 client 升级意外变动 - 权限问题最常见：运行 Go 程序的用户需在
docker用户组中，否则连/var/run/docker.sock都打不开
初始化 docker.Client 时注意传输层和上下文控制
docker.NewClientWithOpts() 是推荐入口，它比旧版 NewAPIClient() 更清晰。你得传入 docker.FromEnv、docker.WithAPIVersionNegotiation 这类选项，而不是手动构造 http.Client。
常见错误现象：cannot connect to the Docker daemon —— 很可能漏了 docker.FromEnv，导致没读取 DOCKER_HOST 环境变量；或者没加 docker.WithHTTPClient() 自定义超时，导致拉镜像时卡死。
立即学习“go语言免费学习笔记（深入）”；
实操建议：
- 始终用
context.WithTimeout(ctx, 30*time.Second)包裹调用，Docker 操作不可控因素多（网络、镜像层下载、容器启动） - 不要复用全局
*docker.Client实例做并发操作——它本身是线程安全的，但若你共享了未隔离的context或自定义http.Transport，反而容易出问题 - 本地开发时，用
docker.WithHost("unix:///var/run/docker.sock")显式指定，别依赖环境变量模糊匹配
列出容器、创建容器、获取日志的典型调用链
这些是最常查、也最容易写错的三个操作。核心区别在于：列表是只读 GET，创建是 POST + JSON body，日志是流式响应（需要边读边处理，不能直接 json.Unmarshal）。
参数差异要点：
-
ContainerList的types.ContainerListOptions中，All: true才能看到已退出容器；默认只返回运行中 -
ContainerCreate的config和hostConfig必须分开传——前者是镜像级配置（Cmd,Env），后者是宿主机级（PortBindings,AutoRemove） -
ContainerLogs返回的是io.ReadCloser，必须用stdcopy.StdCopy()（来自github.com/moby/stdcopy）才能正确分离stdout/stderr流，否则日志混在一起且带 Docker 内部头信息
client, _ := docker.NewClientWithOpts(docker.FromEnv, docker.WithAPIVersionNegotiation())
ctx := context.Background()
// 列出所有容器（含已停止）
containers, _ := client.ContainerList(ctx, types.ContainerListOptions{All: true})
// 创建并启动 nginx 容器
resp, _ := client.ContainerCreate(ctx,
&container.Config{Image: "nginx:alpine", Cmd: []string{"nginx", "-g", "daemon off;"}},
&container.HostConfig{PortBindings: nat.PortMap{"80/tcp": []nat.PortBinding{{HostPort: "8080"}}}},
nil, nil, "my-nginx")
client.ContainerStart(ctx, resp.ID, types.ContainerStartOptions{})
// 获取日志（需 stdcopy）
out, _ := client.ContainerLogs(ctx, resp.ID, types.ContainerLogsOptions{ShowStdout: true, Follow: false})
defer out.Close()
stdcopy.StdCopy(os.Stdout, os.Stderr, out)
构建镜像必须用 BuildKit 或临时 Dockerfile 目录
Client.ImageBuild() 不接受单个 Dockerfile 字符串，必须传入一个 tar archive，里面包含 Dockerfile 和构建上下文文件。这是最容易卡住的点——很多人以为能像 CLI 那样直接给路径。
两种可行路径：
- 用
docker buildx+ BuildKit 后端：需 daemon 开启 BuildKit（export DOCKER_BUILDKIT=1），然后调用client.ImageBuild()并设置BuildOptions{Version: types.BuilderBuildKit} - 手动生成 tar：把
Dockerfile和所需文件（如app.go）放进临时目录，用archive.TarWithOptions()（来自github.com/moby/buildkit/util/archive）打包成io.Reader再传入 - 别硬编码
os.CreateTemp路径后调docker build -f /tmp/Dockerfile——这绕过了 Go client，失去统一错误处理和 context 控制
性能影响：BuildKit 模式支持并发层下载、缓存复用，比传统 builder 快 2–5 倍，但要求 daemon 版本 ≥ 19.03 且显式启用。
最常被忽略的是：所有涉及文件 I/O 的操作（build、cp、logs）都依赖正确的流关闭和 buffer 处理。比如 ContainerLogs 不调 Close() 可能导致 socket 一直挂着；ImageBuild 的 tar reader 若没 fully read，daemon 会认为上传中断而清理中间层。
