Sandbox All-in-One

一个集成了代码执行沙盒（Code Interpreter）和浏览器自动化工具（Browser Tool）的一体化 Docker 镜像项目。

项目概述

Sandbox All-in-One 是一个完整的开发沙盒环境，集成了以下核心服务：

• Code Interpreter: 代码执行沙盒服务，支持 Python、JavaScript 等多种语言
• Browser Tool: 浏览器自动化服务，基于 Playwright + Chromium
• Jupyter Server: 交互式代码编辑和执行环境
• VNC Server: 远程桌面访问，可视化查看浏览器运行
• Nginx: 统一 API 网关，提供统一访问入口
• Supervisord: 进程管理和监控

所有服务通过 Nginx 统一对外暴露，使用 Supervisord 进行进程管理。

项目结构

sandbox-allinone/
├── binary/                          # 编译后的二进制文件目录
│   ├── sandbox-code-interpreter-*   # Code Interpreter 二进制
│   └── sandbox-browsertool-*        # Browser Tool 二进制
├── docker/                          # Docker 镜像构建配置
│   ├── 000-base/                    # 基础镜像层
│   ├── 001-sandbox-code-interpreter-base-env/  # Code Interpreter 基础环境
│   ├── 002-sandbox-code-interpreter/           # Code Interpreter 服务
│   ├── 003-sandbox-browsertool-base-env/       # Browser Tool 基础环境
│   ├── 004-sandbox-browsertool/                # Browser Tool 服务
│   ├── 005-sandbox-all-in-one/                 # 完整集成镜像
│   ├── 006-user-custom/                        # 用户自定义层
│   └── bake/                                   # Docker Buildx Bake 配置
├── tests/                           # E2E 测试
├── Makefile                         # 构建脚本
└── README.md                        # 本文档

环境要求

必需工具

• Docker: 20.10+ （用于构建镜像）
• Docker Buildx: 用于多架构构建
• Make: 用于执行构建命令
• Git: 用于获取版本信息

可选工具

• uv: Python 包管理工具（用于运行 E2E 测试）

构建指南

快速开始

最简单的构建方式（AMD64 架构）：

make bake

详细步骤

构建 Docker 镜像

AMD64 架构（默认）:

make bake

此命令会按顺序构建以下镜像层：

1. 000-base - 基础镜像
2. 001-sandbox-code-interpreter-base-env - Code Interpreter 基础环境（Jupyter）
3. 002-sandbox-code-interpreter - Code Interpreter 服务
4. 003-sandbox-browsertool-base-env - Browser Tool 基础环境
5. 004-sandbox-browsertool - Browser Tool 服务
6. 005-sandbox-all-in-one - 完整集成镜像

ARM64 架构:

make bake-arm64

包含用户自定义层:

make bake-with-custom

此命令会额外构建： 7. 006-user-custom - 用户自定义层（可在 docker/006-user-custom/ 中添加自定义配置）

验证构建结果

# 列出所有构建的镜像
make list-images

版本信息

构建时会自动从 Git 获取版本信息：

• 版本号: 从 Git tag 获取（如 v1.0.0），如果没有 tag 则使用 dev
• 提交哈希: Git commit SHA（短格式）
• 构建时间: UTC 时间戳

版本信息会注入到 Docker 镜像标签中。

高级用法

使用 Docker Buildx Bake 直接构建

# 构建单个镜像层
docker buildx bake -f docker/bake/prod.hcl base

# 构建所有层
docker buildx bake -f docker/bake/prod.hcl all-layers

# 构建完整镜像（包含用户自定义层）
docker buildx bake -f docker/bake/prod.hcl with-user-custom

清理构建缓存

make clean

此命令会：

• 清理 Docker 构建缓存
• 清理错误的构建产物

使用镜像

启动容器

docker run -d \
  --name sandbox-all-in-one \
  --shm-size=2g \
  --security-opt seccomp=unconfined \
  -p 5000:5000 \
  -p 8888:8888 \
  -p 5901:5901 \
  005-sandbox-all-in-one:latest

端口说明

端口	服务	说明
5000	Nginx	统一 API 网关入口（所有服务）
8888	Jupyter	Jupyter Server（可直接访问或通过 Nginx）
5901	VNC	VNC Server（使用 VNC 客户端连接）

查看服务状态

# 查看所有服务状态
docker exec -it sandbox-all-in-one supervisorctl status

# 查看服务日志
docker exec -it sandbox-all-in-one supervisorctl tail -f all

更多使用说明请参考 005-sandbox-all-in-one/README.md。

测试

E2E 测试

# 初始化测试环境
make test-setup

# 运行所有测试
make test-all

# 运行 API 测试
make test-apis

Makefile 命令参考

命令	说明
make help	显示所有可用命令
make bake	构建基础镜像 (000-005, AMD64)
make bake-arm64	构建基础镜像 (000-005, ARM64)
make bake-with-custom	构建完整镜像（包含用户自定义层，000-006, AMD64）
make clean	清理构建缓存
make list-images	列出所有构建的镜像
make test-setup	使用 uv 初始化测试环境
make test-all	运行所有 E2E 测试
make test-apis	运行 API 测试

相关文档

• 005-sandbox-all-in-one 详细文档 - 完整集成服务的详细说明
• 006-user-custom 文档 - 用户自定义层使用说明

故障排查

Docker 构建失败

1. 检查 Docker 和 Docker Buildx 是否正常安装
2. 确保有足够的磁盘空间
3. 尝试清理构建缓存：make clean
4. 确保 binary/ 目录中存在所需的二进制文件

许可证

请查看项目根目录的许可证文件。