qshell 命令行工具

qshell sandbox 是用于管理沙箱服务的命令行工具,适合在本地终端、脚本或 CI 流程中创建沙箱、执行命令、查看日志指标、管理模板和注入规则。

相比 SDK,qshell 更适合以下场景:

• 在终端中快速创建沙箱并进入交互式环境
• 在 CI 中创建一次性沙箱执行测试或构建
• 排查线上沙箱的日志、指标和生命周期状态
• 通过脚本批量清理沙箱或模板
• 不编写业务代码,直接验证模板、注入规则和命令执行效果

安装和认证

安装或编译 qshell 后,先配置沙箱服务的 API Key 和服务地址:

export QINIU_API_KEY=sk_***
export QINIU_SANDBOX_API_URL=https://cn-yangzhou-1-sandbox.qiniuapi.com

也可以使用兼容 E2B 的环境变量:

export E2B_API_KEY=sk_***
export E2B_API_URL=https://cn-yangzhou-1-sandbox.qiniuapi.com

QINIU_* 环境变量优先级高于 E2B_*。当前支持的沙箱区域如下:

Sandbox 命令使用独立 API Key,不依赖 qshell 对象存储命令中的 AK/SK 账号配置。只有在管理密钥注入规则或挂载 Kodo bucket 资源等需要七牛签名鉴权的场景下，才需要 qshell 当前账号或 QINIU_ACCESS_KEY / QINIU_SECRET_KEY。

命令和别名

qshell sandbox 的主命令结构如下:

qshell sandbox <子命令>
qshell sbx <子命令>

完整命令和别名如下:

查看帮助:

qshell sandbox -h
qshell sandbox --doc
qshell sandbox create --doc
qshell sandbox template build --doc

快速开始

列出可用模板:

qshell sandbox template list

创建沙箱并进入交互式终端:

qshell sandbox create <template-id>

使用短别名:

qshell sbx cr <template-id>

交互式终端退出后,qshell 会自动终止本次创建的沙箱。如果希望创建后不进入终端,使用 --detach:

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

命令会输出沙箱 ID,后续可以用这个 ID 连接、执行命令或清理资源:

qshell sandbox exec <sandbox-id> -- python --version
qshell sandbox logs <sandbox-id>
qshell sandbox kill <sandbox-id>

推荐工作流

本地调试模板:

qshell sandbox template build --name demo --dockerfile ./Dockerfile --wait
qshell sandbox create <template-id> --timeout 600 --detach -m app=demo,env=dev
qshell sandbox exec <sandbox-id> -- sh -lc 'python --version && pwd'
qshell sandbox logs <sandbox-id> --follow
qshell sandbox kill <sandbox-id>

CI 中运行测试:

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

按元数据清理调试资源:

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

专题文档

qshell sandbox 的详细用法拆分为以下专题: