Lima：面向容器工作负载的 Linux 虚拟机管理器（Linux Machines）实战指南

Lima 是一个专注于运行容器的 Linux 虚拟机管理工具，它通过自动文件共享与端口转发提供类似 WSL2 的体验，让 macOS、Linux、NetBSD 等主机上的开发者可以一键启动 Linux 虚拟机。本文以本仓库 README 为核心脉络，结合 limactl 命令行实现、内置模板与配置源码，系统讲解从安装启动、容器编排（containerd/nerdctl、Docker、Kubernetes）到配置文件深度定制（模板、参数、provision、probes、端口转发）的完整使用链路。

一、项目定位：让 Linux 虚拟机像 WSL2 一样易用

Lima 的初始目标是向 Mac 用户推广 containerd 及其配套 CLI nerdctl，但它的能力边界远不止于此：非容器应用同样可以跑在 Lima 虚拟机里，同时 Lima 还支持 Docker、Podman、Kubernetes 等其他容器引擎，也支持 macOS 之外的主机（如 Linux、NetBSD 等）。

其核心价值在于两点自动化能力（见 README.md）：

• 自动文件共享：宿主机目录自动暴露给客户机；
• 自动端口转发：客户机端口自动映射到宿主机，与 WSL2 的用户体验对齐。

从源码结构看，这两个能力分别由 hostagent 的挂载与端口转发逻辑承担：pkg/hostagent/mount.go 处理挂载，pkg/hostagent/port.go 负责端口转发，而 pkg/guestagent/guestagent_linux.go 是运行在客户机内的代理，负责响应宿主机的指令。整个项目的 CLI 入口是 cmd/limactl，它提供 create、start、shell、list、delete、edit 等一系列子命令。

二、快速上手：安装、启动与第一条命令

2.1 安装（Homebrew）

在 macOS 上通过 Homebrew 安装：

brew install lima
limactl start

limactl start 首次执行时会经历一个交互流程：从模板创建并启动一个名为 default 的实例。结合 cmd/limactl/start.go 的示例可知：

• limactl start 等价于"先用默认 Ubuntu 模板创建 default 实例（若尚未创建），再启动它"；
• limactl start --name=default template:docker 则是基于 docker 模板创建并启动。

2.2 运行 Linux 命令

lima uname -a

这里的 lima 是一个薄包装脚本（见 cmd/lima），它本质上是 limactl shell $LIMA_INSTANCE 的别名。脚本支持以下环境变量：

环境变量	作用	默认值
LIMA_INSTANCE	指定使用的实例名	default
LIMA_SHELL	指定实例内的 shell 解释器	实例内配置的用户 shell
LIMA_WORKDIR	指定实例内的初始工作目录	宿主机的当前目录
LIMACTL	指定 limactl 二进制路径	$PATH 中的 limactl

因此 lima uname -a 实际上执行的是 limactl shell default uname -a，即通过 SSH 在客户机内执行命令。仓库还提供了类似的容器 CLI 包装脚本：lima nerdctl ...（cmd/nerdctl.lima）、lima docker ...（cmd/docker.lima）、lima kubectl ...（cmd/kubectl.lima）。

2.3 用 containerd 运行容器

lima nerdctl run --rm hello-world

lima nerdctl 脚本内部执行 limactl shell --preserve-env "$LIMA_INSTANCE" nerdctl "$@"，即把宿主机环境变量透传进客户机，再调用 nerdctl。默认模板（templates/default.yaml）会启用用户级（rootless）containerd 及其依赖（BuildKit、Stargz Snapshotter），这是 nerdctl.lima 只在 rootless 模式下工作的原因；如需 rootful 模式，需设置 containerd.system: true 并改用 lima sudo nerdctl ...。

2.4 用 Docker 运行容器

limactl start template:docker
export DOCKER_HOST=$(limactl list docker --format 'unix://{{.Dir}}/sock/docker.sock')
docker run --rm hello-world

这条命令链展示了 Lima 的模板机制与 list 命令的结合：

