保证与边界

Kibotos 明确保证：数据在什么情况下保留、网络与隔离的边界在哪里、出了问题会看到什么，以及哪些接口承担兼容承诺。

数据复制标题链接

一个 Workspace 里的数据分三类，保留规则不同：

需要可靠保存的数据，写进 Volume 挂载目录。

• Volume 只在你删除它、或在删除 Workspace 时按绑定设置删除它。解绑或换绑下来的 Volume 不会被删除，数据原样保留，可以绑到别的 Workspace。
• 可写层Workspace 根文件系统的可写部分，保存安装的软件包这类修改；Operator 的页面称它为保留的可写层。可写层尽力保留，只有 Volume 保证保留数据。保存你在根文件系统上做的改动，例如安装的软件包。正常停止再启动时它会被继续使用；它的存储损坏或丢失时，Workspace 用全新的可写层启动，Workspace 信息里会报告这次重置及原因。不要把它当作唯一的副本。
• /tmp 与 /run 在每次启动时都是空的。内存与进程不跨启动保留，E2B 的暂停与恢复同样如此：恢复后文件按上表保留，进程需要重新启动。
• 宿主突然故障时，最后几秒写入、还没落到存储上的数据可能丢失，与普通电脑断电相同。
• 从 v0.3.0 起，部署方宣告某个存储池丢失时，放在其中的 Volume 变为 LOST，绑定它的 Workspace 无法启动；可写层会重置。

导出与恢复：导出只包含 Volume 里的文件，不包含可写层、内存与进程，.kibotos/credentials 与 .kibotos/browser-state 两个目录也不导出。恢复得到的是一个新的 Workspace，ID、labels 与 annotations 都要重新给出，会话与登录状态需要重新建立。归档默认保留 24 小时，单个归档默认不超过 1 GiB，两个值由部署方配置。见导出、导入与恢复与归档的保留。

Workspace 与 Template复制标题链接

• Workspace 创建时确定使用的 Template revision，之后不变。部署方发布新版本或更换默认 revision，只影响新建的 Workspace。
• 部署方撤回一个 revision 后，不能再用它新建 Workspace，但已经使用它的 Workspace 照常启动。
• 部署方可能在启动时为 Workspace 换上同一系列的新内核与运行环境，用于安全修复。Template 本身的内容不变。

网络复制标题链接

• 默认不能联网。 新建的 Workspace 没有任何出站访问，DNS 查询也被拒绝。需要联网时在创建时或之后修改网络策略，见网络策略。
  • 例外：用 E2B SDK 创建时，SDK 默认要求公网访问，见 E2B 兼容。
• 开放公网后，Workspace 可以发起 TCP 连接、ping 和 DNS 查询。其他 UDP 流量（例如 QUIC、NTP）不放行。
• 可以按目的地址细调：用 IP 或 CIDR 列出放行与拒绝的地址，两者合计最多 256 条。不支持按域名配置。
• 始终不可达，与网络策略无关：
  • 私有地址、运营商级 NAT 地址、回环与链路本地地址（包括云平台常用的元数据地址 169.254.169.254）、组播与保留地址，IPv4 与 IPv6 都是；
  • 宿主自身与部署方的管理网络；
  • 其他 Workspace。
• 调用方自带的出口除外：通过你配置的 Egress 离开的 TCP 连接由你的代理决定去向，可以到达你自己的内网。Egress 要求 v0.3.0 或更新版本。
• 入站：外部不能直接连到 Workspace。要从外部访问 Workspace 里的服务，使用端口转发、服务连接或公开 URL。
• 所有 Workspace 的出站流量以宿主的公网地址出去；需要固定出口地址时使用 Egress。

隔离复制标题链接

• 每个 Workspace 运行在自己的 MicroVM 里，有独立的内核、文件系统与网络。一个 Workspace 里的进程无法看到或访问另一个 Workspace。
• Workspace 里可以用 root 身份运行进程；root 权限只在这个 MicroVM 之内。
• 同一台宿主上的 Workspace 共用宿主的 CPU、内存与磁盘带宽。资源上限按创建或调整时设定的 CPU 与内存执行。

凭证与访问复制标题链接

• 访问数据面的凭证有效期短（默认 5 分钟，最长 15 分钟；绑定到一次执行的凭证最长 1 小时），只对一个 Workspace 的当前执行代有效。
• Workspace 停止或删除时，已经签发的凭证全部失效，打开的连接被断开。
• 需要立即切断所有现有访问而不停止 Workspace 时，撤销它的数据面访问，见原生 API 的 RevokeWorkspaceDataPlane。
• kibo 只在命令运行期间持有凭证，不写入磁盘。
• 公开 URL 不需要凭证，任何拿到地址的人都能访问，用完请撤销。

结果如实报告复制标题链接

• 不把未完成报成成功。 写操作要么完成，要么返回失败或「仍在处理」，不会在部分完成时返回成功。
• 失败带原因。 错误除了标准错误码，还带有原因、发生在哪个阶段、能否重试。例如资源不足时返回 resource_exhausted 并标为可重试。
• 结果不确定时如实说明。 宿主暂时联系不上时，Workspace 可能处于 UNKNOWN，相关命令保持「处理中」。用原来的幂等键重发或查询该命令，直到得到确定结果；不要换一个幂等键重新提交。
• 删除的清理进度可查询。 删除后，运行环境、Volume、可写层等各部分是否已经释放，可以逐项查到，见查看释放情况。

兼容承诺复制标题链接

承诺范围是外部应用直接调用的接口，从 v0.1.0 开始；更早的 v0.0.x 是预发布版本，没有兼容承诺。

不兼容变更留一个 MINOR 版本的过渡期。

• 被取代的字段或方法在引入新形态的那个版本里继续工作，并标记为 deprecated。
• 旧形态最早在下一个 MINOR 版本删除：vX.Y.0 引入的替代形态，旧形态最早在 vX.(Y+1).0 消失。
• PATCH 版本不删除任何东西。

新形态由一个新的能力名宣告。 过渡期内，新旧两个名字同时出现在 GetServerInfo 的能力列表里。判断服务端提供的是哪一种形态时，按能力名精确匹配，缺失时只让那一个操作失败，做法见先查询能力。不要按 source_revision 或版本号分支。

每一次不兼容变更都提前写在发布说明里。 CHANGELOG.md 中每个版本的「升级须知」写明改了什么、旧形态哪个版本删除、调用方要做什么、怎样判断自己是否受影响。升级前读这一节就够，GitHub Release 的正文与它是同一份文本。

不在承诺范围内的有：

• kibo 的参数与输出、部署配置格式、数据库 schema、发布物命名，以及 node 与 guest 之间的内部接口。它们随整套安装一起替换，连续性由重装与升级负责。
• Go SDK 的 Go API，包括其中的生成代码。它另有规则：v1 之前只在 MINOR 版本改变，见 Go SDK 的兼容性。

当前不提供复制标题链接

• 保存或恢复内存现场。
• 从 Workspace 打快照、从快照创建 Workspace，或复制出一个副本（fork）。
• 运行中的 Workspace 在宿主之间不中断地迁移。
• 按域名配置的网络策略。