Files

copilot-swe-agent[bot] e263ddf084 Apply @appcypher's recommendations for microsandbox Docker configuration

Co-authored-by: Sun-ZhenXing <44517244+Sun-ZhenXing@users.noreply.github.com>

2026-01-15 07:43:19 +00:00

5.8 KiB

Raw Blame History

MicroSandbox

English Documentation

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：

# 检查 KVM 设备是否存在
ls -l /dev/kvm

# 检查 CPU 虚拟化支持
grep -E 'vmx|svm' /proc/cpuinfo

如果 /dev/kvm 不存在，请确保在 BIOS 中启用了虚拟化，并加载了 KVM 内核模块：

# 加载 KVM 模块（Intel）
sudo modprobe kvm_intel

# 或者 AMD
sudo modprobe kvm_amd

快速开始

复制示例环境文件：
```
cp .env.example .env
```

（可选）编辑 .env 以自定义资源限制：

# 根据需要调整 CPU 和内存
MICROSANDBOX_CPU_LIMIT=4.00
MICROSANDBOX_MEMORY_LIMIT=4G

构建 Docker 镜像：
```
docker compose build
```
运行 MicroSandbox：
```
docker compose run --rm microsandbox
```

使用示例

交互式会话

启动 MicroSandbox 交互式会话：

docker compose run --rm microsandbox

在沙箱中运行命令

在沙箱内执行特定命令：

docker compose run --rm microsandbox run "echo Hello from sandbox"

获取帮助

查看可用命令和选项：

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 以进行硬件虚拟化。映射方式如下：

devices:
  - /dev/kvm:/dev/kvm

确保宿主系统的 KVM 设备具有适当的权限。

架构支持

MicroSandbox 支持两种主要架构：

amd64（x86_64）：Intel 和 AMD 处理器
arm64（aarch64）：基于 ARM 的处理器（例如 AWS Graviton、通过 Linux VM 的 Apple Silicon）

在构建过程中会根据目标平台自动选择正确的二进制文件。

故障排除

KVM 不可用

如果您看到关于 KVM 不可用的错误：

验证在 BIOS 中启用了硬件虚拟化
检查是否加载了 KVM 内核模块：lsmod | grep kvm
确保 /dev/kvm 存在并具有正确的权限
确认您在 Linux 宿主机上运行（而不是 WSL2 或 macOS）

/dev/kvm 权限被拒绝

# 将您的用户添加到 kvm 组
sudo usermod -aG kvm $USER

# 或使用 sudo 运行
sudo docker compose run --rm microsandbox

性能问题

如果您遇到性能缓慢的问题：

在 .env 中增加 CPU 和内存限制
验证 KVM 加速是否正常工作：dmesg | grep kvm
检查宿主系统资源可用性

参考资料

许可证

MicroSandbox 是 Zerocore AI 的开源项目。有关许可证信息，请参阅上游仓库。

5.8 KiB Raw Blame History Unescape Escape