Moby 项目导读：模块化容器引擎的架构原则、Go 模块体系与 docker/docker 迁移指南

2026-09-05 12:17:29作者：管翌锬

本文基于 Moby 仓库根目录的 README.md 展开，结合仓库内 go.mod、client/go.mod、api/README.md 等实际源码与配置文件进行佐证。读完本篇，你将理解 Moby 作为 Docker 上游开源项目的设计原则与定位、三个 Go 模块（根模块、client、api）的边界与版本策略，并掌握从废弃的 github.com/docker/docker 导入路径迁移到 github.com/moby/moby/client / github.com/moby/moby/api 的具体方法。

一、Moby 是什么：一个容器生态的"乐高积木套装"

Moby 是由 Docker 公司发起的开源项目，目标是推动并加速软件容器化。官方将其定位为一套"乐高积木"（Lego set）式的工具组件集合：

它提供构建容器系统所需的组件：容器构建工具、镜像仓库（registry）、编排工具、运行时（runtime）等；
它提供将这些组件组装成自定义容器系统的框架；
它还是所有容器爱好者与专业人员进行实验、交流想法的场所。

这些组件既可以单独作为构建块使用，也可以配合其他工具与项目组合使用。当前仓库的目录结构印证了这种模块化组织：

目录	职责（从目录结构看）
cmd/	可执行程序入口，如 `cmd/dockerd`（守护进程）、`cmd/docker-proxy`（端口代理）
daemon/	引擎守护进程主体：容器生命周期、镜像、存储驱动、网络、卷、日志驱动等
api/	客户端与服务端共享的 Engine API 类型及 Swagger 定义
client/	Docker Engine API 的 Go 客户端库
integration/ 与 integration-cli/	需要真实守护进程的集成测试
pkg/	通用工具库（用户主目录解析、进程管理、系统信息、尾随文件等）

二、设计原则：模块化、可替换、安全与开发者导向

README 明确列出了 Moby 的四条设计原则，这些原则决定了它的 API 风格与工程文化：

模块化（Modular）：项目包含大量组件，每个组件拥有明确的职责和 API，并协同工作；
自带组件但可替换（Batteries included but swappable）：Moby 内置了构建完整功能容器系统所需的足够组件，但其模块化架构保证大多数组件都可以换成不同实现（例如存储驱动、日志驱动、网络驱动均可插拔）；
可用的安全性（Usable security）：提供安全的默认值，但不以牺牲可用性为代价；
面向开发者（Developer focused）：API 的功能定位是"构建强大工具的组件"，并非面向最终用户的工具；其文档与用户体验（UX）同样面向开发者而非终端用户。

三、目标读者与和 Docker 产品的关系

Moby 的目标读者是希望基于容器修改、调试、修复、实验、发明和构建系统的工程师、集成者与爱好者。它明确"不面向寻找商业支持系统的用户"，而是面向愿意与开源代码一起工作、学习的人。

关于与 Docker 产品的关系，README 给出了几条关键事实：

Moby 中的组件与工具，最初就是 Docker 与社区为 Docker 项目构建的开源组件；
Docker 承诺将 Moby 作为 Docker 产品的上游（upstream）；
其他项目同样被鼓励以 Moby 为上游、复用其组件，所有此类使用方式会被同等对待，外部维护者与贡献者受到欢迎；
Moby 不是 Docker 产品支持或功能请求的提交处，而是贡献者修改开源代码、修复 bug 的地方；
发布版本仅由维护者、社区与用户以**尽力而为（best efforts）**方式支持；需要企业或商业支持的用户，官方指引使用 Docker Desktop 或 Mirantis Container Runtime 等产品。

仓库中的 releases/versions.yaml 记录了当前发布线：last: "29.7.2"、next: "29.8.0"，即本仓库处于 Docker Engine 29.x 系列之上。

四、Go 模块体系：三个模块、三种用途

重要变更（源自 README.md 的 IMPORTANT 提示）：自 2025 年 11 月发布的 Docker v29 起，Go 模块 github.com/docker/docker 已被废弃（deprecated）且不再更新。

仓库中受支持的公开 Go 模块如下：

模块	说明
`github.com/moby/moby/client`	Docker Engine API 的 Go 客户端
`github.com/moby/moby/api`	客户端与服务端共享的 API 类型
`github.com/moby/moby/v2`（根模块）	用于构建基于 Moby 的容器引擎（如 Docker Engine）的代码库。它只产出二进制文件，不适合作为 Go 库导入，且没有任何 API 稳定性保证

仓库中的三个 go.mod 文件印证了这一划分：

根模块 go.mod：module github.com/moby/moby/v2，Go 1.26.3，依赖 containerd v2、hcsshim、libnetwork 相关组件等，规模庞大——这正是一个"构建引擎"而非"提供库"的模块特征；
client/go.mod：module github.com/moby/moby/client，Go 1.24，依赖 github.com/moby/moby/api v1.55.0，并用 replace github.com/moby/moby/api => ../api 在仓库内做本地联编；
api/go.mod：module github.com/moby/moby/api，Go 1.24，依赖极小（go-units、docker-image-spec、opencontainers/image-spec 等），符合"仅共享类型、无重依赖"的定位。

发布标签（Release tags）的命名规则

