实用工具qshell 命令行工具
正在加载文档
最近更新时间: 2026-09-11 17:43:28
本文介绍如何通过 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> \
--injection-rule <openai-rule-id> \
--injection-rule <http-rule-id> \
--detach也可以直接传入内联注入配置:
qshell sandbox create <template-id> \
--inline-injection 'type=openai,api-key=sk-xxx' \
--inline-injection 'type=http,base-url=https://api.example.com,headers=Authorization=Bearer token;X-Env=prod,if-headers=X-Scope=demo,if-queries=inject=true' \
--detach内联注入的 type 支持 openai、anthropic、gemini、qiniu、github 和 http。api-key 用于 AI 服务 API Key，也用于 type=github 的 GitHub Token；headers 仅用于 type=http，多个 Header 使用分号分隔。if-headers 和 if-queries 用于设置匹配条件，只有请求中已存在对应 Header 或 query 参数且值精确匹配时才注入。
GitHub 凭证注入示例:
qshell sandbox create <template-id> \
--inline-injection 'type=github,api-key=ghp-xxx,base-url=https://api.github.com/repos/qiniu/*' \
--detach创建沙箱时可以通过 --resource 在启动前挂载 GitHub 仓库或 Kodo bucket:
qshell sandbox create <template-id> \
--resource 'type=github_repository,url=https://github.com/owner/repo.git,mount-path=/workspace/repo,token=ghp-xxx' \
--detachqshell sandbox create <template-id> \
--resource 'type=kodo,bucket=my-bucket,mount-path=/mnt/kodo,prefix=datasets/,read-only=true' \
--detachGitHub 仓库资源中的 token 由平台用于拉取仓库快照，并会自动派生运行时 GitHub 注入；这时不要再额外传入 --inline-injection type=github。Kodo bucket 资源需要 qshell 能获取七牛 AK/SK 凭据，优先使用 qshell user 当前账号，环境变量 QINIU_ACCESS_KEY / QINIU_SECRET_KEY 作为兜底。
元数据用于标记沙箱,便于后续查询和批量清理:
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 jsonJSON 输出适合脚本处理:
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=12345create <template-id> 进入终端。--detach 并显式 kill。metadata,便于后续批量清理。--auto-pause,避免超时后现场丢失。sandbox list,确认匹配范围。这篇文档有帮助吗？
正在加载反馈服务…