使用 qshell 管理沙箱模板

沙箱模板用于定义沙箱的基础环境,包括基础镜像、依赖包、文件、启动命令和资源配置。qshell sandbox template 可以完成模板初始化、构建、查询、发布和删除。

命令概览

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

常用子命令:

命令	说明
template init	初始化模板项目脚手架
template list	列出模板
template get	查看模板详情
template build	创建并构建模板,或重新构建已有模板
template builds	查看模板构建状态
template publish	发布模板
template unpublish	取消发布模板
template delete	删除模板

初始化模板项目

交互式初始化:

qshell sandbox template init

非交互方式初始化 Python 模板:

qshell sandbox template init --name my-python-template --language python --path ./my-python-template

初始化 Go 模板:

qshell sandbox template init --name my-go-template --language go

初始化 TypeScript 模板:

qshell sandbox template init --name my-ts-template --language typescript

支持的语言:

语言	生成文件
python	template.py, requirements.txt
go	main.go, go.mod, Makefile
typescript	template.ts, package.json

从 Docker 镜像构建

从公共镜像构建:

qshell sandbox template build --name python-demo --from-image python:3.11 --wait

国内网络环境建议使用镜像代理地址:

qshell sandbox template build \
  --name python-demo \
  --from-image crp-internal.qiniucs.com/registry-1.docker.io/library/python:3 \
  --wait

指定资源:

qshell sandbox template build \
  --name python-demo \
  --from-image crp-internal.qiniucs.com/registry-1.docker.io/library/python:3 \
  --cpu 2 \
  --memory 2048 \
  --wait

从 Dockerfile 构建

使用当前目录下的 Dockerfile:

qshell sandbox template build --name my-app --dockerfile ./Dockerfile --wait

指定构建上下文:

qshell sandbox template build --name my-app --dockerfile ./docker/Dockerfile --path ./src --wait

Dockerfile 模式会解析 FROM、RUN、COPY 等指令,并上传构建上下文中需要的文件。

带启动命令和就绪命令:

qshell sandbox template build \
  --name my-service \
  --dockerfile ./Dockerfile \
  --start-cmd "python server.py" \
  --ready-cmd "curl -f http://localhost:8000/health" \
  --wait

基于已有模板构建

可以使用已有模板作为基础模板:

qshell sandbox template build --name my-derived-template --from-template <base-template-id> --wait

这个方式适合在一个稳定基础环境上继续叠加依赖或文件。

重新构建已有模板

重新构建已有模板时使用 --template-id:

qshell sandbox template build --template-id <template-id> --dockerfile ./Dockerfile --wait

忽略缓存强制完整构建:

qshell sandbox template build --template-id <template-id> --dockerfile ./Dockerfile --no-cache --wait

如果只是调整 Dockerfile 或依赖版本,建议使用 --no-cache 确认构建结果。

等待构建和查看状态

--wait 会等待构建完成并流式输出构建日志:

qshell sandbox template build --name my-app --dockerfile ./Dockerfile --wait

不使用 --wait 时,构建命令会返回模板 ID 和构建 ID。之后可以查看状态:

qshell sandbox template builds <template-id> <build-id>

查看模板

列出模板:

qshell sandbox template list

JSON 输出:

qshell sandbox template list --format json

查看模板详情:

qshell sandbox template get <template-id>

模板详情通常用于确认构建状态、资源配置、公开状态和历史构建记录。

发布和取消发布

发布模板:

qshell sandbox template publish <template-id> -y

取消发布:

qshell sandbox template unpublish <template-id> -y

也可以一次处理多个模板:

qshell sandbox template publish tmpl-aaa tmpl-bbb -y
qshell sandbox template unpublish tmpl-aaa tmpl-bbb -y

删除模板

删除单个模板:

qshell sandbox template delete <template-id> -y

删除多个模板:

qshell sandbox template delete tmpl-aaa tmpl-bbb -y

交互式选择删除:

qshell sandbox template delete --select

构建参数参考

参数	说明
--name	创建新模板时使用的模板名称
--template-id	重新构建已有模板时使用的模板 ID
--from-image	基础 Docker 镜像
--from-template	基础沙箱模板
--dockerfile	Dockerfile 路径
--path	Dockerfile 构建上下文目录
--start-cmd	沙箱启动命令
--ready-cmd	就绪检查命令
--cpu	CPU 核数
--memory	内存大小,单位 MiB
--wait	等待构建完成并显示日志
--no-cache	忽略缓存,强制完整构建

使用建议

• 模板名称建议包含业务或团队前缀,避免和其他模板冲突。
• Docker Hub 官方镜像在国内环境建议使用镜像代理地址。
• 构建调试阶段使用 --wait,便于直接查看失败原因。
• 自动化流程中保留 template-id 和 build-id,便于后续查询构建状态。
• 删除模板前先确认没有业务流程依赖该模板。