containerd 2.1.8 超深度分析 — Internal + Pkg 辅助模块汇总 + 设计模式总结

源码：internal/ (31,572行, 205文件) + pkg/ (16,495行, 149文件) + 总结

---

一、Internal 核心子模块

1.1 Shim 运行时 (internal/shim/)

文件	行数	功能
manager.go	470	Shim 进程管理（启动/连接/回收）
shim.go	260	Shim 实例封装
opts.go	120	Shim 选项
reaper.go	80	进程回收

Shim Manager 关键方法

type Manager struct {
    runtime string
    address string
    shimBinary binary ShimBinary  // shim 二进制封装
}

func (m *Manager) Start(ctx context.Context, id string, opts StartOpts) (_ Shim, retErr error) {
    // 1. 构建参数: -namespace, -id, -address, -publish-binary
    // 2. exec shim 二进制
    // 3. 读取 stdout 获取 socket 地址
    // 4. 建立 ttrpc 连接
    // 5. 返回 Shim 实例
}

1.2 Runtime (internal/runtime/v2/)

文件	行数	功能
shim.go	650	Shim 进程管理 + task 管理
task.go	200	Task 代理（转发到 shim ttrpc）
process.go	80	Exec 进程管理
opts.go	100	运行时选项

Runtime V2 Task 管理流程

1.3 NRI (Node Resource Interface)

// NRI 插件接口
type API interface {
    // 启动 NRI 插件
    Start(ctx context.Context, config string) error
    // 容器创建通知
    CreateContainer(ctx context.Context, pod *Pod, container *Container) (*ContainerAdjustment, error)
    // 容器更新通知
    UpdateContainer(ctx context.Context, pod *Pod, container *Container, update *ContainerUpdate) (*ContainerAdjustment, error)
    // 容器停止通知
    StopContainer(ctx context.Context, pod *Pod, container *Container) error
}

NRI 设计：允许第三方插件在容器创建/更新时调整资源配置（如 CPU 亲和性、设备分配）。

1.4 其他 Internal 子模块

模块	功能
eventq	事件队列（有序消费）
kmutex	按 key 加锁的互斥锁
registrar	注册表（key → value 映射）
truncindex	截断索引（前缀搜索）
failpoint	故障注入（测试用）
userns	User namespace ID 映射
erofsutils	EROFS 文件系统工具
fsverity	fs-verity 文件完整性验证
lazyregexp	延迟编译正则表达式
randutil	安全随机数
pprof	性能分析
cleanup	清理工具
tomlext	TOML v2 工具

---

二、Pkg 核心子模块

2.1 OCI (pkg/oci/)

// OCI Spec 构建
func GenerateSpec(opts ...SpecOpts) (*specs.Spec, error) {
    // 1. 创建默认 Spec
    // 2. 应用所有 SpecOpts
    // 3. 返回最终 Spec
}

SpecOpts	作用
WithProcessArgs	设置命令参数
WithProcessCwd	设置工作目录
WithEnv	设置环境变量
WithHostname	设置主机名
WithMounts	设置挂载点
WithLinuxNamespace	添加 namespace
WithCapabilities	设置 capabilities
WithResources	设置 cgroup 资源限制
WithSeccomp	设置 seccomp 规则
WithApparmorProfile	设置 AppArmor

2.2 Archive (pkg/archive/)

// tar 归档操作
func Apply(ctx context.Context, root string, r io.Reader, opts ...ApplyOpt) (int64, error)
// 解压 tar 到 root 目录

func Diff(ctx context.Context, a, b string, opts ...DiffOpt) io.ReadCloser
// 计算两个目录的差异 tar

2.3 cio — 容器 IO 管理

type IO struct {
    Stdin  io.Reader
    Stdout io.Writer
    Stderr io.Writer
    // ...
}

func NewCreator(opts ...Opt) Creator {
    // 创建 IO 管道
    // 支持: fifo / pipe / terminal / null
}

func NewPipeCreator(opts ...Opt) Creator {
    // 使用管道 (用于 exec)
}

IO 创建策略

策略	描述
NewFifoCreator	使用 FIFO (容器 init 进程)
NewPipeCreator	使用管道 (exec 进程)
NewNullCreator	空IO (不需要IO的容器)
Terminal	终端模式 (pty)

2.4 shim (pkg/shim/)

// Shim 配置
type Config struct {
    Path     string    // shim 二进制路径
    Namespace string   // namespace
    WorkDir   string   // 工作目录
    Address   string   // containerd 地址
}

// Shim 选项
type Opts struct {
    BundlePath string
    Debug      bool
    NoSetupLogger bool
    // ...
}

2.5 filters (pkg/filters/)

// 过滤器语法
// filters=="" → 匹配所有
// filters=="id==nginx" → 精确匹配
// filters=="labels.key~=/^app.*/" → 正则匹配
func Parse(s string) (Filter, error)
func Match(filters []Filter, object Adaptor) bool

