wehub-resource-sync
ff9b20b0e5
9.0 KiB
Note
本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
Containerization
Containerization 软件包允许应用程序使用 Linux 容器。 Containerization 使用 Swift 编写，并在 Apple 芯片上采用 Virtualization.framework。
在寻找用于运行容器的命令行二进制文件？
它们可在专用的 apple/container 仓库中获取。
Containerization 提供以下 API：
- 管理 OCI 镜像。
- 与远程镜像仓库交互。
- 创建并填充 ext4 文件系统。
- 与 Netlink 套接字族交互。
- 创建用于快速启动的优化 Linux 内核。
- 启动轻量级虚拟机并管理运行时环境。
- 启动并与容器化进程交互。
- 在 Apple 芯片上使用 Rosetta 2 运行 linux/amd64 容器。
请查看 API 文档，了解 Containerization 提供的 Swift 软件包相关信息。
设计
Containerization 会在各自的轻量级虚拟机中运行每个 Linux 容器。客户端可为每个容器创建独立 IP 地址，从而无需单独进行端口转发。容器通过优化的 Linux 内核配置 以及带有轻量级 init 系统的最小根文件系统，实现亚秒级启动时间。
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子进程，由独立的CloudHypervisorSwift 软件包通过其 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 的实用试验场，其中包含可演练各产品部分核心功能的命令，例如：
Linux 内核
在 macOS 上启动轻量级虚拟机需要 Linux 内核。 Containerization 提供了位于 kernel 目录中的优化内核配置。
该目录包含容器化构建环境，可轻松编译供 Containerization 使用的内核。
该内核配置仅包含支持快速启动和轻量级环境所需的最小功能集。
虽然此配置适用于大多数工作负载，但我们理解部分场景需要额外功能。 为此，Containerization 提供一等 API，支持按容器使用不同的内核配置和版本。 这使容器能够在不同内核版本之间进行开发与验证。
有关如何编译优化内核的说明，请参阅 kernel 目录中的 README。
内核支持
Containerization 允许用户提供内核，但功能测试从内核版本 6.14.9 开始。
预构建内核
若希望使用预构建内核，请确保已将 VIRTIO 驱动编译进内核（而不仅仅是作为模块）。
Kata Containers 项目提供了针对容器优化的 Linux 内核，并已启用所有必需配置选项。releases 页面提供可下载制品，镜像本身（vmlinux.container）可在 /opt/kata/share/kata-containers/ 目录中找到。
准备构建软件包
安装推荐版本的 Xcode。
将活动开发者目录设置为已安装的 Xcode（将 <PATH_TO_XCODE> 替换为实际路径）：
sudo xcode-select -s <PATH_TO_XCODE>
安装 Swiftly,、Swift, 和 Static Linux SDK:
make cross-prep
若你使用自定义终端应用，可能需要将此命令从 .zprofile 移至 .zshrc（将 <USERNAME> 替换为实际值）：
# Added by swiftly
. "/Users/<USERNAME>/.swiftly/env.sh"
重启终端应用。确保以下命令返回 /Users/<USERNAME>/.swiftly/bin/swift（将 <USERNAME> 替换为实际值）：
which swift
若你此前已安装或使用过 Static Linux SDK，可能需要从系统中移除较旧的 SDK 版本（将 <SDK-ID> 替换为实际值）：
swift sdk list
swift sdk remove <SDK-ID>
构建软件包
从源码构建 Containerization：
make all
测试软件包
构建完成后，运行基础测试和集成测试：
make test integration
运行集成测试需要内核。
若本地没有内核，可使用 make fetch-default-kernel 目标获取默认内核。
获取默认内核只需在初次构建之后，或在 make clean 之后执行一次。
make fetch-default-kernel
make all test integration
Protobufs
Containerization 依赖特定版本的 grpc-swift 和 swift-protobuf。你可以安装它们，并通过以下命令重新生成 RPC 接口：
make protos
构建内核
如果你想自行构建内核，请参阅 内核目录 中的说明。
Pre-commit 钩子
运行 make pre-commit 以安装 pre-commit 钩子（pre-commit hook），确保你在运行 git commit 时，变更具有正确的格式和许可证头。
文档
使用以下命令生成本地查看用的 API 文档：
make docs
make serve-docs
在另一个终端中运行以下命令预览文档：
open http://localhost:8000/containerization/documentation/
贡献
欢迎并鼓励为 Containerization 做出贡献。更多信息请参阅 CONTRIBUTING.md。
项目状态
版本 0.1.0 是 Containerization 的首个正式发布版本。更早的版本不提供源码稳定性保证。
由于 Containerization 库仍在积极开发中，源码稳定性仅在次版本（minor version）内得到保证（例如，在 0.1.1 与 0.1.2 之间）。如果你不希望遇到可能破坏源码的包更新，可以改用 .upToNextMinorVersion(from: "0.1.0") 来指定包依赖。
未来次版本可能会根据需要对这些规则进行调整。