跳到主要内容

沙盒快速入门

为 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 文件：

  • 取消注释沙盒相关的环境变量。
  • 在文件底部启用沙盒配置文件。
  1. 在您的 /etc/hosts 文件中添加以下条目以解析执行器管理器服务：
127.0.0.1 sandbox-executor-manager
  1. 像往常一样启动 RAGFlow 服务。

独立运行​

手动设置​

  1. 初始化环境变量：
cp .env.example .env
  1. 使用 Docker Compose 启动沙盒服务：
docker compose -f docker-compose.yml up
  1. 测试沙盒设置：
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