agentic_huge_data_base / wiki
页面 RAGFlow · 11.2 沙箱代码执行器·DeepWiki 中文全文译文
DeepWiki 中文译文 / RAGFlow / 11.2

11.2 · 沙箱代码执行器（Sandbox Code Executor）

复杂文档理解与引用检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目RAGFlow 章节11.2 状态全文译文 模块系统架构、安装与启动、界面与交互、智能体运行时
项目要点页2.5 参考项目 项目章节目录RAGFlow DeepWiki 原始章节Sandbox Code Executor 上一章11.1 下一章11.3
源码线索
  • AGENTS.md
  • CLAUDE.md
  • agent/tools/code_exec.py
  • agent/tools/exesql.py
  • docker/docker-compose.yml
  • docker/entrypoint.sh
  • mcp/client/client.py
  • mcp/client/streamable_http_client.py
  • mcp/server/server.py
  • web/src/pages/agent/form/exesql-form/use-submit-form.ts
模块标签
  • 系统架构
  • 安装与启动
  • 界面与交互
  • 智能体运行时
  • 测试、发布与运维

章节正文

沙箱代码执行器

原始 DeepWiki 页面https://deepwiki.com/infiniflow/ragflow/11.2-sandbox-code-executor

沙箱代码执行器

相关源文件

本章引用的主要源码文件：

  • AGENTS.md
  • CLAUDE.md
  • agent/tools/code_exec.py
  • agent/tools/exesql.py
  • docker/docker-compose.yml
  • docker/entrypoint.sh
  • mcp/client/client.py
  • mcp/client/streamable_http_client.py
  • mcp/server/server.py
  • web/src/pages/agent/form/exesql-form/use-submit-form.ts
  • web/src/pages/agent/form/tool-form/exesql-form/index.tsx
  • web/src/pages/agent/options.ts
  • web/src/pages/next-chats/hooks/use-build-form-refs.ts

沙箱代码执行器是一个安全执行环境，专为在 RAGFlow 智能体工作流中运行任意代码（主要是 Python 或 SQL）而设计。它确保用户提供的脚本和数据库查询与主机环境隔离，同时与工作流引擎保持高性能数据交换。该系统支持多种执行后端，包括本地子进程、基于 gVisor 的安全容器以及外部 SQL 引擎。

系统架构

沙箱系统遵循基于提供者的模式。它将底层执行技术（容器、进程或数据库连接）与智能体组件进行抽象分离。

自然语言到代码实体的映射

以下图表展示了 RAGFlow Canvas 中用户定义的逻辑如何转换为后端执行实体，以及数据如何在系统中流转。

工作流到执行的映射

RAGFlow · 自然语言到代码实体的映射 · 图 1
RAGFlow · 自然语言到代码实体的映射 · 图 1

来源：agent/tools/code_exec.py:191-206, agent/tools/code_exec.py:29-29

SQL 执行数据流

RAGFlow · 自然语言到代码实体的映射 · 图 2
RAGFlow · 自然语言到代码实体的映射 · 图 2

来源：agent/tools/exesql.py:29-47, agent/tools/exesql.py:80-84, agent/tools/exesql.py:127-144

组件集成

1. 代码组件（CodeExec）

CodeExec 工具管理 Python 脚本的执行。它在沙箱和 RAGFlow 引擎之间强制执行严格的契约，以确保数据完整性。

  • 保留键：系统阻止脚本返回与内部元数据冲突的键，例如 _ERROR、_ARTIFACTS 或 content agent/tools/code_exec.py:36-48。
  • 类型校验：_validate_expected_type 递归检查返回的数据是否符合预期的模式（例如 Array<String>、Number、Object）agent/tools/code_exec.py:154-190。
  • 输出规范化：结果通过 normalize_output_value 和 render_canonical_content 进行处理，以确保它们可以序列化为 JSON 或在用户界面中显示 agent/tools/code_exec.py:79-118。
2. SQL 组件（ExeSQL）

ExeSQL 组件允许智能体查询外部数据库。它支持多种引擎，包括 MySQL、PostgreSQL、MariaDB、MSSQL、OceanBase 和 Trino agent/tools/exesql.py:57-57。

  • 安全约束：出于安全原因，如果主机被识别为内部 ragflow-mysql 服务，该组件会明确阻止对内部 rag_flow 数据库的访问 agent/tools/exesql.py:65-69。
  • 参数处理：它使用 get_input_elements_from_text 解析 SQL 模板中的变量（例如 SELECT * FROM table WHERE id = {id}）agent/tools/exesql.py:111-121。
  • 数据转换：结果通过 convert_decimals 进行处理，以处理标准 JSON 原生不支持的 Decimal、NaN 或 Infinity 等类型 agent/tools/exesql.py:88-102。

提供者生命周期与管理

代码执行的生命周期通过基于提供者的架构进行管理。虽然具体的提供者实现各不相同，但它们通常遵循以下步骤：

  1. 初始化：从环境变量或 service_conf.yaml 加载配置 docker/entrypoint.sh:157-176。
  2. 执行：代码被发送到提供者。对于本地执行，这涉及子进程；对于远程提供者，这涉及 API 调用。
  3. 结果捕获：捕获 stdout、stderr 和结构化返回值。
  4. 制品收集：如果代码生成文件（例如 .png 图表），执行器会收集这些制品，通常将它们上传到类似 SANDBOX_ARTIFACT_BUCKET 的存储桶 agent/tools/code_exec.py:33-33。

部署与配置

沙箱及相关执行器在系统启动期间通过 docker/entrypoint.sh 脚本进行配置。

  • 任务执行器激活：使用唯一的 host_id 通过 rag/svr/task_executor.py 启动任务执行器 docker/entrypoint.sh:206-215。
  • MCP 服务器集成：可以启用模型上下文协议（MCP）服务器，为工具执行（包括检索和代码任务）提供标准化接口 docker/entrypoint.sh:38-54, mcp/server/server.py:58-69。
  • 环境变量：关键设置如 SVR_MCP_PORT（默认 9382）和 ADMIN_SVR_HTTP_PORT（默认 9381）定义了这些服务的网络边界 docker/docker-compose.yml:31-36。

安全与故障排除

错误根本原因解决方案
ContractError输出名称是保留键（例如 _ERROR）或包含无效字符 agent/tools/code_exec.py:51-62。在组件配置中重命名输出变量。
ValueError（SQL）尝试访问受保护的内部 rag_flow 数据库 agent/tools/exesql.py:65-69。使用不同的数据库或凭据进行外部查询。
TimeoutError组件执行超过了 COMPONENT_EXEC_TIMEOUT（默认 60 秒）agent/tools/exesql.py:83-83。优化查询/脚本或在环境中增加超时时间。
类型不匹配实际结果类型与定义的模式不匹配 agent/tools/code_exec.py:185-190。更新组件的预期类型或脚本的返回值。

来源：agent/tools/code_exec.py:36-62, agent/tools/exesql.py:65-69, agent/tools/exesql.py:83-83, agent/tools/code_exec.py:185-190