ROMA 项目 E2B 沙箱与 S3 存储集成实战指南：隔离代码执行环境搭建全流程

ROMA 项目 E2B 沙箱与 S3 存储集成实战指南：隔离代码执行环境搭建全流程

【免费下载链接】ROMARecursive-Open-Meta-Agent v0.1 (Beta). A meta-agent framework to build high-performance multi-agent systems.项目地址: https://gitcode.com/GitHub_Trending/roma7/ROMA

导读

本文是 ROMA（Recursive-Open-Meta-Agent）项目中 E2B 代码执行沙箱与 S3 存储集成（docs/E2B_SETUP.md）的深度实战指南。文章将从架构原理出发，完整覆盖环境变量配置、自定义 E2B 模板创建、本地 goofys 挂载、端到端验证、生产部署与故障排查，并结合仓库源码（e2b.py、docker/e2b、scripts/setup_local.sh）与集成测试（test_e2b_integration.py、test_e2e_storage.py）逐层印证。读完本文，你将能够独立搭建一套"主机与沙箱共享同一 S3 存储、Agent 在隔离环境中安全执行代码"的完整运行链路。

一、架构总览：沙箱隔离与共享存储如何共存

E2B 为 ROMA 提供云端隔离的代码执行沙箱，而 S3 通过 goofys（S3 的 FUSE 文件系统实现）挂载成普通目录，使主机与沙箱都能以文件读写的方式访问同一份数据。这套架构的核心价值在于：隔离执行（Agent 生成的代码跑在沙箱内）+ 共享持久化（结果通过 S3 落盘，主机随时可取）。

┌─────────────────────────────────────────────────────────────┐ │ Host System │ │ │ │ ┌────────────┐ ┌─────────────────────────────┐ │ │ │ Agent │────────>│ Toolkit (e.g., DefiLlama) │ │ │ └────────────┘ └─────────────────────────────┘ │ │ │ │ │ │ │ │ │ │ │ ▼ │ │ │ ┌─────────────────────┐ │ │ │ │ FileStorage │ │ │ │ │ (S3 via goofys) │ │ │ │ └─────────────────────┘ │ │ │ │ │ │ ▼ │ │ │ ┌────────────┐ │ │ │ │ E2BToolkit │ │ │ │ └────────────┘ │ │ │ │ │ │ └─────────┼─────────────────────────┼──────────────────────────┘ │ │ │ Same S3 Bucket │ │ │ ┌─────────▼─────────────────────────▼──────────────────────────┐ │ E2B Sandbox │ │ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ start-up.sh: Mounts S3 to /opt/sentient │ │ │ │ via goofys using env vars from host │ │ │ └───────────────────────────────────────────────────┘ │ │ │ │ ┌───────────────────────────────────────────────────┐ │ │ │ Agent-Generated Code Executes │ │ │ │ - Reads from /opt/sentient/executions/... │ │ │ │ - Writes to /opt/sentient/executions/... │ │ │ └───────────────────────────────────────────────────┘ │ │ │ └───────────────────────────────────────────────────────────────┘

在 ROMA 的实际实现中，这一架构由两层代码承载：

• 主机侧：E2BToolkit 负责沙箱生命周期管理与代码执行，FileStorage（见 test_e2e_storage.py 中的导入from roma_dspy.core.storage import FileStorage）负责通过挂载的 S3 路径读写执行产物；
• 沙箱侧：模板启动时执行 mount_s3.sh 将 S3 挂载到$STORAGE_BASE_PATH（默认/opt/sentient），并写入.e2b_ready标记文件表明挂载就绪。

关键设计点：FUSE 挂载不会持久化到模板快照，因此 S3 必须在沙箱运行时挂载。这一点在 template.py 中有明确注释，并由 start_jupyter.sh 在每次沙箱启动时后台执行挂载来完成。

二、前置条件

在开始之前，需要准备三样东西：

1. E2B 账号：在 e2b.dev 注册并获取 API Key。
2. AWS S3 Bucket：创建用于存储的桶，并配置具备 S3 读写权限的 AWS 凭证。
3. E2B CLI（用于模板创建，npm 或 yarn 安装其一即可）：

   npm install -g @e2b/cli # 或 yarn global add @e2b/cli

   仓库的校验脚本 validate_e2b_setup.py 会检查 CLI 版本，要求v2.4.1+，并同时校验e2b（模板构建 SDK）与e2b-code-interpreter（运行时 AsyncSandbox SDK）两个 Python 依赖是否就绪。

三、Step 1：环境变量配置

3.1 配置 .env 文件

将.env.example复制为.env并填写以下内容：

