Docker 式 CLI

定义

Docker 式 CLI 指一类命令行接口：它沿用 Docker 已经普及的子命令（run、ps、logs、exec、stop、rm、pull、build 等）、常用短选项（-d、-p、-v、--rm、--name）以及「镜像 → 容器 → 卷 / 网络」的对象模型。A3S Box 的 a3s-box 属于这一类接口。它在命令外观上接近 Docker，但在隔离默认值、失败策略与产品边界上并不复制 Docker。

问题背景

容器产品的核心对象并不多，但若每个实现都发明一套动词，使用者就无法把已有经验迁移过来。Docker 在 2013 年之后成为教学与脚本中的共同语言。后来的 runtime 若希望被当作「本地容器产品」使用，通常选择兼容这套语言，而不是要求使用者先学习新的术语表。

兼容的是操作语言，不是 Docker 守护进程的全部行为。Box 明确拒绝「接受未知选项并在背后削弱」的做法：不支持的控制必须在产生副作用之前失败。

机制说明

一组最小工作流

下列命令构成一条完整的本地工作流。读懂它们，即读懂第一层的大部分概念。

a3s-box pull alpine:3.20
a3s-box run -d --name web --memory 1g -p 8080:80 nginx:alpine
a3s-box ps
a3s-box logs -f web
a3s-box exec web -- nginx -v
a3s-box stop web
a3s-box rm web

各参数的含义：

片段	含义
run	创建并启动一个工作负载
-d	分离（detach）：命令返回后工作负载继续运行
--name web	人类可读名称，后续命令用该名称引用
--memory 1g	内存上限，最终落到 cgroup 或客户机内存配置
-p 8080:80	把宿主 TCP 8080 发布到工作负载内的 80
nginx:alpine	镜像引用
-- nginx -v	覆盖镜像默认命令；-- 分隔 Box 参数与客户机参数

一次性任务常用 --rm：进程退出后自动删除记录与临时资源，避免留下停止态的 box。

命令与对象域

Docker 式 CLI 把对象分成几组。Box 的 src/cli/src/commands/ 基本按同一分组落文件。

对象域	典型命令
生命周期	run、create、start、stop、restart、rm、kill、pause、wait
交互	exec、attach、logs、top
镜像	pull、build、images、rmi、tag、save、load
存储	volume、cp、diff、export、commit、snapshot
网络	network、port、compose
系统	ps、inspect、stats、events、info、version

create 与 run 的差别在于是否立即 start。run 等价于创建之后启动；失败时的清理语义由 --rm 与重启策略共同决定。

Box 相对 Docker 的刻意差异

1. 隔离默认值。 省略 --isolation 表示 MicroVM。--isolation sandbox 才是共享内核。显式 --isolation microvm 被拒绝，以避免脚本把后端名称当成可互换模式。
2. 失败即关闭。 不支持的网络、设备或隔离组合在预检阶段失败，不会写入一个「看起来成功、实际被削弱」的记录。
3. 产品扩展。 snapshot、pool、attest、seal、scale-api 不属于经典 Docker 集合，但仍然挂在同一二进制下。

在 Box 中的位置

• CLI crate 为 src/cli/，入口 src/cli/src/main.rs，子命令目录 src/cli/src/commands/。
• run 的主函数是 commands/run.rs 中的 execute，随后进入 run/setup.rs 准备镜像与 LocalExecutionManager。
• Python、TypeScript 与 Go SDK 不解析 CLI 的人类可读输出，而是通过 machine bridge 交换结构化消息。CLI 与 SDK 共享同一套本地状态，但传输格式不同。

验证命令

a3s-box --version
a3s-box info
a3s-box run --rm alpine:3.20 -- echo ok

info 报告当前主机的虚拟化、网络与 OCI 能力。它是判断后续命令会走 MicroVM 还是因能力不足而失败的第一步。

相关与易混

• 相关：容器、Compose、一条 run 命令的调用链
• 易混：「命令长得像 Docker」不等于「实现等于 Docker」。尤其不可把 Docker 的默认共享内核隔离，误当成 Box 省略 --isolation 时的行为。