apple-container-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Apple Container Skill

Apple Container 技能

To use the Apple Container CLI, execute the commands below using the

run_shell_command

tool. Note: This CLI is specific to Apple's container implementation.

要使用Apple Container CLI，请使用

run_shell_command

工具执行以下命令。 **注意：**此CLI是Apple专属的容器实现工具。

Common Workflows & Architecture

常见工作流与架构

These patterns represent best practices for using the Apple Container CLI effectively.

这些模式代表了有效使用Apple Container CLI的最佳实践。

1. System Lifecycle Management

1. 系统生命周期管理

Unlike standard Docker Desktop, the container system services are explicit.

Startup: Always verify
```
container system status
```
before running operations. If stopped, run
```
container system start
```
.
Kernel: On first run,
```
system start
```
may prompt to install a Linux kernel. The agent should be aware of this initialization step.
Cleanup: To save resources when not in use, run
```
container system stop
```
.

与标准Docker Desktop不同，容器系统服务是显式管理的。

**启动：**在运行操作前，请务必先验证
```
container system status
```
。如果服务已停止，请运行
```
container system start
```
。
**内核：**首次运行时，
```
system start
```
可能会提示安装Linux内核。Agent需要注意这个初始化步骤。
**清理：**当不使用容器时，为节省资源，请运行
```
container system stop
```
。

2. Networking & Connectivity

2. 网络与连接

DNS: For stable service discovery, configure a local domain:

sudo container system dns create <domain>

(e.g.,

test

)

container system property set dns.domain <domain>

Access containers via
```
http://<container-name>.<domain>
```
.

Inter-Container: Containers are on a
```
vmnet
```
. Direct IP communication (
```
192.168.64.x
```
) works but can be fragile due to isolation.
Host Gateway Strategy (Reliable Fallback): If network plugins are missing or you encounter "No route to host":
1. Publish the service port to the host (e.g.,
```
-p 5432:5432
```
  ).
2. Connect from other containers using the Host Gateway IP (
```
192.168.64.1
```
  ).
3. Note: Disable SSL (
```
sslmode=disable
```
  ) if connection resets occur via the gateway.
Localhost: Port forwarding (
```
-p 8080:80
```
) works as expected for accessing containers from the host.

**DNS：**为实现稳定的服务发现，请配置本地域名：

sudo container system dns create <domain>

（例如：

test

）

container system property set dns.domain <domain>

通过
```
http://<container-name>.<domain>
```
访问容器。

**容器间通信：**容器位于
```
vmnet
```
网络中。直接IP通信（
```
192.168.64.x
```
）可行，但由于隔离机制可能不稳定。
**主机网关策略（可靠备选方案）：**如果缺少网络插件或遇到“无法访问主机”错误：
1. 将服务端口发布到主机（例如：
```
-p 5432:5432
```
  ）。
2. 使用主机网关IP（
```
192.168.64.1
```
  ）从其他容器连接。
3. *注意：*如果通过网关连接时出现重置问题，请禁用SSL（
```
sslmode=disable
```
  ）。
**本地主机：**端口转发（
```
-p 8080:80
```
）可按预期工作，用于从主机访问容器。

3. Data Persistence

3. 数据持久化

Volume Initialization: New volumes may contain a
```
lost+found
```
directory, which can cause "directory not empty" errors.
Best Practice: Always configure services (like PostgreSQL) to use a subdirectory within the volume.
- Example:
```
PGDATA=/var/lib/postgresql/data/pgdata
```
  instead of the root mount point.

**卷初始化：**新卷可能包含
```
lost+found
```
目录，这会导致“目录非空”错误。
最佳实践：始终配置服务（如PostgreSQL）使用卷内的子目录。
- *示例：*使用
```
PGDATA=/var/lib/postgresql/data/pgdata
```
  而非根挂载点。

4. Development Patterns

4. 开发模式

Git/SSH: Use the
```
--ssh
```
flag (
```
container run --ssh ...
```
) to forward the host's SSH agent. This is the preferred method for cloning private repositories inside containers.
Hot Reloading: Use
```
--volume
```
(e.g.,
```
-v $(pwd):/app
```
) to mount source code for immediate feedback, just like standard Docker.
Builder Tuning: The build process runs in its own VM. For large builds, explicitly scale the builder:
```
container builder start --cpus 4 --memory 8g
```
.

