From 5b5ffed819653f074714273b1975b72f5e7462bd Mon Sep 17 00:00:00 2001 From: Sun-ZhenXing <1006925066@qq.com> Date: Sat, 3 Jan 2026 17:10:41 +0800 Subject: [PATCH] feat: add microsandbox --- builds/goose/Dockerfile | 3 +- builds/goose/docker-compose.yaml | 1 + builds/microsandbox/.env.example | 32 ++++ builds/microsandbox/Dockerfile | 52 +++++++ builds/microsandbox/README.md | 188 ++++++++++++++++++++++++ builds/microsandbox/README.zh.md | 188 ++++++++++++++++++++++++ builds/microsandbox/docker-compose.yaml | 69 +++++++++ src/frpc/docker-compose.yaml | 12 ++ src/frps/docker-compose.yaml | 8 +- 9 files changed, 551 insertions(+), 2 deletions(-) create mode 100644 builds/microsandbox/.env.example create mode 100644 builds/microsandbox/Dockerfile create mode 100644 builds/microsandbox/README.md create mode 100644 builds/microsandbox/README.zh.md create mode 100644 builds/microsandbox/docker-compose.yaml diff --git a/builds/goose/Dockerfile b/builds/goose/Dockerfile index 6a5e521..cec98f5 100644 --- a/builds/goose/Dockerfile +++ b/builds/goose/Dockerfile @@ -1,4 +1,5 @@ -FROM debian:bookworm-slim@sha256:b1a741487078b369e78119849663d7f1a5341ef2768798f7b7406c4240f86aef +ARG DEBIAN_VERSION=13.2-slim +FROM debian:${DEBIAN_VERSION} ARG GOOSE_VERSION=1.18.0 ARG TARGETARCH diff --git a/builds/goose/docker-compose.yaml b/builds/goose/docker-compose.yaml index 7fe124d..90cfc8d 100644 --- a/builds/goose/docker-compose.yaml +++ b/builds/goose/docker-compose.yaml @@ -20,6 +20,7 @@ services: - linux/amd64 - linux/arm64 args: + - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2-slim} - GOOSE_VERSION=${GOOSE_VERSION:-1.18.0} image: ${GLOBAL_REGISTRY:-}alexsuntop/goose:${GOOSE_VERSION:-1.18.0} environment: diff --git a/builds/microsandbox/.env.example b/builds/microsandbox/.env.example new file mode 100644 index 0000000..2c5912a --- /dev/null +++ b/builds/microsandbox/.env.example @@ -0,0 +1,32 @@ +# MicroSandbox Configuration +# KVM-based secure sandbox environment + +# Global registry prefix (optional) +# Leave empty to pull from Docker Hub +GLOBAL_REGISTRY= + +# MicroSandbox version +# Default: 0.2.6 +MICROSANDBOX_VERSION=0.2.6 + +# Auto pull base images on build +# Default: true +MICROSANDBOX_AUTO_PULL_IMAGES=true + +# Timezone +# Default: UTC +TZ=UTC + +# ============================================ +# Resource Limits +# ============================================ + +# CPU limits +# MicroSandbox requires more CPU for KVM virtualization +MICROSANDBOX_CPU_LIMIT=4.00 +MICROSANDBOX_CPU_RESERVATION=1.00 + +# Memory limits +# MicroSandbox requires more memory for running VMs +MICROSANDBOX_MEMORY_LIMIT=4G +MICROSANDBOX_MEMORY_RESERVATION=1G diff --git a/builds/microsandbox/Dockerfile b/builds/microsandbox/Dockerfile new file mode 100644 index 0000000..f207a17 --- /dev/null +++ b/builds/microsandbox/Dockerfile @@ -0,0 +1,52 @@ +ARG DEBIAN_VERSION=13.2-slim +FROM debian:${DEBIAN_VERSION} + +ARG DEBIAN_FRONTEND=noninteractive +ARG MICROSANDBOX_VERSION=0.2.6 +ARG TARGETARCH + +RUN apt update && \ + apt install -y --no-install-recommends \ + ca-certificates \ + curl && \ + apt clean && \ + rm -rf /var/lib/apt/lists/* + +# Download and install microsandbox binary based on architecture +RUN ARCH=${TARGETARCH:-amd64} && \ + case "${ARCH}" in \ + amd64) MICROSANDBOX_ARCH="x86_64" ;; \ + arm64) MICROSANDBOX_ARCH="aarch64" ;; \ + *) echo "Unsupported architecture: ${ARCH}" && exit 1 ;; \ + esac && \ + curl -fsSL "https://github.com/zerocore-ai/microsandbox/releases/download/microsandbox-v${MICROSANDBOX_VERSION}/microsandbox-${MICROSANDBOX_VERSION}-linux-${MICROSANDBOX_ARCH}.tar.gz" \ + -o /tmp/microsandbox.tar.gz && \ + mkdir -p /usr/local/bin /usr/local/lib && \ + tar -xzf /tmp/microsandbox.tar.gz -C /tmp && \ + cd /tmp/microsandbox-${MICROSANDBOX_VERSION}-linux-${MICROSANDBOX_ARCH} && \ + mv ms* /usr/local/bin/ && \ + mv *.so.* /usr/local/lib/ && \ + chmod +x /usr/local/bin/ms* && \ + rm -rf /tmp/microsandbox* + +# Setup directories for root user +RUN mkdir -p /root/.local/bin /root/.local/lib /root/.microsandbox + +# Set up environment variables (based on setup_env.sh) +ENV PATH="/root/.local/bin:/usr/local/bin:${PATH}" +ENV LD_LIBRARY_PATH="/root/.local/lib:/usr/local/lib:${LD_LIBRARY_PATH}" +ENV HOME="/root" + +WORKDIR /root + +ARG MICROSANDBOX_AUTO_PULL_IMAGES=true +RUN if [ "${MICROSANDBOX_AUTO_PULL_IMAGES}" = "true" ]; then \ + msb pull microsandbox/python && \ + msb pull microsandbox/node; \ + fi + +VOLUME [ "/root/.microsandbox/namespaces" ] + +# Default to microsandbox CLI +ENTRYPOINT ["/usr/local/bin/msb"] +CMD ["server", "start", "--host", "0.0.0.0", "--port", "5555"] diff --git a/builds/microsandbox/README.md b/builds/microsandbox/README.md new file mode 100644 index 0000000..a44d509 --- /dev/null +++ b/builds/microsandbox/README.md @@ -0,0 +1,188 @@ +# MicroSandbox + +[中文文档](README.zh.md) + +MicroSandbox is a KVM-based secure sandbox environment developed by Zerocore AI. It provides isolated, lightweight virtual machines for running untrusted code safely using hardware-level virtualization. + +## Features + +- **KVM-Based Virtualization**: Leverages hardware virtualization for strong isolation +- **Lightweight**: Minimal overhead compared to traditional VMs +- **Secure**: Hardware-level isolation protects the host system +- **Fast Startup**: Quick VM initialization for rapid testing +- **Multi-Architecture**: Support for both x86_64 (amd64) and ARM64 (aarch64) platforms + +## Prerequisites + +- Docker and Docker Compose installed +- Hardware virtualization support (KVM): + - Intel VT-x or AMD-V enabled in BIOS + - `/dev/kvm` device available on the host +- Linux host system (KVM is Linux-specific) +- Privileged container access (required for KVM) + +### Check KVM Support + +Before running MicroSandbox, verify that your system supports KVM: + +```bash +# Check if KVM device exists +ls -l /dev/kvm + +# Check CPU virtualization support +grep -E 'vmx|svm' /proc/cpuinfo +``` + +If `/dev/kvm` doesn't exist, ensure virtualization is enabled in your BIOS and the KVM kernel module is loaded: + +```bash +# Load KVM module (Intel) +sudo modprobe kvm_intel + +# Or for AMD +sudo modprobe kvm_amd +``` + +## Quick Start + +1. Copy the example environment file: + + ```bash + cp .env.example .env + ``` + +2. (Optional) Edit `.env` to customize resource limits: + + ```bash + # Adjust CPU and memory as needed + MICROSANDBOX_CPU_LIMIT=4.00 + MICROSANDBOX_MEMORY_LIMIT=4G + ``` + +3. Build the Docker image: + + ```bash + docker compose build + ``` + +4. Run MicroSandbox: + + ```bash + docker compose run --rm microsandbox + ``` + +## Usage Examples + +### Interactive Session + +Start an interactive session with MicroSandbox: + +```bash +docker compose run --rm microsandbox +``` + +### Run a Command in Sandbox + +Execute a specific command inside the sandbox: + +```bash +docker compose run --rm microsandbox run "echo Hello from sandbox" +``` + +### Get Help + +View available commands and options: + +```bash +docker compose run --rm microsandbox --help +``` + +## Configuration + +### Environment Variables + +| Variable | Description | Default | +| --------------------------------- | ------------------------------ | ------- | +| `MICROSANDBOX_VERSION` | MicroSandbox version | `0.2.6` | +| `MICROSANDBOX_AUTO_PULL_IMAGES` | Auto pull base images on build | `true` | +| `MICROSANDBOX_PORT_OVERRIDE` | Port mapping for MicroSandbox | `5555` | +| `TZ` | Container timezone | `UTC` | +| `MICROSANDBOX_CPU_LIMIT` | Maximum CPU cores | `4.00` | +| `MICROSANDBOX_CPU_RESERVATION` | Reserved CPU cores | `1.00` | +| `MICROSANDBOX_MEMORY_LIMIT` | Maximum memory allocation | `4G` | +| `MICROSANDBOX_MEMORY_RESERVATION` | Reserved memory | `1G` | + +### Volume Mounts + +- `microsandbox_config`: MicroSandbox configuration and state +- `microsandbox_workspace`: Working directory for sandbox operations + +## Security Considerations + +### Privileged Mode + +MicroSandbox requires `privileged: true` to access KVM devices. This is necessary for hardware virtualization but grants the container elevated privileges. Consider the following: + +- Only run MicroSandbox on trusted systems +- Review the code you plan to execute in the sandbox +- Keep the MicroSandbox image updated with security patches +- Use network isolation if running untrusted code + +### KVM Device Access + +The container requires access to `/dev/kvm` for hardware virtualization. This is mapped as: + +```yaml +devices: + - /dev/kvm:/dev/kvm +``` + +Ensure your host system's KVM device has appropriate permissions. + +## Architecture Support + +MicroSandbox supports both major architectures: + +- **amd64** (x86_64): Intel and AMD processors +- **arm64** (aarch64): ARM-based processors (e.g., AWS Graviton, Apple Silicon via Linux VM) + +The correct binary is automatically selected during the build process based on your target platform. + +## Troubleshooting + +### KVM Not Available + +If you see errors about KVM not being available: + +1. Verify hardware virtualization is enabled in BIOS +2. Check if KVM kernel module is loaded: `lsmod | grep kvm` +3. Ensure `/dev/kvm` exists and has correct permissions +4. Confirm you're running on a Linux host (not WSL2 or macOS) + +### Permission Denied on /dev/kvm + +```bash +# Add your user to the kvm group +sudo usermod -aG kvm $USER + +# Or run with sudo +sudo docker compose run --rm microsandbox +``` + +### Performance Issues + +If you experience slow performance: + +- Increase CPU and memory limits in `.env` +- Verify KVM acceleration is working: `dmesg | grep kvm` +- Check host system resource availability + +## References + +- [MicroSandbox GitHub Repository](https://github.com/zerocore-ai/microsandbox) +- [Zerocore AI](https://zerocore.ai/) +- [KVM Documentation](https://www.linux-kvm.org/) + +## License + +MicroSandbox is an open-source project by Zerocore AI. Please refer to the [upstream repository](https://github.com/zerocore-ai/microsandbox) for license information. diff --git a/builds/microsandbox/README.zh.md b/builds/microsandbox/README.zh.md new file mode 100644 index 0000000..cff12d5 --- /dev/null +++ b/builds/microsandbox/README.zh.md @@ -0,0 +1,188 @@ +# 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 版本 | `0.2.6` | +| `MICROSANDBOX_AUTO_PULL_IMAGES` | 构建时自动拉取基础镜像 | `true` | +| `MICROSANDBOX_PORT_OVERRIDE` | MicroSandbox 端口映射 | `5555` | +| `TZ` | 容器时区 | `UTC` | +| `MICROSANDBOX_CPU_LIMIT` | CPU 核心数上限 | `4.00` | +| `MICROSANDBOX_CPU_RESERVATION` | CPU 核心数预留 | `1.00` | +| `MICROSANDBOX_MEMORY_LIMIT` | 最大内存分配 | `4G` | +| `MICROSANDBOX_MEMORY_RESERVATION` | 内存预留 | `1G` | + +### 卷挂载 + +- `microsandbox_config`：MicroSandbox 配置和状态 +- `microsandbox_workspace`：沙箱操作的工作目录 + +## 安全注意事项 + +### 特权模式 + +MicroSandbox 需要 `privileged: true` 以访问 KVM 设备。这对于硬件虚拟化是必需的，但会授予容器提升的权限。请考虑以下事项： + +- 仅在受信任的系统上运行 MicroSandbox +- 审查您计划在沙箱中执行的代码 +- 保持 MicroSandbox 镜像更新以获取安全补丁 +- 如果运行不受信任的代码，请使用网络隔离 + +### 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)。 diff --git a/builds/microsandbox/docker-compose.yaml b/builds/microsandbox/docker-compose.yaml new file mode 100644 index 0000000..eba9a6a --- /dev/null +++ b/builds/microsandbox/docker-compose.yaml @@ -0,0 +1,69 @@ +# Docker Compose Configuration for MicroSandbox +# KVM-based secure sandbox environment +# https://github.com/zerocore-ai/microsandbox + +x-defaults: &defaults + restart: unless-stopped + logging: + driver: json-file + options: + max-size: 100m + max-file: 3 + +services: + microsandbox: + <<: *defaults + build: + context: . + dockerfile: Dockerfile + platforms: + - linux/amd64 + - linux/arm64 + args: + - DEBIAN_VERSION=${DEBIAN_VERSION:-13.2-slim} + - MICROSANDBOX_VERSION=${MICROSANDBOX_VERSION:-0.2.6} + - MICROSANDBOX_AUTO_PULL_IMAGES=${MICROSANDBOX_AUTO_PULL_IMAGES:-true} + image: ${GLOBAL_REGISTRY:-}alexsuntop/microsandbox:${MICROSANDBOX_VERSION:-0.2.6} + ports: + - ${MICROSANDBOX_PORT_OVERRIDE:-5555}:${MICROSANDBOX_PORT:-5555} + privileged: true + cap_add: + - SYS_ADMIN + - NET_ADMIN + - SYS_PTRACE + - SYS_RESOURCE + security_opt: + - apparmor=unconfined + - seccomp=unconfined + environment: + - TZ=${TZ:-UTC} + - MICROSANDBOX_HOME=/root/.microsandbox + volumes: + - microsandbox_config:/root/.microsandbox/namespaces + - microsandbox_workspace:/workspace + devices: + - /dev/kvm:/dev/kvm + - /dev/net/tun:/dev/net/tun + command: + [ + "server", + "start", + "--host", + "0.0.0.0", + "--port", + "${MICROSANDBOX_PORT:-5555}", + "--dev", + ] + working_dir: /workspace + deploy: + resources: + limits: + cpus: ${MICROSANDBOX_CPU_LIMIT:-4.00} + memory: ${MICROSANDBOX_MEMORY_LIMIT:-4G} + reservations: + cpus: ${MICROSANDBOX_CPU_RESERVATION:-1.00} + memory: ${MICROSANDBOX_MEMORY_RESERVATION:-1G} + +volumes: + microsandbox_config: + microsandbox_workspace: diff --git a/src/frpc/docker-compose.yaml b/src/frpc/docker-compose.yaml index ebba719..09cc76e 100644 --- a/src/frpc/docker-compose.yaml +++ b/src/frpc/docker-compose.yaml @@ -34,3 +34,15 @@ services: reservations: cpus: ${FRPC_CPU_RESERVATION:-0.1} memory: ${FRPC_MEMORY_RESERVATION:-64M} + healthcheck: + test: + [ + "CMD", + "sh", + "-c", + "curl -f http://$${FRP_ADMIN_USER}:$${FRP_ADMIN_PASSWORD}@localhost:$${FRP_ADMIN_PORT}/api/status || exit 1", + ] + interval: 30s + timeout: 10s + retries: 3 + start_period: 10s diff --git a/src/frps/docker-compose.yaml b/src/frps/docker-compose.yaml index ed44278..0f13f56 100644 --- a/src/frps/docker-compose.yaml +++ b/src/frps/docker-compose.yaml @@ -36,7 +36,13 @@ services: cpus: ${FRPS_CPU_RESERVATION:-0.1} memory: ${FRPS_MEMORY_RESERVATION:-64M} healthcheck: - test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:${FRP_ADMIN_PORT:-7500}/"] + test: + [ + "CMD", + "sh", + "-c", + "curl -f http://$${FRP_ADMIN_USER}:$${FRP_ADMIN_PASSWORD}@localhost:$${FRP_ADMIN_PORT}/api/serverinfo || exit 1", + ] interval: 30s timeout: 10s retries: 3