文件

上传、下载、删除 guest 里的文件，监视目录的变化。示例使用 Go SDK、E2B SDK 与 kibo workspace file。程序经 /v1/files 传输文件内容，用 FilesystemService 管理目录，见用 API。

上传与下载复制标题链接

下面的例子先上传一个文件，再把它下载回来。Go 示例使用连接 ctrl 里的 client：

session, err := dataplane.Open(client, workspaceID, dataplane.WithScopes(
	ctrlv1.DataPlaneScope_DATA_PLANE_SCOPE_FILE_READ,
	ctrlv1.DataPlaneScope_DATA_PLANE_SCOPE_FILE_WRITE,
))
if err != nil {
	log.Fatal(err)
}
defer session.Close()

content := "hello\n"
if _, err := session.PutFile(ctx, "/data/report.txt", strings.NewReader(content), int64(len(content)), dataplane.PutOptions{}); err != nil {
	log.Fatal(err)
}

file, err := session.GetFile(ctx, "/data/report.txt", dataplane.FileOptions{})
if err != nil {
	log.Fatal(err)
}
defer file.Close()
data, err := io.ReadAll(file)

上传复制标题链接

kibo workspace file put 与 Go SDK 的 PutFile 在上传后核对大小与 SHA-256 摘要。下面的参数属于 kibo。

本地路径写 - 时，put 从标准输入读。下面的命令写入一个短文本文件：

echo hello | kibo workspace file put "$workspace_id" - /data/hello.txt

下载复制标题链接

get 先写到目标旁边的临时文件，收全后再替换目标。失败时目标不变。

• 下载目标的权限规则见写入下载的文件。
• 本地路径写 - 时，get 写到标准输出。

下面的命令显示 guest 里一个文件的前几行：

kibo workspace file get "$workspace_id" /data/report.txt - | head -n 20

大小与时限复制标题链接

• 上传的文件最多 1 GiB，更大的文件以 resource_exhausted 失败。下载不限大小：超过 1 GiB 的文件 kibo 分段读取，下载期间文件被改写时以完整性失败退出，本地目标不变。
• 每次传输最快 64 MiB/s。
• 上传与下载不受全局 --timeout 限制，传多久都可以。--timeout 只限制传输前发往 ctrl 的请求。
• 传输连续一分钟没有收发数据时以失败退出。

删除复制标题链接

delete 删除 guest 中的文件或目录，目录连同其中的内容一起删除。命令也可以写成 rm，-y（--yes）跳过确认：

kibo workspace file delete "$workspace_id" /data/report-copy.txt --yes

监视目录复制标题链接

watch 子命令逐行打印目录里条目的变化，直到按 Ctrl-C。下面的命令监视 Volume：

kibo workspace file watch "$workspace_id" /data

每行先写事件，再写条目的路径。--entry 同时打印每个条目的元数据。

• 只看一层：子目录自身的新建、删除、改名照常报告，子目录里的变化不报告。
• 相邻的相同变化可能只报一次。

遇到下列情况时，watch 以失败退出，此后的变化不再报告：

• 目录被删除或移走。
• Workspace 停止。
• 事件来不及送达。

guest 账号与路径复制标题链接

各子命令都可以用 --user 指定以哪个 guest 账号读写。远端路径可以写绝对路径，也可以写相对这个账号 home 目录的路径。规则见执行账号与工作目录。

用 API复制标题链接

文件内容经数据面的 HTTP 端点 /v1/files 传输，不走 RPC。目录与元数据由 FilesystemService 处理，监视目录用其中的 WatchDir。

• 程序需要 FILE_READ 或 FILE_WRITE 范围的数据面凭证，见申请会话凭证。kibo 自己申请所需的凭证。
• /v1/files 与 FilesystemService 请求里的路径可以相对执行账号的 home 目录。user 字段与路径的规则见执行账号与工作目录。
• 全部参数、响应头、状态码、方法与消息见 /v1/files 与 FilesystemService。

传输文件内容复制标题链接

/v1/files 与 RPC 在数据面的同一地址上，GET 读文件，PUT 写文件：

GET  <endpoint>/v1/files?path=/data/report.txt
PUT  <endpoint>/v1/files?path=/data/report.txt&mode=0644&create_only=true

查询参数 user、mode、create_only 与 kibo 的 --user、--mode、--create-only 作用相同。不认识的参数、重复的参数和不合法的取值返回 400（invalid_argument），请求不会到达 guest。

读文件：

• 一次响应最多 1 GiB。更大的文件分段读，每个请求带一段 Range: bytes=…。一个请求带多段时返回 400。
• 要确保各段来自文件的同一个版本，在 If-Range 里带上第一次响应的 ETag。文件已经变化时，请求返回整个文件而不是这一段；文件超过 1 GiB 时返回 413（resource_exhausted）。

写文件：

• 一次 PUT 的请求体最多 1 GiB，不能分段写入一个文件。
• PUT 返回 200 时，文件已经写入存储。响应体是 JSON：{"path": …, "size_bytes": …, "sha256": …}，调用方应核对大小与摘要。

下面两种写入失败不可重试，目标原有的文件都保持不变：

FilesystemService 的写操作遇到这两种情况返回同样的错误码。

每个请求最快 64 MiB/s。调用方 5 秒没有发送请求体或没有读取响应时，请求被中断；等 guest 的时间不计入。

错误响应带 Connect 错误码与 JSON 形式的 ErrorDetail，程序可以像处理 RPC 错误一样处理。

目录与元数据复制标题链接

持续掌握目录内容复制标题链接

WatchDir 报告一个目录里条目的变化，调用方不必轮询。要持续掌握目录的完整内容：

1. 调 WatchDir，等到第一条消息 started。
2. 用 ListDir 取全量。在 started 之前取，两者之间的变化可能既不在结果里，也没有事件。
3. 之后按事件更新。事件只说明哪个路径可能变了，要细节就 Stat，或在请求里设 include_entry。
4. 流以任何原因结束，从第 1 步重来。

started 之后、流结束之前，目录里的每一次变化至少产生一个事件；做不到时流以 resource_exhausted 结束。

事件类型与只看一层的规则与 kibo 相同，见监视目录。此外：

• path 是请求的目录加条目名。请求的目录是指向目录的符号链接时跟随。
• include_entry 让 CREATE、WRITE、CHMOD 带上条目的 EntryInfo，条目已经不在时不带。
• 每个 Workspace 最多 64 条监视流，超出时新的请求返回 resource_exhausted。
• 每条流每秒最多送出 1000 个事件，空闲时每 10 秒一条心跳。

流不会以成功结束，结束原因如下：

注意复制标题链接

• Workspace 的 guest 早于 v0.2.0 时，WatchDir 返回 failed_precondition（CAPABILITY_UNAVAILABLE）。重启 Workspace 后可用。
• Workspace 的 guest 早于 v0.3.0 时，文件请求只接受绝对路径，见工作目录与相对路径。

下一步复制标题链接

• 命令与终端：在 guest 里执行命令、打开终端。
• Volume 与导出恢复：独立于 Workspace 保存数据。
• kibo CLI 参考：全局参数与本地文件输出。
• API 概览：自己的程序需要的凭证与约定。