**Git/SSH：**使用
```
--ssh
```
标志（
```
container run --ssh ...
```
）转发主机的SSH代理。这是在容器内克隆私有仓库的首选方法。
**热重载：**使用
```
--volume
```
（例如：
```
-v $(pwd):/app
```
）挂载源代码以获得即时反馈，与标准Docker的用法一致。
**构建器调优：**构建过程在独立VM中运行。对于大型构建，请显式扩展构建器：
```
container builder start --cpus 4 --memory 8g
```
。

Critical Setup

关键设置

Before running containers, the system services usually need to be running.

Check Status:
```
container system status
```
Start Services:
```
container system start
```
(may require
```
sudo
```
if installing kernel/root components, but usually run as user)

在运行容器前，系统服务通常需要处于运行状态。

检查状态：
```
container system status
```
启动服务：
```
container system start
```
（如果安装内核/根组件可能需要
```
sudo
```
，但通常以普通用户身份运行即可）

Commands

命令

System Management

系统管理

container system start
: Starts the container services.

Options:

--enable-kernel-install

--disable-kernel-install

--app-root <path>

--install-root <path>

container system stop
: Stops the container services.
- Options:
```
--prefix <string>
```
  .
container system status
: Checks if services are running.
container system version
: Shows CLI and API server versions.

container system logs
: Displays system logs.

Options:
```
--follow
```
,
```
--last <time>
```
(e.g.,
```
5m
```
,
```
1h
```
).

container system df
: Shows disk usage.
container system dns create <domain>
: Creates a local DNS domain (requires sudo).
container system dns list
: Lists configured local DNS domains.
container system dns delete <domain>
: Deletes a local DNS domain (requires sudo).
container system property list
: Lists system properties (config).
container system property get <id>
: Gets a system property value.

container system property set <id> <value>
: Sets a system property.

Examples:

container system property set dns.domain my.local

container system property clear <id>
: Resets a system property to default.

container system kernel set
: Installs/updates the Linux kernel.

Options:

--recommended

--arch <arch>

--binary <path>

container system start
：启动容器服务。

选项：

--enable-kernel-install

--disable-kernel-install

--app-root <path>

--install-root <path>

。

container system stop
：停止容器服务。
- 选项：
```
--prefix <string>
```
  。
container system status
：检查服务是否运行。
container system version
：显示CLI和API服务器版本。
container system logs
：显示系统日志。
- 选项：
```
--follow
```
  ,
```
--last <time>
```
  （例如：
```
5m
```
  ,
```
1h
```
  ）。
container system df
：显示磁盘使用情况。
container system dns create <domain>
：创建本地DNS域名（需要sudo权限）。
container system dns list
：列出已配置的本地DNS域名。
container system dns delete <domain>
：删除本地DNS域名（需要sudo权限）。
container system property list
：列出系统属性（配置）。
container system property get <id>
：获取系统属性值。

container system property set <id> <value>
：设置系统属性。

示例：

container system property set dns.domain my.local

container system property clear <id>
：将系统属性重置为默认值。

container system kernel set
：安装/更新Linux内核。

选项：

--recommended

--arch <arch>

--binary <path>

。

Container Lifecycle

容器生命周期

container run [OPTIONS] IMAGE [COMMAND] [ARG...]
: Runs a command in a new container.
- Common Options:
  - ```
  -d, --detach
```
  : Run in background.
- ```
-i, --interactive
```
    : Keep STDIN open.
  - ```
  -t, --tty
```
  : Allocate a pseudo-TTY.
- ```
-p, --publish <host-port:container-port>
```
    : Publish a port.
  - ```
  -v, --volume <host-path:container-path>
```
  : Mount a volume.
- ```
--name <string>
```
    : Assign a name.
  - ```
  --rm
```
  : Remove after stop.
- ```
-e, --env <key=value>
```
    : Set environment variable.
  - ```
  -u, --user <user>
```
  : Set user (name|uid[:gid]).
- ```
-w, --workdir <dir>
```
    : Set working directory.
  - ```
  -c, --cpus <count>
```
  : CPU limit.
- ```
-m, --memory <size>
```
    : Memory limit (e.g.,
```
512M
```
    ,
```
2G
```
    ).
