沙箱快速上手 (Sandbox Quickstart)

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

特性 (Features)

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

架构设计 (Architecture)

该架构包含针对每个受支持语言运行时的隔离 Docker 基础镜像，并由执行管理器 (Executor Manager) 服务进行管理。执行管理器通过使用 gVisor 拦截系统调用来编排沙箱化的代码执行，并可选用 seccomp 配置文件以提供增强的系统调用过滤。

前提条件 (Prerequisites)

与 gVisor 兼容的 Linux 发行版。
已安装并配置 gVisor。
Docker 25.0 或更高版本 (API 1.44+)。确保您的执行管理器镜像内置了 29.1.0 或更高版本的 Docker CLI，以保持与最新 Docker 守护进程 (Daemons) 的兼容性。
Docker Compose 2.26.1 或更高版本（与 RAGFlow 的要求一致）。
已安装 uv 包与项目管理器。
（可选）用于简化命令行管理的 GNU Make。

注意

错误信息 client version 1.43 is too old. Minimum supported API version is 1.44 表明您执行管理器镜像中内置的 Docker CLI 版本低于当前使用的 Docker 守护进程所要求的 29.1.0。要解决此问题，请从 Docker Hub 拉取最新的 infiniflow/sandbox-executor-manager:latest，或在 ./sandbox/executor_manager 中重新构建它。

构建 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 运行

验证 gVisor 是否已正确安装并正常运行。
配置位于 docker/.env 的 .env 文件：
- 取消注释与沙箱 (Sandbox) 相关的环境变量。
- 在文件底部启用 sandbox profile。
在您的 /etc/hosts 文件中添加以下条目，以解析执行管理器服务：
```
127.0.0.1 es01 infinity mysql minio redis sandbox-executor-manager
```
照常启动 RAGFlow 服务。

独立运行

手动设置

初始化环境变量：
```
cp .env.example .env
```
使用 Docker Compose 启动沙箱服务：
```
docker compose -f docker-compose.yml up
```

测试沙箱设置：

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

监控 (Monitoring)

跟踪执行管理器制造容器的日志：

docker logs -f sandbox-executor-manager

或者使用 Makefile 快捷方式：

make logs