使用 qshell 排查沙箱问题

本文介绍如何使用 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,process

JSON 输出:

qshell sandbox logs <sandbox-id> --format json

日志排查适用于:

• 沙箱启动异常
• 进程执行失败
• 服务启动后无响应
• 注入规则未按预期生效
• envd 或进程管理相关问题

查看资源指标

查看当前资源使用:

qshell sandbox metrics <sandbox-id>

持续跟踪:

qshell sandbox metrics <sandbox-id> --follow

JSON 输出:

qshell sandbox metrics <sandbox-id> --format json

指标排查适用于:

• CPU 持续满载
• 内存不足
• 磁盘空间增长异常
• 长任务执行慢

API Key 问题

如果出现类似 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"

资源未释放

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

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、是否执行批量清理