2.6 其他 Pkg 子模块

模块	行数	功能
sys	770	系统调用封装 (MkdirAllWithACL/IsProcessAlive/…)
netns	396	Network namespace 管理
tracing	299	OpenTelemetry 追踪
progress	284	进度条显示
namespaces	226	Namespace 工具 (context 提取/注入)
reference	156	Docker 引用解析 (docker.io/library/nginx:latest)
gc	194	GC 算法 (标记-清除)
dialer	164	Unix socket 拨号器
seccomp	128	Seccomp 配置生成
ioutil	264	IO 工具
rdt	115	Intel RDT 资源管理
apparmor	96	AppArmor profile 设置
cap	187	Linux capabilities 操作
blockio	111	Block IO 管理
stdio	63	标准IO工具
cdi	56	Container Device Interface
oom	30	OOM Score 设置
protobuf	77	Protobuf 工具
identifiers	73	ID 校验
labels	70	Label 工具
deprecation	68	废弃警告
timeout	66	超时配置
rootfs	522	Rootfs 挂载
kernelversion	94	内核版本检测
epoch	108	时间戳一致性
snapshotters	96	Snapshotter 工具

---

三、完整架构图（6层 + 模块间关系）

---

四、全局设计模式总结

#	模式	体现	模块
1	Plugin 体系	Register → Graph → Init → RegisterService	plugins/
2	侧导入	_ "builtins" 触发 init()	cmd/builtins/
3	Proxy 模式	Client → gRPC Proxy → Remote Plugin	client/, proxy/
4	CAS	Content Store 以 digest 为 key	core/content/
5	Copy-on-Write	overlayfs snapshotter	core/snapshots/
6	标记-清除 GC	从 Leases/Images 标记	core/metadata/gc
7	Shim 隔离	独立进程，containerd 重启不影响	internal/shim/
8	ttrpc 轻量协议	替代 gRPC 用于 shim	ttrpc
9	多容器一 Shim	v2 架构	shim-runc-v2
10	Sandbox 抽象	Pod 级管理 + 自定义控制器	core/sandbox/
11	CRI 适配	CRI Service → containerd API 转换	plugins/cri/
12	事件总线	Publish/Subscribe 解耦	core/events/
13	Namespace 隔离	gRPC metadata + BoltDB bucket	pkg/namespaces/
14	IO Creator 策略	Fifo/Pipe/Null/Terminal	pkg/cio/
15	选项模式	SpecOpts/NewContainerOpts/…	pkg/oci/
16	Walker 模式	Content.Walk/Snapshotter.Walk	core/
17	Ingest 临时区	Writer → ingest → commit → blobs	core/content/
18	Per-key Mutex	kmutex 按 namespace 加锁	internal/kmutex/
19	Transfer 统一	Pull/Push/Import/Export 统一接口	core/transfer/
20	NRI 插件	容器创建/更新时第三方干预	internal/nri/

---

五、10大核心发现

1. Plugin 体系是 containerd 的骨架 — 25+ 内置插件，拓扑排序初始化，依赖注入解耦，类型断言分发到 gRPC/ttrpc/TCP 三种 Server

2. 双协议设计 — gRPC 对外（Client SDK），ttrpc 对内（Shim 通信），ttrpc 帧协议极简高效

3. Shim 隔离是容器可靠性的关键 — Shim 独立于 containerd daemon 运行，containerd 崩溃/重启不影响容器，v2 支持多容器一 shim

4. CAS 是存储核心 — Content Store 以 digest 为 key（sha256:abcd），所有镜像层、manifest、config 都是 blob，Ingest 临时区保证原子写入

5. Metadata 是 BoltDB 单文件 — 8 类 bucket（containers/images/content/snapshots/leases/namespaces），per-namespace kmutex 加锁，标记-清除 GC

6. Snapshotter 是可插拔的 — overlayfs（默认）/btrfs/devicemapper/native/remote，通过 Plugin 注册，Prepare/Commit/View 三种操作

7. CRI Plugin 是 Kubernetes 的桥梁 — 将 CRI RuntimeService/ImageService 适配为 containerd 的 Container/Task/Sandbox/Image 操作

8. Sandbox 支持 Pod 级隔离 — PodSandbox (pause 容器) + 自定义 Controller (Firecracker 等)，为 Kata Containers 等安全容器提供基础

9. Transfer Service 统一传输 — Pull/Push/Import/Export 统一为 Transfer 接口，支持流处理器（StreamProcessor）做加解密/格式转换

10. Namespace 是多租户的基础 — 从 gRPC metadata 提取 namespace，注入 context，所有操作自动隔离。Kubernetes 的每个 namespace 对应 containerd 的一个 namespace