apple-container

Apple container

Apple 的 container 是一款开源命令行工具，用于在 Apple 芯片 Mac 上构建、运行和管理 OCI/Linux 容器。每个容器都运行在自己的轻量级虚拟机中（由 Containerization 框架和 Virtualization API 提供支持），因此没有类似 Docker 的共享守护进程——服务由 launchd 按用户运行。镜像是标准 OCI 制品，因此可与 Docker 注册表及其他 OCI 工具互操作。该命令行工具刻意采用类似 Docker 的用法（container run、container build，以及通过 container image push/pull 执行镜像操作），但它是独立工具：不要假设 Docker 的命令路径、 标志、默认值或守护进程行为同样适用（例如，没有顶层的 container images/push/pull 命令——镜像操作命令位于 container image 下）。

要求

• 仅支持 Apple 芯片（M1 或更新机型）。不支持 Intel Mac。
• 官方支持的目标版本为 macOS 26（Tahoe）。 维护者不支持较旧的 macOS，通常也不会修复无法在 26 上复现的问题。该二进制文件仍可在 macOS 15（Sequoia） 上运行，但网络功能有所缩减：仅可使用单个默认子网，且 container network 命令组和 --network 标志会报错。 仅限 macOS 26 的功能会在参考文件中逐一注明。
• 版本： 本技能介绍 1.0.0 版本（功能最完整的版本）。machine 命令组、container cp、container export、container prune、container image prune、container registry list 和 container system version 均为 1.0.0 中新增（0.7.1 中没有）——参考文件中，晚于 0.7.1 推出的功能均标注为 (1.0.0+)。运行 container --version 和 container <group> --help，查看已安装版本支持的功能。
• 从项目的 GitHub Releases 页面（apple/container）下载已签名的 .pkg 安装包并运行即可安装。完整的 要求／兼容性矩阵，以及容器专属虚拟机模型的工作方式，请参阅 references/concepts.md。

设置

安装已签名的软件包，然后启动一次后台服务：

1. 下载最新的已签名 .pkg 安装包，地址： GitHub Releases 页面。
2. 双击下载的软件包并按提示操作，输入管理员密码，以便将文件安装到 /usr/local 下。（没有文档记录的 CLI installer 调用方式——需通过图形界面软件包安装。）
3. 启动服务并确认服务运行正常：

# Start the container services (container-apiserver + helpers via launchd). On first run it
# offers to install the default Linux kernel — accept it, or start non-interactively with
# `--disable-kernel-install` and add a kernel later via `container system kernel set`.
container system start

# Verify services are healthy
container system status

运行任何容器／镜像／构建命令前，都必须先运行 container system start——连接／XPC 错误几乎总是表示服务已停止，因此请重新运行该命令。使用 container system stop 停止并注销 launchd 服务（该命令仅接受 -p/--prefix）。 container system start 的启动标志（-a/--app-root、--install-root、--log-root、 --enable-kernel-install/--disable-kernel-install、--timeout）见 references/configuration.md。

升级／降级／卸载需使用 /usr/local/bin 中的辅助脚本（先运行 container system stop）：update-container.sh（添加 -v <version> 可指定版本），以及 uninstall-container.sh -d（删除用户数据）或 -k（保留用户数据）。完整操作步骤见 references/workflows.md。

命令组一览

所有命令均按 container <group> <subcommand> 的格式调用。容器生命周期动词（run、 create、start、stop、exec、logs、inspect、list/ls、delete/rm、kill、 stats）和 build 均为顶层命令；push、pull 和 tag 等镜像操作则位于 container image 下。运行 container <group> --help 查看确切的标志，或阅读 references/commands.md 查看完整命令矩阵。

组	功能	示例
容器生命周期	创建、启动、运行、停止、执行命令、检查、列出和移除容器	container run --rm -it docker.io/library/alpine sh
build	在构建器 VM 中根据 Dockerfile 构建 OCI 镜像	container build -t myapp:latest .
image	列出、标记、检查、移除、加载/保存、清理本地镜像；向仓库推送/拉取镜像	container image ls
registry	向 OCI 仓库进行身份验证（登录/登出/列出）	container registry login ghcr.io
system	启动/停止/查看服务状态、日志、磁盘用量（df）、DNS、内核和属性	container system status
network	创建/列出/移除容器网络（仅限 macOS 26）	container network create mynet
volume	创建/列出/检查/移除持久卷	container volume create data
builder	管理运行 container build 的构建器 VM（启动/停止/查看状态）	container builder status
machine （1.0.0+）	持久化 Linux“机器”环境（在 1.0.0 中新增）	container machine --help

各组的准确子命令名称、别名、参数和标志见 references/commands.md。运行不熟悉的命令前请先查阅该文件，不要 猜测与 Docker 等效的语法。

浏览此技能

请阅读与任务相对应的参考文件；不要猜测标志或行为。

• references/commands.md — 完整的 CLI 参考：包含每个命令组、子命令、 别名、参数和标志。构造任何具体的 container ... 调用，或在使用某个标志前确认 其存在时，请阅读此文件。
• references/concepts.md — 架构（每个容器对应一个 VM、Containerization 框架）、 系统要求以及 macOS 15 与 26 的差异、网络模型、每个容器的 IP、安全模型，以及 Docker 与 container 的对比。要解释某项功能如何或为何运行，或 Docker 的思维模式 会导致错误答案时，请阅读此文件。
• references/configuration.md — 系统服务、config.toml / 属性模型、 默认内核、DNS 域名、默认仓库、构建器资源和机器设置。要更改默认值、调整 CPU/内存、 指定私有仓库或管理内核时，请阅读此文件。
• references/workflows.md — 可直接复制粘贴的任务步骤（运行镜像、构建并推送、 配置本地 DNS、挂载卷、开放端口）以及常见故障的排查方法。 用户想要完成具体的端到端任务时，请先阅读此文件。

关键规则

• 这不是 Docker。 CLI 的外观与 Docker 相似，但标志、默认值和守护进程行为有所不同。请查看 references/commands.md 确认语法，不要假定它与 Docker 等效。
• 务必先确保服务已启动。 在执行任何容器／镜像／构建命令前，运行 container system start（并通过 container system status 确认）；连接错误通常意味着服务已停止。
• 镜像是标准 OCI 制品，可与 Docker 注册表和其他 OCI 工具互操作。未指定注册表的镜像引用默认使用 docker.io（可通过 registry.domain 属性配置——参见 references/configuration.md）。
• 每个容器在其网络上都有自己的 IP 地址（每个容器对应一个轻量级虚拟机）。这里没有共享的 Docker 网桥；可通过容器的 IP 地址直接访问，或设置本地 DNS 域名（container system dns create ...，需要管理员权限）以通过名称访问。
• container network 需要 macOS 26。 在 macOS 15 上只有一个默认子网可用，且网络命令组不可用——参见 references/concepts.md。
• 需要确保精确性时，请使用完全限定的镜像引用（例如使用 docker.io/library/alpine，而不是仅写 alpine），以避免镜像来源注册表不明确。