From ff9b20b0e5508989e0d7f2554d76c690f4aa7efb Mon Sep 17 00:00:00 2001 From: wehub-resource-sync Date: Mon, 13 Jul 2026 10:15:22 +0000 Subject: [PATCH] docs: make Chinese README the default --- README.md | 172 ++++++++++++++++++++++++++++-------------------------- 1 file changed, 88 insertions(+), 84 deletions(-) diff --git a/README.md b/README.md index 3bf6398..bf25564 100644 --- a/README.md +++ b/README.md @@ -1,151 +1,155 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/apple/containerization) · [上游 README](https://github.com/apple/containerization/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 +

Containerization logo  Containerization

-The Containerization package allows applications to use Linux containers. -Containerization is written in [Swift](https://www.swift.org) and uses [Virtualization.framework](https://developer.apple.com/documentation/virtualization) on Apple silicon. +Containerization 软件包允许应用程序使用 Linux 容器。 +Containerization 使用 [Swift](https://www.swift.org) 编写，并在 Apple 芯片上采用 [Virtualization.framework](https://developer.apple.com/documentation/virtualization)。 -> **Looking for command line binaries for running containers?**\ -> They are available in the dedicated [apple/container](https://github.com/apple/container) repository. +> **在寻找用于运行容器的命令行二进制文件？**\ +> 它们可在专用的 [apple/container](https://github.com/apple/container) 仓库中获取。 -Containerization provides APIs to: +Containerization 提供以下 API： -- [Manage OCI images](./Sources/ContainerizationOCI/). -- [Interact with remote registries](./Sources/ContainerizationOCI/Client/). -- [Create and populate ext4 file systems](./Sources/ContainerizationEXT4/). -- [Interact with the Netlink socket family](./Sources/ContainerizationNetlink/). -- [Create an optimized Linux kernel for fast boot times](./kernel/). -- [Spawn lightweight virtual machines and manage the runtime environment](./Sources/Containerization/LinuxContainer.swift). -- [Spawn and interact with containerized processes](./Sources/Containerization/LinuxProcess.swift). -- Use Rosetta 2 for running linux/amd64 containers on Apple silicon. +- [管理 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 容器。 -Please view the [API documentation](https://apple.github.io/containerization/documentation/) for information on the Swift packages that Containerization provides. +请查看 [API 文档](https://apple.github.io/containerization/documentation/)，了解 Containerization 提供的 Swift 软件包相关信息。 -## Design +## 设计 -Containerization executes each Linux container inside of its own lightweight virtual machine. Clients can create dedicated IP addresses for every container to remove the need for individual port forwarding. Containers achieve sub-second start times using an optimized [Linux kernel configuration](/kernel) and a minimal root filesystem with a lightweight init system. +Containerization 会在各自的轻量级虚拟机中运行每个 Linux 容器。客户端可为每个容器创建独立 IP 地址，从而无需单独进行端口转发。容器通过优化的 [Linux 内核配置](/kernel) 以及带有轻量级 init 系统的最小根文件系统，实现亚秒级启动时间。 -[vminitd](/vminitd) is a small init system, which is a subproject within Containerization. -`vminitd` is spawned as the initial process inside of the virtual machine and provides a GRPC API over vsock. -The API allows the runtime environment to be configured and containerized processes to be launched. -`vminitd` provides I/O, signals, and events to the calling process when a process is run. +[vminitd](/vminitd) 是一个小型 init 系统，属于 Containerization 的子项目。 +`vminitd` 作为虚拟机内的初始进程启动，并通过 vsock 提供 GRPC API。 +该 API 允许配置运行时环境并启动容器化进程。 +`vminitd` 在进程运行时向调用进程提供 I/O、信号和事件。 -## Backends +## 后端 -Containerization abstracts the VMM behind the `VirtualMachineManager` / -`VirtualMachineInstance` protocols and ships two implementations: +Containerization 在 `VirtualMachineManager` / +`VirtualMachineInstance` 协议背后抽象了 VMM，并提供两种实现： -- **macOS — Virtualization.framework** (`VZVirtualMachineManager`). The shipping path on Apple silicon. Uses Apple's `Virtualization` framework directly; no extra binaries required. -- **Linux — cloud-hypervisor + KVM** (`CHVirtualMachineManager`). One `cloud-hypervisor` subprocess per VM, controlled over its REST-on-UDS API by the standalone [`CloudHypervisor`](./Sources/CloudHypervisor) Swift package. Block storage uses virtio-blk, shared directories use virtio-fs (one `virtiofsd` per share), networking uses TAP, and the guest agent is reached over cloud-hypervisor's hybrid vsock — same `vminitd` contract as the macOS path, so guest-side semantics are unchanged. +- **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` 契约，因此客户机侧语义保持不变。 -The Linux backend requires: +Linux 后端需要： -- `cloud-hypervisor` and `virtiofsd` on the host. Both are looked up on `PATH` by default; `CHVirtualMachineManager.init` accepts explicit URLs to override. `virtiofsd` is resolved lazily — a VM that uses only block-device mounts can run without it installed at all. Recent stable releases of each are recommended (smoke testing pins specific versions). -- KVM access (`/dev/kvm` readable + writable by the calling user). -- Pre-staged TAP / bridge / NAT plumbing if the container needs networking. `TAPInterface` consumes an existing TAP device by name; bringing it up, attaching it to a bridge, and configuring NAT or routing is the caller's responsibility. +- 主机上安装 `cloud-hypervisor` 和 `virtiofsd`。默认情况下两者均在 `PATH` 上查找；`CHVirtualMachineManager.init` 可接受显式 URL 进行覆盖。`virtiofsd` 采用惰性解析——仅使用块设备挂载的 VM 即使未安装它也可运行。建议使用各组件的近期稳定版本（冒烟测试会固定特定版本）。 +- KVM 访问权限（`/dev/kvm` 对调用用户可读且可写）。 +- 若容器需要联网，需预先配置 TAP / 网桥 / NAT 网络设施。`TAPInterface` 按名称使用现有 TAP 设备；将其启用、接入网桥以及配置 NAT 或路由由调用方负责。 -The integration test suite (`make linux-integration`) runs inside an apple/container Linux VM with nested virt enabled (`container run --virtualization`). The kata kernel fetched by `make fetch-default-kernel` does not enable KVM, so the integration suite uses the in-repo kernel at `kernel/vmlinux-arm64` (or `kernel/vmlinuz-x86_64` on x86_64 hosts) instead — build it with `make -C kernel` before invoking `make linux-integration`. On Linux the suite runs only the cross-platform scenarios that don't depend on macOS-only types; the full suite remains macOS-only for now. +集成测试套件（`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。 -## Requirements +## 要求 -To build the Containerization package, you need: +要构建 Containerization 软件包，你需要： -- Mac with Apple silicon +- 配备 Apple 芯片的 Mac - macOS 26 - Xcode 26 -Older versions of macOS are not supported. +不支持更早版本的 macOS。 -## Example Usage +## 使用示例 -For examples of how to use the libraries' API surface, the cctl executable is a good start. This app is a useful playground for exploring the API. It contains commands that exercise some of the core functionality of the various products, such as: +若要了解如何使用这些库的 API 接口，cctl 可执行文件是一个不错的起点。该应用是探索 API 的实用试验场，其中包含可演练各产品部分核心功能的命令，例如： -1. [Manipulating OCI images](./Sources/cctl/ImageCommand.swift) -2. [Logging in to container registries](./Sources/cctl/LoginCommand.swift) -3. [Creating root filesystem blocks](./Sources/cctl/RootfsCommand.swift) -4. [Running simple Linux containers](./Sources/cctl/RunCommand.swift) +1. [操作 OCI 镜像](./Sources/cctl/ImageCommand.swift) +2. [登录容器镜像仓库](./Sources/cctl/LoginCommand.swift) +3. [创建根文件系统块](./Sources/cctl/RootfsCommand.swift) +4. [运行简单的 Linux 容器](./Sources/cctl/RunCommand.swift) -## Linux kernel +## Linux 内核 -A Linux kernel is required for spawning lightweight virtual machines on macOS. -Containerization provides an optimized kernel configuration located in the [kernel](./kernel) directory. +在 macOS 上启动轻量级虚拟机需要 Linux 内核。 +Containerization 提供了位于 [kernel](./kernel) 目录中的优化内核配置。 -This directory includes a containerized build environment to easily compile a kernel for use with Containerization. +该目录包含容器化构建环境，可轻松编译供 Containerization 使用的内核。 -The kernel configuration is a minimal set of features to support fast start times and a lightweight environment. +该内核配置仅包含支持快速启动和轻量级环境所需的最小功能集。 -While this configuration will work for the majority of workloads we understand that some will need extra features. -To solve this Containerization provides first class APIs to use different kernel configurations and versions on a per container basis. -This enables containers to be developed and validated across different kernel versions. +虽然此配置适用于大多数工作负载，但我们理解部分场景需要额外功能。 +为此，Containerization 提供一等 API，支持按容器使用不同的内核配置和版本。 +这使容器能够在不同内核版本之间进行开发与验证。 -See the [README](/kernel/README.md) in the kernel directory for instructions on how to compile the optimized kernel. +有关如何编译优化内核的说明，请参阅 kernel 目录中的 [README](/kernel/README.md)。 -### Kernel Support +### 内核支持 -Containerization allows user provided kernels but tests functionality starting with kernel version `6.14.9`. +Containerization 允许用户提供内核，但功能测试从内核版本 `6.14.9` 开始。 -### Pre-built Kernel +### 预构建内核 -If you wish to consume a pre-built kernel, make sure it has `VIRTIO` drivers compiled into the kernel (not merely as modules). +若希望使用预构建内核，请确保已将 `VIRTIO` 驱动编译进内核（而不仅仅是作为模块）。 -The [Kata Containers](https://github.com/kata-containers/kata-containers) project provides a Linux kernel that is optimized for containers, with all required configuration options enabled. The [releases](https://github.com/kata-containers/kata-containers/releases/) page contains downloadable artifacts, and the image itself (`vmlinux.container`) can be found in the `/opt/kata/share/kata-containers/` directory. +[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/` 目录中找到。 -## Prepare to build package +## 准备构建软件包 -Install the recommended version of Xcode. +安装推荐版本的 Xcode。 -Set the active developer directory to the installed Xcode (replace ``): +将活动开发者目录设置为已安装的 Xcode（将 `` 替换为实际路径）： ```bash sudo xcode-select -s ``` -Install [Swiftly](https://github.com/swiftlang/swiftly), [Swift](https://www.swift.org), and [Static Linux SDK](https://www.swift.org/documentation/articles/static-linux-getting-started.html): +安装 [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 ``` -If you use a custom terminal application, you may need to move this command from `.zprofile` to `.zshrc` (replace ``): +若你使用自定义终端应用，可能需要将此命令从 `.zprofile` 移至 `.zshrc`（将 `` 替换为实际值）： ```bash # Added by swiftly . "/Users//.swiftly/env.sh" ``` -Restart the terminal application. Ensure this command returns `/Users//.swiftly/bin/swift` (replace ``): - +重启终端应用。确保以下命令返回 `/Users//.swiftly/bin/swift`（将 `` 替换为实际值）： ```bash which swift ``` -If you've installed or used a Static Linux SDK previously, you may need to remove older SDK versions from the system (replace ``): - +若你此前已安装或使用过 Static Linux SDK，可能需要从系统中移除较旧的 SDK 版本（将 `` 替换为实际值）： ```bash swift sdk list swift sdk remove ``` -## Build the package +## 构建软件包 -Build Containerization from sources: +从源码构建 Containerization： ```bash make all ``` -## Test the package +## 测试软件包 -After building, run basic and integration tests: +构建完成后，运行基础测试和集成测试： ```bash make test integration ``` -A kernel is required to run integration tests. -If you do not have a kernel locally, a default kernel can be fetched using the `make fetch-default-kernel` target. +运行集成测试需要内核。 +若本地没有内核，可使用 `make fetch-default-kernel` 目标获取默认内核。 -Fetching the default kernel only needs to happen after an initial build or after a `make clean`. +获取默认内核只需在初次构建之后，或在 `make clean` 之后执行一次。 ```bash make fetch-default-kernel @@ -154,43 +158,43 @@ make all test integration ## Protobufs -Containerization depends on specific versions of `grpc-swift` and `swift-protobuf`. You can install them and re-generate RPC interfaces with: +Containerization 依赖特定版本的 `grpc-swift` 和 `swift-protobuf`。你可以安装它们，并通过以下命令重新生成 RPC 接口： ```bash make protos ``` -## Building a kernel +## 构建内核 -If you'd like to build your own kernel please see the instructions in the [kernel directory](./kernel/README.md). +如果你想自行构建内核，请参阅 [内核目录](./kernel/README.md) 中的说明。 -## Pre-commit hook +## Pre-commit 钩子 -Run `make pre-commit` to install a pre-commit hook that ensures that your changes have correct formatting and license headers when you run `git commit`. +运行 `make pre-commit` 以安装 pre-commit 钩子（pre-commit hook），确保你在运行 `git commit` 时，变更具有正确的格式和许可证头。 -## Documentation +## 文档 -Generate the API documentation for local viewing with: +使用以下命令生成本地查看用的 API 文档： ```bash make docs make serve-docs ``` -Preview the documentation by running in another terminal: +在另一个终端中运行以下命令预览文档： ```bash open http://localhost:8000/containerization/documentation/ ``` -## Contributing +## 贡献 -Contributions to Containerization are welcomed and encouraged. Please see [CONTRIBUTING.md](/CONTRIBUTING.md) for more information. +欢迎并鼓励为 Containerization 做出贡献。更多信息请参阅 [CONTRIBUTING.md](/CONTRIBUTING.md)。 -## Project Status +## 项目状态 -Version 0.1.0 is the first official release of Containerization. Earlier versions have no source stability guarantees. +版本 0.1.0 是 Containerization 的首个正式发布版本。更早的版本不提供源码稳定性保证。 -Because the Containerization library is under active development, source stability is only guaranteed within minor versions (for example, between 0.1.1 and 0.1.2). If you don't want potentially source-breaking package updates, you can specify your package dependency using .upToNextMinorVersion(from: "0.1.0") instead. +由于 Containerization 库仍在积极开发中，源码稳定性仅在次版本（minor version）内得到保证（例如，在 0.1.1 与 0.1.2 之间）。如果你不希望遇到可能破坏源码的包更新，可以改用 .upToNextMinorVersion(from: "0.1.0") 来指定包依赖。 -Future minor versions of the package may introduce changes to these rules as needed. +未来次版本可能会根据需要对这些规则进行调整。