1. template:docker 从内置 docker 模板创建并启动名为 docker 的实例；
2. limactl list docker --format '...' 以 Go 模板输出实例目录下的 Docker socket 路径（cmd/limactl/list.go 定义了 --format 支持 json/yaml/table/go-template，也支持 --filter 用 yq 表达式过滤实例）；
3. 宿主机 docker CLI 通过 DOCKER_HOST 直连客户机内的 Docker daemon。

2.5 用 Kubernetes 部署工作负载

limactl start template:k8s
export KUBECONFIG=$(limactl list k8s --format 'unix://{{.Dir}}/copied-from-guest/kubeconfig.yaml')
kubectl apply -f ...

template:k8s 会在客户机内通过 kubeadm 部署单节点控制面集群（详见下文"内置模板实战"），并把客户机内的 kubeconfig 通过 copyToHost 机制拷贝到宿主机 {{.Dir}}/copied-from-guest/ 下。

三、模板机制：从"零配置"到"参数化"

3.1 模板的三种来源

limactl create / limactl start 接受以下参数形式（cmd/limactl/start.go）：

参数形式	含义	示例
（无参数）	使用默认模板创建 default 实例	limactl create
template:名称	使用内置命名模板	limactl create template:docker
本地文件路径	使用自定义 YAML	limactl create ./my-vm.yaml
URL	从远程拉取模板（需可信来源）	limactl create https://.../alpine.yaml
-	从 stdin 读取模板（必须配 --name）	cat t.yaml | limactl create --name=local -

