finch

<!-- markdownlint-disable first-line-h1 no-inline-html --> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/runfinch/finch/main/contrib/logo/Finch_Horizontal_White.svg"> <source media="(prefers-color-scheme: light)" srcset="https://yellow-cdn.veclightyear.com/87312a0a/4fe800c1-ab4c-468e-a374-faccc1983f49.svg"> <img alt="雀鸟标志" width=40% height=auto src="https://yellow-cdn.veclightyear.com/87312a0a/4fe800c1-ab4c-468e-a374-faccc1983f49.svg"> </picture> ## 你好，Finch <!-- markdownlint-restore --> [](https://pkg.go.dev/github.com/runfinch/finch) [](https://goreportcard.com/report/github.com/runfinch/finch) [](https://github.com/runfinch/finch/actions/workflows/ci.yaml) [](https://runfinch.github.io/finch/dev/bench/) [](https://github.com/runfinch/finch/releases) [](https://github.com/runfinch/finch/releases/)

Finch是一个用于容器开发的开源客户端。它的简单安装程序提供了一个轻量级的原生客户端，以及其他开源组件的精选发行版。Finch的目标不是创造更多需要考虑和选择的选项，而是通过使其他项目易于安装和使用来促进它们的发展，同时提供一个简单的原生客户端来将所有这些整合在一起。

Finch提供了一个与nerdctl集成的简单客户端。对于核心的构建/运行/推送/拉取命令，Finch依赖nerdctl来处理繁重的工作。它与containerd协作进行容器管理，与BuildKit协作处理开放容器倡议（OCI）镜像构建。这些组件都被整合在一起，并在由Lima管理的虚拟机中运行。

使用Finch，你可以利用这些现有的项目，而无需追踪所有细节。只需安装并开始运行和构建你的容器！

开始使用 Finch

该项目在不久的将来会有更完整的文档和教程。现在让我们先从这里开始。如前所述，finch 与 nerdctl 集成。虽然 Finch 并未实现 100% 的上游命令，但最常用的命令已经就位并且可以正常工作。nerdctl 命令参考可作为文档的起点。

安装 Finch

macOS

在 macOS 上开始使用 Finch，prerequisites 如下：

• macOS catalina (10.15) 或更高版本，较新版本会尽力测试
• Intel 或 Apple Silicon M1 系统（适用于 macOS）
• 建议的最低配置为 2 CPU，4 GB 内存

从项目的 GitHub 发布页面下载适合你架构的发布包，下载后双击并按照指示操作。

通过 brew 安装 Finch

brew install --cask finch

Windows

在 Windows 上开始使用 Finch，prerequisites 如下：

• Windows 10 版本 2004 及更高版本（Build 19041 及更高版本）
• 基于 AMD64 的 Windows 系统
• 已安装 WSL 2（wsl --install）

从项目的 GitHub 发布页面下载 MSI 安装程序，下载后双击并按照指示操作。

安装完成后，需要执行一次 finch vm init 来设置底层系统。这个初始设置通常需要大约一分钟。

finch vm init
INFO[0000] 正在初始化并启动 Finch 虚拟机...
..
INFO[0067] Finch 虚拟机启动成功

运行容器和构建镜像

现在你可以运行一个测试容器了。如果你熟悉容器开发，你可以按预期使用 run 命令。

finch run --rm public.ecr.aws/finch/hello-finch

如果你是容器新手，那太令人兴奋了！在安装并初始化 Finch 后，尝试运行上面的命令。run 命令会在本地镜像不存在时拉取镜像，然后为你创建并运行一个容器。注意，方便的 --rm 选项会在容器执行完毕后删除容器实例。

要构建镜像，可以尝试 finch 客户端仓库中的一个快速示例。

git clone https://github.com/runfinch/finch.git
cd finch/contrib/hello-finch
finch build . -t hello-finch
..

再次强调，如果你是容器新手，你刚刚构建了一个容器镜像。干得好！

