内容
<p align="center">
<img src="logo.png" alt="NexusBox Logo" width="220" />
</p>
<h1 align="center">NexusBox</h1>
<p align="center">
<strong>AI 代理沙盒，支持 MCP 集成</strong>
</p>
<p align="center">
<a href="README_zh.md">中文</a> •
<a href="#features">功能</a> •
<a href="#quick-start">快速开始</a> •
<a href="#docker-deployment">Docker 部署</a> •
<a href="#mcp-tools">MCP 工具</a> •
<a href="#trae-integration">Trae 集成</a> •
<a href="#api-reference">API 参考</a> •
<a href="#security">安全性</a> •
<a href="#multi-tenancy">多租户</a>
</p>
<p align="center">
<a href="docs/quick-start-guide.md">快速开始指南（英文）</a> •
<a href="docs/quick-start-guide_zh.md">快速开始指南（中文）</a>
</p>
---
## 什么是 NexusBox？
NexusBox 是一个专为 AI 代理设计的**企业级沙盒平台**。它提供了一个完全隔离的执行环境，允许 AI 代理执行实际操作 — 执行 shell 命令、读取/写入文件、运行代码和自动化浏览器 — **而不会对主机造成任何风险**。
与只支持 `curl` 或 `docker exec` 的简单演示沙盒不同，NexusBox 实现了 **模型上下文协议（MCP）**，以公开 18 种 AI 代理可以自主调用的真实工具。当与 Trae、Claude Desktop 或 Cursor 等 AI 编码助手集成时，NexusBox 将它们从文本生成器转变为可以在隔离的工作空间中安全执行危险操作的**自主代理**。
### 为什么选择 NexusBox？
| 问题 | NexusBox 解决方案 |
|---------|-------------------|
| AI 代理无法执行真实命令 | 18 种 MCP 工具，用于 shell、文件、代码、浏览器操作 |
| 运行 AI 生成的代码会使主机面临风险 | 工作空间隔离，路径遍历保护 |
| 没有代理-工具交互的标准协议 | MCP（模型上下文协议）- 行业标准 |
| 演示沙盒仅支持 `curl` | 完整的开发环境：Python、Node.js、Chromium、Jupyter、VS Code |
| 没有多租户隔离 | 每个租户的工作空间、网络策略、资源配额 |
| 黑盒执行，无可观察性 | 健康检查、结构化日志记录、Prometheus 指标 |
---
## 功能
### 核心能力
- **Shell 执行** - 同步或后台运行任何 shell 命令，支持超时控制
- **文件操作** - 在沙盒工作空间中读取、写入、列出、搜索、替换、删除和移动文件
- **代码执行** - 运行 Python 和 Node.js 代码，支持临时文件处理和超时限制
- **浏览器自动化** - 通过 CDP（Chrome DevTools Protocol）导航、截图、点击、输入和执行 JavaScript
- **端口代理** - 将 HTTP 流量转发到沙盒中进行 Web 服务测试
### 企业功能
- **MCP（模型上下文协议）** - 用于 AI 代理集成的 JSON-RPC 2.0 标准接口
- **多租户隔离** - 每个租户的工作空间、网络策略和资源配额
- **安全强化** - 路径遍历保护、权限降低、rootless 模式、seccomp
- **完整的开发环境** - JupyterLab、code-server（浏览器中的 VS Code）、Chromium、noVNC 桌面
- **可观察性** - 健康检查、结构化日志记录、Prometheus 指标、审计日志记录
- **优雅的生命周期** - 状态机管理、资源清理的优雅关闭
---
## 快速开始
### 选项 1：原生二进制（快速，无 Docker）
前提条件：[Go 1.22+](https://go.dev/dl/)
```bash
# 克隆仓库
git clone https://github.com/nexusbox/nexusbox.git
cd nexusbox
# 设置 Go 代理（中国用户）
export GOPROXY=https://goproxy.cn,direct
# 构建
go build -o nexusbox-agent ./cmd/sandbox-dev
# 运行
./nexusbox-agent \
-port=8080 \
-mcp-port=8079 \
-proxy-port=6081 \
-workspace=/path/to/your/workspace \
-log-level=info
```
### 2：Docker Compose（完整环境）
参见下面的 [Docker 部署](#docker-deployment)。
### 验证
```bash
# 健康检查
curl http://localhost:8080/healthz
# 预期：ok
# 列出 MCP 工具
curl -X POST http://localhost:8079/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
# 通过 MCP 执行 shell 命令
curl -X POST http://localhost:8079/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"shell_exec","arguments":{"command":"echo Hello NexusBox && whoami"}},"id":2}'
```
---
## Docker 部署
### 前提条件
- Docker 20.10+
- Docker Compose 2.0+
### 构建和启动
```bash
cd nexusbox
# 构建和启动（首次构建约 30 分钟）
docker-compose -f deploy/docker/docker-compose.yaml up --build -d
# 查看启动日志（等待“NexusBox Sandbox - Ready”）
docker logs -f nexusbox-sandbox
# 健康检查
curl http://localhost:8080/healthz
```
### 服务端口
| 端口 | 服务 | URL | 描述 |
|------|---------|-----|-------------|
| 8080 | 网关 API | http://localhost:8080 | 所有操作的 REST API |
| 8079 | MCP 中心 | http://localhost:8079/mcp | AI 代理的 MCP 端点 |
| 6080 | noVNC | http://localhost:6080 | 基于 Web 的远程桌面 |
| 8888 | JupyterLab | http://localhost:8888 | Python 笔记本环境 |
| 8200 | code-server | http://localhost:8200 | 浏览器中的 VS Code |
| 6081 | 端口代理 | http://localhost:6081/proxy/ | HTTP 端口转发 |
### 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `WORKSPACE` | `/home/sandbox` | 沙盒工作空间目录 |
| `LOG_LEVEL` | `info` | 日志级别：debug、info、warn、error |
| `HOST_PORT` | `8080` | 网关 API 主机端口映射 |
| `MCP_PORT` | `8079` | MCP 中心主机端口映射 |
| `VNC_PORT` | `6080` | noVNC 主机端口映射 |
| `JUPYTER_PORT` | `8888` | JupyterLab 主机端口映射 |
| `CODE_SERVER_PORT` | `8200` | code-server 主机端口映射 |
| `PROXY_SERVER` | _(empty)_ | 出站请求的 HTTP 代理 |
| `JWT_PUBLIC_KEY` | _(empty)_ | 身份验证的 JWT 公钥 |
### 自定义配置
```bash
# 运行自定义端口和工作空间
HOST_PORT=9080 MCP_PORT=9079 WORKSPACE=/data/projects \
docker-compose -f deploy/docker/docker-compose.yaml up -d
```
### 部署后测试
容器运行后，运行这些测试以验证所有服务：
```bash
# 1. 网关健康检查
curl http://localhost:8080/healthz
# 预期：ok
# 2. 系统环境
curl http://localhost:8080/v1/system/env
# 3. 列出所有 MCP 工具（应返回 18 种工具）
curl -s -X POST http://localhost:8079/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python3 -m json.tool
# 4. 执行 shell 命令
curl -s -X POST http://localhost:8079/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"shell_exec","arguments":{"command":"uname -a && whoami && pwd"}},"id":2}'
# 5. 写入和读取文件
curl -s -X POST http://localhost:8079/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"file_write","arguments":{"path":"test.txt","content":"Hello from NexusBox!"}},"id":3}'
curl -s -X POST http://localhost:8079/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"file_read","arguments":{"path":"test.txt"}},"id":4}'
# 6. 运行 Python 代码
curl -s -X POST http://localhost:8079/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"code_run","arguments":{"language":"python","code":"import platform; print(f\"Running on {platform.platform()}\")"}},"id":5}'
# 7. 运行 Node.js 代码
curl -s -X POST http://localhost:8079/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"code_run","arguments":{"language":"nodejs","code":"console.log(`Node.js ${process.version} on ${process.platform}`)"}},"id":6}'
# 8. 验证路径遍历保护（应被阻止）
curl -s -X POST http://localhost:8079/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"file_read","arguments":{"path":"../../etc/passwd"}},"id":7}'
# 预期："路径在工作空间之外"
# 9. 测试网关 REST API
curl -s -X POST http://localhost:8080/v1/shell/exec \
-H "Content-Type: application/json" \
-d '{"command":"ls -la /home/sandbox"}'
curl -s -X POST http://localhost:8080/v1/code/execute \
-H "Content-Type: application/json" \
-d '{"language":"python","code":"print(2+3)"}'
# 10. 检查 noVNC 桌面（在浏览器中打开）
# http://localhost:6080
# 11. 检查 JupyterLab（在浏览器中打开）
# http://localhost:8888
# 12. 检查 code-server（在浏览器中打开）
# http://localhost:8200
```
### 停止和清理
```bash
# 停止容器
docker-compose -f deploy/docker/docker-compose.yaml down
# 停止并删除卷（删除所有工作空间数据）
docker-compose -f deploy/docker/docker-compose.yaml down -v
```
---
## MCP 工具
NexusBox 通过 `http://localhost:8079/mcp` 端点公开 18 种工具，均使用 JSON-RPC 2.0 格式。
### Shell 工具
| 工具 | 描述 | 关键参数 |
|------|-------------|---------------|
| `shell_exec` | 同步执行 shell 命令 | `command`、`timeout`（最大 300s）、`workDir` |
| `shell_background` | 在后台启动长时间运行的命令 | `command`、`id` |
| `shell_check` | 检查后台命令的状态 | `id` |
**示例 - 执行命令：**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "shell_exec",
"arguments": {
"command": "git clone https://github.com/example/repo.git && cd repo && make build",
"timeout": 120,
"workDir": "/home/sandbox"
}
},
"id": 1
}
```
### 文件工具
| 工具 | 描述 | 关键参数 |
|------|-------------|---------------|
| `file_read` | 读取文件内容 | `path`、`offset`、`limit` |
| `file_write` | 写入文件内容 | `path`、`content`、`append` |
| `file_list` | 列出目录内容 | `path`、`recursive` |
| `file_search` | 搜索文件中的文本 | `path`、`pattern`、`filePattern` |
| `file_replace` | 查找并替换文件中的文本 | `path`、`search`、`replace`、`replaceAll` |
| `file_delete` | 删除文件或目录 | `path`、`recursive` |
| `file_move` | 移动或重命名文件 | `source`、`destination` |
**示例 - 写入和读取文件：**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "file_write",
"arguments": {
"path": "src/main.py",
"content": "from http.server import HTTPServer, BaseHTTPRequestHandler\n\nclass Handler(BaseHTTPRequestHandler):\n def do_GET(self):\n self.send_response(200)\n self.end_headers()\n self.wfile.write(b'Hello from NexusBox!')\n\nHTTPServer(('0.0.0.0', 8080), Handler).serve_forever()"
}
},
"id": 1
}
```
### 代码工具
| 工具 | 描述 | 关键参数 |
|------|-------------|---------------|
| `code_run` | 执行 Python 或 Node.js 代码 | `language`（python/nodejs）、`code`、`timeout`（最大 120s） |
| `code_install` | 安装包 | `language`（python/nodejs）、`packages` |
**示例 - 运行 Python 代码：```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "code_run",
"arguments": {
"language": "python",
"code": "import json\nprint(json.dumps({'status': 'ok', 'value': 42}, indent=2)",
"timeout": 10
}
},
| 工具 | 描述 | 关键参数 |
|------|-------------|---------------|
| `browser_navigate` | 导航到 URL | `url` |
| `browser_screenshot` | 捕获截图 | _(无)_ |
| `browser_click` | 点击元素 | `selector` |
| `browser_type` | 在元素中输入文本 | `selector`、`text` |
| `browser_eval` | 执行 JavaScript | `expression` |
| `browser_get_text` | 获取页面文本内容 | `selector` |
**示例 - 导航并截图：**
```json
{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "browser_navigate",
"arguments": { "url": "https://example.com" }
},
"id": 1
}
```
> **注意：** 浏览器工具需要 Chromium 通过 CDP 运行在端口 9222 上（包含在 Docker 部署中）。
---
## Trae 集成
NexusBox 设计为与 **Trae**（以及其他 MCP 兼容的 AI 助手）无缝协作。当配置 Trae 的 AI 使用 NexusBox 的 MCP 工具而不是其内置工具时，提供**沙盒执行**，保护您的主机安全。
### 步骤 1：启动 NexusBox
```bash
# 选项 A：原生二进制
./nexusbox-agent -port=8080 -mcp-port=8079 -proxy-port=6081 -workspace=/path/to/workspace
# 选项 B：Docker
docker-compose -f deploy/docker/docker-compose.yaml up -d
```
### 2：配置 Trae
在您的**项目根目录**中创建 `.trae/mcp.json`：
```json
{
"mcpServers": {
"nexusbox": {
"url": "http://localhost:8079/mcp",
"transport": "http"
}
}
}
```
### 步骤 3：Trae 中启用项目级 MCP
1. 打开 Trae 设置
2. 导航到 **MCP** 部分
3. 在 **"导入设置"**下，启用：**"启动项目级 MCP，允许从项目根目录的 .trae/mcp.json 文件自动加载 MCP 配置"**
4. 重新加载窗口：`Ctrl+Shift+P` → `Reload Window`
### 步骤 4：Trae 中使用 NexusBox 工具
在 Trae AI 聊天中，使用明确请求 NexusBox MCP 工具的提示：
```
请仅使用 nexusbox MCP 工具完成以下任务。
不要使用 LS、Read 或 RunCommand 等内置工具。
可用的 nexusbox 工具：
- shell_exec：在沙盒中执行 shell 命令
- file_read / file_write：读写沙盒工作空间中的文件
- file_list：列出目录内容
- code_run：执行 Python 或 Node.js 代码
- browser_navigate / browser_screenshot：浏览器自动化
任务：[您的任务]
```
### 如何验证 NexusBox 是否正常工作
| 指示器 | NexusBox MCP 活动 | 内置工具活动 |
|-----------|--------------------|-----------------------|
| 工具名称 | `file_list`、`shell_exec`、`code_run` | `LS`、`Read`、`RunCommand` |
| 执行路径 | 通过 `localhost:8079/mcp` 的 HTTP | 直接本地执行 |
| 路径遍历 | **阻止**（仅限工作空间） | 无保护 |
| 隔离 | 沙盒工作空间 | 主机访问权限 |
### Trae 示例提示
**创建并运行 Python 项目：**
```
仅使用 nexusbox MCP 工具。不要使用 LS、Read 或 RunCommand。
1. 使用 file_write 在 src/app.py 中创建简单的 HTTP 服务器
2. 使用 code_run 执行它（超时：5 秒）
3. 使用 shell_exec 验证服务器已启动
```
**分析代码库：**
```
仅使用 nexusbox MCP 工具。不要使用 LS、Read 或 RunCommand。
1. 使用 file_list 探索项目结构
2. 使用 file_read 读取关键源文件
3. 使用 shell_exec 运行测试
4. 使用 file_replace 修复失败的测试
```
**CI/CD 模拟：**
```
仅使用 nexusbox MCP 工具。不要使用 LS、Read 或 RunCommand。
模拟 CI/CD 管道：
1. 使用 shell_exec 创建项目目录
2. 使用 file_write 创建应用程序代码和 Dockerfile
3. 使用 code_run 运行单元测试
4. 使用 shell_exec 模拟 docker build 和部署
```
---
## API 参考
### 网关 REST API（端口 8080）
| 方法 | 端点 | 描述 |
|--------|----------|-------------|
| GET | `/healthz` | 健康检查 |
| POST | `/v1/shell/exec` | 执行 shell 命令 |
| POST | `/v1/shell/sessions` | 创建 shell 会话 |
| POST | `/v1/file/read` | 读取文件 |
| POST | `/v1/file/write` | 写入文件 |
| POST | `/v1/file/list` | 列出目录 |
| POST | `/v1/code/execute` | 执行代码（Python/Node.js） |
| POST | `/v1/browser/navigate` | 导航浏览器 |
| POST | `/v1/browser/screenshot` | 截取屏幕截图 |
| POST | `/v1/sandboxes` | 创建沙盒实例 |
| GET | `/v1/sandboxes` | 列出沙盒实例 |
| GET | `/v1/system/env` | 系统环境信息 |
| GET | `/v1/metrics` | Prometheus 指标 |
### MCP 端点（端口 8079）
| 方法 | 描述 |
|--------|-------------|
| `initialize` | 初始化 MCP 连接 |
| `tools/list` | 列出所有可用工具 |
| `tools/call` | 调用工具 |
| `resources/list` | 列出资源（空） |
| `prompts/list` | 列出提示（空） |
| `ping` | 健康检查 |
所有 MCP 请求均使用 JSON-RPC 2.0 格式通过 HTTP POST 发送到 `/mcp`。
---
## 安全性
### 工作空间隔离
所有文件操作都限制在沙盒工作空间内。`resolvePath()` 函数防止路径遍历攻击：
```
# 这是被阻止的：
file_read("../../etc/passwd")
→ 错误："路径在工作空间之外"
# 这可行（在工作空间内）：
file_read("src/main.py")
→ 返回文件内容
```
### Docker 安全强化
Docker 部署应用了多个安全层：
```yaml
security_opt:
- no-new-privileges:true # 防止权限提升
cap_drop:
- ALL # 丢弃所有 Linux 功能
cap_add:
- CHOWN # 只添加需要的功能
- DAC_OVERRIDE
- FOWNER
- SETGID
- SETUID
- NET_BIND_SERVICE
mem_limit: "8g" # 内存限制
shm_size: "2gb" # Chromium 的共享内存
```
### 命令执行安全性
- Shell 命令有 **最大 300 秒超时时间**
- 代码执行有 **最大 120 秒超时时间**
- 后台进程被跟踪，可以监控
- 代码执行后，所有临时文件都被清理
---
## 多租户
NexusBox 支持企业部署的多租户隔离。
### 隔离级别
| 级别 | 资源过度提交 | 节点策略 | 用例 |
|-------|-------------------|----------------|----------|
| `标准` | 100% | 共享节点 | 开发 |
| `增强` | 50% | 首选节点 | 生产 |
| `最大` | 0% | 专用节点 | 合规（金融/医疗保健） |
### 租户配置
```go
tenant := &v1alpha1.Tenant{
ObjectMeta: metav1.ObjectMeta{Name: "tenant-a"},
Spec: v1alpha1.TenantSpec{
DisplayName: "团队 A",
IsolationLevel: v1alpha1.IsolationLevelMaximum,
ResourceQuota: v1alpha1.TenantResourceQuota{
CPU: "64",
Memory: "128Gi",
MaxInstances: 100,
MaxInstancesPerNode: 50,
},
NetworkPolicy: &v1alpha1.TenantNetworkPolicy{
AllowInterTenantCommunication: false,
},
},
}
```
### 户隔离保证
- **文件隔离**: 每个租户的工作空间都是隔离的，租户之间禁止路径穿越
- **网络隔离**: 默认禁用租户之间的通信
- **资源隔离**: 每个租户的 CPU、内存和实例数量配额都受到限制
- **节点隔离**: 在 `Maximum` 级别可以为租户分配专用节点
---
## 项目结构
```
NexusBox/
├── cmd/
│ ├── sandbox-dev/ # 本地开发入口
│ ├── sandbox-agent/ # 代理守护进程
│ ├── sandbox-manager/ # 集群管理器
│ └── sandbox-scheduler/ # 调度器
├── pkg/
│ ├── mcp/ # MCP 中心和工具服务器
│ │ ├── hub.go # MCP 中心（JSON-RPC 2.0 路由器）
│ │ ├── shell_server.go # Shell 执行工具
│ │ ├── file_server.go # 文件操作工具
│ │ ├── code_server.go # 代码执行工具
│ │ └── browser_server.go # 浏览器自动化工具
│ ├── gateway/ # REST API 网关
│ ├── proxy/ # 端口代理
│ ├── tenant/ # 多租户管理
│ ├── security/ # 安全（mTLS，无根，权限）
│ ├── sandbox/ # 沙盒生命周期和运行时
│ ├── scheduler/ # 调度框架和插件
│ ├── cri/ # CRI（容器运行时接口）
│ ├── observability/ # 指标，跟踪，健康检查，审计
│ └── ... # 其他包
├── deploy/
│ ├── docker/
│ │ ├── Dockerfile # 多阶段 Docker 构建
│ │ ├── docker-compose.yaml
│ │ ├── supervisord.conf # 进程管理器配置
│ │ └── nexusbox-entrypoint.sh
│ ├── k8s/ # Kubernetes CRDs 和部署
│ └── config/ # 配置文件
├── .trae/
│ └── mcp.json # Trae MCP 配置
├── logo.png
└── go.mod
```
---
## 技术栈
| 组件 | 技术 |
|-----------|------------|
| 语言 | Go 1.22 |
| 协议 | MCP（模型上下文协议）/ JSON-RPC 2.0 |
| 容器运行时 | containerd / runc / gVisor |
| 浏览器自动化 | Chromium + CDP（Chrome DevTools 协议） |
| 代码执行 | Python 3 + Node.js 22 |
| 桌面 | TigerVNC + noVNC |
| IDE | code-server（浏览器中的 VS Code） |
| 笔记本 | JupyterLab |
| 进程管理器 | Supervisor |
| 容器编排 | Docker Compose / Kubernetes |
| 监控 | Prometheus + OpenTelemetry |
| 存储 | etcd / OverlayFS |
---
## 许可证
MIT 许可证
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器