内置模板存放在 templates 目录，涵盖 Ubuntu、Debian、Fedora、Alpine、Arch Linux、Rocky、openSUSE、FreeBSD、macOS、Windows 等系统，以及 docker、podman、k8s、k0s、k3s、buildkit、apptainer、homebrew 等应用场景；实验性模板位于 templates/experimental（如 hcs、wsl2、vnc、alsa 等）。内部基础模板（_images/* 与 _default/*）不会在模板选择列表中出现（filterHiddenTemplates 会过滤以 _ 开头的模板）。

3.2 创建/启动时的常用参数

limactl start 继承了 limactl create 的全部参数（cmd/limactl/start.go 中这些 flag 会标注为 [limactl create]）：

# 指定实例名与资源大小
limactl create --name=default --cpus=2 --memory=2

# 用 yq 表达式修改配置
limactl create --set='.cpus = 2 | .memory = "2GiB"'

# 覆盖模板参数（param 键）
limactl create --name=default --param containerdSnapshotter=false template:docker

# 列出模板与驱动
limactl create --list-templates
limactl create --list-drivers

# 查看当前实例并启动（仅 start 有）
limactl start --foreground
limactl start --timeout=300s
limactl start --progress   # 通过 tail cloud-init 日志展示 provision 进度

此外 --arch、--vm-type、--mount-type、--image-variant、--arch-variant 等参数允许在创建时直接覆盖架构、虚拟化驱动与挂载方式。需要注意：vmType 只能在创建实例时指定，已创建实例的 vmType 无法变更。

3.3 base 模板继承与 param 参数

每个模板可以通过 base 字段继承其他模板，合并结果在实例创建时固化进实例目录（templates/default.yaml）：

minimumLimaVersion: 2.0.0
base:
- template:_images/ubuntu-lts
- template:_default/mounts

• _images/ubuntu-lts 提供镜像定义（location/arch/digest 等）；
• _default/mounts（templates/_default/mounts.yaml）默认把宿主机家目录只读挂载进客户机（自 Lima v2.0 起 /tmp/lima 不再默认挂载）。

param 定义模板参数，在 YAML 中通过 {{.Param.Key}} 引用，在 provision 脚本与 probes 中通过环境变量 $PARAM_Key 引用（templates/default.yaml）。例如 docker 模板的 param.containerdSnapshotter 默认值为 true，通过 --param 即可在创建时覆盖。

四、核心配置文件详解

每个实例的核心配置是 lima.yaml（位于实例目录下）。完整的字段说明可以参考模板文件 templates/default.yaml（与嵌入二进制的 pkg/limayaml/default.yaml 内容一致）。以下按用途归纳核心配置。

4.1 基础资源与系统

配置项	内置默认值	说明
vmType	"vz"（macOS 13.5+），否则 "qemu"	虚拟化驱动，可选 qemu/vz/default，仅创建时可指定
arch	"default"（跟随宿主机架构）	可选 x86_64、aarch64
cpus	min(4, 宿主机 CPU 核数)	CPU 核数
memory	min("4GiB", 宿主机内存一半)	内存大小
disk	"100GiB"	磁盘大小
os	"Linux"	客户机操作系统
images	无（必须指定）	OpenStack 兼容磁盘镜像，支持 kernel/initrd 自定义内核引导
user	与宿主用户同名（非法则 lima）	客户机用户：name、uid、home、shell、passwordlessSudo 等
timezone	继承宿主机时区	可设为空字符串以不设置

从 pkg/limayaml/defaults.go 可以看到这些内置默认值在 Go 代码中落地（如 cpus、memory 的动态计算，以及 9p 的 Default9pSecurityModel = "none"、Default9pProtocolVersion = "9p2000.L"、Default9pMsize = "128KiB" 等常量）。

4.2 挂载与文件共享

mounts:
- location: "~"
  # mountPoint: null      # 默认等于 location
  # writable: false       # reverse-sshfs 下不建议设为 true
  sshfs:
    cache: true
    followSymlinks: false
  # 9p:
  #   securityModel: "none"    # passthrough / mapped-xattr / mapped-file / none
  #   protocolVersion: "9p2000.L"
  #   msize: "128KiB"
  #   cache: "fscache"         # 只读默认 fscache，可写默认 mmap
mountType: "default"          # reverse-sshfs / 9p / virtiofs
mountInotify: false           # EXPERIMENTAL

• mountType 默认解析为：QEMU 在非 Windows 上为 9p，vz 为 virtiofs；
• location 与 mountPoint 支持模板变量：{{.Home}}、{{.Dir}}、{{.Name}}、{{.UID}}、{{.User}}、{{.Param.Key}} 等；
• 注意：9p 在 Linux 内核 v6.9/v6.10/v6.11 存在已知问题（v6.12-rc5 修复），可通过 mountTypesUnsupported 声明当前发行版内核不支持的挂载类型。

4.3 网络与端口转发

networks:
- lima: shared          # 由 Lima 托管，需安装 socket_vmnet
  # macAddress: ""
  # interface: "lima0"
  # metric: 100
# - socket: "/var/run/socket_vmnet"   # 非托管网络，需自行启动 daemon
# - vzNAT: true                       # 仅 vz；宿主机可访问，其他客户机不可

portForwards:
- guestPort: 80
  hostPort: 8080        # 默认 hostPort 与 guestPort 相同
  # guestIP: "127.0.0.1"   # 默认值，也会匹配 0.0.0.0 / :: / ::1
  # hostIP: "127.0.0.1"    # 默认值；0.0.0.0 会对外暴露
  # proto: "tcp"           # tcp / udp / any
- guestPortRange: [4000, 4999]
  # hostPortRange: [4000, 4999]
- guestSocket: "/run/user/{{.UID}}/my.sock"
  hostSocket: "{{.Dir}}/sock/mysocket"
  # reverse: false          # 仅 Unix socket 支持反向

规则要点：

• 规则按顺序匹配，第一条命中即生效；22 端口与 ssh.localPort 之间的转发不可覆盖；
• Lima 内部会在规则末尾追加一条回退规则：guestIP: 127.0.0.1、proto: any、guestPortRange: [1, 65535] 映射到宿主机 127.0.0.1 同端口；
• guestIPMustBeZero: false 可使 0.0.0.0 匹配任意绑定接口；
• socket 转发建议放入 {{.Dir}}/sock 目录以避免与 Lima 内部 socket 冲突。

4.4 SSH 与 DNS

ssh:
  localPort: 0           # 0 表示自动分配空闲端口
  loadDotSSHPubKeys: false   # 加载 ~/.ssh/*.pub（配合 rsync 等场景）
  forwardAgent: false
  forwardX11: false
  forwardX11Trusted: false
  overVsock: true        # vz + Linux 客户机默认 true

hostResolver:
  enabled: true          # 宿主机 DNS 代理，VPN/mDNS 变更自动同步进客户机
  ipv6: false            # IPv6 仅在使用 vmnet 且宿主机支持 IPv6 时可用
  hosts:
    host.docker.internal: host.lima.internal   # 静态映射

hostResolver.enabled: false 时，可改用显式 dns 列表（QEMU user-mode 网络默认只挑一个宿主 nameserver）。

4.5 provision 与 probes：客户机初始化

provision 脚本必须以幂等方式编写（重启可能重复执行），支持多种模式（templates/default.yaml）：

模式	执行时机/权限	说明
boot	cloud-init init 阶段，/bin/sh 直接执行	最早执行的脚本
system	final 阶段，root 权限	安装软件包等系统级操作
user	final 阶段，普通用户权限	用户级配置
dependency	final 阶段，在包安装脚本前	可配合 skipDefaultDependencyResolution 跳过默认依赖解析
data	final 阶段，boot 脚本之后	写入文件而不执行
yq	final 阶段	用 yq 表达式编辑客户机内文件
ansible	其他脚本之后（已废弃）	需要 ansible-playbook，建议直接调用

执行顺序遵循 cloud-init 的 init → config → final 三个阶段：boot 脚本在 init 阶段执行，00-lima.boot.sh 在 final 阶段执行，随后依次是 Lima 预置 boot 脚本、30-install-packages.sh（期间执行 dependency 脚本）、data 文件、yq 处理、system 脚本、user 脚本。预置脚本位于 pkg/cidata/cidata.TEMPLATE.d。

probes 是就绪探测脚本（当前仅支持 readiness 模式），以用户模式运行，需以 #! 开头；探测失败会展示 hint 提示信息（例如指引查看 /var/log/cloud-init-output.log）。

4.6 containerd、附加磁盘与其他

containerd:
  system: false          # rootful containerd
  user: true             # rootless containerd（Linux x86_64/aarch64 默认 true）
additionalDisks:
- name: "data"           # 客户机内以 lima-data 标签、/mnt/lima-data 挂载
  format: true
  fsType: "ext4"
copyToHost:              # 客户机文件拷贝到宿主机
- guest: "/root/.kube/config.localhost"
  host: "{{.Dir}}/copied-from-guest/kubeconfig.yaml"
  skipIfMissing: true
  deleteOnStop: true
plain: false             # plain 模式忽略挂载/转发/containerd 等，不运行 guestagent
nestedVirtualization: false   # 仅在 Apple M3+ 且 vz/krunkit 下支持
tpm: false               # EXPERIMENTAL，需要 swtpm，仅 qemu

其他还有 caCerts（移除默认 CA 或注入自定义 CA）、upgradePackages（开机升级）、env（注入客户机环境变量，代理变量自动补充大写变体）、propagateProxyEnv（默认把 limactl start 进程的代理环境变量带入客户机，并把 localhost/127.0.0.1 替换为宿主机网关地址）、audio/video（QEMU 音频与显示，video.display 默认 none）、firmware（legacy BIOS / UEFI）等。

五、配置优先级：lima.yaml 与全局覆盖

每次启动实例时，最终配置由多层合并决定（见 templates/default.yaml 与 pkg/limayaml/load.go 的实现）：

1. 实例自身的 lima.yaml；
2. $LIMA_HOME/_config/default.yaml：为所有实例提供全局默认值，每次 limactl start 都会生效；
3. $LIMA_HOME/_config/override.yaml：优先级高于实例 lima.yaml，可全局强制覆盖（如统一开启家目录可写）；
4. $LIMA_HOME/_config/base.yaml（EXPERIMENTAL）：类似 default.yaml，但在实例创建时的 base 模板合并阶段生效，会成为 lima.yaml 的一部分。

合并规则：

• 切片（mounts、provision）与映射（env）是"组合"而非"替换"：切片按 override → lima.yaml → default.yaml 顺序拼接；映射按 default.yaml → lima.yaml → override.yaml 依次覆盖；
• 例外：dns 直接采用最高优先级文件的列表；mounts 中 location 相同的条目会更新 writable，按 default → lima → override 顺序处理；networks 中 interface 相同的条目由高优先级定义替换低优先级定义。

这套机制让团队可以在不修改每个实例配置的前提下统一基线，也可以针对单实例做局部定制。

六、内置模板实战：Docker 与 Kubernetes

6.1 docker 模板：一条龙部署 rootless Docker

templates/docker.yaml 是理解 Lima 模板能力的绝佳样例，它完整演示了 base、provision、probes、hostResolver、portForwards、message、param 的协同：

minimumLimaVersion: 2.0.0
base:
- template:_images/ubuntu-lts
- template:_default/mounts

# containerd 由 Docker 管理，所以 Lima 不再启用
containerd:
  system: false
  user: false

provision:
- mode: system
  script: |
    #!/bin/sh
    sed -i 's/host.lima.internal.*/host.lima.internal host.docker.internal/' /etc/hosts