build 命令将与构建系统（在 Finch 的情况下是 Moby 项目的 BuildKit）一起工作，从 Dockerfile 创建一个 OCI 镜像，Dockerfile 是一种用于创建镜像的特殊配方。然后可以使用这个镜像来创建容器。你可以使用 finch images 命令查看本地拉取和构建的镜像。

Finch 通过 --platform 选项使跨架构构建和运行容器变得简单。与 run 命令一起使用时，它将使用指定的架构创建容器。例如，在 Apple Silicon M1 系统上，--platform=amd64 将创建一个容器并在其中使用 x86-64 架构运行进程。

uname -ms
Darwin arm64

finch run --rm --platform=amd64 public.ecr.aws/amazonlinux/amazonlinux uname -ms
Linux x86_64

你还可以在构建时使用 --platform 选项，轻松创建多平台镜像。

使用Finch

我们计划在这里创建更多的文档和教程，面向容器新手用户，以及为高级用户提供一些技巧和窍门。目前，如果你已经准备好试用，请尽管开始！你会发现大多数命令和选项与其他工具类似，并且如你所期望的那样（或者说，正如nerdctl上游文档中所记录的那样）。我们日常使用的大多数命令都已覆盖，包括卷和网络管理以及Compose支持。如果Finch不能满足你的某些需求，请考虑提出问题或提交拉取请求。

Finch与其他工具

安装程序会在系统的特定区域安装Finch及其依赖项，它可以与其他容器开发工具和谐共存。Finch是一个新项目，并不打算成为其他工具的直接替代品。因此，我们不建议将其他命令名称别名或链接到finch。

配置

Finch具有简单且可扩展的配置。

macOS

首次运行时会在${HOME}/.finch/finch.yaml生成一个配置文件。目前，这个配置文件包含了底层虚拟机的系统资源限制选项。这些默认限制是根据主机系统可用资源动态生成的，但可以通过手动编辑配置文件进行更改。

完整的配置选项列表，请查看这里的结构体。

一个finch.yaml示例如下：

# cpus: 分配给虚拟机的vCPU数量。（必填）
cpus: 4
# memory: 分配给虚拟机的内存大小。（必填）
memory: 4GiB
# snapshotters: 用户想要使用的快照工具（第一个快照工具将被设置为默认快照工具）
# 支持的快照工具列表：
# - soci https://github.com/awslabs/soci-snapshotter/tree/main
# 一旦设置了此选项，快照工具将在finch vm init或finch vm start时安装。
# 快照工具的二进制文件将下载到虚拟机上，并进行配置以备使用。
# 要将默认快照工具改回overlayfs，只需从finch.yaml中删除snapshotters值或将snapshotters设置为`overlayfs`
# 要完全移除快照工具的二进制文件，请进入虚拟机并删除/usr/local/bin/{snapshotter binary}
# 并删除位于/etc/containerd/config.toml的containerd配置文件中的快照工具配置
snapshotters:
- soci
# creds_helpers: 将自动安装和配置的凭证助手列表。
# 支持的凭证助手列表：
# - ecr-login https://github.com/awslabs/amazon-ecr-credential-helper
# 一旦设置了此选项，凭证助手将在finch vm init或finch vm start时安装。
# 二进制文件将下载到主机上，如果~/.finch/文件夹中不存在config.json，则会创建并填充该文件。
# 如果已存在，credsStore的值将被覆盖。
# 要退出使用凭证助手，请从config.json的credsStore参数中删除该值，
# 并从finch.yaml中删除creds_helper值。
# 要完全移除凭证助手，可以从~/.finch/creds-helpers中删除二进制文件，或完全删除creds-helpers
# 文件夹。（可选）
creds_helpers:
- ecr-login
# additional_directories: 默认不支持的工作目录。在macOS中，默认只支持home目录。
# 例如，如果你想将一个不在home目录下的目录挂载到容器中，
# 那么你需要指定这个字段，将该目录或其任何祖先目录添加为工作目录。（可选）
additional_directories:
# 每个额外目录的路径。
- path: /Volumes
# vmType: 设置用于启动VM的虚拟化技术。（可选）
# 仅在启动新VM时生效（仅在vm init时）。
# 可选值："qemu"或"vz"。
#   - "qemu"：使用QEMU作为虚拟化技术。
#   - "vz"（默认）：使用Virtualization.framework作为虚拟化技术。
#
# 注意：在1.2.0版本之前，"qemu"是默认选项，对于不支持Virtualization.framework的
# macOS版本（13.0.0之前），它仍然是默认选项。
vmType: "vz"
# rosetta: 设置是否启用Rosetta作为VM内x86_64二进制文件的binfmt_misc处理程序，
# 作为qemu用户模式仿真的替代方案。（可选）
# 仅在启动新VM时生效（仅在vm init时）。
# 仅在使用vmType "vz"的Apple Silicon上运行macOS 13+时可用。
# 如果设为true，也会将vmType设置为"vz"。
#
# 注意：尽管Rosetta通常比qemu用户模式仿真更快，但它会导致一些性能回退，
# 如这个问题所述：
# https://github.com/lima-vm/lima/issues/1269
rosetta: false

