使用 qshell 管理沙箱实例

本文介绍如何通过 qshell sandbox 创建、列出、连接、暂停、恢复和终止沙箱实例。使用前请先完成 qshell 命令行工具的认证配置。

创建沙箱

最简单的创建方式是传入模板 ID:

qshell sandbox create <template-id>

命令会等待沙箱启动完成,然后进入交互式终端。终端会话结束后,qshell 会自动终止本次创建的沙箱,适合临时调试。

使用别名:

qshell sbx cr <template-id>

后台创建

如果希望创建沙箱后让它继续运行,不要立即进入终端,使用 --detach:

qshell sandbox create <template-id> --detach

建议同时设置超时时间:

qshell sandbox create <template-id> --timeout 300 --detach

后台创建成功后,命令会输出类似信息:

Sandbox ID:   sb-xxxxxxxxxxxx
Template ID:  tmpl-xxxxxxxxxxxx

Connect:  qshell sandbox connect sb-xxxxxxxxxxxx
Exec:     qshell sandbox exec sb-xxxxxxxxxxxx -- <command>
Kill:     qshell sandbox kill sb-xxxxxxxxxxxx

后续所有操作都使用 Sandbox ID。

超时时间

--timeout 用于指定沙箱超时时间,单位为秒:

qshell sandbox create <template-id> --timeout 600 --detach

交互式终端连接期间,qshell 会通过 keep-alive 机制保持沙箱存活。后台模式下,沙箱会按服务端超时策略自动结束。

自动暂停

默认情况下,沙箱超时后会被终止。使用 --auto-pause 可以让沙箱到期后进入暂停状态:

qshell sandbox create <template-id> --timeout 300 --auto-pause --detach

暂停状态会保留文件系统和运行状态,后续可以恢复。这个选项适合需要保留调试现场的场景。

环境变量

创建沙箱时可以传入环境变量:

qshell sandbox create <template-id> \
  -e NODE_ENV=development \
  -e PORT=3000 \
  --detach

-e 是 --env-var 的短写,可以重复指定。传入的环境变量会成为沙箱环境的一部分。

元数据

元数据用于标记沙箱,便于后续查询和批量清理:

qshell sandbox create <template-id> --detach -m app=demo,env=dev,owner=alice

元数据格式为逗号分隔的键值对:

key1=value1,key2=value2

建议在调试、CI 和批量任务中都添加元数据,例如:

qshell sandbox create <template-id> --detach -m app=ci,repo=my-service,run=12345

列出沙箱

默认只列出运行中的沙箱:

qshell sandbox list

使用别名:

qshell sbx ls

列出运行中和已暂停的沙箱:

qshell sandbox list --state running,paused

限制返回数量:

qshell sandbox list --limit 20

按元数据过滤:

qshell sandbox list -m app=demo,env=dev

输出 JSON:

qshell sandbox list --format json

JSON 输出适合脚本处理:

qshell sandbox list --format json | jq '.[].sandboxID'

连接沙箱

连接到已有沙箱终端:

qshell sandbox connect <sandbox-id>

使用别名:

qshell sbx cn <sandbox-id>

connect 不会在终端退出后自动终止沙箱。它只负责连接到已经存在的沙箱,适合恢复调试会话。

暂停沙箱

暂停单个沙箱:

qshell sandbox pause <sandbox-id>

暂停多个沙箱:

qshell sandbox pause sb-aaa sb-bbb sb-ccc

暂停所有运行中的沙箱:

qshell sandbox pause --all

按元数据暂停:

qshell sandbox pause --all -m app=demo

恢复沙箱

恢复单个沙箱:

qshell sandbox resume <sandbox-id>

恢复多个沙箱:

qshell sandbox resume sb-aaa sb-bbb

恢复所有已暂停的沙箱:

qshell sandbox resume --all

按元数据恢复:

qshell sandbox resume --all -m app=demo

终止沙箱

终止单个沙箱:

qshell sandbox kill <sandbox-id>

终止多个沙箱:

qshell sandbox kill sb-aaa sb-bbb sb-ccc

终止所有运行中的沙箱:

qshell sandbox kill --all

终止运行中和已暂停的沙箱:

qshell sandbox kill --all --state running,paused

按元数据清理:

qshell sandbox kill --all --state running,paused -m app=demo,env=dev

脚本化示例

创建沙箱、执行测试并清理:

set -e

SANDBOX_ID="$(qshell sandbox create <template-id> --timeout 300 --detach -m app=ci | awk '/Sandbox ID:/ {print $3}')"

cleanup() {
  qshell sandbox kill "${SANDBOX_ID}" || true
}
trap cleanup EXIT

qshell sandbox exec "${SANDBOX_ID}" -- sh -lc 'pytest -q'

批量清理某个 CI run 创建的沙箱:

qshell sandbox kill --all --state running,paused -m app=ci,run=12345

使用建议

• 本地临时调试可以直接使用 create <template-id> 进入终端。
• 脚本和 CI 建议使用 --detach 并显式 kill。
• 所有自动化创建的沙箱都建议添加 metadata,便于后续批量清理。
• 长时间调试可以使用 --auto-pause,避免超时后现场丢失。
• 批量操作前先用相同过滤条件执行 sandbox list,确认匹配范围。