- mode: system
  script: |
    #!/bin/bash
    set -eux -o pipefail
    command -v docker >/dev/null 2>&1 && exit 0
    export DEBIAN_FRONTEND=noninteractive
    curl -fsSL https://get.docker.com | sh
    systemctl disable --now docker.service docker.socket containerd.service containerd.socket || true
    systemctl mask docker.service docker.socket containerd.service containerd.socket || true
    apt-get install -y uidmap dbus-user-session
- mode: yq
  path: "{{.Home}}/.config/docker/daemon.json"
  expression: |
    .features.cdi = true |
    .features.containerd-snapshotter = {{.Param.containerdSnapshotter}}
  owner: "{{.User}}"
- mode: user
  script: |
    #!/bin/bash
    set -eux -o pipefail
    systemctl --user start dbus
    dockerd-rootless-setuptool.sh install
    docker context use rootless

hostResolver:
  hosts:
    host.docker.internal: host.lima.internal

portForwards:
- guestSocket: "/run/user/{{.UID}}/docker.sock"
  hostSocket: "{{.Dir}}/sock/docker.sock"

要点解读：

• 前两条 system 脚本分别建立 host.docker.internal 域名与安装 Docker（幂等：command -v docker ... && exit 0）；
• 关闭并 mask 掉系统级 Docker 服务，安装 uidmap/dbus-user-session 以支持 rootless 模式；
• 用 mode: yq 直接编辑客户机内 daemon.json，开启 CDI 与 containerd-snapshotter；
• 最后以用户身份安装 rootless setup 并切换 context；
• 探测脚本会轮询 docker 命令与 rootlesskit 进程是否就绪；
• Docker socket 通过 guestSocket → hostSocket 转发到实例目录，宿主机 docker context create lima-{{.Name}} 即可接入；
• 模板启动完成后会在终端打印 message 提示下一步操作；若启用了 Rosetta，还会给出 --device=lima-vm.io/rosetta=cached 运行 x86_64 容器的指引。

