核心概念

Template、Workspace 与 Volume 是每次使用 Kibotos 都会遇到的对象。本页介绍它们和其他对象、Workspace 的状态，以及控制面与数据面两条访问路径。

对象复制标题链接

flowchart LR
  T["Template<br/>revision"] -->|创建时确定| W[Workspace]
  W ---|绑定 0 或 1 个| V[Volume]
  W -.->|网络策略引用| E[Egress]
  W -.->|网络策略引用| R[Resolver]
  X[Exposure] -->|公开一个端口| W
  W -->|导出| TR[Transfer]
  TR -->|恢复为新的| W2[Workspace]

Template 与 revision复制标题链接

Template 是创建 Workspace 用的系统镜像，例如最小系统、编程工具链或桌面环境。

• 每次发布产生一个不可变的 revision，部署方为每个 Template 选定一个默认 revision（default revision）。
• 创建 Workspace 时可以只写 Template，由系统选当前的默认 revision；也可以指定 revision。
• 选定后不再改变：部署方之后发布新版本、改了默认 revision，已经存在的 Workspace 不跟着换。

Workspace复制标题链接

Workspace 是 Agent 工作的环境，每个 Workspace 运行在自己的 MicroVM 里。

• 创建后 ID 不变。
• 每次成功启动是一次新的运行，称为执行代（generation），从 1 开始递增。停止后，这一次运行的凭证、进程和连接全部失效，下次启动要重新申请凭证。
• 属性有 CPU、内存、可写层大小、到期时间、网络策略、labels 与 annotations。可写层（writable layer）是根文件系统上可写的部分，保留规则见保证与边界。
• Volume 与可写层存放在部署方的存储池里。每次启动时，系统选一台能访问这些存储池的宿主运行它，可能与上次不是同一台。

Volume复制标题链接

Volume 是独立于 Workspace 的持久卷。

• 创建 Workspace 时默认同时创建一个独占的 Volume，挂在 /data；也可以绑定已有的 Volume，或不要 Volume。
• 一个 Workspace 最多绑定一个 Volume，一个 Volume 同时只属于一个 Workspace。Workspace 停止后可以换绑或解绑，下次启动时生效。
• 默认创建的 Volume 随 Workspace 一起删除，绑定的已有 Volume 默认保留，都可以在绑定时改。数据在什么情况下保留见保证与边界。

其他对象复制标题链接

Workspace 的状态复制标题链接

stateDiagram-v2
  CREATING --> AVAILABLE
  AVAILABLE --> STOPPING: 停止 / 到期
  STOPPING --> STOPPED
  STOPPED --> STARTING: 启动
  STARTING --> AVAILABLE
  AVAILABLE --> FAILED: 出错
  FAILED --> STOPPED: 强制停止
  STOPPED --> DELETING: 删除
  DELETING --> DELETED

图中只画了主干：

• 除 DELETING 与 DELETED 外，任何状态都可以直接删除。
• 创建和启动过程中出错也会进入 FAILED。
• guest 是否在回应（RESPONDING 或 UNRESPONSIVE）单独报告，不改变状态。

每个状态下能做哪些操作、FAILED 怎样恢复，见各状态下能做的操作与从 FAILED 恢复。

控制面与数据面复制标题链接

访问 Kibotos 有两条路：

文件和进程的流量不经过 ctrl，所以大文件和长时间的输出不受控制面的负载影响。代价是多一步申请凭证，并在 Workspace 重新启动后重新申请；kibo 和 E2B 网关会自动完成这一步。请求怎样流动见架构。

写操作的约定复制标题链接

具体字段与错误码见原生 API 的写操作的约定。