沙盒快速入门

一个专为 RAGFlow 及其他需要隔离代码执行环境的应用设计的、安全的、可插拔的代码执行后端。

功能：

• 与 RAGFlow 无缝集成 — 可与 RAGFlow 的代码组件开箱即用。
• 高安全性 — 使用 gVisor 进行系统调用级别的沙盒化以隔离执行。
• 可定制的沙盒 — 轻松修改 seccomp 配置文件以定制系统调用限制。
• 可插拔的运行时支持 — 可扩展以支持任何编程语言的运行时。
• 开发者友好 — 使用方便的 Makefile 快速设置。

架构

该架构由执行器管理服务管理的、为每种支持的语言运行时提供的隔离 Docker 基础镜像组成。执行器管理器使用 gVisor 进行系统调用拦截，并可选地使用 seccomp 配置文件进行增强的系统调用过滤，从而协调沙盒化的代码执行。

前提条件

• 与 gVisor 兼容的 Linux 发行版。
• 已安装并配置 gVisor。
• Docker 版本 24.0.0 或更高。
• Docker Compose 版本 2.26.1 或更高（与 RAGFlow 要求类似）。
• 已安装 uv 包和项目管理器。
• （可选）GNU Make，用于简化的命令行管理。

构建 Docker 基础镜像

沙盒使用隔离的基础镜像来提供安全的容器化执行环境。

手动构建基础镜像

docker build -t sandbox-base-python:latest ./sandbox_base_image/python
docker build -t sandbox-base-nodejs:latest ./sandbox_base_image/nodejs

或者，使用 Makefile 一次性构建所有基础镜像

make build

接下来，构建执行器管理器镜像

docker build -t sandbox-executor-manager:latest ./executor_manager

与 RAGFlow 一起运行

1. 验证 gVisor 是否已正确安装并可运行。

2. 配置位于 docker/.env 的 .env 文件

• 取消注释与沙盒相关的环境变量。
• 在文件底部启用沙盒配置文件。

3. 将以下条目添加到您的 /etc/hosts 文件中以解析执行器管理器服务

127.0.0.1 sandbox-executor-manager

4. 像往常一样启动 RAGFlow 服务。

独立运行

手动设置

1. 初始化环境变量

cp .env.example .env

2. 使用 Docker Compose 启动沙盒服务

docker compose -f docker-compose.yml up

3. 测试沙盒设置

source .venv/bin/activate
export PYTHONPATH=$(pwd)
uv pip install -r executor_manager/requirements.txt
uv run tests/sandbox_security_tests_full.py

使用 Makefile

用一个命令运行所有设置、构建、启动和测试

make

监控

要跟踪执行器管理器容器的日志

docker logs -f sandbox-executor-manager

或者使用 Makefile 快捷方式

make logs