apple-container-skill

Apple Container 技能

将 Apple 的 container CLI 用作原生 macOS Linux 容器运行时。此技能应指导 Agent 如何选择，而不只是提供命令语法。

首要步骤

开始实际工作前，先确认主机和运行时是否可用：

sw_vers
uname -m
command -v container
container --version
container system status
container system version

• 受支持的工作流要求使用 Apple silicon（arm64）和 macOS 26+。Apple 不支持更早的 macOS 版本；不要将 macOS 15 的变通方案描述为受支持的操作。
• 记录 CLI 和服务版本，将其与当前签名版本进行比较，并确保版本匹配后再开始实际工作。截至 2026 年 10 月，1.5.0 是处理不可信镜像、镜像归档、注册表、容器标识符或实验性 Kubernetes 时的安全基线；1.3.1 和 1.4.1 修复了路径遍历、主机文件访问、凭据处理及相关 OCI 缺陷；1.5.0 会在将来宾提供的 kubeconfig 值合并到主机 kubeconfig 前对其进行清理。对于上游已修复的缺陷，应先升级，而不是自行设计变通方案。
• 如果缺少 CLI，优先使用 GitHub releases 页面上由 Apple 签名的安装程序。Homebrew 也可用，但如果通过 Homebrew 安装后运行 container system start 时出现插件缺失，请升级或重新安装 formula。
• 如果状态显示服务已停止，请使用 container system start 启动服务。首次启动时可能会提示安装推荐的 Linux 内核。
• 将已安装的 container <command> --help 视为权威的命令说明。版本摘要甚至生成的命令参考都可能滞后于随附的解析器；不要臆测 Docker 子命令或标志。
• 在将问题归咎于应用代码前，先运行冒烟测试：

container run --rm docker.io/library/alpine:latest sh -lc 'uname -a; nslookup github.com'

对于未知或不稳定的环境，请运行随附的诊断工具：

bash skills/apple-container-skill/scripts/diagnose.sh

选择合适的运行时形态

• 对于一次性应用容器、单次 Linux 命令、项目开发 Shell、镜像冒烟测试，以及应将状态保存在绑定挂载或命名卷中的服务，请使用 container run。
• 对于长期运行的 Linux 工作区，请使用 container machine：例如反复进行发行版测试、运行系统服务、使用 VS Code Remote SSH、保留持久根文件系统，或采用“在 macOS 上编辑，在 Linux 中构建”的工作循环。
• 仅将实验性的 container k8s 用于一次性本地单节点 Kubernetes 集群。不要将其描述为生产级或多节点 Kubernetes 运行时，并提醒用户，创建集群会写入或更新 kubeconfig 条目，而删除集群会移除对应条目。1.5.0 中没有 container k8s start：要重启已停止的集群，请先删除再重新创建；不要编写从旧示例中复制的 start 命令脚本。
• 不要将 machine 简单描述为“持久容器”。Machine 是围绕容器、独立的持久根磁盘和主机集成构建的便捷封装。它会映射主机用户、转发 SSH Agent 支持，并将 macOS 主目录挂载到 /Users/<user>，而 Linux 用户的 $HOME 则是 /home/<user>。
• 当前的 Container Machine 镜像需要包含 /sbin/init。Apple Container 1.3 放宽了 machine 路径限制，当前 Apple 指南直接使用 alpine:latest；在当前版本中，应先尝试使用包含 /sbin/init 的指定镜像，再派生自定义镜像。如果镜像缺少 init，或工作流需要受管理的系统服务，请构建支持 OpenRC 或 systemd 的镜像。
• 编写 machine 命令脚本时，优先使用选项终止符：container machine run -n dev -- whoami 或 container machine run -n dev -- /bin/sh -c 'whoami; pwd; echo "$HOME"'。在 heredoc／非交互式脚本中避免使用 -i，因为它可能从标准输入中读取脚本剩余内容。

机器镜像选择

当用户指定发行版镜像时，保留发行版选择，但正确选择运行时形态：

