苹果容器

apple-container
分类编程
作者Agentic Awesome Skills 社区
许可Apache-2.0
评分4.80/5
使用11.0K

Apple container

使用场景

  • 在搭载 Apple 芯片的 macOS 上，使用 Apple 开源的 container CLI 构建、运行或管理 OCI/Linux 容器时。
  • 希望使用轻量级的单容器虚拟机而非 Docker 守护进程时。
  • 将 Docker 风格的工作流（构建、运行、执行、日志、网络）迁移到 Apple 容器工具链时。

Apple 的 container 是一个开源 CLI，用于在 Apple 芯片 Mac 上构建、运行和管理 OCI/Linux 容器。每个容器都运行在自己的轻量级虚拟机中（由 Containerization 框架和 Virtualization API 支持），因此没有像 Docker 那样的共享守护进程 —— 服务通过 launchd 按用户运行。镜像为标准 OCI 产物，因此可与 Docker 仓库和其他 OCI 工具互操作。该 CLI 在设计上模仿 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 release 页面 (apple/container) 下载经签名的 .pkg 安装包并运行。完整要求/兼容性矩阵及单容器虚拟机模型的工作原理请参阅 references/concepts.md。

快速上手

安装签名安装包后，首次启动后台服务：

1. *
1. 从 GitHub releases 页面 下载最新的已签名安装程序 .pkg。
2. 双击下载的安装包并按照提示操作，输入管理员密码以便将文件放置在 /usr/local 下。（目前没有文档记录的 CLI installer 调用方式 —— 请通过 GUI 安装包进行安装。）
3. 启动服务并确认其状态正常：

bash
# 启动容器服务（通过 launchd 启动 container-apiserver 及辅助程序）。首次运行时

会提示安装默认 Linux 内核 —— 请接受，或使用 --disable-kernel-install 进行非交互式启动，


稍后通过 container system kernel set 添加内核。

container system start

验证服务状态是否正常

container system status

在执行任何容器/镜像/构建命令之前，必须先运行 container system start —— 出现连接/XPC 错误几乎总是意味着服务已停止，请重新运行该命令。使用 container system stop（仅支持 -p/--prefix 参数）停止并注销 launchd 服务。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 lifecycle | 创建、启动、运行、停止、执行、检查、列出、删除容器 | 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 "machine" 环境（1.0.0 版本新增） | container machine --help |

每个命令组的准确子命令名称、别名、参数和标志均记录在 references/commands.md 中 —— 在运行不熟悉的命令前请查阅该文档，而不要猜测其是否与 Docker 语法一致。

快速上手指南

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

  • references/commands.md —— 详尽的 CLI 参考：包含所有命令组、子命令、别名、参数和标志。
  • references/commands.md — 包含所有可用命令及其标志。阅读此文档以构建具体的 container ... 调用，或在执行前确认某个标志是否存在。
  • references/concepts.md — 涵盖架构（每容器一个 VM、容器化框架）、系统要求及 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（每个容器对应一个轻量级 VM）。不存在共享的 Docker 网桥；请直接通过 IP 访问容器，或设置本地 DNS 域名（需管理员权限，运行 container system dns create ...）以实现基于名称的访问。
  • container network 需要 macOS 26。 在 macOS 15 上仅可用单个默认子网，且无法使用 network 命令组 —— 详见 references/concepts.md。
  • 在需要精确度时请使用全限定镜像引用（例如使用 docker.io/library/alpine 而非简单的 alpine），以避免镜像来源仓库的歧义。

局限性

  • Apple Container 要求使用 Apple 芯片，且在不同 macOS 版本中的支持和网络行为有显著差异；在依赖某个标志前，请先验证已安装的 CLI 版本。
  • OCI 镜像和仓库内容属于第三方输入。在拉取或运行镜像前，请检查并信任镜像来源。
  • 本技能本身并不保证容器工作负载默认安全：挂载、发布端口、特权设置、仓库凭据和清理操作可能会导致数据泄露或丢失。
  • 在卸载、修剪（pruning）、删除容器、卷或镜像前请暂停，并对每项破坏性操作请求明确批准。