进程与终端

进程与终端 API 由 envd 的 process.Process Connect RPC 服务提供，用于在沙箱内启动命令、连接已有进程、发送输入、调整 PTY 大小和终止进程。

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

如需指定沙箱内执行用户，可设置 Authorization: Basic <base64("user:")>。Go SDK 和 qshell 默认使用 user。请求体和响应体使用 protobuf JSON 字段名，也就是 lowerCamelCase。

Connect RPC 路径

方法	请求路径	类型	描述
List	/process.Process/List	Unary	列出运行中的进程
Start	/process.Process/Start	Server streaming	启动进程，并流式返回进程事件
Connect	/process.Process/Connect	Server streaming	连接到已有进程，并流式返回进程事件
Update	/process.Process/Update	Unary	更新进程配置，目前主要用于调整 PTY 大小
SendInput	/process.Process/SendInput	Unary	向进程发送 stdin 或 PTY 输入
StreamInput	/process.Process/StreamInput	Client streaming	以客户端流方式发送输入，保证输入顺序
SendSignal	/process.Process/SendSignal	Unary	向进程发送信号
CloseStdin	/process.Process/CloseStdin	Unary	关闭非 PTY 进程的 stdin

数据结构

ProcessConfig

字段名称	字段类型	描述
cmd	string	可执行命令
args	string[]	命令参数
envs	object	环境变量
cwd	string	工作目录

PTY

字段名称	字段类型	描述
size.cols	integer	终端列数
size.rows	integer	终端行数

ProcessSelector

通过 PID 或标签选择进程：

字段名称	字段类型	描述
pid	integer	进程 ID
tag	string	进程标签

ProcessEvent

Start 和 Connect 返回进程事件流：

事件	字段	描述
start	pid	进程已启动并分配 PID
data	stdout / stderr / pty	进程输出；JSON 协议中二进制字段按 base64 表示
end	exitCode / exited / status / error	进程结束事件
keepalive	无	保活事件

列出进程

请求路径

POST /process.Process/List

请求参数

请求体为空对象：

{}

响应字段

字段名称	字段类型	描述
processes[].config	object	进程启动配置
processes[].pid	integer	进程 ID
processes[].tag	string	进程标签

请求示例

curl -X POST "$ENVD_API_BASE/process.Process/List" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -H "Authorization: Basic dXNlcjo=" \
  -H "Connect-Protocol-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{}'

启动进程

请求路径

POST /process.Process/Start

请求参数

参数名称	参数类型	必填	描述
process	object	是	进程配置
pty	object	否	PTY 配置；传入后进程以伪终端方式运行
tag	string	否	进程标签
stdin	boolean	否	是否打开 stdin；兼容字段，默认行为由服务端决定

请求示例

启动普通命令：

curl -N -X POST "$ENVD_API_BASE/process.Process/Start" \
  -H "X-Access-Token: $ENVD_ACCESS_TOKEN" \
  -H "Authorization: Basic dXNlcjo=" \
  -H "Connect-Protocol-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "process": {
      "cmd": "bash",
      "args": ["-lc", "echo hello"]
    },
    "tag": "hello"
  }'

启动 PTY：

{
  "process": {
    "cmd": "bash",
    "args": ["-i", "-l"],
    "envs": {
      "TERM": "xterm"
    },
    "cwd": "/home/user"
  },
  "pty": {
    "size": {
      "cols": 80,
      "rows": 24
    }
  },
  "tag": "terminal"
}

连接已有进程

请求路径

POST /process.Process/Connect

请求参数

参数名称	参数类型	必填	描述
process.pid	integer	二选一	通过 PID 连接进程
process.tag	string	二选一	通过标签连接进程

请求示例

{
  "process": {
    "pid": 1234
  }
}

发送输入

请求路径

POST /process.Process/SendInput

请求参数

参数名称	参数类型	必填	描述
process	object	是	进程选择器
input.stdin	bytes	二选一	非 PTY 进程 stdin 输入
input.pty	bytes	二选一	PTY 输入

JSON 协议中，bytes 字段使用 base64 表示。

请求示例

{
  "process": {
    "tag": "terminal"
  },
  "input": {
    "pty": "ZWNobyBoZWxsbwo="
  }
}

调整 PTY 大小

请求路径

POST /process.Process/Update

请求参数

参数名称	参数类型	必填	描述
process	object	是	进程选择器
pty.size.cols	integer	否	新的终端列数
pty.size.rows	integer	否	新的终端行数

请求示例

{
  "process": {
    "tag": "terminal"
  },
  "pty": {
    "size": {
      "cols": 120,
      "rows": 40
    }
  }
}

发送信号

请求路径

POST /process.Process/SendSignal

请求参数

参数名称	参数类型	必填	描述
process	object	是	进程选择器
signal	string 或 integer	是	信号，可取 SIGNAL_SIGTERM（15）或 SIGNAL_SIGKILL（9）

关闭 stdin

请求路径

POST /process.Process/CloseStdin

请求参数

参数名称	参数类型	必填	描述
process	object	是	进程选择器

CloseStdin 仅适用于非 PTY 进程。PTY 场景请发送 Ctrl+D（0x04）表示 EOF。

相关文档

• 沙箱运行时
• 文件系统
• 命令执行
• PTY 终端