# Storage Configuration STORAGE_BASE_PATH=/opt/sentient ROMA_S3_BUCKET=your-s3-bucket-name AWS_REGION=us-east-1 # AWS Credentials AWS_ACCESS_KEY_ID=your_aws_access_key AWS_SECRET_ACCESS_KEY=your_aws_secret_key # E2B Configuration E2B_API_KEY=your_e2b_api_key E2B_TEMPLATE_ID=roma-dspy-sandbox

各变量的语义与源码落点：

3.2 验证配置

from roma_dspy.config.manager import ConfigManager config = ConfigManager().load_config() print(f"Storage path: {config.storage.base_path}") print(f"S3 bucket: {os.getenv('ROMA_S3_BUCKET')}")

四、Step 2：创建自定义 E2B 模板

模板定义了沙箱的初始环境。为了让沙箱具备 S3 挂载能力，需要创建自定义模板。

4.1 方式一：CLI 初始化模板（文档基线流程）

# 在仓库根目录初始化模板 e2b template init roma-dspy-sandbox

该命令创建.e2b/目录存放模板配置。随后将启动脚本复制进模板并赋予执行权限：

cp docker/e2b/start-up.sh .e2b/start-up.sh chmod +x .e2b/start-up.sh

start-up.sh（沙箱启动时运行）负责：安装 goofys、将 S3 挂载到$STORAGE_BASE_PATH、校验写权限、初始化 Python 依赖。

构建并发布模板：

e2b template build # 输出示例： # ✓ Template built successfully # Template ID: roma-dspy-sandbox-abc123 # 将返回的 Template ID 写入 .env echo "E2B_TEMPLATE_ID=<your-template-id>" >> .env

确认模板已创建：

e2b template list

4.2 方式二：E2B v2 Python SDK 声明式构建（仓库当前实现）

从仓库的 docker/e2b 目录结构看，当前项目采用E2B v2 Python SDK以声明式方式定义模板，这是比 CLI 更可复现、可版本化的方式：

• template.py：基于官方code-interpreter-v1模板扩展（保留 Jupyter 配置），在构建期完成：安装fuse、curl、jq等系统包 → 下载安装 goofys → 写入/etc/fuse.conf的user_allow_other→ 从宿主机注入 AWS 凭证与存储路径到模板环境变量 → 用uv安装requirements.txt依赖 → 复制 mount_s3.sh 与 start_jupyter.sh。模板的ready_cmd会同时检查 Jupyter 健康检查端口和 S3 挂载标记.e2b_ready，两者就绪才认为沙箱可用；
• build_dev.py / build_prod.py：分别以roma-dspy-sandbox-dev/roma-dspy-sandbox为 alias 执行AsyncTemplate.build；
• validate_e2b_setup.py：一站式校验脚本，覆盖环境变量、模板定义导入、E2B CLI/SDK、模板构建、沙箱创建与 S3 挂载读写，支持--skip-build与--skip-s3跳过部分步骤。

建议：生产环境以 template.py + 构建脚本的方式管理模板，实现模板即代码（Template-as-Code）。

4.3 模板验证

# 列出模板（确认 ID 与 .env 中 E2B_TEMPLATE_ID 一致） e2b template list

五、Step 3：本地存储挂载（主机侧）

主机侧同样需要把 S3 挂载到本地，才能让FileStorage直接以文件路径方式读写。

5.1 运行本地设置脚本

chmod +x scripts/setup_local.sh ./scripts/setup_local.sh

该脚本（setup_local.sh）的完整执行逻辑：

1. 加载 .env：读取STORAGE_BASE_PATH、ROMA_S3_BUCKET、AWS_REGION；
2. 探测 goofys：依次检查$HOME/go/bin/goofys（ARM64 兼容构建）、/usr/local/bin/goofys、PATH 中的 goofys，并实际执行--version验证架构可运行；
3. 校验 AWS 凭证：优先使用环境变量中的AWS_ACCESS_KEY_ID，否则要求~/.aws/credentials存在；
4. 确定挂载点：默认挂到$HOME/.roma/s3_mount，若STORAGE_BASE_PATH尚未挂载则创建符号链接STORAGE_BASE_PATH -> 挂载点，保证跨环境路径一致；
5. 挂载 S3：goofys 挂载参数采用1s 的 stat/type cache TTL（注释明确：为加速 HOST ↔ E2B 跨挂载同步）；
6. 验证：创建$STORAGE_BASE_PATH/executions目录并写入测试文件确认写权限。

5.2 验证本地存储

# 检查挂载 mount | grep goofys # 验证目录结构 ls -la /opt/sentient/executions/ # 测试写访问 echo "test" > /opt/sentient/executions/test.txt cat /opt/sentient/executions/test.txt rm /opt/sentient/executions/test.txt

