199 lines
5.8 KiB
Markdown
199 lines
5.8 KiB
Markdown
# MicroSandbox
|
||
|
||
[English Documentation](README.md)
|
||
|
||
MicroSandbox 是由 Zerocore AI 开发的基于 KVM 的安全沙箱环境。它使用硬件级虚拟化技术提供隔离的轻量级虚拟机，用于安全地运行不受信任的代码。
|
||
|
||
## 特性
|
||
|
||
- **基于 KVM 的虚拟化**：利用硬件虚拟化实现强隔离
|
||
- **轻量级**：相比传统虚拟机开销更小
|
||
- **安全**：硬件级隔离保护宿主系统
|
||
- **快速启动**：虚拟机初始化快速，便于快速测试
|
||
- **多架构支持**：支持 x86_64（amd64）和 ARM64（aarch64）平台
|
||
|
||
## 前置要求
|
||
|
||
- 已安装 Docker 和 Docker Compose
|
||
- 硬件虚拟化支持（KVM）：
|
||
- 在 BIOS 中启用 Intel VT-x 或 AMD-V
|
||
- 宿主机上可用 `/dev/kvm` 设备
|
||
- Linux 宿主系统（KVM 是 Linux 特有的）
|
||
- 特权容器访问权限（KVM 需要）
|
||
|
||
### 检查 KVM 支持
|
||
|
||
在运行 MicroSandbox 之前，请验证您的系统支持 KVM：
|
||
|
||
```bash
|
||
# 检查 KVM 设备是否存在
|
||
ls -l /dev/kvm
|
||
|
||
# 检查 CPU 虚拟化支持
|
||
grep -E 'vmx|svm' /proc/cpuinfo
|
||
```
|
||
|
||
如果 `/dev/kvm` 不存在，请确保在 BIOS 中启用了虚拟化，并加载了 KVM 内核模块：
|
||
|
||
```bash
|
||
# 加载 KVM 模块（Intel）
|
||
sudo modprobe kvm_intel
|
||
|
||
# 或者 AMD
|
||
sudo modprobe kvm_amd
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
1. 复制示例环境文件：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
2. （可选）编辑 `.env` 以自定义资源限制：
|
||
|
||
```bash
|
||
# 根据需要调整 CPU 和内存
|
||
MICROSANDBOX_CPU_LIMIT=4.00
|
||
MICROSANDBOX_MEMORY_LIMIT=4G
|
||
```
|
||
|
||
3. 构建 Docker 镜像：
|
||
|
||
```bash
|
||
docker compose build
|
||
```
|
||
|
||
4. 运行 MicroSandbox：
|
||
|
||
```bash
|
||
docker compose run --rm microsandbox
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 交互式会话
|
||
|
||
启动 MicroSandbox 交互式会话：
|
||
|
||
```bash
|
||
docker compose run --rm microsandbox
|
||
```
|
||
|
||
### 在沙箱中运行命令
|
||
|
||
在沙箱内执行特定命令：
|
||
|
||
```bash
|
||
docker compose run --rm microsandbox run "echo Hello from sandbox"
|
||
```
|
||
|
||
### 获取帮助
|
||
|
||
查看可用命令和选项：
|
||
|
||
```bash
|
||
docker compose run --rm microsandbox --help
|
||
```
|
||
|
||
## 配置
|
||
|
||
### 环境变量
|
||
|
||
| 变量 | 描述 | 默认值 |
|
||
| --------------------------------- | ------------------------ | ----------- |
|
||
| `MICROSANDBOX_VERSION` | MicroSandbox 版本 | `latest` |
|
||
| `DEBIAN_VERSION` | Debian 基础镜像版本 | `13.2-slim` |
|
||
| `MICROSANDBOX_AUTO_PULL_IMAGES` | 构建时自动拉取基础镜像 | `true` |
|
||
| `MICROSANDBOX_DEV_MODE` | 启用开发模式（无需 API 密钥） | `true` |
|
||
| `MICROSANDBOX_PORT` | 容器内部端口 | `5555` |
|
||
| `MICROSANDBOX_PORT_OVERRIDE` | 外部主机端口映射 | `5555` |
|
||
| `TZ` | 容器时区 | `UTC` |
|
||
| `MICROSANDBOX_CPU_LIMIT` | CPU 核心数上限 | `4` |
|
||
| `MICROSANDBOX_CPU_RESERVATION` | CPU 核心数预留 | `1` |
|
||
| `MICROSANDBOX_MEMORY_LIMIT` | 最大内存分配 | `4G` |
|
||
| `MICROSANDBOX_MEMORY_RESERVATION` | 内存预留 | `1G` |
|
||
|
||
### 卷挂载
|
||
|
||
- `microsandbox_namespaces`：MicroSandbox 命名空间配置和虚拟机状态
|
||
- `microsandbox_workspace`：沙箱操作的工作目录
|
||
|
||
## 安全注意事项
|
||
|
||
### 特权模式
|
||
|
||
MicroSandbox 需要 `privileged: true` 以访问 KVM 设备。这对于硬件虚拟化是必需的，但会授予容器提升的权限。请考虑以下事项:
|
||
|
||
- 仅在受信任的系统上运行 MicroSandbox
|
||
- 审查您计划在沙箱中执行的代码
|
||
- 保持 MicroSandbox 镜像更新以获取安全补丁
|
||
- 如果运行不受信任的代码，请使用网络隔离
|
||
- 在生产环境中，通过设置 `MICROSANDBOX_DEV_MODE=false` 禁用开发模式
|
||
|
||
**为什么需要特权模式？**
|
||
|
||
MicroSandbox 使用 KVM（基于内核的虚拟机）来提供硬件级隔离。与共享主机内核的 Docker 容器不同，MicroSandbox 创建具有自己内核的真实虚拟机。这提供了更强的安全边界，即使 Docker 容器本身以特权模式运行。
|
||
|
||
特权容器只是协调器——实际的不受信任代码在具有硬件强制边界的隔离虚拟机内运行。此架构专门设计用于安全地运行不受信任的代码。
|
||
|
||
### KVM 设备访问
|
||
|
||
容器需要访问 `/dev/kvm` 以进行硬件虚拟化。映射方式如下：
|
||
|
||
```yaml
|
||
devices:
|
||
- /dev/kvm:/dev/kvm
|
||
```
|
||
|
||
确保宿主系统的 KVM 设备具有适当的权限。
|
||
|
||
## 架构支持
|
||
|
||
MicroSandbox 支持两种主要架构：
|
||
|
||
- **amd64**（x86_64）：Intel 和 AMD 处理器
|
||
- **arm64**（aarch64）：基于 ARM 的处理器（例如 AWS Graviton、通过 Linux VM 的 Apple Silicon）
|
||
|
||
在构建过程中会根据目标平台自动选择正确的二进制文件。
|
||
|
||
## 故障排除
|
||
|
||
### KVM 不可用
|
||
|
||
如果您看到关于 KVM 不可用的错误：
|
||
|
||
1. 验证在 BIOS 中启用了硬件虚拟化
|
||
2. 检查是否加载了 KVM 内核模块：`lsmod | grep kvm`
|
||
3. 确保 `/dev/kvm` 存在并具有正确的权限
|
||
4. 确认您在 Linux 宿主机上运行（而不是 WSL2 或 macOS）
|
||
|
||
### /dev/kvm 权限被拒绝
|
||
|
||
```bash
|
||
# 将您的用户添加到 kvm 组
|
||
sudo usermod -aG kvm $USER
|
||
|
||
# 或使用 sudo 运行
|
||
sudo docker compose run --rm microsandbox
|
||
```
|
||
|
||
### 性能问题
|
||
|
||
如果您遇到性能缓慢的问题：
|
||
|
||
- 在 `.env` 中增加 CPU 和内存限制
|
||
- 验证 KVM 加速是否正常工作：`dmesg | grep kvm`
|
||
- 检查宿主系统资源可用性
|
||
|
||
## 参考资料
|
||
|
||
- [MicroSandbox GitHub 仓库](https://github.com/zerocore-ai/microsandbox)
|
||
- [Zerocore AI](https://zerocore.ai/)
|
||
- [KVM 文档](https://www.linux-kvm.org/)
|
||
|
||
## 许可证
|
||
|
||
MicroSandbox 是 Zerocore AI 的开源项目。有关许可证信息，请参阅[上游仓库](https://github.com/zerocore-ai/microsandbox)。
|