c03771751c
feat(elasticsearch): upgrade Elasticsearch version to 9.3.0 in environment and docker-compose files feat(gitlab): update GitLab version to 18.8.3-ce.0 in environment and docker-compose files feat(grafana): bump Grafana version to 12.3.2 in environment and docker-compose files feat(jenkins): upgrade Jenkins version to 2.541-lts-jdk17 in environment and docker-compose files fix(minio): remove unnecessary newline in docker-compose file feat(nginx): downgrade Nginx version to 1.28.2-alpine3.22 in environment and docker-compose files feat(ollama): update Ollama version to 0.14.3 in environment and docker-compose files feat(prometheus): upgrade Prometheus version to 3.5.1 in environment and docker-compose files feat(rabbitmq): update RabbitMQ version to 4.2.3-management-alpine in environment and docker-compose files
242 lines
7.1 KiB
Markdown
242 lines
7.1 KiB
Markdown
# OpenSandbox
|
||
|
||
[English](README.md) | 中文
|
||
|
||
一个通用的 AI 应用沙箱平台，提供多语言 SDK、统一的沙箱 API 以及 Docker/Kubernetes 运行时。适用于代码智能体、GUI 智能体、智能体评估、AI 代码执行和强化学习训练等场景。
|
||
|
||
## 功能特性
|
||
|
||
- **多语言 SDK 支持**：提供 Python、JavaScript/TypeScript、Java/Kotlin 和 Go 客户端 SDK
|
||
- **统一的沙箱 API**：为沙箱生命周期、命令执行和文件操作提供一致的接口
|
||
- **多种运行时选项**：支持 Docker 和 Kubernetes 运行时
|
||
- **安全加固**：内置安全特性，包括能力限制、特权提升防护和资源限制
|
||
- **灵活的配置**：支持各种网络模式、资源约束和安全配置
|
||
- **代码解释器**：预构建的镜像，支持 Python、Node.js、Java 和 Go 内核
|
||
|
||
## 快速开始
|
||
|
||
### 前置要求
|
||
|
||
- Docker Engine（Docker 运行时必需）
|
||
- Docker Compose
|
||
- 足够的权限访问 Docker socket
|
||
|
||
> **使用 Colima 的 macOS 用户注意**：您需要在启动 OpenSandbox 之前设置 `DOCKER_HOST` 环境变量：
|
||
>
|
||
> ```bash
|
||
> export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"
|
||
> ```
|
||
|
||
### 部署
|
||
|
||
1. **复制环境文件并根据需要配置：**
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. **编辑 `config.toml` 设置您的 API 密钥：**
|
||
|
||
```toml
|
||
[server]
|
||
api_key = "your-secret-api-key-change-this"
|
||
```
|
||
|
||
**重要**：在生产环境中必须更改默认的 API 密钥！
|
||
|
||
3. **启动服务：**
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
4. **验证服务是否运行：**
|
||
|
||
```bash
|
||
curl http://localhost:8080/health
|
||
```
|
||
|
||
您应该收到成功的健康检查响应。
|
||
|
||
## 配置
|
||
|
||
### 环境变量
|
||
|
||
主要环境变量（完整列表见 [.env.example](.env.example)）：
|
||
|
||
| 变量 | 描述 | 默认值 |
|
||
| ---------------------------------- | -------------------------- | ----------------------------- |
|
||
| `OPENSANDBOX_SERVER_VERSION` | OpenSandbox 服务器镜像版本 | `v1.0.5` |
|
||
| `OPENSANDBOX_SERVER_PORT_OVERRIDE` | 主机端口映射 | `8080` |
|
||
| `DOCKER_HOST` | Docker socket 路径 | `unix:///var/run/docker.sock` |
|
||
| `OPENSANDBOX_SERVER_CPU_LIMIT` | CPU 核心限制 | `2.0` |
|
||
| `OPENSANDBOX_SERVER_MEMORY_LIMIT` | 内存限制 | `2G` |
|
||
|
||
### 服务器配置
|
||
|
||
主配置文件为 [config.toml](config.toml)。主要配置部分：
|
||
|
||
- **[server]**：HTTP 服务器设置（主机、端口、日志级别、API 密钥）
|
||
- **[runtime]**：运行时类型和 execd 镜像配置
|
||
- **[docker]**：Docker 特定设置，包括网络模式和安全选项
|
||
|
||
#### 网络模式
|
||
|
||
- **bridge**（推荐）：容器拥有隔离的网络，支持多个沙箱
|
||
- **host**：容器共享主机网络，一次只能运行一个沙箱实例
|
||
|
||
#### 安全特性
|
||
|
||
- **能力限制**：从容器中移除危险的 Linux 能力
|
||
- **特权提升防护**：阻止容器内的特权提升
|
||
- **进程限制**：控制每个沙箱的最大进程数
|
||
- **AppArmor/Seccomp 配置文件**：可选的安全配置文件（留空使用 Docker 默认值）
|
||
|
||
## 使用方法
|
||
|
||
### 基本沙箱创建（Python SDK）
|
||
|
||
```python
|
||
from opensandbox import Sandbox
|
||
from datetime import timedelta
|
||
|
||
# 创建一个代码解释器沙箱
|
||
sandbox = await Sandbox.create(
|
||
"opensandbox/code-interpreter:v1.0.1",
|
||
entrypoint="/opt/opensandbox/code-interpreter.sh",
|
||
env={"PYTHON_VERSION": "3.11"},
|
||
timeout=timedelta(minutes=10)
|
||
)
|
||
|
||
async with sandbox:
|
||
# 执行 Python 代码
|
||
result = await sandbox.execute(
|
||
"python",
|
||
"-c",
|
||
"print('Hello from OpenSandbox!')"
|
||
)
|
||
print(result.stdout)
|
||
```
|
||
|
||
### API 认证
|
||
|
||
所有 API 请求都需要在 `X-API-Key` 头中包含 `config.toml` 中配置的密钥：
|
||
|
||
```bash
|
||
curl -H "X-API-Key: your-secret-api-key-change-this" \
|
||
http://localhost:8080/sandboxes
|
||
```
|
||
|
||
## 预构建镜像
|
||
|
||
OpenSandbox 提供了几个预构建的沙箱镜像：
|
||
|
||
- **opensandbox/code-interpreter**：多语言代码解释器（Python、Node.js、Java、Go）
|
||
- **opensandbox/vscode**：VS Code Server 环境
|
||
- **opensandbox/desktop**：支持 VNC 的完整桌面环境
|
||
- **opensandbox/playwright**：使用 Playwright 进行浏览器自动化
|
||
- **opensandbox/chrome**：Chromium 浏览器环境
|
||
|
||
## 端口
|
||
|
||
| 端口 | 服务 | 描述 |
|
||
| ---- | ------------------ | --------------- |
|
||
| 8080 | OpenSandbox Server | HTTP API 服务器 |
|
||
|
||
## 数据持久化
|
||
|
||
- **opensandbox_data**：服务器数据和状态
|
||
|
||
## 健康检查
|
||
|
||
该服务在 `/health` 端点提供内置的健康检查：
|
||
|
||
```bash
|
||
curl http://localhost:8080/health
|
||
```
|
||
|
||
## 安全注意事项
|
||
|
||
### Docker Socket 访问
|
||
|
||
此服务需要访问 Docker socket（`/var/run/docker.sock`）以创建和管理沙箱容器。这是一个高权限操作。
|
||
|
||
**安全影响：**
|
||
|
||
- 具有 Docker socket 访问权限的容器可能会控制主机系统
|
||
- 仅在受信任的环境中部署
|
||
- 在生产环境中考虑使用 Docker-in-Docker 或 rootless Docker 以获得额外的隔离
|
||
|
||
**替代方案：**
|
||
|
||
- 使用 Kubernetes 运行时而不是 Docker 运行时（需要 Kubernetes 集群）
|
||
- 使用受限用户权限和资源配额进行部署
|
||
|
||
### API 密钥安全
|
||
|
||
- **切勿在生产环境中使用默认 API 密钥**
|
||
- 安全存储 API 密钥（例如，使用 Docker secrets、密钥管理器的环境变量）
|
||
- 定期轮换 API 密钥
|
||
- 限制网络暴露（使用防火墙规则、反向代理）
|
||
|
||
### 资源限制
|
||
|
||
始终配置适当的 CPU 和内存限制以防止资源耗尽：
|
||
|
||
```yaml
|
||
deploy:
|
||
resources:
|
||
limits:
|
||
cpus: '2.0'
|
||
memory: 2G
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### Docker Socket 连接问题
|
||
|
||
**错误**：Failed to initialize Docker service
|
||
|
||
**解决方案**：
|
||
|
||
- 确保 Docker Desktop/Engine 正在运行
|
||
- 在使用 Colima 的 macOS 上：设置 `DOCKER_HOST=unix://${HOME}/.colima/default/docker.sock`
|
||
- 检查 Docker socket 权限：`ls -l /var/run/docker.sock`
|
||
|
||
### 健康检查失败
|
||
|
||
**错误**：Health check timeout
|
||
|
||
**解决方案**：
|
||
|
||
- 检查容器日志：`docker compose logs opensandbox-server`
|
||
- 验证服务是否成功启动：`docker compose ps`
|
||
- 如果服务需要更多时间初始化，增加 docker-compose.yaml 中的 `start_period`
|
||
|
||
### 沙箱创建失败
|
||
|
||
**错误**：Failed to create sandbox
|
||
|
||
**解决方案**：
|
||
|
||
- 确保 execd 镜像可访问：`docker pull opensandbox/execd:v1.0.5`
|
||
- 检查可用的系统资源（CPU、内存、磁盘空间）
|
||
- 查看服务器日志以获取详细的错误消息
|
||
|
||
## 许可证
|
||
|
||
此项目是 OpenSandbox 套件的一部分。详情请参阅主 [LICENSE](https://github.com/alibaba/OpenSandbox/blob/main/LICENSE) 文件。
|
||
|
||
## 参考资料
|
||
|
||
- [OpenSandbox GitHub 仓库](https://github.com/alibaba/OpenSandbox)
|
||
- [OpenSandbox 文档](https://github.com/alibaba/OpenSandbox/tree/main/docs)
|
||
- [Docker 安全](https://docs.docker.com/engine/security/)
|
||
|
||
## 支持
|
||
|
||
如有问题和疑问：
|
||
|
||
- [GitHub Issues](https://github.com/alibaba/OpenSandbox/issues)
|
||
- [官方文档](https://github.com/alibaba/OpenSandbox)
|