文件系统

文件系统 API 由 envd 的 filesystem.Filesystem Connect RPC 服务和 /files HTTP 接口共同提供，用于读取、写入、列目录、移动、删除文件以及监听目录变化。

调用前请先参考沙箱运行时 API获取 envd Endpoint 和 envdAccessToken。

Connect RPC 接口通过 Authorization: Basic <base64("user:")> 指定沙箱内文件操作用户。Go SDK 和 qshell 默认使用 user。请求体和响应体使用 protobuf JSON 字段名，也就是 lowerCamelCase。

Connect RPC 路径

方法	请求路径	类型	描述
Stat	/filesystem.Filesystem/Stat	Unary	获取文件或目录信息
ListDir	/filesystem.Filesystem/ListDir	Unary	列出目录内容
MakeDir	/filesystem.Filesystem/MakeDir	Unary	创建目录
Move	/filesystem.Filesystem/Move	Unary	移动或重命名文件、目录
Remove	/filesystem.Filesystem/Remove	Unary	删除文件或目录
WatchDir	/filesystem.Filesystem/WatchDir	Server streaming	监听目录变化
CreateWatcher	/filesystem.Filesystem/CreateWatcher	Unary	创建非流式目录监听器
GetWatcherEvents	/filesystem.Filesystem/GetWatcherEvents	Unary	拉取监听器事件
RemoveWatcher	/filesystem.Filesystem/RemoveWatcher	Unary	删除监听器

EntryInfo 字段

字段名称	字段类型	描述
name	string	文件名
type	string	文件类型，可取 FILE_TYPE_FILE、FILE_TYPE_DIRECTORY
path	string	完整路径
size	integer	文件大小，单位为字节
mode	integer	文件模式
permissions	string	权限字符串
owner	string	所有者
group	string	所属组
modifiedTime	string	最近修改时间
symlinkTarget	string	符号链接目标路径

获取文件信息

请求路径

POST /filesystem.Filesystem/Stat

请求参数

参数名称	参数类型	必填	描述
path	string	是	文件或目录路径

请求示例

curl -X POST "$ENVD_API_BASE/filesystem.Filesystem/Stat" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -H "Authorization: Basic dXNlcjo=" \
  -H "Connect-Protocol-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{"path": "/tmp/hello.txt"}'

列出目录

请求路径

POST /filesystem.Filesystem/ListDir

请求参数

参数名称	参数类型	必填	描述
path	string	是	目录路径
depth	integer	否	递归深度

响应字段

字段名称	字段类型	描述
entries	EntryInfo[]	目录内容

请求示例

curl -X POST "$ENVD_API_BASE/filesystem.Filesystem/ListDir" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -H "Authorization: Basic dXNlcjo=" \
  -H "Connect-Protocol-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{"path": "/tmp", "depth": 1}'

创建目录

请求路径

POST /filesystem.Filesystem/MakeDir

请求参数

参数名称	参数类型	必填	描述
path	string	是	目录路径

成功时返回创建后的 EntryInfo。

移动文件或目录

请求路径

POST /filesystem.Filesystem/Move

请求参数

参数名称	参数类型	必填	描述
source	string	是	源路径
destination	string	是	目标路径

成功时返回移动后的 EntryInfo。

删除文件或目录

请求路径

POST /filesystem.Filesystem/Remove

请求参数

参数名称	参数类型	必填	描述
path	string	是	文件或目录路径

成功时返回空对象。

监听目录变化

请求路径

POST /filesystem.Filesystem/WatchDir

请求参数

参数名称	参数类型	必填	描述
path	string	是	目录路径
recursive	boolean	否	是否递归监听子目录

事件类型

事件	描述
EVENT_TYPE_CREATE	文件或目录创建
EVENT_TYPE_WRITE	文件写入
EVENT_TYPE_REMOVE	文件或目录删除
EVENT_TYPE_RENAME	文件或目录重命名
EVENT_TYPE_CHMOD	权限变化

非流式目录监听

如果调用环境不方便消费流式响应，可以使用非流式监听器。

创建监听器

POST /filesystem.Filesystem/CreateWatcher

请求参数：

参数名称	参数类型	必填	描述
path	string	是	目录路径
recursive	boolean	否	是否递归监听

响应字段：

字段名称	字段类型	描述
watcherId	string	监听器 ID

拉取事件

POST /filesystem.Filesystem/GetWatcherEvents

请求参数：

参数名称	参数类型	必填	描述
watcherId	string	是	监听器 ID

删除监听器

POST /filesystem.Filesystem/RemoveWatcher

请求参数：

参数名称	参数类型	必填	描述
watcherId	string	是	监听器 ID

下载文件

请求路径

GET /files

请求参数

参数名称	参数类型	必填	描述
path	string	否	文件路径，需要 URL 编码；可以是相对用户 Home 的路径
username	string	否	用于解析相对路径的用户
signature	string	否	文件访问签名；使用 X-Access-Token 时不需要。Go SDK 默认生成签名 URL
signature_expiration	integer	否	签名过期时间，Unix 秒级时间戳

成功时返回 application/octet-stream 文件内容。

请求示例

curl -X GET "$ENVD_API_BASE/files?path=%2Ftmp%2Fhello.txt" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -o hello.txt

上传文件

请求路径

POST /files

请求参数

查询参数同下载文件。请求体使用 multipart/form-data，字段名为 file。

成功时返回写入后的 EntryInfo 数组。

请求示例

curl -X POST "$ENVD_API_BASE/files?path=%2Ftmp%2Fhello.txt" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -F "file=@hello.txt"

相关文档

• 沙箱运行时
• 进程与终端
• 文件管理