插件系统与 launchd 集成

apple/container 有一个出人意料的设计：它自身的内置组件——Linux 运行时、vmnet 网络管理器、镜像助手——全都是插件。它们遵循与第三方扩展完全相同的发现与注册机制。这套插件系统并非事后附加的扩展方案，而是整个项目组织自身功能的核心方式。

本文将完整梳理插件系统的运作链路：从 config.json 的结构定义，到目录扫描、launchd plist 生成、Mach 服务命名规范，再到 CLI 对未识别子命令的透明 execvp 分发。

插件类型与 config.json 结构

每个插件都是一个目录，其中包含一个 config.json 文件，以及可选的 bin/ 子目录（存放可执行文件）。PluginConfig 结构体定义了这套 schema。

最关键的区分在于：CLI 插件没有 servicesConfig，而 daemon 插件有。Daemon 插件可以声明一个或多个服务，每个服务对应一种 DaemonPluginType：

classDiagram
    class PluginConfig {
        +abstract: String
        +author: String?
        +servicesConfig: ServicesConfig?
        +isCLI: Bool
    }
    class ServicesConfig {
        +loadAtBoot: Bool
        +runAtLoad: Bool
        +services: [Service]
        +defaultArguments: [String]
    }
    class Service {
        +type: DaemonPluginType
        +description: String?
    }
    class DaemonPluginType {
        <<enumeration>>
        runtime
        network
        core
        auxiliary
    }
    PluginConfig --> ServicesConfig
    ServicesConfig --> Service
    Service --> DaemonPluginType

类型	生命周期	示例
runtime	每个容器一个实例	container-runtime-linux
network	每个网络一个实例	container-network-vmnet
core	单例，与 API server 绑定	container-core-images
auxiliary	保留，供未来使用	—

内置 runtime 插件的 config.json 很有参考价值：

{
    "abstract": "Linux container runtime plugin",
    "servicesConfig": {
        "loadAtBoot": false,
        "runAtLoad": false,
        "services": [{ "type": "runtime" }],
        "defaultArguments": []
    }
}

注意 loadAtBoot 为 false——runtime 插件不会在 API server 启动时注册到 launchd，而是在创建容器时按需注册。network 插件的 config.json 同样将 loadAtBoot 设为 false，但将 runAtLoad 设为 true，这意味着它一被加载到 launchd 就会立即启动。

提示： 第 99 行的 isCLI 计算属性逻辑很简单：servicesConfig == nil。没有服务配置的插件就是 CLI 插件。这也意味着，如果一个插件同时包含 servicesConfig，它既可以提供 daemon 服务，也可以提供 CLI 界面。

插件发现：扫描目录中的 config.json

PluginLoader.findPlugins() 会按优先级顺序扫描多个目录来查找已安装的插件：

1. 用户插件 — <installRoot>/libexec/container-plugins/
2. App bundle 插件 — Bundle.main.resourceURL/plugins/（用于 .app 安装方式）
3. 安装根目录插件 — <installRoot>/libexec/container/plugins/（用于 Unix 风格安装）

flowchart TD
    A[findPlugins] --> B[For each plugin directory]
    B --> C[List subdirectories]
    C --> D[For each subdirectory]
    D --> E[Try each PluginFactory]
    E --> F{Factory creates Plugin?}
    F -->|Yes| G{Name already seen?}
    F -->|No| H[Try next factory]
    G -->|Yes| I[Skip - shadowed]
    G -->|No| J[Add to results]
    J --> K[Record name in set]

遮蔽（shadowing）机制是这里的关键：如果同名插件同时存在于用户目录和安装根目录，用户版本优先。这让用户无需修改系统安装即可覆盖内置插件。扫描顺序至关重要——用户目录优先扫描，pluginNames 是一个 Set<String>，用于防止重复加载。

PluginFactory 协议支持不同的目录布局。DefaultPluginFactory 期望存在 config.json 和 bin/ 目录；AppBundlePluginFactory 则处理 macOS app bundle 的布局格式。工厂模式使得发现逻辑无需关心具体的目录结构细节。

launchd 注册：Plist 生成与 bootstrap/bootout

当一个 daemon 插件需要运行时，PluginLoader.registerWithLaunchd() 负责生成 launchd plist 并完成注册，流程如下：

1. 根据插件名称和可选的实例 ID 构造 launchd label
2. 构建命令行参数（默认为 ["start"]，加上资源路径和 debug 标志）
3. 过滤环境变量，仅传递以 CONTAINER_ 开头的变量以及代理相关配置
4. 生成包含 label、参数、环境变量、Mach 服务名称和 session 类型的 LaunchPlist 结构
5. 将 plist 序列化写入磁盘
6. 调用 ServiceManager.register(plistPath:) 执行 launchctl bootstrap