6.2 k8s 模板：单节点集群与多节点扩展

templates/k8s.yaml 通过 kubeadm 部署 Kubernetes，同样大量运用参数化：

param:
  proxy: ""                 # k8s.io 软件包代理，如 http://host.lima.internal:3142
  mirror: ""                # 镜像仓库镜像，如 http://host.lima.internal:8080
  stability: "stable"       # stable 或 prerelease
  release: "v1.37"          # stable 或 v1.xx 分支
  version: "stable"         # stable 或 v1.xx.y
  flannelVersion: "v0.28.9" # latest 或 v0.xx.y
  url: ""                   # 加入集群时的 API Server 地址
  token: ""                 # kubeadm join token
  discoveryTokenCaCertHash: ""

使用方式：

# 单节点控制面
limactl start template:k8s
export KUBECONFIG=$(limactl list k8s --format 'unix://{{.Dir}}/copied-from-guest/kubeconfig.yaml')
kubectl get no

# 多节点：先启动第一个节点并生成 join 命令
limactl start --name k8s --network lima:user-v2 template:k8s
limactl shell k8s sudo kubeadm token create --print-join-command

# 再用打印出的参数启动第二个节点
limactl start --name k8s-1 --network lima:user-v2 template:k8s \
              --param url="<ADDRESS>" --param token="<TOKEN>" \
              --param discoveryTokenCaCertHash="<HASH>"