若希望开机自挂载，脚本末尾已提示可加入 crontab：@reboot <repo>/scripts/setup_local.sh。

六、Step 4：测试 E2B 集成

6.1 基础链路测试：主机写入 → 沙箱读取

以下代码演示了完整闭环：主机通过FileStorage写入文件，沙箱内代码经 goofys 挂载读取同一文件。

from roma_dspy.tools.core.e2b import E2BToolkit from roma_dspy.config.manager import ConfigManager from roma_dspy.core.storage import FileStorage # Load config config = ConfigManager().load_config() # Create storage storage = FileStorage( config=config.storage, execution_id="test_e2b_001" ) # Write file on host test_data = b"Hello from host!" await storage.put("test.txt", test_data) print(f"Wrote to: {storage.get_artifacts_path('test.txt')}") # Create E2B toolkit e2b = E2BToolkit() # Read file in E2B sandbox code = f""" import os file_path = '{storage.get_artifacts_path('test.txt')}' print(f'Reading from: {{file_path}}') with open(file_path, 'r') as f: content = f.read() print(f'Content: {{content}}') """ result = e2b.run_python_code(code) print(result)

预期输出（run_python_code始终返回 JSON 字符串，结构见 e2b.py）：

{ "success": true, "results": [], "stdout": [ "Reading from: /opt/sentient/executions/test_e2b_001/artifacts/test.txt", "Content: Hello from host!" ], "stderr": [], "error": null, "sandbox_id": "..." }

6.2 沙箱能力与生命周期（源码级说明）

E2BToolkit 的核心行为：

• 原生异步：基于e2b_code_interpreter.AsyncSandbox，全部工具方法为 async，避免阻塞事件循环，支持多 Agent 并行；
• 懒创建：首次调用工具时才创建沙箱（get_sandbox_status在创建前返回no_sandbox）；
• 健康检查与自动重建：每次操作前_ensure_sandbox_alive检查沙箱存活，死亡时按auto_reinitialize（默认 True）自动重建；
• 24 小时硬限制：E2B 沙箱最长存活 24h，默认max_lifetime_hours=23.5，超时前主动预重启；校验逻辑要求max_lifetime_hours不得超过 24，且不得小于timeout折算的小时数；
• 状态保持：同一沙箱跨多次调用保持文件系统与变量状态（集成测试 test_sandbox_persistence_across_calls 验证了这一点）；
• S3 可选：设置ROMA_S3_BUCKET才启用持久化存储，未设置时沙箱独立运行、功能不受影响。

可用的沙箱工具（由 test_all_tools_available 断言）：run_python_code、run_command、get_sandbox_status、restart_sandbox、upload_file、download_file、list_files、read_file_content、write_file_content、create_directory、install_package、get_sandbox_url。

6.3 运行仓库自带的集成测试

# 运行 E2B 集成测试（需要 E2B_API_KEY，未设置会自动跳过） pytest tests/integration/test_e2b_integration.py -v # 运行端到端存储测试（需要 E2B + S3 全套凭证） pytest tests/integration/test_e2e_storage.py -v

test_e2e_storage.py 覆盖了完整闭环：主机写 → E2B 读 → E2B 处理后写回 → 主机读回，并额外验证了路径一致性（artifacts/temp/results/plots/reports/outputs/logs 七个目录在沙箱内全部存在）、大文件传输（含 10000 元素 JSON）、并发读写与清理逻辑。运行 E2E 测试前需确认E2B_API_KEY、ROMA_S3_BUCKET、AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY四个环境变量全部就绪。

七、Step 5：生产部署

7.1 按环境隔离配置

开发环境（.env.development）：

STORAGE_BASE_PATH=/opt/sentient/dev ROMA_S3_BUCKET=roma-storage-dev E2B_TEMPLATE_ID=roma-dspy-sandbox-dev

生产环境（.env.production）：

STORAGE_BASE_PATH=/opt/sentient/prod ROMA_S3_BUCKET=roma-storage-prod E2B_TEMPLATE_ID=roma-dspy-sandbox-prod

环境隔离的核心收益：存储路径 + 桶名 + 模板 ID 三者同时隔离，杜绝开发数据污染生产数据。

7.2 模板更新流程

修改挂载脚本或沙箱配置后，需重新构建模板：

# 修改 docker/e2b/start-up.sh（或 template.py / mount_s3.sh） cp docker/e2b/start-up.sh .e2b/start-up.sh e2b template build

采用 SDK 方式时则直接执行python docker/e2b/build_prod.py。

八、故障排查

8.1 沙箱无法访问 S3

症状：沙箱内代码执行报文件不存在。排查步骤：

