Code 组件 (Code Component)

该组件允许用户在其智能体 (Agent) 中集成 Python 或 JavaScript 代码，以进行动态数据处理。

适用场景 (Scenarios)

当您需要在智能体中集成复杂的代码逻辑（Python 或 JavaScript）以进行动态数据处理时，Code 组件是必不可少的。

前提条件 (Prerequisites)

1. 确保已正确安装 gVisor

我们使用 gVisor 将代码执行与宿主系统进行隔离。请按照官方安装指南安装 gVisor，在继续操作前请确保您的操作系统与之兼容。

2. 确保已正确安装沙箱 (Sandbox)

RAGFlow Sandbox 是一个安全、可插拔的代码执行后端。它作为 Code 组件的代码执行器。请按照此处说明安装 RAGFlow Sandbox。

Docker 客户端版本

执行管理器 (Executor Manager) 镜像现在打包了 Docker CLI 29.1.0 (API 1.44+)。旧版本的镜像使用的是 Docker 24.x，在面对较新的 Docker 守护进程时会报错 client version 1.43 is too old（客户端版本 1.43 太旧）。如果您遇到此错误，请拉取最新的 infiniflow/sandbox-executor-manager:latest，或者在 ./sandbox/executor_manager 中重新构建它。

注意

如果您的 RAGFlow 沙箱 (Sandbox) 无法正常工作，请务必参考本文档中的故障排查部分。我们向您保证，它能解决 99.99% 的问题！

3. （可选）安装所需的依赖项

如果您需要将自己的 Python 或 JavaScript 软件包导入到沙箱 (Sandbox) 中，请按照如何将我自己的 Python 或 JavaScript 包导入沙箱？一节中提供的命令来安装这些额外的依赖项。

4. 在 RAGFlow 中启用沙箱专属设置

确保在 ragflow/docker/.env 中启用了所有与沙箱相关的特定设置。

5. 做出更改后重启服务

对配置或环境的任何更改都需要完全重启服务才能生效。

配置项 (Configurations)

Input (输入)

您可以为 Code 组件指定多个输入源。点击 Input variables (输入变量) 区域中的 + Add variable (添加变量) 以包含所需的输入变量。

Code (代码)

此字段允许您输入并编辑您的源代码。

重要提示

如果您的代码实现中包含已定义的变量（无论是输入变量还是输出变量），请确保它们也在相应的 Input 或 Output 区域中指定。

Python 代码示例

    def main(arg1: str, arg2: str) -> dict:
        return {
            "result": arg1 + arg2,
        }

JavaScript 代码示例


    const axios = require('axios');
    async function main(args) {
      try {
        const response = await axios.get('https://github.com/infiniflow/ragflow');
        console.log('Body:', response.data);
      } catch (error) {
        console.error('Error:', error.message);
      }
    }

Return values (返回值)

您在此处定义 Code 组件的输出变量。

重要提示

如果您在此处定义了输出变量，请确保它们在您的代码实现中也进行了定义；否则，它们的值将为 null。以下是两个示例：

Output (输出)

定义的输出变量将自动在此处填充。

故障排查 (Troubleshooting)

`HTTPConnectionPool(host='sandbox-executor-manager', port=9385): Read timed out.`

根本原因

您未正确安装 gVisor，且 runsc 未被识别为有效的 Docker 运行时 (Runtime)。
您未拉取运行器 (Runners) 所需的基础镜像，因此未启动任何运行器。

解决方案

针对 gVisor 问题：

安装 gVisor。
重启 Docker。

运行以下命令进行复查：

docker run --rm --runtime=runsc hello-world

针对基础镜像问题，拉取所需的基础镜像：

docker pull infiniflow/sandbox-base-nodejs:latest
docker pull infiniflow/sandbox-base-python:latest

`docker: Error response from daemon: client version 1.43 is too old. Minimum supported API version is 1.44`

根本原因

您的执行管理器 (Executor Manager) 镜像使用的是 Docker CLI 24.x (API 1.43)，但宿主机的 Docker 守护进程（例如 Docker 25+ / 29.x）现在需要 API 1.44+。

解决方案

拉取最新的执行管理器镜像，或在 ./sandbox/executor_manager 中重新构建它以升级内置的 Docker 客户端：

docker pull infiniflow/sandbox-executor-manager:latest
# 或者
docker build -t sandbox-executor-manager:latest ./sandbox/executor_manager

`HTTPConnectionPool(host='none', port=9385): Max retries exceeded.`

根本原因

未在 /etc/hosts 中映射 sandbox-executor-manager。

解决方案

在 /etc/hosts 中添加一条新条目：

127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager

`Container pool is busy`

根本原因

所有运行器目前都处于使用状态，正在执行任务。

解决方案

请稍后重试，或在配置中增加连接池大小 (Pool Size)，以提高可用性并减少等待时间。

常见问题 (FAQ)

如何将我自己的 Python 或 JavaScript 包导入沙箱 (Sandbox)？

要导入您的 Python 软件包，请修改 sandbox_base_image/python/requirements.txt 来安装所需的依赖项。例如，要添加 openpyxl 软件包，请执行以下命令行操作：

(ragflow) ➜ ragflow/sandbox main ✓ pwd # 确保您在正确的目录下
/home/infiniflow/workspace/ragflow/sandbox

(ragflow) ➜ ragflow/sandbox main ✓ echo "openpyxl" >> sandbox_base_image/python/requirements.txt # 将软件包写入 requirements.txt 文件

(ragflow) ➜ ragflow/sandbox main ✗ cat sandbox_base_image/python/requirements.txt # 确保软件包已被成功添加
numpy
pandas
requests
openpyxl # 已经在这里了

(ragflow) ➜ ragflow/sandbox main ✗ make # 重新构建 docker 镜像，此命令会重新构建镜像并立即启动服务。若仅需构建镜像，请改用 `make build`。

(ragflow) ➜ ragflow/sandbox main ✗ docker exec -it sandbox_python_0 /bin/bash # 进入容器以检查软件包是否安装成功


# 在容器中
nobody@ffd8a7dd19da:/workspace$ python # 启动 python 终端交互界面
Python 3.11.13 (main, Aug 12 2025, 22:46:03) [GCC 12.2.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import openpyxl # 导入软件包以验证安装
>>>
# 没问题，安装成功！

要导入您的 JavaScript 软件包，请导航至 sandbox_base_image/nodejs 并使用 npm 安装所需的包。例如，要添加 lodash 软件包，请运行以下命令：

(ragflow) ➜ ragflow/sandbox main ✓ pwd
/home/infiniflow/workspace/ragflow/sandbox

(ragflow) ➜ ragflow/sandbox main ✓ cd sandbox_base_image/nodejs

(ragflow) ➜ ragflow/sandbox/sandbox_base_image/nodejs main ✓ npm install lodash 

(ragflow) ➜ ragflow/sandbox/sandbox_base_image/nodejs main ✓ cd ../.. # 回到沙箱根目录

(ragflow) ➜ ragflow/sandbox main ✗ make # 重新构建 docker 镜像，此命令会重新构建镜像并立即启动服务。若仅需构建镜像，请改用 `make build`。

(ragflow) ➜ ragflow/sandbox main ✗ docker exec -it sandbox_nodejs_0 /bin/bash # 进入容器以检查软件包是否安装成功

# 在容器中
nobody@dd4bbcabef63:/workspace$ npm list lodash # 通过 npm list 进行验证
/workspace
`-- lodash@4.17.21 extraneous

nobody@dd4bbcabef63:/workspace$ ls node_modules | grep lodash # 或者通过列出 node_modules 进行验证
lodash

# 没问题，安装成功！