该模板的 provision 脚本包含三个关键阶段：安装 kubeadm/kubelet/kubectl 并配置 containerd 的 systemd cgroup 驱动与 CNI bin 目录、kubeadm init（控制面节点）或 kubeadm join（工作节点）、安装 Flannel Pod 网络并去除控制面污点。kubeconfig 通过 copyToHost 拷贝到宿主机，其中 deleteOnStop: true 保证实例停止后宿主机上的副本被清理。

七、日常管理与调试

• 查看实例：limactl list（支持 --format json|yaml|table|go-template、--filter '.status == "Running"'、--quiet）；
• 进入 shell：limactl shell INSTANCE，lima 是其别名；--workdir 指定起始目录，--preserve-env 透传环境变量（可用 LIMA_SHELLENV_BLOCK/LIMA_SHELLENV_ALLOW 控制黑白名单），--sync 可在进入前把宿主机目录 rsync 到客户机、退出时交互式确认回传；
• 启动/停止/删除：limactl start、limactl stop、limactl delete、limactl factory-reset；
• 复制文件：limactl copy；
• 编辑配置：limactl edit INSTANCE（cmd/limactl/edit.go）；
• 快照：limactl snapshot（配合 pkg/snapshot）；
• GUI/远程开发：macOS 上有 Lima xbar 插件与 lima-gui（Qt）等社区 GUI 方案，配合 VS Code Remote 即可获得与本地一致的开发体验；
• 调试：limactl --debug 可输出详细日志，--log-level 调整日志级别。

仓库在 hack/bats/tests 提供了大量 Bats 集成测试（如 shell.bats、list.bats、param.bats、protect.bats、mcp.bats），可作为理解命令行为的可执行文档。

八、生态采纳与社区

Lima 是一个 CNCF 孵化项目。README 列出的采纳者覆盖了容器桌面生态的主流工具：

• 容器环境：Rancher Desktop（桌面端 Kubernetes 与容器管理）、Colima（macOS 上最小化配置的 Docker/Kubernetes）、Finch（本地容器开发 CLI）、Podman Desktop（提供 Lima 虚拟机插件）；
• GUI：Lima xbar 插件（菜单栏启停虚拟机并显示状态）、lima-gui（Qt 图形界面）。

这些下游项目进一步印证了 Lima 作为"虚拟机底座"的定位：上游只负责把 Linux 虚拟机、文件共享与端口转发做到开箱即用，具体的容器引擎与 UI 由生态各取所需。

九、贡献与参与

• 贡献指南与 DCO（Developer Certificate of Origin）要求：所有提交必须使用 git commit -s 签名；
• 沟通渠道：GitHub Discussions、CNCF Slack 的 #lima 频道、月度社区会议（Zoom）；
• 社交媒体：X（@TheLimaProject）、Mastodon；
• 行为准则遵循 CNCF Code of Conduct。

十、进一步阅读

• 项目总览、路线图、采用者列表；
• 官方文档站点的源文件位于 website/content/en/docs，包含安装、配置（config）、用法（usage）、模板（templates）、参考（reference）、FAQ 与发布说明等章节；
• 配置模板完整字段：templates/default.yaml（内置默认值解析见 pkg/limayaml/defaults.go）；
• CLI 入口与子命令实现：cmd/limactl；
• 客户机侧初始化脚本：pkg/cidata/cidata.TEMPLATE.d。

适用前提说明：本文命令与配置以当前仓库（Lima v2.x 系列，minimumLimaVersion: 2.0.0）为准；vz 驱动需要 macOS 13 及以上，Rosetta 与嵌套虚拟化等能力有明确的平台限制（Apple Silicon / Apple M3+），Windows 主机由 HCS 与 WSL2 驱动支持，实际使用前请以 limactl start 的交互式配置确认与自身环境匹配。