1. 确认环境变量已传入沙箱：

   e2b = E2BToolkit() status = e2b.get_sandbox_status() print(status) # 检查 env vars

   注意get_sandbox_status返回 JSON 中包含template、timeout等信息；若要直接确认沙箱内变量，可参考 test_environment_variables_passed 在沙箱内用os.getenv逐一核验STORAGE_BASE_PATH、ROMA_S3_BUCKET、AWS_*五个变量；

2. 在 E2B Dashboard 查看启动脚本日志；
3. 验证 AWS 凭证有效：

   aws s3 ls s3://$ROMA_S3_BUCKET

8.2 goofys 挂载失败

症状：本地设置脚本失败或挂载点为空。排查步骤：

1. 检查 AWS 凭证：

   aws sts get-caller-identity

2. 确认桶存在：

   aws s3 ls | grep $ROMA_S3_BUCKET

3. 检查 goofys 安装与架构兼容性（ARM64 需使用$HOME/go/bin/goofys的兼容构建，见 setup_local.sh）：

   which goofys goofys --version

8.3 主机与沙箱路径不一致

症状：主机写入的文件在沙箱中看不到。排查步骤：

1. 确认STORAGE_BASE_PATH在.env、本地脚本输出、E2B 启动脚本三处完全一致；
2. 确认两侧挂载的是同一个桶：

   # 本地 mount | grep goofys # E2B（在沙箱内执行） mount | grep goofys

8.4 模板不存在

症状：E2B 工具报 template not found。排查步骤：

1. 确认模板已构建：

   e2b template list

2. 核对.env中E2B_TEMPLATE_ID与模板 ID 一致；
3. 必要时重新构建：

   e2b template build

九、高级配置

9.1 自定义 goofys 挂载参数

编辑挂载脚本中的 goofys 命令可按需调优。仓库默认实现（mount_s3.sh）与本地脚本均采用1s 缓存 TTL，以保证主机与沙箱间的跨挂载同步足够快；若单机吞吐优先，可调大缓存：

goofys \ --region "${AWS_REGION}" \ --stat-cache-ttl 5m \ # 更长缓存，减少元数据往返 --type-cache-ttl 5m \ --max-idle-handles 1000 \ # 更多文件句柄 --dir-mode 0755 \ --file-mode 0644 \ "${S3_BUCKET}" \ "${STORAGE_BASE_PATH}"

注意：沙箱内 mount_s3.sh 使用-o allow_other并设--dir-mode=0777 --file-mode=0666（更宽松），以保证沙箱内不同用户可访问挂载点。

9.2 多套模板（环境级定制）

# 开发模板 e2b template init roma-dspy-dev cp docker/e2b/start-up.sh .e2b/start-up.sh e2b template build # 生产模板（带优化配置） e2b template init roma-dspy-prod # 按需编辑 .e2b/start-up.sh 后 e2b template build

9.3 存储用量监控

from roma_dspy.core.storage import FileStorage storage = FileStorage(config=config.storage, execution_id="exec_123") info = await storage.get_storage_info() print(f"Total size: {info['total_size_mb']} MB") print(f"File count: {info['file_count']}")

十、最佳实践

1. 始终使用 Execution ID 隔离存储：所有产物路径以 execution_id 为作用域，避免多任务数据交叉；
2. 执行后清理临时文件：

   await storage.cleanup_execution_temp_files()

3. 监控成本：跟踪 S3 存储量与 E2B 沙箱使用时长（沙箱按运行时间计费，合理设置timeout与max_lifetime_hours可控制成本）；
4. 模板版本化管理：

   e2b template build --name roma-dspy-prod-v1.0.0

   配合 template.py 的声明式定义，可实现模板变更可审查、可回滚；

5. 严格检查执行结果：run_python_code返回 JSON 字符串，务必解析后检查success字段：

   result = e2b.run_python_code(code) result_data = json.loads(result) if not result_data["success"]: logger.error(f"E2B execution failed: {result_data['error']}")

6. 资源回收：沙箱使用完毕调用aclose()或使用async with上下文管理器，避免沙箱泄漏。

十一、进一步阅读

• 配置指南：配置文件、Agent 与运行时参数
• 快速上手：含just e2b-test/just e2b-build快捷命令
• 部署指南：生产环境整体部署
• E2B Toolkit 源码：沙箱生命周期与全部工具方法实现
• E2B 模板定义 与 构建脚本：模板即代码
• E2E 存储集成测试：主机与沙箱数据链路验证范本

【免费下载链接】ROMARecursive-Open-Meta-Agent v0.1 (Beta). A meta-agent framework to build high-performance multi-agent systems.项目地址: https://gitcode.com/GitHub_Trending/roma7/ROMA