• 对于一次性命令或应用容器，直接将指定镜像用于 container run。
• 对于 container machine，检查指定镜像是否包含 /sbin/init。在 Apple Container 1.3 及更高版本中，满足此要求时可直接使用标准镜像；Apple 当前的快速入门使用 alpine:latest。
• 如果缺少 /sbin/init，或者用户需要由 systemd 管理的服务，请说明此要求，并基于指定镜像构建机器镜像，而不是悄悄切换发行版。
• 对于 Alpine 机器，安装 openrc 和 openrc-init，添加相关用户和网络工具，设置 CMD ["/sbin/openrc-init"]，然后构建本地 *-machine 镜像。只安装 openrc 并使用 BusyBox /sbin/init 可能会导致系统启动后立即关闭。
• 对于 Ubuntu/Debian 机器，根据需要添加 systemd、dbus、sudo、SSH 和网络工具，设置 systemd 目标，然后构建本地 *-machine 镜像。
• 在 Apple Container 1.2 或更早版本中，请先升级，再考虑通过永久自定义镜像规避缺少 OpenRC、路径被屏蔽或路径只读的问题。

安全规则

执行以下操作前请先询问：

• 运行 sudo、安装、升级、卸载或更改 DNS 解析器条目。
• 全局清理：container prune、container image prune、container volume prune、container network prune，或删除所有资源。
• 删除并非为当前任务创建的具名机器、卷、镜像或容器。
• 编辑 ~/.ssh/config、更改主机防火墙或 VPN 设置，或将绑定挂载范围扩大到项目目录之外。
• 传递会禁用或削弱安全控制的内核参数。仅在有文档说明的内核级要求时使用 --kernel-arg，不要将其用于普通应用配置。
• 向 --masked-path 或 --read-only-path 传递 NONE，因为这会清除运行时安全默认设置，而不是增加限制。

请优先使用优雅停止方式（container stop、container machine stop），然后再强制删除或运行 container kill。

实用默认配置

常见的项目 Shell：

container run --rm -it -v "$PWD:/work" -w /work docker.io/library/ubuntu:24.04 bash

构建并运行镜像：

container build -t local/app:dev .
container run --rm -p 8080:8080 local/app:dev

长期运行的机器：

container machine create docker.io/library/alpine:latest --name dev --set-default --cpus 4 --memory 8G
# Run the first command from a real terminal so initial user setup has a host PTY.
container machine run -n dev -- /bin/sh -c 'whoami; pwd; echo "$HOME"'
container machine stop dev

当前重要行为