container create [OPTIONS] IMAGE [ARG...]
: Creates a container without starting it (same options as
```
run
```
).

container start [OPTIONS] CONTAINER...
: Starts stopped containers.

Options:
```
-a, --attach
```
,
```
-i, --interactive
```
.

container stop [OPTIONS] CONTAINER...
: Stops running containers.

Options:

-t, --time <seconds>

(wait before kill),

-s, --signal <signal>

container kill [OPTIONS] CONTAINER...
: Kills containers immediately.

Options:
```
-s, --signal <signal>
```
.

container delete [OPTIONS] CONTAINER...
: Deletes containers (aliases:
```
rm
```
).
- Options:
```
-f, --force
```
  (delete even if running).

container exec [OPTIONS] CONTAINER COMMAND [ARG...]
: Executes a command in a running container.

Options:
```
-it
```
,
```
-d
```
,
```
-w
```
,
```
-e
```
,
```
-u, --user
```
.

container list [OPTIONS]
: Lists containers (aliases:
```
ls
```
,
```
ps
```
).
- Options:
```
-a, --all
```
  (show stopped too),
```
-q
```
  (quiet, IDs only).
container inspect CONTAINER...
: JSON details of containers.

container logs [OPTIONS] CONTAINER
: Fetches container logs.

Options:
```
-f, --follow
```
,
```
--tail <n>
```
,
```
--boot
```
(show boot logs).

container stats
: Live stream of resource usage.
- Options:
```
--no-stream
```
  .

container run [OPTIONS] IMAGE [COMMAND] [ARG...]
：在新容器中运行命令。
- 常见选项：
  - ```
  -d, --detach
```
  ：在后台运行。
- ```
-i, --interactive
```
    ：保持STDIN打开。
  - ```
  -t, --tty
```
  ：分配伪终端。
- ```
-p, --publish <host-port:container-port>
```
    ：发布端口。
  - ```
  -v, --volume <host-path:container-path>
```
  ：挂载卷。
- ```
--name <string>
```
    ：分配名称。
  - ```
  --rm
```
  ：停止后自动删除容器。
- ```
-e, --env <key=value>
```
    ：设置环境变量。
  - ```
  -u, --user <user>
```
  ：设置用户（名称|uid[:gid]）。
- ```
-w, --workdir <dir>
```
    ：设置工作目录。
  - ```
  -c, --cpus <count>
```
  ：CPU限制。
- ```
-m, --memory <size>
```
    ：内存限制（例如：
```
512M
```
    ,
```
2G
```
    ）。
container create [OPTIONS] IMAGE [ARG...]
：创建容器但不启动（选项与
```
run
```
相同）。

container start [OPTIONS] CONTAINER...
：启动已停止的容器。

选项：
```
-a, --attach
```
,
```
-i, --interactive
```
。

container stop [OPTIONS] CONTAINER...
：停止运行中的容器。

选项：

-t, --time <seconds>

（终止前等待时间）,

-s, --signal <signal>

。

container kill [OPTIONS] CONTAINER...
：立即终止容器。

选项：
```
-s, --signal <signal>
```
。

container delete [OPTIONS] CONTAINER...
：删除容器（别名：
```
rm
```
）。
- 选项：
```
-f, --force
```
  （即使容器运行中也删除）。

container exec [OPTIONS] CONTAINER COMMAND [ARG...]
：在运行中的容器内执行命令。

选项：
```
-it
```
,
```
-d
```
,
```
-w
```
,
```
-e
```
,
```
-u, --user
```
。

container list [OPTIONS]
：列出容器（别名：
```
ls
```
,
```
ps
```
）。
- 选项：
```
-a, --all
```
  （同时显示已停止的容器）,
```
-q
```
  （仅显示ID）。
container inspect CONTAINER...
：查看容器的JSON详情。

container logs [OPTIONS] CONTAINER
：获取容器日志。

选项：
```
-f, --follow
```
,
```
--tail <n>
```
,
```
--boot
```
（显示启动日志）。

container stats
：实时流式显示资源使用情况。
- 选项：
```
--no-stream
```
  。

Image Management

镜像管理

container build [OPTIONS] PATH
: Builds an image from a Dockerfile.

Options:

-t <tag>