Windows

首次运行时会在$env:LOCALAPPDATA\.finch\finch.yaml生成一个配置文件。目前，由于WSL的限制，此配置文件不包含系统资源限制选项。

完整的配置选项列表，请查看这里的结构体。

一个finch.yaml示例如下：

# snapshotters: 用户想要使用的快照工具（第一个快照工具将被设置为默认快照工具）
# 支持的快照工具列表：
# - soci https://github.com/awslabs/soci-snapshotter/tree/main
# 一旦设置了此选项，快照工具将在finch vm init或finch vm start时安装。
# 快照工具的二进制文件将下载到虚拟机上，并进行配置以备使用。
# 要将默认快照工具改回overlayfs，只需从finch.yaml中删除snapshotters值或将snapshotters设置为`overlayfs`
# 要完全移除快照工具的二进制文件，请进入虚拟机并删除/usr/local/bin/{snapshotter binary}
# 并删除位于/etc/containerd/config.toml的containerd配置文件中的快照工具配置
snapshotters:
- soci
# creds_helpers: 将自动安装和配置的凭证助手列表。
# 支持的凭证助手列表：
# - ecr-login https://github.com/awslabs/amazon-ecr-credential-helper
# 一旦设置了此选项，凭证助手将在finch vm init或finch vm start时安装。
# 二进制文件将下载到主机上，如果~/.finch/文件夹中不存在config.json，则会创建并填充该文件。
# 如果已存在，credsStore的值将被覆盖。
# 要退出使用凭证助手，请从config.json的credsStore参数中删除该值，
# 并从finch.yaml中删除creds_helper值。
# 要完全移除凭证助手，可以从$env:LOCALAPPDATA\.finch\creds-helpers中删除二进制文件，或完全删除creds-helpers
# 文件夹。（可选）
creds_helpers:
- ecr-login

# 设置用于启动VM的wsl2虚拟化技术。（可选）
vmType: "wsl2"

常见问题

本节包含关于使用Finch的常见问题。

如何进入VM的shell？

macOS

LIMA_HOME=/Applications/Finch/lima/data /Applications/Finch/lima/bin/limactl shell finch

Windows

wsl -d lima-finch

下一步是什么？

我们很高兴能够公开启动这个项目，也很想听听你的意见。如果你有想法或发现了bug，请开一个issue。如果你有想提议或头脑风暴的内容，欢迎开始讨论。我们也欢迎提交pull request！关于如何贡献以及成为审核员和维护者的路径，请查看CONTRIBUTING文档了解更多信息。

随着项目获得一些动力，维护者们将开始创建里程碑，并寻求建立定期发布的节奏。随着时间推移，我们还将从社区的想法和提出的问题中整理出一个公开的路线图。我们已经有一些想法，包括：

• 更小的客户操作系统占用空间
• Linux客户端支持
• 正式的可扩展性
• 持续的性能改进
• 持续的稳定性和可用性改进

如果你想与我们交谈，请在CNCF slack上的#finch频道找到我们。