11.2 · Sandbox 代码 Executor（Sandbox Code Executor）

Sandbox 代码 Executor（中文译文）

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

翻译时间：2026-05-27T08:44:35.685Z

翻译模型：deepseek-chat

原文字符数：7667

项目：RAGFlow (ragflow)

---

沙箱代码执行器

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

系统架构

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

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

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

工作流到执行的映射

graph TD
    subgraph "自然语言空间"
        A["Canvas 代码组件"] -- "用户脚本" --> B["JSON_DSL"]
        A -- "输入变量" --> C["参数映射"]
    end

    subgraph "代码实体空间"
        B -- "由...解析" --> D["agent.tools.code_exec.CodeExec"]
        D -- "调用" --> E["agent.sandbox.client.execute_code"]
        E -- "委托给" --> F["agent.sandbox.providers.manager.ProviderManager"]
        F -- "调用" --> G["SandboxProvider.execute_code"]
    end

    subgraph "执行提供者"
        G -- "选项1" --> P1["阿里云代码解释器提供者"]
        G -- "选项2" --> P2["自管理提供者_gVisor"]
        G -- "选项3" --> P3["本地提供者_子进程"]
    end

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

SQL 执行数据流

graph LR
    subgraph "自然语言空间"
        UserQuery["{sys.query}"] -- "模板字符串" --> Component["ExeSQL 组件"]
    end

    subgraph "代码实体空间"
        Component -- "实例化" --> Tool["agent.tools.exesql.ExeSQL"]
        Tool -- "校验" --> Param["agent.tools.exesql.ExeSQLParam"]
        Tool -- "调用" --> Invoke["_invoke"]
        Invoke -- "执行" --> DB["pymysql/psycopg2/pyodbc"]
    end

    subgraph "数据存储"
        DB -- "查询" --> MySQL["MySQL 服务器"]
        DB -- "查询" --> PG["PostgreSQL 服务器"]
    end

来源：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。

安全与故障排除

来源：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