沙箱资源
一、基本概念
沙箱是一个隔离的云端运行环境。您可以基于模板创建代码沙箱、浏览器沙箱或自定义沙箱，用于执行不可信代码、运行自动化任务和调试应用等场景。
- 镜像：提供操作系统、运行时和预装软件的基础环境，支持系统预制镜像和自定义镜像。
- 模板：在镜像基础上固化资源规格、环境变量、生命周期、存储和网络配置。
- 沙箱实例：基于模板启动的实际运行环境。
- 快照：保存某个沙箱实例的状态，便于后续复用或排查。
- Secrets：统一管理沙箱外网登录、外部云存储、第三方服务对接所需的自定义鉴权凭证。
平台提供三种类型的沙箱，三类沙箱均提供隔离运行环境：
类型 | 定义 | 适用场景 |
代码沙箱 | 以执行代码与系统命令为核心的无图形界面沙箱，Agent 仅通过标准输出（stdout）、标准错误（stderr）与进程返回码感知执行结果，全程无可视化交互入口。 | 运行 Python/Node.js 脚本、数据处理、文件生成、代码测试 |
浏览器沙箱 | 以控制 Web 浏览器为核心，沙箱内运行真实 Chrome 实例，Agent 通过 Playwright、Puppeteer 或 CDP 协议下发操作指令，以页面 DOM、网络请求与脚本执行结果作为反馈。 | 网页自动化、浏览器测试、网页操作和文件下载 |
自定义沙箱 | 用户可按业务需求定义预装软件与依赖、CPU/内存规格、启动命令、环境变量、存储挂载、网络访问策略及生命周期规则；沙箱的交互方式取决于所选镜像和配置，可用于承载具有专用运行环境或特殊资源需求的代码执行、自动化任务等场景。 | 有特殊依赖、资源规格、网络或存储要求的业务 |
二、使用指南
根据用户不同的使用场景我们提供以下两种使用路径参考：
使用方式 | 适用场景 | 核心路径 |
使用预置环境 | 标准代码执行、数据处理、网页自动化等常见任务 | 选择预置模板 → 按需配置凭证 → 创建沙箱实例 |
构建自定义环境 | 有专用依赖、特殊资源、网络、存储或启动配置要求 | 自定义镜像 → 自定义模板 → 沙箱实例 → 快照 |
2.1 使用预置环境创建沙箱
如果您的任务是常见的代码执行或浏览器自动化，建议优先使用平台预置模板。您无需创建镜像或模板，选择模板后即可创建实例。
2.1.1 创建沙箱实例
操作 | 平台页面 |
|
2.1.2 创建并引用凭证
如果实例中的程序需要访问 OSS、数据库或第三方 API，请先创建 Secrets（凭证），再在本次实例的环境变量中引用。不要将密码、Token 或访问密钥直接写入代码、启动命令或日志。
操作 | 平台页面 |
| |
在“环境变量”中使用以下格式： ${secret.凭证名称} 例如，创建ACCESS_KEY后，设置： 环境变量键名：ACCESS_KEY 环境变量键值：${secret.OSS_ACCESS_KEY} 实例启动时，系统会将引用替换为真实凭证内容。凭证名称区分大小写，必须完全一致。 |
2.1.3 使用和管理实例
- 实例状态变为运行中后，即可通过控制台或 API/SDK 使用，如需使用 API/SDK 接入，可查看API完整指引。
- 需要看运行结果或排查异常时，进入实例详情查看日志和监控。
- 任务暂时不用但希望保留环境时，点击暂停实例；彻底不再使用时，点击销毁实例。
提示：第一次使用时，可以先基于预置模板创建实例。当预置环境缺少依赖、资源或网络配置时，再创建自定义模板或镜像。
- 沙箱实例是实际的运行环境，您可以在沙箱列表页面查看、筛选和管理项目内的实例，实例包含以下状态：
实例状态 | 含义 | 建议操作 |
创建中 | 系统正在准备运行环境 | 等待实例变为运行中 |
运行中 | 实例可执行任务 | 使用、查看详情、日志或监控；可暂停或销毁 |
休眠中 | 计算资源已暂停，环境仍可恢复 | 恢复继续使用，或销毁 |
删除中 | 系统正在销毁实例 | 等待完成 |
异常 | 实例运行发生异常 | 优先看日志和监控；必要时保留快照后重建 |
- 暂停：实例进入休眠状态，适用于任务暂时停止但之后还要继续的场景
- 恢复：系统重新启动实例，恢复耗时会受实例配置和资源情况影响
- 销毁：永久删除实例，销毁后实例数据不可恢复，如需保留当前状态，请先创建快照
查看实例详情
操作 | 平台页面 |
|
2.2 构建自定义环境
自定义环境创建顺序为：
自定义镜像 → 自定义模板（含凭证、网络和存储）→ 沙箱实例 → 快照如果预置镜像已包含所需软件，可跳过自定义镜像，直接创建自定义模板。
2.2.1 创建自定义镜像
镜像决定沙箱的基础软件环境，例如操作系统、语言版本、浏览器、系统工具和预装依赖。
操作 | 平台页面 |
构建成功后，在创建自定义模板时选择该镜像 |
【注意：系统镜像仅可查看和使用；只有自定义镜像支持编辑、删除。删除镜像前，请确认没有模板依赖。】
2.2.2 创建凭证并配置自定义模板
模板将镜像、资源和运行规则组合为可复用方案。对于需要访问外部服务的环境，建议在创建模板前先准备凭证，然后将凭证引用写入模板环境变量，使后续基于该模板创建的所有实例都能按统一方式获得所需配置。
操作 | 平台页面 |
安全建议：Secrets 仅保存敏感值本身；不要将真实密钥写入 Dockerfile、镜像、模板描述或启动命令。 | |
|
模版中各配置项说明如下：
配置项 | 说明 |
资源规格 | vCPU 可选 1、2、4核；内存与 vCPU 联动选择 |
启动命令 | 实例启动时优先执行的命令；留空时执行内置启动脚本 |
环境变量 | 用于配置程序运行参数；敏感信息使用${secret.凭证名称}引用 |
生命周期 | 可设置空闲自动休眠、最长休眠时间和最大存活时长
|
云存储 | 模板支持挂载 KFS（万擎文件存储）和 OSS（阿里云对象存储）。每个挂载可配置存储来源、路径、挂载路径和读写权限。使用 OSS 时，还需选择鉴权凭证并填写 Bucket、地域 ID 和外网 Endpoint。 |
网络策略 | 可选完全禁止公网、完全开放公网或自定义域名白名单 |
模板状态变为就绪后，才能用于创建实例。修改 CPU、内存或镜像后需重新构建；修改环境变量、启动命令、存储、网络或生命周期配置后可直接保存。
2.2.3 基于自定义模板创建实例
在模板管理中找到状态为“就绪”的模板，单击新建沙箱；也可以在沙箱实例页面选择该模板后创建。
实例会继承模板的沙箱类型、镜像、资源规格、环境变量（包括凭证引用）、启动命令、生命周期、存储和网络配置。创建后可按“2.1.3 使用和管理实例”进行暂停、恢复、销毁及查看日志、监控等操作。
2.2.4 创建快照
快照用于保存实例某一时刻的状态，适合保留已完成配置的环境、关键阶段的结果或异常现场。
在「沙箱列表」或「实例详情」中创建快照后，可在沙箱快照页面查看快照状态、来源实例、关联模板、大小和过期时间。
快照支持设置为“永不过期”或自定义过期时间。快照删除后不可恢复，并会释放相应存储空间。
存储提示：快照和模板共同占用共享存储。当系统提示容量不足时，请先删除无用快照和模板，再按需申请提高存储配额。
三、常见问题
为什么不能创建沙箱？
请确认所选模板状态为“就绪”；如模板仍在构建、更新或失败，请等待完成或修正配置后重试。若实例数量、资源或存储接近上限，请在配额管理中确认可用额度。
为什么不能删除模板或镜像？
模板可能仍被实例引用，镜像可能仍被模板依赖。请先处理下游关联资源。系统预置模板和系统镜像不支持删除。
沙箱异常怎么办？
先进入实例详情查看日志和监控，检查启动命令、环境变量、依赖、资源和网络配置。若需要保留问题现场，请先创建快照；无法恢复时再销毁并重建实例。