sandbox
项目概述
sandbox 是一个基于 Go 语言开发的轻量级沙箱环境，用于安全地执行代码，支持 Python 和 Node.js 等运行时。该项目主要用于低代码框架的测试和验证，提供了网络访问控制、资源限制等安全特性。
功能特点
- 多语言支持：内置支持 Python 和 Node.js 运行时，其他运行时可以通过 RegisterRuntime 注册。
- 网络控制：
- 支持允许/阻止互联网访问
- 支持允许特定端口监听
- 支持 IP 白名单和黑名单
- 资源限制：
- CPU 使用率限制
- 内存使用限制
- SWAP 限制
- /dev/shm 和 /tmp 大小限制
- 环境配置：支持自定义环境变量
- 安全隔离：提供安全的执行环境，防止恶意代码影响系统
- 跨平台支持：支持 Linux 和 macOS 操作系统
- 状态管理：支持沙箱状态持久化和恢复
项目架构
核心代码结构
sandbox/
├── plugin.go # 插件入口，注册 sandbox 模块到 gojs 框架
├── sandbox.go # 定义沙箱的核心结构和配置
├── master.go # 管理沙箱的生命周期和状态
├── runtime.go # 运行时管理
├── sandbox_linux.go # Linux 平台实现
├── sandbox_darwin.go # macOS 平台实现
├── pythonRuntime.go # Python 运行时实现
├── nodejsRuntime.go # Node.js 运行时实现
├── util.go # 工具函数
├── base_test.js # 测试入口文件
├── testcase/ # 测试用例目录
│ ├── base_allow.py # 允许模式测试
│ ├── base_deny.py # 拒绝模式测试
│ ├── secret.py # 敏感信息测试
│ └── base_allow.js # Node.js 环境测试
└── README.md # 项目说明文档
核心组件
-
Plugin 模块：
- 注册 sandbox 模块到 gojs 框架
- 提供 Start、Fetch、Query 等 API 接口
- 管理沙箱的启动和恢复
-
Sandbox 核心：
- 定义沙箱的配置结构（Config）
- 管理沙箱的状态和生命周期
- 提供资源限制和网络控制功能
-
运行时管理：
- 支持 Python 和 Node.js 运行时
- 处理不同运行时的启动和配置
-
平台适配：
- Linux 平台实现（sandbox_linux.go）
- macOS 平台实现（sandbox_darwin.go）
技术实现
沙箱隔离机制
- 文件系统隔离：使用挂载点和只读挂载
- 网络隔离：通过 namespace 机制控制网络访问
- 资源限制：使用 cgroups（Linux）或等效机制限制资源使用
- 进程隔离：创建独立的进程环境
核心 API
| API | 说明 |
|---|---|
| Start(config) | 创建并启动新的沙箱实例 |
| Fetch(id) | 根据 ID 获取沙箱实例 |
| Query(name) | 根据名称查询沙箱实例 |
| Sandbox.status() | 获取沙箱状态 |
| Sandbox.wait(timeout) | 等待沙箱执行完成 |
| Sandbox.kill() | 终止沙箱进程（适用于服务类或运行过久的场景，简单一次性场景不需要调用） |
安装与使用
基本使用
- 导入 sandbox 模块：
import sandbox from 'apigo.cc/gojs/sandbox'
- 配置并启动沙箱：
const sb = sandbox.start({
projectDir: "data",
runtime: { language: "python", venv: "test", version: "3.12" },
startArgs: ["-c", "print('Hello, sandbox!')"],
network: {
allowInternet: true,
allowListen: [19999]
},
limits: { cpu: 0.5, mem: 0.2 }
})
- 等待执行完成：
sb.wait(10000) // 等待最多 10 秒
- 查看执行状态：
const status = sb.status()
console.log(status)
配置选项
| 选项 | 类型 | 说明 |
|---|---|---|
| Name | string | 沙盒名称 |
| projectDir | string | 宿主机的工作目录（自动映射到沙盒内workDir） |
| workDir | string | 沙盒内的工作目录 |
| envs | map[string]string | 环境变量，支持$变量 |
| volumes | []Volume | 挂载列表 |
| limits | Limits | 资源限制 |
| network | struct | 网络配置 |
| gpu | struct | GPU 配置 |
| extraOptions | []string | 额外参数 |
| autoStart | bool | 是否自动启动沙盒进程 |
| startCmd | string | 启动命令 |
| startArgs | []string | 启动参数 |
| runtime | struct | 运行时配置 |
| noLog | bool | 是否不显示沙盒运行日志 |
资源限制配置
| 选项 | 类型 | 说明 |
|---|---|---|
| Cpu | float64 | CPU 核心限制 (如 0.5) |
| Mem | float64 | 内存限制 (单位: GB) |
| Swap | float64 | SWAP 限制 (单位: GB) |
| Shm | uint | /dev/shm 大小 (单位: MB) |
| Tmp | uint | /tmp 大小 (单位: MB) |
网络配置
| 选项 | 类型 | 说明 |
|---|---|---|
| AllowInternet | bool | 是否允许出站网络连接 |
| AllowLocalNetwork | bool | 是否允许访问本地网络 |
| AllowListen | []int | 允许监听端口列表 |
| AllowList | []string | 允许出站访问的 IP/端口 列表 |
| BlockList | []string | 拒绝访问的 IP/端口 列表 |
测试说明
运行测试
go test -v .
测试用例说明
-
base_allow.py：测试允许模式下的功能，包括：
- 内存使用限制（128M 允许，512M 拒绝）
- CPU 使用率限制
- 网络监听（允许特定端口）
- 网络访问（允许互联网访问，阻止特定 IP）
- 环境变量配置
- 外部依赖安装（cowsay）
-
base_deny.py：测试拒绝模式下的功能，包括：
- 网络监听（只允许特定端口）
- 网络访问（只允许白名单 IP 和端口）
-
secret.py：测试敏感信息处理
-
base_allow.js：测试 Node.js 环境下的功能
压力测试
测试脚本还包含了压力测试，会并发执行多个沙箱实例，测试系统的稳定性和性能。
日志管理
沙盒内的stdout会自动重定向到日志文件，stderr也会被重定向到日志文件。
日志存储在 [projectDir]/logs/ 目录中，包括：
- 标准输出日志（stdout_*.log）
- 标准错误日志（stderr_*.log）
注意事项
-
macOS 限制：macOS 系统不支持某些 Linux 特有的功能，如 cgroup 限制和 IP 过滤。测试脚本会自动检测操作系统并调整测试逻辑。
-
资源限制：在 macOS 上，资源限制（CPU 和内存）不会生效。
-
网络限制：在 macOS 上，网络细化限制（IP 过滤）不会生效。
-
权限要求：在 Linux 上，建议以 root 权限运行，否则也能运行但部分功能会受限。
许可证
本项目采用 MIT 许可证，详见 LICENSE 文件。