实用工具qshell 命令行工具
正在加载文档
最近更新时间: 2026-09-11 17:43:27
qshell sandbox 是用于管理沙箱服务的命令行工具,适合在本地终端、脚本或 CI 流程中创建沙箱、执行命令、查看日志指标、管理模板和注入规则。
相比 SDK,qshell 更适合以下场景:
安装或编译 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.comQINIU_* 环境变量优先级高于 E2B_*。当前支持的沙箱区域如下:
| 区域 | 区域标识符 | API Endpoint |
|---|---|---|
| 中国（扬州1） | cn-yangzhou-1 | https://cn-yangzhou-1-sandbox.qiniuapi.com |
| 美国（达拉斯1） | us-south-1 | https://us-south-1-sandbox.qiniuapi.com |
Sandbox 命令使用独立 API Key,不依赖 qshell 对象存储命令中的 AK/SK 账号配置。只有在管理密钥注入规则或挂载 Kodo bucket 资源等需要七牛签名鉴权的场景下，才需要 qshell 当前账号或 QINIU_ACCESS_KEY / QINIU_SECRET_KEY。
qshell sandbox 的主命令结构如下:
qshell sandbox <子命令>
qshell sbx <子命令>完整命令和别名如下:
| 完整命令 | 别名 | 说明 |
|---|---|---|
sandbox | sbx | 沙箱命令入口 |
sandbox list | sbx ls | 列出运行中或已暂停的沙箱,支持状态、元数据和数量过滤 |
sandbox create | sbx cr | 创建沙箱,可进入交互式终端或使用后台模式 |
sandbox connect | sbx cn | 连接到已有沙箱终端 |
sandbox exec | sbx ex | 在沙箱中执行命令,支持前台、后台、stdin、工作目录、用户和环境变量 |
sandbox kill | sbx kl | 终止一个或多个沙箱,支持按状态和元数据批量清理 |
sandbox pause | sbx ps | 暂停一个或多个运行中的沙箱 |
sandbox resume | sbx rs | 恢复一个或多个已暂停的沙箱 |
sandbox logs | sbx lg | 查看沙箱日志,支持级别、logger、持续跟踪和 JSON 输出 |
sandbox metrics | sbx mt | 查看沙箱资源指标,支持持续跟踪和 JSON 输出 |
sandbox template | sbx tpl | 沙箱模板命令入口 |
sandbox template list | sbx tpl ls | 列出沙箱模板 |
sandbox template get | sbx tpl gt | 查看模板详情和构建记录 |
sandbox template delete | sbx tpl dl | 删除一个或多个模板,支持交互式选择 |
sandbox template build | sbx tpl bd | 创建并构建模板,或重新构建已有模板 |
sandbox template builds | sbx tpl bds | 查看指定模板构建的状态和日志 |
sandbox template publish | sbx tpl pb | 发布模板,将模板设为公开 |
sandbox template unpublish | sbx tpl upb | 取消发布模板,将模板设为私有 |
sandbox template init | sbx tpl it | 初始化模板项目脚手架 |
sandbox injection-rule | sbx ir | 密钥注入规则命令入口 |
sandbox injection-rule list | sbx ir ls | 列出注入规则 |
sandbox injection-rule get | sbx ir gt | 查看注入规则详情 |
sandbox injection-rule create | sbx ir cr | 创建注入规则 |
sandbox injection-rule update | sbx ir up | 更新注入规则 |
sandbox injection-rule delete | sbx ir dl | 删除一个或多个注入规则,支持交互式选择 |
查看帮助:
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=devqshell sandbox 的详细用法拆分为以下专题:
| 文档 | 内容 |
|---|---|
使用 qshell 管理沙箱实例 | 创建、连接、列出、暂停、恢复、终止沙箱 |
使用 qshell 执行沙箱命令 | 前台命令、后台命令、stdin、工作目录、用户和环境变量 |
使用 qshell 管理沙箱模板 | 模板初始化、构建、查询、发布、删除 |
使用 qshell 管理密钥注入 | 注入规则、内联注入、OpenAI/Anthropic/Gemini/Qiniu/GitHub/HTTP 配置 |
使用 qshell 排查沙箱问题 | 日志、指标、创建失败、连接失败、构建失败、资源清理 |
这篇文档有帮助吗？
正在加载反馈服务…