实用工具qshell 命令行工具
正在加载文档
最近更新时间: 2026-09-11 17:43:33
本文介绍如何使用 qshell 排查沙箱创建失败、连接失败、命令执行失败、模板构建失败、日志异常和资源未释放等问题。
排查任何问题前,先确认沙箱是否存在以及处于什么状态:
qshell sandbox list --state running,paused按元数据过滤:
qshell sandbox list --state running,paused -m app=demo输出 JSON 便于脚本检查:
qshell sandbox list --state running,paused --format json查看默认日志:
qshell sandbox logs <sandbox-id>查看更低级别日志:
qshell sandbox logs <sandbox-id> --level DEBUG只看错误:
qshell sandbox logs <sandbox-id> --level ERROR持续跟踪日志:
qshell sandbox logs <sandbox-id> --follow按 logger 过滤:
qshell sandbox logs <sandbox-id> --loggers envd,processJSON 输出:
qshell sandbox logs <sandbox-id> --format json日志排查适用于:
查看当前资源使用:
qshell sandbox metrics <sandbox-id>持续跟踪:
qshell sandbox metrics <sandbox-id> --followJSON 输出:
qshell sandbox metrics <sandbox-id> --format json指标排查适用于:
如果出现类似 API key is required 的错误,检查环境变量:
env | grep -E 'QINIU_API_KEY|QINIU_SANDBOX_API_URL|E2B_API_KEY|E2B_API_URL'推荐配置:
export QINIU_API_KEY=sk_***
export QINIU_SANDBOX_API_URL=https://cn-yangzhou-1-sandbox.qiniuapi.com如果同时设置了 QINIU_* 和 E2B_*,qshell 会优先使用 QINIU_*。
先确认模板是否存在:
qshell sandbox template get <template-id>确认模板构建完成后再创建:
qshell sandbox create <template-id> --timeout 300 --detach如果模板正在构建或构建失败,查看构建状态:
qshell sandbox template builds <template-id> <build-id>创建时添加元数据,便于后续定位:
qshell sandbox create <template-id> --detach -m app=debug,case=create-failed确认沙箱仍在运行或暂停:
qshell sandbox list --state running,paused如果沙箱已暂停,先恢复:
qshell sandbox resume <sandbox-id>然后重新连接:
qshell sandbox connect <sandbox-id>如果沙箱已经被终止,需要重新创建。
先执行简单命令确认基础执行链路:
qshell sandbox exec <sandbox-id> -- echo ok检查当前用户、目录和 PATH:
qshell sandbox exec <sandbox-id> -- sh -lc 'whoami; pwd; echo $PATH'检查命令是否存在:
qshell sandbox exec <sandbox-id> -- sh -lc 'which python; which node; which npm'需要管道、重定向或多条命令时,使用 sh -lc:
qshell sandbox exec <sandbox-id> -- sh -lc 'cd /app && npm test > /tmp/test.log 2>&1'再查看输出:
qshell sandbox exec <sandbox-id> -- cat /tmp/test.log后台启动服务:
qshell sandbox exec <sandbox-id> -b -- sh -lc 'python -m http.server 8000'检查进程:
qshell sandbox exec <sandbox-id> -- sh -lc 'ps aux | grep http.server'检查端口:
qshell sandbox exec <sandbox-id> -- sh -lc 'ss -lntp || netstat -lntp'查看日志:
qshell sandbox logs <sandbox-id> --follow使用 --wait 构建可以直接看到构建日志:
qshell sandbox template build --name my-app --dockerfile ./Dockerfile --wait重新构建并忽略缓存:
qshell sandbox template build --template-id <template-id> --dockerfile ./Dockerfile --no-cache --wait常见检查点:
Dockerfile 路径是否正确--path 是否包含 COPY 需要的文件RUN 命令是否依赖外网start-cmd 和 ready-cmd 是否能在模板环境中执行确认注入规则存在:
qshell sandbox injection-rule get <rule-id>创建沙箱时引用规则:
qshell sandbox create <template-id> --detach --injection-rule <rule-id>临时验证可以使用内联注入:
qshell sandbox create <template-id> --detach --inline-injection 'type=openai,api-key=sk-xxx'如果是自定义 HTTP 注入,确认 base-url 和 headers 写法:
qshell sandbox injection-rule create \
--name api-auth \
--type http \
--base-url https://api.example.com \
--headers "Authorization=Bearer token,X-Env=dev"如果注入只应该命中特定请求,确认 --if-headers / --if-queries 与沙箱内实际请求完全一致:
qshell sandbox injection-rule create \
--name api-auth-scoped \
--type http \
--base-url https://api.example.com/v1/* \
--headers "Authorization=Bearer token" \
--if-headers "X-Scope=prod" \
--if-queries "inject=true"如果是 GitHub 注入,--api-key 传入的是 GitHub Token；--base-url 只能使用 github.com 或 api.github.com:
qshell sandbox injection-rule create \
--name github-api \
--type github \
--api-key ghp-xxx \
--base-url https://api.github.com/repos/qiniu/*列出运行中和已暂停的沙箱:
qshell sandbox list --state running,paused按元数据清理:
qshell sandbox kill --all --state running,paused -m app=demo如果自动化脚本会创建沙箱,建议始终设置 trap:
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| 问题 | 优先检查 |
|---|---|
| 认证失败 | QINIU_API_KEY / E2B_API_KEY 是否设置 |
| 请求到错环境 | QINIU_SANDBOX_API_URL / E2B_API_URL 是否正确 |
| 创建失败 | 模板是否存在、构建是否完成 |
| 连接失败 | 沙箱是否仍在 running 或 paused |
| 命令失败 | 是否需要 sh -lc、工作目录是否存在、命令是否安装 |
| 服务无响应 | 后台进程是否存在、端口是否监听、日志是否报错 |
| 构建失败 | Dockerfile、构建上下文、基础镜像、网络访问 |
| 资源泄漏 | 是否设置 metadata、是否执行批量清理 |
这篇文档有帮助吗？
正在加载反馈服务…