sequenceDiagram
    participant API as container-apiserver
    participant PL as PluginLoader
    participant SM as ServiceManager
    participant LD as launchd

    API->>PL: registerWithLaunchd(plugin, instanceId)
    PL->>PL: Generate LaunchPlist
    PL->>PL: Write plist to disk
    PL->>SM: register(plistPath)
    SM->>LD: launchctl bootstrap <domain> <plist>
    LD->>LD: Register Mach services
    LD-->>SM: OK

ServiceManager 是对 /bin/launchctl 的轻量封装：注册时调用 launchctl bootstrap，注销时调用 launchctl bootout，重启时调用 launchctl kickstart，发送信号时调用 launchctl kill。domain 通过查询 launchctl managername 动态确定——GUI 会话返回 Aqua，后台会话返回 Background，系统会话返回 System，分别映射到 gui/<uid>、user/<uid> 和 system。

PluginLoader.swift#L268-L275 中的环境变量过滤是一项安全措施：只有以 CONTAINER_ 开头的变量以及常见代理变量（http_proxy、HTTP_PROXY 等）才会传递给插件进程，从而避免敏感环境变量意外泄露。

Mach 服务命名规范

Mach 服务命名遵循 Plugin.swift#L59-L75 中定义的固定模式：

com.apple.container.{type}.{pluginName}[.{instanceId}]

示例：

• com.apple.container.runtime.container-runtime-linux.abc123 — 容器 abc123 的 runtime 实例
• com.apple.container.network.container-network-vmnet — 单例 network 插件
• com.apple.container.core.container-core-images — 单例 images 插件

flowchart LR
    subgraph "Singleton plugins"
        N["com.apple.container.network.container-network-vmnet"]
        I["com.apple.container.core.container-core-images"]
    end
    subgraph "Per-instance plugins"
        R1["com.apple.container.runtime.container-runtime-linux.{uuid1}"]
        R2["com.apple.container.runtime.container-runtime-linux.{uuid2}"]
    end

实例 ID 后缀对 runtime 插件至关重要——每个容器都需要独立的 runtime 进程，对应各自的 Mach 服务名称。SandboxClient.machServiceLabel 方法在建立连接时负责构造这个 label，ContainersService 在向 launchd 注册插件时也会用到它。

launchd label 的格式略有不同：com.apple.container.{pluginName}[.{instanceId}]——没有 type 部分。这是因为 launchd label 在所有服务中必须唯一，而插件名称本身已经包含了足够的上下文信息。

CLI 插件分发：execvp 机制

插件系统的最后一个环节处理 CLI 扩展。当你输入一个未识别的子命令（如 container foo）时，DefaultCommand 会接管处理。

DefaultCommand 被注册为 Application 命令配置中的 defaultSubcommand，凡是不匹配已知命令的参数都会由它接收。其 run() 方法的执行逻辑如下：

1. 通过 API server 创建 PluginLoader
2. 将第一个参数作为潜在的插件名称提取出来
3. 搜索同名插件
4. 验证该插件是 CLI 插件（plugin.config.isCLI）
5. 将信号处理器重置为默认值（让插件自行管理信号）
6. 调用 plugin.exec(args:) ——内部执行 execvp

flowchart TD
    A["container foo --bar baz"] --> B[DefaultCommand.run]
    B --> C{Plugin 'foo' exists?}
    C -->|No| D[Print error with hint paths]
    C -->|Yes| E{Is CLI plugin?}
    E -->|No| D
    E -->|Yes| F[Reset SIGINT/SIGTERM]
    F --> G["plugin.exec(args)"]
    G --> H["execvp('/path/to/foo', args)"]
    H --> I[Plugin takes over process]

Plugin.swift#L102-L111 中的 execvp 调用会直接替换当前进程，而非 fork 一个子进程。插件二进制接管执行后，从用户的角度来看，它与原生子命令别无二致。DefaultCommand.swift#L104-L107 中的信号重置则确保插件以干净的信号处理状态启动，而不会继承 CLI 的自定义信号处理器。

提示： 如果你正在开发 CLI 插件，当插件未找到时，错误信息中会列出插件的正确安装目录。这些路径是根据 install root 动态计算得出的，不是硬编码的，因此始终准确。

下一步

至此，我们已经完整了解了 apple/container 如何通过插件系统来发现、加载和管理各个组件。本系列的最后一篇文章将聚焦于构建系统——这是一个与 XPC 架构截然不同的设计。container build 通过 vsock 上的 gRPC 与运行在 Linux VM 内部的 BuildKit 进程通信，使用 HPACK 元数据头传递构建配置，并通过双向流处理进度更新和终端尺寸调整事件。这是一套完全不同的通信模型，而选择这种模型的原因，正好揭示了整个项目更深层的架构哲学。