DifySandbox 完整使用手册

DifySandbox 使用手册DifySandbox 是 Dify 平台开源的轻量级代码执行沙箱专为 AI 应用场景设计。本文将详细介绍 DifySandbox 的安装、配置和使用方法帮助开发者快速集成安全的代码执行能力。一、DifySandbox 简介DifySandbox 是一个专为 AI 应用场景设计的代码执行沙箱具有以下特点轻量级基于 Go 语言开发资源占用低多语言支持支持 Python、JavaScript、Java 等主流语言安全隔离多种隔离级别可选确保代码安全执行易于集成提供 RESTful API便于各种应用集成与其他方案对比特性DifySandboxJudge0自建沙盒部署复杂度简单中等复杂资源占用低中等高启动时间1秒1-3秒可优化适用场景AI 应用通用平台定制需求二、快速开始2.1 Docker 部署# 拉取镜像dockerpull langgenius/dify-sandbox:latest# 运行容器dockerrun-d--namedifysandbox-p8194:8194-v/var/run/docker.sock:/var/run/docker.sock langgenius/dify-sandbox:latest# 测试是否启动成功curlhttp://localhost:8194/health2.2 Docker Compose 部署# docker-compose.ymlversion:3.8services:difysandbox:image:langgenius/dify-sandbox:latestcontainer_name:difysandboxports:-8194:8194volumes:-/var/run/docker.sock:/var/run/docker.sockenvironment:-SANDBOX_MEMORY_LIMIT256-SANDBOX_CPU_LIMIT1-SANDBOX_MAX_EXECUTION_TIME30restart:unless-stoppedhealthcheck:test:[CMD,curl,-f,http://localhost:8194/health]interval:30stimeout:10sretries:3# 启动服务docker-composeup-d# 查看日志docker-composelogs-fdifysandbox三、API 使用详解3.1 执行代码请求地址POST /v1/sandbox/runcurl-XPOSThttp://localhost:8194/v1/sandbox/run-HContent-Type: application/json-d{ code: print(sum(range(1, 11))), language: python3 }响应结果{success:true,exit_code:0,stdout:55,stderr:,execution_time:0.015,execution_memory:35840}3.2 完整参数列表参数类型必填说明codestring是要执行的代码languagestring是编程语言stdinstring否标准输入timeoutint否超时时间秒默认 30memory_limitint否内存限制MB默认 256支持的语言language 值说明python3Python 3javascriptJavaScript (Node.js)javaJavagoGorustRustcCcppC3.3 Python 示例importrequestsdefrun_python_code(code:str,timeout:int30):responserequests.post(http://localhost:8194/v1/sandbox/run,json{code:code,language:python3,timeout:timeout})returnresponse.json()# 示例计算斐波那契数列resultrun_python_code( def fib(n): if n 1: return n return fib(n-1) fib(n-2) for i in range(10): print(fib(i), end ) )print(result)# {success: True, exit_code: 0, stdout: 0 1 1 2 3 5 8 13 21 34,...}3.4 JavaScript 示例constaxiosrequire(axios);asyncfunctionrunJavaScript(code){constresponseawaitaxios.post(http://localhost:8194/v1/sandbox/run,{code:code,language:javascript});returnresponse.data;}// 示例数组操作runJavaScript(const arr [1, 2, 3, 4, 5]; const doubled arr.map(x x * 2); console.log(doubled.join(, ));).then(result{console.log(result.stdout);// 输出: 2, 4, 6, 8, 10});3.5 Java 示例curl-XPOSThttp://localhost:8194/v1/sandbox/run-HContent-Type: application/json-d{ code: public class Main { public static void main(String[] args) { System.out.println(\Hello from Java!\); } }, language: java }四、安全配置4.1 环境变量配置环境变量默认值说明SANDBOX_MEMORY_LIMIT256内存限制MBSANDBOX_CPU_LIMIT1CPU 核心数SANDBOX_MAX_EXECUTION_TIME30最大执行时间秒SANDBOX_MAX_OUTPUT_SIZE1024最大输出大小KBSANDBOX_ENABLE_NETWORKfalse是否允许网络访问4.2 安全策略级别DifySandbox 支持多种安全策略级别级别 1基础隔离默认资源限制CPU、内存、执行时间适用于可信代码、内部系统级别 2增强隔离禁用网络限制文件系统访问适用于用户提交的代码级别 3最高隔离完全隔离的容器禁止所有危险操作适用于不受信任的代码4.3 网络访问控制默认情况下网络访问是禁用的。如需启用dockerrun-d--namedifysandbox-p8194:8194-eSANDBOX_ENABLE_NETWORKtrue langgenius/dify-sandbox:latest4.4 自定义允许的模块Python对于 Python可以限制可导入的模块dockerrun-d--namedifysandbox-p8194:8194-eSANDBOX_ALLOWED_PYTHON_MODULESmath,random,json,collections langgenius/dify-sandbox:latest五、在 Dify 平台中使用5.1 配置 Code Executor 节点打开 Dify Studio添加 “Code Executor” 节点选择 “DifySandbox” 作为执行器配置默认参数5.2 在工作流中使用┌─────────────┐ ┌──────────────────┐ ┌─────────────┐ │ User Input │ ──▶ │ Code Executor │ ──▶ │ Output │ │ │ │ (Python Script) │ │ │ └─────────────┘ └──────────────────┘ └─────────────┘示例工作流代码# 从用户输入获取数据user_input{{user_input}}# 处理数据resulteval(user_input)# 返回结果print(fResult:{result})六、集成到应用6.1 Python SDK 封装importrequestsfromtypingimportOptional,Dict,AnyclassDifySandbox:def__init__(self,base_url:strhttp://localhost:8194):self.base_urlbase_urldefrun(self,code:str,language:strpython3,stdin:Optional[str]None,timeout:int30,memory_limit:int256)-Dict[str,Any]:responserequests.post(f{self.base_url}/v1/sandbox/run,json{code:code,language:language,stdin:stdin,timeout:timeout,memory_limit:memory_limit},timeouttimeout5)response.raise_for_status()returnresponse.json()# 使用示例sandboxDifySandbox()resultsandbox.run(print(Hello!),python3)print(result)6.2 Java SDK 封装importokhttp3.*;importorg.json.JSONObject;importjava.util.concurrent.TimeUnit;publicclassDifySandbox{privatefinalOkHttpClientclient;privatefinalStringbaseUrl;publicDifySandbox(StringbaseUrl){this.clientnewOkHttpClient.Builder().connectTimeout(30,TimeUnit.SECONDS).readTimeout(60,TimeUnit.SECONDS).build();this.baseUrlbaseUrl;}publicJSONObjectrun(Stringcode,Stringlanguage){JSONObjectbodynewJSONObject();body.put(code,code);body.put(language,language);RequestrequestnewRequest.Builder().url(baseUrl/v1/sandbox/run).post(RequestBody.create(body.toString(),MediaType.get(application/json))).build();try(Responseresponseclient.newCall(request).execute()){returnnewJSONObject(response.body().string());}catch(Exceptione){thrownewRuntimeException(e);}}}6.3 JavaScript/Node.js 封装constaxiosrequire(axios);classDifySandbox{constructor(baseUrlhttp://localhost:8194){this.clientaxios.create({baseURL:baseUrl,timeout:60000});}asyncrun(code,languagepython3,options{}){constresponseawaitthis.client.post(/v1/sandbox/run,{code,language,...options});returnresponse.data;}// 便捷方法asyncrunPython(code,options{}){returnthis.run(code,python3,options);}asyncrunJavaScript(code,options{}){returnthis.run(code,javascript,options);}}// 使用示例constsandboxnewDifySandbox();constresultawaitsandbox.runPython(import json data {name: Dify, version: 1.0} print(json.dumps(data)));console.log(result.stdout);七、监控与运维7.1 健康检查# 检查服务状态curlhttp://localhost:8194/health# 响应示例{status:healthy,version:1.0.0}7.2 日志管理# 查看容器日志dockerlogs difysandbox# 实时查看日志dockerlogs-fdifysandbox# 按级别过滤dockerlogs difysandbox21|grepERROR7.3 性能监控建议集成 Prometheus 进行监控# prometheus.ymlscrape_configs:-job_name:difysandboxstatic_configs:-targets:[difysandbox:8194]7.4 常见问题排查问题可能原因解决方案执行超时代码死循环/计算量大增加 timeout 或优化代码内存超限申请过多内存减小 memory_limit 或优化代码连接失败服务未启动检查容器状态和网络语言不支持language 参数错误使用支持的语言标识八、最佳实践8.1 安全建议最小权限原则仅授予必要的资源限制网络隔离默认禁用网络访问输入验证对用户输入进行严格验证超时设置合理设置执行超时时间日志审计记录所有执行记录8.2 性能优化连接复用使用连接池减少开销批量执行需要执行多条代码时批量处理资源预估根据代码复杂度合理分配资源缓存结果对相同代码进行结果缓存8.3 高可用部署# docker-compose-cluster.ymlversion:3.8services:difysandbox-1:image:langgenius/dify-sandbox:latestdeploy:replicas:2environment:-SANDBOX_MEMORY_LIMIT256networks:-sandbox-networkdifysandbox-2:image:langgenius/dify-sandbox:latestdeploy:replicas:2environment:-SANDBOX_MEMORY_LIMIT256networks:-sandbox-networknginx:image:nginx:alpineports:-8194:80volumes:-./nginx.conf:/etc/nginx/nginx.conf:rodepends_on:-difysandbox-1-difysandbox-2networks:-sandbox-networknetworks:sandbox-network:driver:bridge九、API 参考9.1 端点列表方法路径说明GET/health健康检查POST/v1/sandbox/run执行代码GET/v1/sandbox/languages支持的语言列表9.2 错误响应{success:false,error:Execution timeout,error_code:TIMEOUT}错误码说明错误码说明TIMEOUT执行超时MEMORY_LIMIT内存超限RUNTIME_ERROR运行时错误COMPILE_ERROR编译错误INVALID_LANGUAGE不支持的语言INVALID_REQUEST请求参数错误十、总结DifySandbox 是一个功能强大且易于使用的代码执行沙箱特别适合 AI 应用场景。其主要优势包括轻量级资源占用低启动快速安全可靠多级别安全策略易于集成RESTful API 多语言 SDK开源免费Apache 2.0 许可证无论是构建 AI 编程助手、智能客服还是代码评测工具DifySandbox 都是一个值得考虑的选择。参考资源GitHub: https://github.com/langgenius/dify-sandboxDify 官网: https://dify.ai本文由 OpenClaw 自动发布