go 语言通过调用 docker cli 或 docker engine http api 管理容器，推荐使用官方 client 库对接 api 实现生产级控制；需注意权限配置、端口绑定格式、镜像拉取响应消费及构建日志流式处理。
Go 语言本身不直接构建或运行 Docker 容器，它通过调用 docker CLI 命令或对接 Docker Engine 的 HTTP API（即 Docker daemon 的 REST 接口）来实现容器管理。直接 exec docker 命令简单但依赖环境；调用 API 更可控、可嵌入、适合服务化场景。
用 os/exec 调用 docker run 最快上手
适合脚本化、CI 工具、一次性任务等轻量场景。关键点不是“能不能跑”，而是“如何捕获错误和输出”。
- 必须检查
cmd.Run()或cmd.CombinedOutput()的返回错误，Docker 命令失败时 exit code 非零，但 Go 不自动报错 - 避免硬编码镜像名或端口，用变量传入并做基础校验（例如端口是否为数字、镜像名是否含
:） - 注意 shell 注入风险：不要拼接用户输入到
cmd.Args，应使用cmd.Args = []string{"docker", "run", "-p", port, image}显式构造 - 后台运行容器时，加
-d参数后docker run立即返回容器 ID，可用strings.TrimSpace(out)提取
cmd := exec.Command("docker", "run", "-d", "-p", "8080:80", "--name", "mynginx", "nginx:alpine")
out, err := cmd.CombinedOutput()
if err != nil {
log.Fatalf("docker run failed: %v, output: %s", err, out)
}
fmt.Printf("Started container: %s", strings.TrimSpace(string(out)))
用 github.com/docker/docker/api/types 调用 Docker API
这是生产级做法，绕过 shell、支持超时、认证、复用连接。前提是你本地或远程的 Docker daemon 已启用 API（默认 unix:///var/run/docker.sock）。
- 初始化 client 必须指定 version，如
"1.41"，版本不匹配会导致400 Bad Request或字段缺失 -
ImagePullOptions中设All: true才能拉取多层镜像；不设则可能因本地无 base layer 报No such image - 创建容器时，
HostConfig.PortBindings是 map[string][]PortBinding，key 格式是"80/tcp"，不是"80" - 容器启动后需显式调用
ContainerStart，ContainerCreate只是创建，状态仍是created
cli, _ := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
resp, _ := cli.ImagePull(context.Background(), "nginx:alpine", types.ImagePullOptions{})
io.Copy(io.Discard, resp) // 必须消费响应体，否则 Pull 会卡住
config := &container.Config{Image: "nginx:alpine"}
hostConfig := &container.HostConfig{
PortBindings: nat.PortMap{"80/tcp": []nat.PortBinding{{HostPort: "8080"}}},
}
container, _ := cli.ContainerCreate(context.Background(), config, hostConfig, nil, nil, "mynginx")
cli.ContainerStart(context.Background(), container.ID, types.ContainerStartOptions{})
常见错误：connection refused / permission denied
不是代码写错了，而是 Docker 环境没配好。这两个错误占实际调试时间的 70% 以上。
立即学习“go语言免费学习笔记（深入）”；
-
dial unix /var/run/docker.sock: connect: permission denied→ 当前用户不在docker组，运行sudo usermod -aG docker $USER并重登终端 -
dial tcp 127.0.0.1:2375: connect: connection refused→ Docker daemon 没开 TCP 监听（默认只监听 Unix socket），需改/lib/systemd/system/docker.service中ExecStart加-H tcp://0.0.0.0:2375并重启服务（不推荐暴露公网） - 用
client.FromEnv时，确保DOCKER_HOST环境变量未被意外覆盖（比如 CI 环境里有残留值）
构建镜像不能靠 Go 直接调用 docker build
Go 程序可以执行 docker build -t myapp .，但无法替代 Dockerfile 语义或构建缓存逻辑。真正需要“在 Go 中构建镜像”的场景极少——绝大多数情况应把构建交给 CI 流水线或 docker buildx。
- 如果非要在 Go 中触发构建，务必用
cmd.Dir指定上下文路径，且确保该目录下有有效的Dockerfile - 构建过程输出是流式数据，别用
CombinedOutput()，改用StdoutPipe()+ 实时扫描日志行（例如匹配"Successfully built [a-f0-9]{12}"） - 注意资源占用：并发调用多个
docker build可能打满磁盘 I/O 或内存，需加限流
真正的难点从来不在“怎么写那几行 Go 代码”，而在于理解 Docker daemon 的权限模型、网络模型和生命周期——这些决定了你的程序是在协助运维，还是在制造新的故障面。