-f <dockerfile>

--build-arg <key=val>

--no-cache

-o, --output <type>

container image pull [OPTIONS] NAME[:TAG]
: Pulls an image from a registry.

Options:

--platform <os/arch>

--arch <arch>

--os <os>

container image push NAME[:TAG]
: Pushes an image.
container image list
: Lists local images (aliases:
```
ls
```
,
```
images
```
).
container image delete IMAGE...
: Deletes images (aliases:
```
rm
```
,
```
rmi
```
).
container image prune
: Removes unused images.
container image tag SOURCE TARGET
: Tags an image.
container image inspect IMAGE...
: JSON details of images.

container image save -o <path> IMAGE
: Saves image to tar.

Options:
```
--platform <os/arch>
```
.

container image load -i <path>
: Loads image from tar.

container build [OPTIONS] PATH
：从Dockerfile构建镜像。

选项：

-t <tag>

-f <dockerfile>

--build-arg <key=val>

--no-cache

-o, --output <type>

。

container image pull [OPTIONS] NAME[:TAG]
：从镜像仓库拉取镜像。

选项：

--platform <os/arch>

--arch <arch>

--os <os>

。

container image push NAME[:TAG]
：推送镜像到仓库。
container image list
：列出本地镜像（别名：
```
ls
```
,
```
images
```
）。
container image delete IMAGE...
：删除镜像（别名：
```
rm
```
,
```
rmi
```
）。
container image prune
：删除未使用的镜像。
container image tag SOURCE TARGET
：为镜像打标签。
container image inspect IMAGE...
：查看镜像的JSON详情。

container image save -o <path> IMAGE
：将镜像保存为tar文件。

选项：
```
--platform <os/arch>
```
。

container image load -i <path>
：从tar文件加载镜像。

Volume Management

卷管理

container volume create [OPTIONS] NAME
: Creates a volume.

Options:
```
-s, --size <size>
```
,
```
--label <key=val>
```
.

container volume list
: Lists volumes (aliases:
```
ls
```
).
container volume inspect NAME...
: JSON details.
container volume delete NAME...
: Deletes volumes (aliases:
```
rm
```
).
container volume prune
: Removes unused volumes.

container volume create [OPTIONS] NAME
：创建卷。

选项：
```
-s, --size <size>
```
,
```
--label <key=val>
```
。

container volume list
：列出卷（别名：
```
ls
```
）。
container volume inspect NAME...
：查看卷的JSON详情。
container volume delete NAME...
：删除卷（别名：
```
rm
```
）。
container volume prune
：删除未使用的卷。

Network Management

网络管理

container network create NAME
: Creates a network.

Options:

--subnet <cidr>

--subnet-v6 <cidr>

--label <key=val>

container network list
: Lists networks (aliases:
```
ls
```
).
container network inspect NAME...
: JSON details.
container network delete NAME...
: Deletes networks (aliases:
```
rm
```
).
container network prune
: Removes unused networks.

container network create NAME
：创建网络。

选项：

--subnet <cidr>

--subnet-v6 <cidr>

--label <key=val>

。

container network list
：列出网络（别名：
```
ls
```
）。
container network inspect NAME...
：查看网络的JSON详情。
container network delete NAME...
：删除网络（别名：
```
rm
```
）。
container network prune
：删除未使用的网络。

Registry & Builder

镜像仓库与构建器

container registry login SERVER
: Log in to a registry.

Options:

-u <username>

--password-stdin

--scheme <auto|https|http>

container registry logout SERVER
: Log out.
container builder status
: Check BuildKit builder status.

container builder start
: Start the builder manually.

Options:
```
--cpus <count>
```
,
```
--memory <size>
```
.

container builder stop
: Stops the builder.
container builder delete
: Deletes the builder.
container builder prune
: Clear builder cache.

container registry login SERVER
：登录镜像仓库。

选项：

-u <username>

--password-stdin

--scheme <auto|https|http>

。

container registry logout SERVER
：登出镜像仓库。
container builder status
：检查BuildKit构建器状态。

container builder start
：手动启动构建器。

选项：
```
--cpus <count>
```
,
```
--memory <size>
```
。

container builder stop
：停止构建器。
container builder delete
：删除构建器。
container builder prune
：清理构建器缓存。