> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/apple/containerization) · [上游 README](https://github.com/apple/containerization/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
Containerization
Containerization 软件包允许应用程序使用 Linux 容器。
Containerization 使用 [Swift](https://www.swift.org) 编写，并在 Apple 芯片上采用 [Virtualization.framework](https://developer.apple.com/documentation/virtualization)。
> **在寻找用于运行容器的命令行二进制文件？**\
> 它们可在专用的 [apple/container](https://github.com/apple/container) 仓库中获取。
Containerization 提供以下 API：
- [管理 OCI 镜像](./Sources/ContainerizationOCI/)。
- [与远程镜像仓库交互](./Sources/ContainerizationOCI/Client/)。
- [创建并填充 ext4 文件系统](./Sources/ContainerizationEXT4/)。
- [与 Netlink 套接字族交互](./Sources/ContainerizationNetlink/)。
- [创建用于快速启动的优化 Linux 内核](./kernel/)。
- [启动轻量级虚拟机并管理运行时环境](./Sources/Containerization/LinuxContainer.swift)。
- [启动并与容器化进程交互](./Sources/Containerization/LinuxProcess.swift)。
- 在 Apple 芯片上使用 Rosetta 2 运行 linux/amd64 容器。
请查看 [API 文档](https://apple.github.io/containerization/documentation/)，了解 Containerization 提供的 Swift 软件包相关信息。
## 设计
Containerization 会在各自的轻量级虚拟机中运行每个 Linux 容器。客户端可为每个容器创建独立 IP 地址，从而无需单独进行端口转发。容器通过优化的 [Linux 内核配置](/kernel) 以及带有轻量级 init 系统的最小根文件系统，实现亚秒级启动时间。
[vminitd](/vminitd) 是一个小型 init 系统，属于 Containerization 的子项目。
`vminitd` 作为虚拟机内的初始进程启动，并通过 vsock 提供 GRPC API。
该 API 允许配置运行时环境并启动容器化进程。
`vminitd` 在进程运行时向调用进程提供 I/O、信号和事件。
## 后端
Containerization 在 `VirtualMachineManager` /
`VirtualMachineInstance` 协议背后抽象了 VMM，并提供两种实现：
- **macOS — Virtualization.framework**（`VZVirtualMachineManager`）。Apple 芯片上的正式交付路径。直接使用 Apple 的 `Virtualization` 框架；无需额外二进制文件。
- **Linux — cloud-hypervisor + KVM**（`CHVirtualMachineManager`）。每个 VM 对应一个 `cloud-hypervisor` 子进程，由独立的 [`CloudHypervisor`](./Sources/CloudHypervisor) Swift 软件包通过其 REST-on-UDS API 进行控制。块存储使用 virtio-blk，共享目录使用 virtio-fs（每个共享对应一个 `virtiofsd`），网络使用 TAP，并通过 cloud-hypervisor 的混合 vsock 访问客户机代理——与 macOS 路径采用相同的 `vminitd` 契约，因此客户机侧语义保持不变。
Linux 后端需要：
- 主机上安装 `cloud-hypervisor` 和 `virtiofsd`。默认情况下两者均在 `PATH` 上查找；`CHVirtualMachineManager.init` 可接受显式 URL 进行覆盖。`virtiofsd` 采用惰性解析——仅使用块设备挂载的 VM 即使未安装它也可运行。建议使用各组件的近期稳定版本（冒烟测试会固定特定版本）。
- KVM 访问权限（`/dev/kvm` 对调用用户可读且可写）。
- 若容器需要联网，需预先配置 TAP / 网桥 / NAT 网络设施。`TAPInterface` 按名称使用现有 TAP 设备；将其启用、接入网桥以及配置 NAT 或路由由调用方负责。
集成测试套件（`make linux-integration`）在启用嵌套虚拟化（`container run --virtualization`）的 apple/container Linux VM 内运行。由 `make fetch-default-kernel` 获取的 kata 内核未启用 KVM，因此集成套件改用仓库内的内核 `kernel/vmlinux-arm64`（在 x86_64 主机上则为 `kernel/vmlinuz-x86_64`）——在调用 `make linux-integration` 之前，请先用 `make -C kernel` 进行构建。在 Linux 上，该套件仅运行不依赖 macOS 专有类型的跨平台场景；完整套件目前仍仅限 macOS。
## 要求
要构建 Containerization 软件包，你需要：
- 配备 Apple 芯片的 Mac
- macOS 26
- Xcode 26
不支持更早版本的 macOS。
## 使用示例
若要了解如何使用这些库的 API 接口，cctl 可执行文件是一个不错的起点。该应用是探索 API 的实用试验场，其中包含可演练各产品部分核心功能的命令，例如：
1. [操作 OCI 镜像](./Sources/cctl/ImageCommand.swift)
2. [登录容器镜像仓库](./Sources/cctl/LoginCommand.swift)
3. [创建根文件系统块](./Sources/cctl/RootfsCommand.swift)
4. [运行简单的 Linux 容器](./Sources/cctl/RunCommand.swift)
## Linux 内核
在 macOS 上启动轻量级虚拟机需要 Linux 内核。
Containerization 提供了位于 [kernel](./kernel) 目录中的优化内核配置。
该目录包含容器化构建环境，可轻松编译供 Containerization 使用的内核。
该内核配置仅包含支持快速启动和轻量级环境所需的最小功能集。
虽然此配置适用于大多数工作负载，但我们理解部分场景需要额外功能。
为此，Containerization 提供一等 API，支持按容器使用不同的内核配置和版本。
这使容器能够在不同内核版本之间进行开发与验证。
有关如何编译优化内核的说明，请参阅 kernel 目录中的 [README](/kernel/README.md)。
### 内核支持
Containerization 允许用户提供内核，但功能测试从内核版本 `6.14.9` 开始。
### 预构建内核
若希望使用预构建内核，请确保已将 `VIRTIO` 驱动编译进内核（而不仅仅是作为模块）。
[Kata Containers](https://github.com/kata-containers/kata-containers) 项目提供了针对容器优化的 Linux 内核，并已启用所有必需配置选项。[releases](https://github.com/kata-containers/kata-containers/releases/) 页面提供可下载制品，镜像本身（`vmlinux.container`）可在 `/opt/kata/share/kata-containers/` 目录中找到。
## 准备构建软件包
安装推荐版本的 Xcode。
将活动开发者目录设置为已安装的 Xcode（将 `` 替换为实际路径）：
```bash
sudo xcode-select -s
```
安装 [Swiftly](https://github.com/swiftlang/swiftly),、[Swift](https://www.swift.org), 和 [Static Linux SDK](https://www.swift.org/documentation/articles/static-linux-getting-started.html):
```bash
make cross-prep
```
若你使用自定义终端应用，可能需要将此命令从 `.zprofile` 移至 `.zshrc`（将 `` 替换为实际值）：
```bash
# Added by swiftly
. "/Users//.swiftly/env.sh"
```
重启终端应用。确保以下命令返回 `/Users//.swiftly/bin/swift`（将 `` 替换为实际值）：
```bash
which swift
```
若你此前已安装或使用过 Static Linux SDK，可能需要从系统中移除较旧的 SDK 版本（将 `` 替换为实际值）：
```bash
swift sdk list
swift sdk remove
```
## 构建软件包
从源码构建 Containerization：
```bash
make all
```
## 测试软件包
构建完成后，运行基础测试和集成测试：
```bash
make test integration
```
运行集成测试需要内核。
若本地没有内核，可使用 `make fetch-default-kernel` 目标获取默认内核。
获取默认内核只需在初次构建之后，或在 `make clean` 之后执行一次。
```bash
make fetch-default-kernel
make all test integration
```
## Protobufs
Containerization 依赖特定版本的 `grpc-swift` 和 `swift-protobuf`。你可以安装它们，并通过以下命令重新生成 RPC 接口：
```bash
make protos
```
## 构建内核
如果你想自行构建内核，请参阅 [内核目录](./kernel/README.md) 中的说明。
## Pre-commit 钩子
运行 `make pre-commit` 以安装 pre-commit 钩子（pre-commit hook），确保你在运行 `git commit` 时，变更具有正确的格式和许可证头。
## 文档
使用以下命令生成本地查看用的 API 文档：
```bash
make docs
make serve-docs
```
在另一个终端中运行以下命令预览文档：
```bash
open http://localhost:8000/containerization/documentation/
```
## 贡献
欢迎并鼓励为 Containerization 做出贡献。更多信息请参阅 [CONTRIBUTING.md](/CONTRIBUTING.md)。
## 项目状态
版本 0.1.0 是 Containerization 的首个正式发布版本。更早的版本不提供源码稳定性保证。
由于 Containerization 库仍在积极开发中，源码稳定性仅在次版本（minor version）内得到保证（例如，在 0.1.1 与 0.1.2 之间）。如果你不希望遇到可能破坏源码的包更新，可以改用 .upToNextMinorVersion(from: "0.1.0") 来指定包依赖。
未来次版本可能会根据需要对这些规则进行调整。