• container system property get、set 和 clear 已在 1.0 中移除。请使用 ~/.config/container/config.toml 设置默认值，并仅使用 container system property list 查看生效的配置。
• Apple 的签名安装程序会将 CLI 安装到 /usr/local/bin/container；如果新打开的 Shell 找不到 container，请直接检查该路径。
• Apple Container 1.3 移除了注册表的 --scheme auto 值。当前版本仅接受 https（默认值）或显式指定的 http；仅在刻意信任的本地注册表中使用 HTTP。
• Apple Container 1.3.1 和 1.4.1 包含针对精心构造的标识符、映像层和布局、注册表身份验证以及主机文件访问的安全修复。Apple Container 1.5.0 还会在将 Kubernetes Guest 提供的 kubeconfig 值合并到主机 kubeconfig 之前进行清理。不要仅因较旧的运行时通过了基本冒烟测试，就用它处理不可信的 OCI 输入或实验性 Kubernetes。
• container build 可能会让 BuildKit 构建器继续运行。如果验证任务必须确保没有运行时进程，请检查 container builder status，然后使用 container builder stop 和 container builder delete。
• Apple Container 1.2.1 新增了 container build --ssh default；对于私有构建依赖，请使用此选项，而不要将 SSH 密钥复制到构建上下文或映像中。
• 通常应使用 -p/--publish 处理主机到容器的流量；如果失败，请检查应用是否在容器内监听 0.0.0.0。
• 对于 Unix 套接字，请根据通信方向选择：将主机上已存在的套接字绑定挂载（-v）到容器中；如果容器中的进程会创建套接字，且主机必须能够访问它，请使用 --publish-socket host_path:container_path。对于非 root 客户端，请检查两端的所有权和权限模式。Apple Container 1.1 修复了非 root 用户访问已挂载套接字的问题。
• Apple Container 1.1 还修复了 container cp 对本地相对路径的处理；在较旧版本中，请使用绝对路径或升级，不要浪费时间排查正确的相对路径。
• Apple Container 1.2 可防止不可信映像中的裸 ENV 条目隐式复制同名主机变量。仍应明确设置继承行为：仅在有意传递主机变量时使用 -e NAME，并优先使用 KEY=value、环境变量文件或密钥机制，以确保运行可复现。
• 仅在有内核、安全或调试需求时使用可重复指定的 --kernel-arg key=value，并通过 cat /proc/cmdline 验证生效的命令行。不要将其用于应用设置，也不要随意替换 lsm=landlock 等安全默认值。
• 截至 1.5.0（已通过已安装的 container run --help 验证），不存在 container run --stop-signal。如需设置可复用的默认值，请在映像中使用 STOPSIGNAL；如需由操作员选择信号，请使用 container stop -s SIGNAL。
• --masked-path 和 --read-only-path 是 run 和 create 的实验性附加隔离控制选项。请通过已安装版本的帮助信息进行验证，优先添加路径；未经明确批准，绝不要使用 NONE 清除运行时默认值。
• container clean <running-container...> 会从每个容器的根文件系统及其命名卷挂载中回收未使用的文件系统空间。该命令的作用范围有限，要求容器正在运行，不能替代全局 prune 命令。
• container system status 在 1.4.1 中新增了主机、客户端、路径和资源字段；1.5.0 保留了这一结构。请按字段名读取结构化输出，并容许新增字段，不要依赖旧结构。
• 在 1.5.0 及更高版本中，即使映像的 ENTRYPOINT 为空，命令参数也会运行（已在本地通过 ENTRYPOINT [] 映像验证）。如果较旧的运行时似乎会忽略此类映像的命令，请升级，而不要包装映像或重写其入口点。
• Apple Container 1.5.0 修复了 localhost DNS 变更后容器出站流量丢失的问题，也修复了构建上下文中符号链接祖先目录下的文件被丢弃的问题。在较旧的运行时中遇到这两种情况，都应视为升级信号，而不是重新设计网络或将文件复制出符号链接目录树的理由。
• 除非工作流已证明可行，否则请将命名卷视为只能附加到一个容器；不要假设同一个命名卷可以同时附加到多个正在运行的容器。
• 容器到主机的流量不使用 Docker 的魔法主机别名。请配置 localhost DNS 域：

sudo container system dns create host.container.internal --localhost 203.0.113.113

这可能会停用 Private Relay，而且重启后可能需要重新创建数据包过滤规则。

• container network 用户定义网络需要 macOS 26+。容器名称解析目前仅适用于默认网络；在自定义网络上，请使用检查得到的 IP，而不要承诺提供 Docker 风格的服务发现。
• 没有 container compose。对于简单且可信的技术栈，可将其转换为明确的构建、运行、就绪检查和清理命令；如果需要 Compose 语义，则保留支持 Compose 的运行时。
• 如果网络原本正常，却在 VPN 或终端安全设置变更后出现故障，应先怀疑 vmnet/VPN 路由，而不是修改应用代码。
• 用户完成设置期间，机器首次执行命令可能需要使用真实的主机终端。如果无头首次运行失败并出现 Operation not supported by device，请在 PTY 中重试初始化；之后可将非交互式 machine run ... -- command 调用编写为脚本。不要在 heredoc 或无人值守任务中添加 -i。

参考资料

• 阅读 references/workflows.md，了解常见的开发、构建、网络、注册表、卷、机器、文件系统空间回收和实验性 Kubernetes 操作手册。
• 如果服务启动、DNS、VPN、vmnet、构建器、Rosetta、端口发布或机器模式出现故障，请阅读 references/troubleshooting.md。
• 确定所需的工作流后，可阅读 references/commands.md，了解简明的命令说明。