使用 qshell 执行沙箱命令

qshell sandbox exec 用于在已运行的沙箱中执行命令。它适合运行测试、安装依赖、启动服务、检查文件、读取环境信息以及在 CI 中执行一次性任务。

基本用法

命令格式:

qshell sandbox exec <sandbox-id> -- <command...>

示例:

qshell sandbox exec <sandbox-id> -- ls -la

使用别名:

qshell sbx ex <sandbox-id> -- ls -la

-- 后面的内容会作为远程命令传给沙箱。推荐始终保留 --,避免本地命令行参数和远程命令参数混淆。

前台执行

默认是前台执行。qshell 会实时输出 stdout/stderr,并等待命令结束:

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

运行测试:

qshell sandbox exec <sandbox-id> -- pytest -q

查看系统信息:

qshell sandbox exec <sandbox-id> -- uname -a

使用 shell 执行复杂命令

exec 的 -- 后面是远程进程参数,不是本地 shell 脚本。需要管道、重定向、通配符、变量展开或多条命令时,请显式使用 sh -lc:

qshell sandbox exec <sandbox-id> -- sh -lc 'cat /etc/os-release | head -5'

多条命令:

qshell sandbox exec <sandbox-id> -- sh -lc 'cd /app && npm install && npm test'

变量展开:

qshell sandbox exec <sandbox-id> -- sh -lc 'echo "HOME=$HOME"; pwd'

重定向:

qshell sandbox exec <sandbox-id> -- sh -lc 'python script.py > /tmp/output.log 2>&1'

工作目录

使用 --cwd 或 -c 指定命令工作目录:

qshell sandbox exec <sandbox-id> --cwd /app -- npm install

短写:

qshell sandbox exec <sandbox-id> -c /app -- npm test

如果目录不存在,命令会执行失败。排查时可以先查看目录:

qshell sandbox exec <sandbox-id> -- ls -la /

执行用户

使用 --user 或 -u 指定执行用户:

qshell sandbox exec <sandbox-id> --user root -- apt-get update

短写:

qshell sandbox exec <sandbox-id> -u root -- whoami

是否允许指定用户执行取决于模板内的用户配置。

环境变量

使用 --env 或 -e 为单次命令传入环境变量:

qshell sandbox exec <sandbox-id> \
  -e NODE_ENV=production \
  -e PORT=3000 \
  -- node app.js

这些变量只影响本次命令,不等同于创建沙箱时传入的全局环境变量。

配合 shell 使用:

qshell sandbox exec <sandbox-id> -e NAME=sandbox -- sh -lc 'echo "hello $NAME"'

后台运行

长时间运行的命令可以使用 --background 或 -b:

qshell sandbox exec <sandbox-id> --background -- python server.py

短写:

qshell sbx ex <sandbox-id> -b -- python server.py

后台模式会打印进程 PID 后立即返回。适合启动 Web 服务、后台 worker 或长时间任务。

启动服务后可以通过日志或后续命令检查状态:

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'

stdin 管道

qshell 支持从本地 stdin 向沙箱命令传入数据:

echo "hello sandbox" | qshell sandbox exec <sandbox-id> -- cat

统计本地文件行数:

cat ./data.txt | qshell sandbox exec <sandbox-id> -- wc -l

筛选内容:

printf "line1\nline2\nline3\n" | qshell sandbox exec <sandbox-id> -- grep line2

传输二进制数据时,建议在远端写入文件:

cat image.png | qshell sandbox exec <sandbox-id> -- sh -lc 'cat > /tmp/image.png'

前台任务和后台任务选择

场景	推荐模式
运行单次测试	前台执行
读取文件或系统信息	前台执行
启动服务	后台执行
执行长时间训练或构建	后台执行或前台配合日志
CI 中需要根据退出码判断成功失败	前台执行

CI 示例

创建沙箱、运行测试、清理资源:

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'

把测试结果写入沙箱文件:

qshell sandbox exec "${SANDBOX_ID}" -- sh -lc 'pytest -q > /tmp/pytest.log 2>&1'
qshell sandbox exec "${SANDBOX_ID}" -- cat /tmp/pytest.log

常见问题

本地管道没有在远端生效时,确认管道是在 qshell 前面:

echo "hello" | qshell sandbox exec <sandbox-id> -- cat

远端管道没有生效时,使用 sh -lc:

qshell sandbox exec <sandbox-id> -- sh -lc 'cat /etc/os-release | head -5'

命令找不到时,先检查 PATH:

qshell sandbox exec <sandbox-id> -- sh -lc 'echo $PATH; which python; which node'

工作目录不存在时,先列出目录:

qshell sandbox exec <sandbox-id> -- find / -maxdepth 2 -type d 2>/dev/null | head