在macOS上用Colima代替Docker
Colima 是 macOS 上最直接的本地容器运行时方案之一。它通过 Lima 启动一个 Linux 虚拟机，在这层 Linux 环境里运行 Docker、containerd，以及可选的 k3s Kubernetes，再把这些能力暴露给宿主机上的 docker、 kubectl 和其他常用客户端。本文整理 Colima 在 macOS 上的工作原理、安装方法、推荐配置、验证步骤以及几个最常见的运维注意事项。
容器并不是“比虚拟机更轻的 macOS 进程”。容器依赖 Linux 内核提供的 Namespace、cgroups、OverlayFS 等机制。macOS 不提供这套 Linux 内核接口，因此在 macOS 上运行 Linux 容器时，底层一定存在一个 Linux 虚拟机。
这也是理解 Colima 的关键前提。它并没有绕过虚拟化，而是把虚拟化这一层做得更轻、更透明：用 Lima 管理 Linux 虚拟机，用 Colima 负责容器运行时和宿主机 CLI 的集成。
Colima 可以视为 Lima 之上的一层开发者友好封装。Lima 负责虚拟机、文件共享和端口转发，Colima 负责在虚拟机中配置容器运行时，并把它无缝接到宿主机工作流里。
从使用者视角看，Colima 有三个特征最重要：
- 它在 macOS 上提供 Docker、containerd 和可选 Kubernetes 的本地运行环境。
- 它直接复用宿主机上的命令行客户端，而不是强制引入一个单独的桌面应用工作流。
- 它支持多 Profile，每个 Profile 都是一台独立虚拟机，适合把轻量 Docker 环境和启用 Kubernetes 的环境分开管理。
在 macOS 上做本地容器开发，问题通常不在“能不能跑起来”，而在于环境是否足够可控。Colima 的价值主要体现在三个方面：
- 结构更清晰。宿主机 CLI、Linux 虚拟机、容器运行时三层边界明确，排障时更容易定位问题落在哪一层。
- 控制更细。CPU、内存、磁盘、架构、Kubernetes、网络和挂载方式都可以用命令行或 YAML 配置。
- 更接近工程化使用。它天然适合脚本化、Profile 隔离、CI 风格的命令流，而不是围绕 GUI 操作组织工作。
如果机器上已经装有 Docker Desktop，也不一定必须先卸载。更重要的是明确当前激活的 Docker context，避免命令误连到错误的 daemon。
在 macOS 上，最简单的安装方式是 Homebrew。Docker runtime 需要宿主机安装 Docker CLI；如果要启用 Kubernetes，还需要 kubectl。
|
1 |
brew install colima docker kubectl |
首次启动可以先使用默认配置验证链路是否正常：
|
1 2 3 |
colima start docker run --rm hello-world docker ps |
如果只想把它作为 Docker daemon 使用，这一步已经足够。若需要本地 Kubernetes，可以在启动时直接打开：
|
1 2 |
colima start --kubernetes kubectl get nodes |
如果系统里同时存在多个 Docker daemon，先确认当前 context：
|
1 2 |
docker context ls docker context use colima |
Colima 支持用命令行参数临时配置，也支持用 YAML 保存持久配置。日常使用中，最稳妥的入口通常是 colima start --edit：它会打开当前 Profile 的配置文件并在保存后启动实例。
下面是一份适合本地开发的通用示例。它移除了项目私有镜像源和业务环境假设，只保留公共环境下最常见、最有价值的选项。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
# 资源配置。默认值足以启动单个容器，但本地同时跑数据库、应用和 K3s 时通常偏小。 cpu: 4 memory: 8 disk: 100 # 创建后不可变的关键项。保持宿主机架构，使用 Docker runtime。 arch: host runtime: docker # 单节点 k3s。关闭默认 Traefik，避免抢占本地开发环境里的入口层职责。 kubernetes: enabled: true version: v1.35.0+k3s1 k3sArgs: - --disable=traefik # 给 VM 分配一个可从宿主机访问的地址，便于排障和直接探测。 network: address: true mode: shared # 在较新的 macOS 上优先使用 Apple Virtualization Framework。 vmType: vz # Apple Silicon 上运行 linux/amd64 用户态程序时启用 Rosetta。 rosetta: true # VZ + virtiofs 是 macOS 上常见的高性能组合。 mountType: virtiofs # 启动后自动激活 Docker / Kubernetes context。 autoActivate: true # 给 VM 预装少量排障工具。脚本需要幂等。 provision: - mode: system script: | apt-get update apt-get install -y vim curl htop git make dnsutils net-tools iputils-ping telnet |
官方文档把配置分为资源、VM、运行时、网络、挂载、SSH、Provision 与环境变量几组。下表汇总当前官方模板中的主要配置项，以及文档中额外说明的 rootDisk。
| 配置项 | 默认值 | 说明 | 备注 |
| cpu | 2 | 分配给 VM 的 vCPU 数量。 | 资源项 |
| memory | 2 | 分配给 VM 的内存，单位 GiB。 | 资源项 |
| disk | 100 | 容器数据盘大小，单位 GiB。 | 创建后只能增大 |
| rootDisk | 20 | VM 根文件系统磁盘大小，单位 GiB。 | 官方配置文档有说明 |
| arch | host | VM 架构，可跟随宿主机，或显式指定其他架构。 | 创建后不可变 |
| runtime | docker | 容器运行时。 | 创建后不可变 |
| modelRunner | docker | AI 模型运行器后端。 | AI workload 配置 |
| hostname | null | 自定义 VM 主机名。 | 默认是 colima 或 colima-<profile> |
| kubernetes.enabled | false | 是否启用内置 k3s。 | Kubernetes 组 |
| kubernetes.version | latest stable | k3s 版本，需与官方 k3s 版本号严格匹配。 | Kubernetes 组 |
| kubernetes.k3sArgs | --disable=traefik | 传给 k3s server 的附加参数。 | Kubernetes 组 |
| kubernetes.port | 0 | Kubernetes API 监听端口，0 表示自动选取未占用端口。 | Kubernetes 组 |
| autoActivate | true | 启动后自动激活 Docker / Kubernetes context。 | 客户端行为 |
| network.address | false | 给 VM 分配可达 IP。 | macOS only |
| network.mode | shared | 网络模式，官方文档列出 shared 与 bridged。 | macOS only |
| network.interface | en0 | bridged 模式使用的宿主机网卡。 | 仅 bridged 生效 |
| network.preferredRoute | false | 是否把分配到的 VM IP 设为优先路由。 | 需 address=true |
| network.dns | [] | 自定义 DNS 解析器列表。 | 网络组 |
| network.dnsHosts | host.docker.internal: host.lima.internal | 内置 DNS 主机映射。 | 网络组 |
| network.hostAddresses | false | 复制宿主机 IP 到 VM，便于按指定主机地址做端口转发。 | 网络组 |
| network.gatewayAddress | 192.168.5.2 | VM 网关地址，自定义时最后一个八位组必须为 2。 | 网络组 |
| forwardAgent | false | 是否转发宿主机 SSH agent。 | SSH 组 |
| docker | {} | 直接映射到 Docker daemon.json 的配置块。 | 高级配置 |
| vmType | qemu | 虚拟化后端。 | 创建后不可变 |
| portForwarder | ssh | 端口转发实现，可选 ssh、grpc、none。 | 网络组 |
| rosetta | false | Apple Silicon 上启用 amd64 用户态仿真。 | 需要 VZ |
| binfmt | true | 启用外来架构二进制仿真。 | 跨架构兼容 |
| nestedVirtualization | false | 启用嵌套虚拟化。 | 需较新的 Apple Silicon 与 VZ |
| mountType | qemu 时 sshfs，vz 时 virtiofs | 宿主机目录挂载驱动。 | 创建后不可变 |
| mountInotify | false | 向 VM 传播 inotify 文件事件。 | 实验性 |
| cpuType | host | QEMU 的 CPU 类型。 | QEMU only |
| provision | [] | 启动时执行的 Provision 脚本。 | 需幂等 |
| sshConfig | true | 是否自动更新宿主机 ~/.ssh/config。 | SSH 组 |
| sshPort | 0 | VM SSH 服务端口，0 表示随机端口。 | SSH 组 |
| mounts | [] | 额外挂载目录列表；设为 null 可禁用所有挂载。 | 挂载组 |
| diskImage | "" | 自定义 VM 磁盘镜像路径。 | 高级配置 |
| env | {} | 注入到 VM 内部的环境变量。 | 环境变量组 |
Colima 官方文档给出了三层配置入口。第一层是 colima start --edit，它直接编辑当前实例的配置文件；第二层是 colima template，它修改后续新建实例继承的默认模板；第三层是环境变量，例如 COLIMA_HOME、 COLIMA_PROFILE 和 DOCKER_CONFIG，用于改变配置根目录、活动 Profile 和 Docker 客户端配置目录。
|
1 2 3 4 5 6 7 8 9 |
# 编辑当前 Profile 配置 colima start --edit # 编辑默认模板 colima template # 显式指定编辑器 colima start --edit --editor code colima template --editor code |
配置文件路径也值得明确记住：
- 默认 Profile： ~/.colima/default/colima.yaml
- 命名 Profile： ~/.colima/<profile>/colima.yaml
- 默认模板： ~/.colima/_templates/default.yaml
官方文档还特别指出，arch、runtime、vmType、mountType 属于创建后不可变的设置；修改这几项时，正确路径不是重启，而是删除实例并按新参数重建。
配置完成后，先检查虚拟机状态：
|
1 |
colima status |
如果启用了 network.address，并且宿主机安装了 jq，可以直接取出 VM IP：
|
1 2 3 |
export COLIMA_VM_IP=$(colima status -j | jq -r .ip_address) echo "$COLIMA_VM_IP" ping "$COLIMA_VM_IP" |
随后验证 Docker 和 Kubernetes 两条控制链是否都可用：
|
1 2 3 |
docker ps kubectl config get-contexts kubectl get nodes |
若需要进入底层虚拟机排查问题，可以直接 SSH：
|
1 |
colima ssh |
官方命令文档的结构很清晰：一个 start 负责创建与启动实例，若干生命周期命令负责停启和删除，状态与连接命令负责观察和进入虚拟机，此外还有 Kubernetes、containerd、模板、升级与补全相关的辅助命令。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# 启动默认 Profile colima start # 启动并启用 Kubernetes colima start --kubernetes # 查看所有 Profile colima list # 停止当前实例 colima stop # 删除当前实例及其容器数据 colima delete --data --force |
| 命令 | 典型形式 | 作用 |
| start | colima start [profile] | 创建或启动指定 Profile，对大多数配置项也在这一命令上完成。 |
| stop | colima stop [profile] | 停止指定实例。 |
| restart | colima restart [profile] | 重启实例。 |
| delete | colima delete [profile] | 删除实例；可选择是否连同数据一并清理。 |
| status | colima status [profile] | 查看实例状态、运行时、架构、挂载方式、socket 路径等信息。 |
| list | colima list | 列出所有 Profile。 |
| ssh | colima ssh [profile] -- command | 进入 VM，或直接在 VM 内执行单条命令。 |
| ssh-config | colima ssh-config [profile] | 输出当前 VM 的 SSH 连接配置。 |
| kubernetes start | colima kubernetes start [profile] | 在已运行实例上启用 Kubernetes。 |
| kubernetes stop | colima kubernetes stop [profile] | 关闭 Kubernetes。 |
| kubernetes reset | colima kubernetes reset [profile] | 重置内置 Kubernetes 集群。 |
| model run | colima model run <model> | 运行 AI 模型。 |
| model serve | colima model serve <model> | 以 Web UI 方式提供模型服务。 |
| nerdctl | colima nerdctl -- <command> | 在 containerd runtime 下转发 nerdctl 命令。 |
| nerdctl install | colima nerdctl install | 安装独立可调用的 nerdctl。 |
| template | colima template | 生成或编辑默认配置模板。 |
| update | colima update | 更新 Colima。 |
| prune | colima prune [profile] | 清理未使用数据以释放磁盘空间。 |
| version | colima version | 输出版本信息。 |
| completion | colima completion [shell] | 生成 shell 自动补全脚本。 |
colima start 是参数最集中的命令。官方命令文档把它拆成资源、运行时、VM、网络、挂载、Kubernetes、SSH、DNS 与配置九组。
| 分组 | 参数 | 说明 |
| 资源 | --cpus, --memory, --disk, --root-disk | 设置 CPU、内存、数据盘和根盘容量。 |
| 运行时 | --runtime, --activate | 选择运行时，并决定启动后是否自动切换客户端 context。 |
| VM | --arch, --vm-type, --cpu-type, --hostname, --disk-image, --vz-rosetta, --nested-virtualization, --binfmt, --foreground | 控制架构、虚拟化后端、CPU 模型、磁盘镜像与前台运行方式。 |
| 网络 | --network-address, --network-host-addresses, --network-mode, --network-interface, --network-preferred-route, --gateway-address, --port-forwarder | 控制可达 IP、桥接模式、网关与端口转发实现。 |
| 挂载 | --mount, --mount-type, --mount-inotify | 控制宿主机目录挂载与文件事件传播。 |
| Kubernetes | --kubernetes, --kubernetes-version, --k3s-arg, --k3s-listen-port | 启用 k3s、指定版本，并传递附加参数。 |
| SSH | --ssh-agent, --ssh-config, --ssh-port | 控制 SSH agent 转发、宿主机 SSH 配置生成和端口。 |
| DNS | --dns, --dns-host | 配置 DNS 解析器与主机映射。 |
| 配置 | --edit, --editor, --template, --save-config, --env | 控制配置文件编辑、模板使用、参数持久化和 VM 环境变量注入。 |
| 命令 | 参数 | 说明 |
| delete | --data, --force | --data 会连同镜像、卷等数据一起删除， --force 跳过确认。 |
| list | --json | 以 JSON 形式输出所有 Profile。 |
| ssh | -- command | 不进入交互式 shell，直接在 VM 里执行单条命令。 |
| model run / serve | --profile, --runner, --port | 选择 Profile、模型运行器，以及 serve 的 Web UI 端口。 |
| completion | bash, zsh, fish, powershell | 为不同 shell 生成补全脚本。 |
当你修改了底层创建期参数，例如架构、运行时、虚拟机类型或挂载驱动，而变更没有按预期生效时，最常见的原因不是配置语法错误，而是这些参数属于创建期决策。这类参数通常需要删除实例后重建。
很多“Cannot connect to the Docker daemon”问题，本质上不是 Colima 没有启动，而是本地 docker CLI 仍然连着别的 context。优先检查 docker context ls，再决定是否切到 colima。
使用 Docker runtime 时，在同一个 Colima 实例里构建或拉取的镜像可以被 Kubernetes 直接使用。这对本地调试非常方便，因为不需要把每次本地构建都重新推到远端仓库。若切换为 containerd runtime，则镜像管理方式会随之变化，调试路径也应按 containerd 的 namespace 语义理解。
network.address: true 让宿主机能直接访问虚拟机 IP，这对排障很有用，但常规应用访问仍应优先通过容器端口映射完成。应用层服务应该通过 -p HOST:CONTAINER 或 Kubernetes Service/Ingress 暴露，而不是把 VM IP 当成唯一访问入口。
如果你的目标只是“在 macOS 上拥有一个可脚本化、可重建、可启用 Kubernetes 的本地 Linux 容器环境”，Colima 基本就是最短路径。它尤其适合以下几类场景：
- 需要在 macOS 上长期维护本地 Docker 与 K3s 开发环境。
- 希望把运行时控制逻辑写进脚本、Makefile 或项目 bootstrap 流程。
- 需要按项目拆分多个隔离环境，例如一个轻量 Docker Profile 加一个启用 Kubernetes 的 Profile。
- 需要在 Apple Silicon 上兼顾原生 ARM 开发与部分 amd64 兼容需求。
Leave a Reply