Docker Engine 的发布标签使用 docker- 前缀，例如 docker-v29.0.0 对应 Docker Engine 29.0.0；
这些标签只用于从根模块构建 Docker Engine 二进制，必须通过 go get 消费（即不可 go get）；
client 与 api 两个模块独立版本化，各自拥有独立标签，例如 client/v1.x.x、api/v1.x.x。

版本号在构建期如何注入？从 dockerversion/version_lib.go 可以看到：GitCommit、Version、BuildTime、PlatformName 等变量默认为 "library-import"，构建时会被构建期信息覆盖（通过 go build 的 -ldflags 注入）——这也解释了为什么根模块被当作库导入时没有任何语义保证。

五、从 `github.com/docker/docker` 迁移

迁移的核心动作是替换导入路径，README 给出的 diff 示例如下：

- import "github.com/docker/docker/client"
+ import "github.com/moby/moby/client"

- import "github.com/docker/docker/api/types"
+ import "github.com/moby/moby/api/types"

需要注意的破坏性变更：README 明确指出 v29 包含大量破坏性 API 变更，包括 options 结构体化、方法重命名、类型迁移等，完整的 Go SDK 变更清单以官方 docker-v29.0.0 发布说明为准（请以发布说明为准，本文不转载外部链接）。

从当前仓库源码可以看到新 API 形态的直观样例。client/README.md 中的"列出所有容器"（等价于 docker ps --all）示例：

package main

import (
	"context"
	"fmt"

	"github.com/moby/moby/client"
)

func main() {
	// 使用 client.FromEnv 从常用环境变量（DOCKER_HOST、DOCKER_API_VERSION）
	// 配置客户端；API 版本协商默认开启，连接较旧守护进程时可自动降级。
	apiClient, err := client.New(
		client.FromEnv,
		client.WithUserAgent("my-application/1.0.0"),
	)
	if err != nil {
		panic(err)
	}
	defer apiClient.Close()

	// 列出所有容器（含已停止的）。
	result, err := apiClient.ContainerList(context.Background(), client.ContainerListOptions{
		All: true,
	})
	if err != nil {
		panic(err)
	}

	// 打印每个容器的 ID、状态和创建它的镜像。
	fmt.Printf("%s  %-22s  %s\n", "ID", "STATUS", "IMAGE")
	for _, ctr := range result.Items {
		fmt.Printf("%s  %-22s  %s\n", ctr.ID, ctr.Status, ctr.Image)
	}
}

这个示例同时体现了 v29 的 API 风格变化：方法接收具名 options 结构体（client.ContainerListOptions）而非旧的多个散参数，返回值是带 Items 字段的结构化结果（见 client/client.go 文档注释中的同一示例）。此外，client/client.go 定义了版本协商边界：MaxAPIVersion = "1.56"（支持的最高 REST API 版本，协商时可向下降级）、MinAPIVersion = "1.40"（低于该版本不参与协商），客户端默认开启 API 版本协商以兼容较旧守护进程。

Engine API 的组成

api/README.md 进一步说明了 API 层在仓库中的落点：

api/swagger.yaml：API 的 Swagger 定义，可用于自动生成文档、（进行中的）Go 服务端/客户端代码生成，以及供第三方做机器可读的接口内省；
api/types/：客户端与服务端共享的类型，多为手写，部分从 Swagger 自动生成；
client/：命令行客户端使用的 Go 客户端，同样可供第三方 Go 程序使用；
daemon/：提供该 API 的守护进程。

六、构建引擎二进制：从根模块出发

如果你要基于 Moby 根模块构建容器引擎（而非导入库），入口是 cmd/dockerd/main.go，构建工具链由根目录 Makefile 提供。Makefile 注释中给出了两个有代表性的用法：

通过 make KEEPBUNDLE=1 binary 构建并保留产物目录；
通过 DOCKER_LDFLAGS 在构建期改写打包变量，例如改变内置存储驱动优先级：

make DOCKER_LDFLAGS="-X github.com/moby/moby/v2/daemon/graphdriver.priority=overlay2,zfs" dynbinary

-X 指向 github.com/moby/moby/v2/daemon/graphdriver 包变量，与前述"构建期通过 ldflags 注入变量"的机制一致。Makefile 还透传了大量 DOCKER_*、TEST_* 环境变量用于构建与测试编排，具体清单见 Makefile。

七、许可与合规

Moby 采用 Apache License 2.0 许可，完整文本见 LICENSE；
README 的 Legal 部分提示：Moby 的使用与转移可能受到美国及其他政府出口法规限制，使用者有责任确保自身使用与转移不违反适用法律，更多背景见 NOTICE。

小结：如何正确使用这个仓库

写 Go 程序对接容器引擎：导入 github.com/moby/moby/client，共享类型导入 github.com/moby/moby/api，二者独立版本化、可 go get；
构建/定制容器引擎：使用根模块 github.com/moby/moby/v2，它只产出二进制，不要作为库导入；
旧项目迁移：将 github.com/docker/docker/{client,api/types} 替换为新路径，并按 v29 发布说明处理 options 结构体、方法重命名等破坏性变更；
理解 API 全貌：从 api/swagger.yaml 与 api/docs/ 下各版本 API 文档入手，从 cmd/dockerd 与 daemon/ 入手理解引擎实现。