本文主要介绍函数服务（veFaaS）提供的云沙箱相关创建、使用、管理操作。 ## 功能介绍 veFaaS 云沙箱是专为 AI 任务执行打造的高弹性、低成本、有状态、安全隔离、运维便捷、功能丰富的 Serverless 云沙箱。用户无需关心底层基础设施，可按需秒级拉起云沙箱环境。在推理场景中，云沙箱提供 AI 驱动的任务执行环境；在训练场景中，如模型 RL/RFT 训练，云沙箱执行环境能够支撑代码运行、增强工具调用、处理复杂任务。 ## 创建云沙箱函数 ### 前提条件 * 已开通函数服务。 * 首次使用函数服务，需完成跨服务授权。 * （可选）如需挂载对象存储（TOS），请参考 [挂载 TOS 对象存储](https://www.volcengine.com/docs/6662/1222882) 内容操作。 * （可选）如需访问私有网络 VPC，请确保已开通火山引擎私有网络，已在函数待部署地域创建私有网络、子网和安全组。详细操作请参见 [创建私有网络](https://www.volcengine.com/docs/6401/69467)、[创建子网](https://www.volcengine.com/docs/6401/67823)、[创建安全组](https://www.volcengine.com/docs/6401/68894)。 * （可选）若需要查看函数日志，请确保已开通火山引擎日志服务。其中，使用自定义日志项目投递函数日志时，需确保已创建日志项目和主题。详细操作请参见 [创建日志项目](https://www.volcengine.com/docs/6470/72005#%E5%88%9B%E5%BB%BA%E6%97%A5%E5%BF%97%E9%A1%B9%E7%9B%AE)、[创建日志主题](https://www.volcengine.com/docs/6470/72004#%E5%88%9B%E5%BB%BA%E6%97%A5%E5%BF%97%E4%B8%BB%E9%A2%98)。 ### 操作步骤 1. 登录 [函数服务控制台](https://console.volcengine.com/vefaas)。 2. 在顶部导航栏，选择目标地域。 3. 左侧导航栏选择 **函数**，并在 **函数** 页面单击 **创建函数**。 4. 在 **创建函数** 页面，选择 **创建「云沙箱」**，并按照如下说明配置参数。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_dcc7692ac3ccf50c400daaa05e5afe7b.png =967x) * **基础配置** |**配置项** |**说明** | |---|---| |名称 |自定义云沙箱函数名称。同一账号下函数名称不可重复，函数名称创建成功后不支持修改。 | |备注 |描述函数信息，可以为空。 | * **函数代码** |**配置项** |**说明** | |---|---| |运行时 |选择函数代码的运行时环境。本场景支持 **Native**。 | |部署方式 |云沙箱仅支持 **容器镜像** 部署方式。请按需选择：|\ | ||\ | |* **镜像仓库**：从您的火山引擎镜像仓库（CR）中选择具体要部署的镜像。支持通过实例、命名空间和仓库类型（公有/私有）进行筛选。|\ | | 选择 **镜像仓库** 中的镜像时，veFaaS 支持获取该镜像中的 **启动命令**、**环境变量** 等信息，您可以自主勾选是否使用已选镜像的 **启动命令** 或 **环境变量** 作为当前函数的 **启动命令** 或 **环境变量**。|\ | |* **公共镜像**：函数服务预置的开箱即用的镜像，可直接使用。 | |Webserver 模式 |是。需要您在镜像/代码中实现 HTTP Server 并监听端口处理请求。 | |启动命令 |默认启动命令为`bash /root/sandbox/scripts/run.sh`。如果使用您的自定义镜像部署函数，请按实际需求改为您的镜像启动脚本。 | |监听端口 |输入 HTTP Server 所监听的端口。默认监听端口为 **8080**。如果使用您的自定义镜像部署函数，请按实际需求改为您的服务监听端口。|\ | |:::warning|\ | |您启动的 HTTP Server 需监听`0.0.0.0:Port`或`*:Port`。否则会导致请求超时错误。|\ | ||\ | |:::| * **高级配置** |**配置项** |**说明** | |---|---| |CPU 分配模式 |始终分配 CPU。应用启动后，不支持缩容到 0，需为容器生命周期付费。 | |计算模式 |云沙箱仅支持使用 CPU 实例。 | |实例规格 |默认规格为 1 vCPU 2 GiB，可根据您的实际需求自定义调整。 | |执行超时 |根据代码执行需求，按需配置执行时。可选范围： 1 ~ 900 s。 | |单实例多并发 |支持是否开启单个实例并发处理多个请求的功能：|\ | ||\ | |* **开启**：每个实例可并发处理多个请求，且只计算一次内存使用量，可大幅降低资源开销，进而节省成本。开启后，需设置单个函数实例最大可承载的并发请求数量。 |\ | |* **关闭**：每个实例只能同时处理一个请求。 | |网络 |配置函数的公网和 VPC，支持以下 3 种组合：|\ | ||\ | |* 关闭 **VPC 访问**：函数不能访问 VPC，函数可通过默认网卡访问公网。函数服务会收取公网出流量费用。|\ | |* 开启 **VPC 访问**，开启 **函数访问公网**：函数可访问 VPC，函数可通过默认网卡访问公网，函数服务会收取公网出流量费用。|\ | |* 开启 **VPC 访问**，关闭 **函数访问公网**：函数可访问 VPC，函数无法通过默认网卡访问公网。如需访问公网，需自行在 VPC 下配置 NAT 网关，详细操作可参见 [创建公网 NAT 网关](https://www.volcengine.com/docs/6404/69468)。函数服务侧不收取公网出流量费用。 | |存储 |为函数挂载远端存储。配置后您的函数可以像访问本地系统一样访问远端存储，实现数据的持久化存储和多函数间共享。|\ | ||\ | |* 挂载 NAS 文件存储请参见 [挂载 NAS 文件存储](https://www.volcengine.com/docs/6662/1215960)。|\ | |* 挂载 TOS 对象存储请参见 [挂载 TOS 对象存储](https://www.volcengine.com/docs/6662/1222882)。 | |日志功能 |是否启用日志功能。开启后，函数的 stdout/stderr 日志将被采集至日志服务的指定日志项目（Project）和日志主题（Topic）中。您可查看该函数的执行日志，方便查看函数运行状态和定位问题。更多介绍请参见 [日志管理](https://www.volcengine.com/docs/6662/124699)。 | |环境变量 |自定义配置的环境变量，在函数代码运行时可以直接读取到。云沙箱函数需要设置环境变量（`HOME:/home/tiger`）：|\ | ||\ | |* **键**：`HOME`|\ | |* **值**：`/home/tiger` | |所属项目 |函数所属的项目。如果您未指定具体项目，则默认加入 default 项目。更多介绍请参见 [项目管理](https://www.volcengine.com/docs/6662/1337750)。 | |标签 |用于标记资源，便于搜索和资源聚合。单击 **添加标签**，根据界面提示为当前函数添加合适的标签。更多介绍请参见 [标签管理](https://www.volcengine.com/docs/6662/1337751)。 | |服务条款和服务等级协议 |请仔细阅读产品相关的服务条款和服务等级协议，确认后勾选参数前的复选框。 | 4. 单击 **确定**，完成函数创建。 ## 发布云沙箱函数创建完云沙箱函数后，需要发布函数。详细操作，请参见 [发布函数](https://www.volcengine.com/docs/6662/97471)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b51701565909305bfa2a6325ee0ed950.png =989x) ## 创建云沙箱实例 1. 在 [函数服务控制台](https://console.volcengine.com/vefaas/) 已创建的云沙箱函数详情页，选择 **资源管理** 页签，单击 **创建实例**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_a98530f8991adbd0a4665bfd38c79ae4.png =968x) 2. 在创建实例对话框中配置实例参数。 |**配置项** |**说明** | |---|---| |配置生命周期时长 |沙箱实例的存活时长。根据控制台提示的时间范围、时间单位等，自定义配置。 | |实例元信息 |实例 Label 元信息，示例：`user:2100******`。后续可通过元信息``筛选查询沙箱。|\ | |可在如下场景中使用：|\ | ||\ | |* 将沙盒与用户会话关联。|\ | |* 存储沙盒（如 API 密钥）的自定义用户数据。|\ | |* 将沙箱与用户 ID 关联，以便后续连接到沙箱[ ](https://e2b.dev/docs/sandbox/connect)。 | |环境变量 |自定义配置实例级别环境变量，若未配置，则复用函数的环境变量配置。|\ | |:::tip|\ | |若实例环境变量 Key 与函数级别环境变量 Key 重名，则实例级别环境变量 Value 将覆盖函数环境变量配置。|\ | ||\ | |:::| |TOS 存储配置 |启用 TOS 挂载的函数，显示该配置。|\ | ||\ | |* **Bucket 子目录**：您预期想要挂载的 TOS 路径。|\ | |* **本地目录**：下拉选择函数级别配置的 TOS 本地目录。 | 3. 单击 **确定**，创建实例，实例状态显示为 **Ready**，表示实例创建成功。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_3ab464613a4a0ec7532027bc80fdcf78.png =966x) 4. （可选）在实例列表的搜索框，以及沙箱实例 **操作** 列，通过对应操作按钮管理沙箱实例。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_58bfe01e1279952c25b4991d0b94d496.png =968x) |**操作** |**说明** | |---|---| |搜索框 |在搜索框中输入元信息（格式为`key=value`），可查询对应的沙箱实例。 | |日志 |查看沙箱实例相关的日志信息。 | | Webshell |登录实例 Webshell 端口，查看实例配置 env，常用的命令如下：|\ | ||\ | |* 查询 Sandbox 服务 proc id：`ps aux \| grep "sandbox"`|\ | |* 查看进程 env：`cat /proc/${your_sandbox_proc_id}/environ \| tr '\0' '\n'`|\ | | :::tip|\ | | 其中将`${your_sandbox_proc_id}`替换为您查询到的实际 Sandbox 服务 proc id，例如 proc id 为 15，则完整命令为：cat /proc/15/environ \| tr '\0' '\n'。|\ | ||\ | | :::| |修改超时时间 |修改云沙箱实例存活时长。 | |删除 |删除沙箱实例。 | ## 创建和配置 API 网关触发器 1. 在 [API 网关控制台](https://console.volcengine.com/veapig/) ，创建 API 网关实例。需要注意以下列举的参数配置，其余参数说明和详细的操作步骤请参见 [创建实例](https://www.volcengine.com/docs/6569/85693)。 |**配置项** |**说明** | |---|---| |地域 |选择与云沙箱函数相同的地域。 | |网关类型 |选择 **Serverless 网关**。 | 2. 在 [API 网关控制台](https://console.volcengine.com/veapig/) ，创建 API 网关服务（域名），关联上一步创建的 API 实例。详情请参见 [创建服务](https://www.volcengine.com/docs/6569/85695)。 3. 在 [函数服务控制台](https://console.volcengine.com/vefaas/) 找到已创建的云沙箱函数，为该函数创建 API 网关触发器。需要注意以下列举的参数配置，其余参数说明和详细的操作步骤请参见 [创建 API 网关触发器](https://www.volcengine.com/docs/6662/116904)。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_9efa34a6ffe98ff5d61c6294f9880cab.png =967x) |**配置项** |**说明** | |---|---| |网关实例 |选择已创建的 API 网关实例。 | |网关服务 |选择已创建的 API 网关服务（域名）。 | 4. 创建 API 网关触发器成功后，获取触发器的 **公网访问** 地址，以备后续使用。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_96777f39e60c38b448b4c0eba4645057.png =967x) ## 云沙箱测试 ### 控制台测试 1. 在 [函数服务控制台](https://console.volcengine.com/vefaas/) 云沙箱函数详情页面，单击右上角的 **测试**。 2. 在函数测试面板，按需修改`data`字段，然后单击 **测试**。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b86661f1a8843ba63970a0de205f7228.png =967x) 3. **函数测试** 面板显示 **测试结果：成功**，表示云沙箱测试已成功。 ### API 网关域名请求测试通过本地`curl`命令，调用 API 来测试云沙箱函数。可通过 x\-faas\-insatnce\-name 指定实例请求。 * 将`https://****.apigateway-cn-beijing.volceapi.com`替换为您自己云沙箱函数的访问地址。 * 根据实际情况，替换`data`下的参数值，相关参数说明和示例，请参见开源文档 [Sandbox Fusion](https://bytedance.github.io/SandboxFusion/zh-Hans/docs/api/run-code-run-code-post/)。 ```Bash curl 'https://****.apigateway-cn-beijing.volceapi.com/run_code' \ -H 'accept: application/json, text/plain, */*' \ -H 'accept-language: zh-CN,zh;q=0.9' \ -H 'content-type: application/json' \ -H 'x-faas-instance-name: vefaas-ojxvvagw-ondm2cscas-d1eg8b1vnaumg4bf9190-sandbox' \ --data '{ "code": "ls", "language": "bash", "files":{} }' ``` ### Playground 测试 1. 访问前文中获取的 API 网关触发器公网访问地址。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_b432522912f21fb3959f58aa850b6af4.png =966x) 2. 在 SandboxFusion 页面，单击 **Playground** 页签，选择 **Sandbox** 页面。 3. 在 Code 文本框中输入待运行代码段并选择对应编程语言，单击 **Submit** 提交代码运行请求。等待运行完成后，可查看结果输出。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_d934520ef5a4c1f995bccad027ba2f0d.png =966x)