`Vpod`

快速入门 • 文档 • 问题 • 参与贡献

demo

什么是 `vpod`？

vpod 是一个轻量级、可移植的沙箱，为不受信任的进程提供即时的 Linux 环境。它采用 RISC‑V 架构，完全运行在 WebAssembly 内部。

快速启动：不到一秒即可启动。
可移植：无需任何安装配置即可在任何地方运行。
隔离性：所有执行状态都保留在 WASM 沙箱内。

工作原理

vpod 运行一个完整的 RISC‑V 系统（RV64GC，单 vCPU），该系统被编译为 WebAssembly。在其内部启动了一个带有真实用户空间的真实 Linux 内核，因此 shell、工具和守护进程的行为与在真实硬件上完全一致。

快照。 vpod 并非从头启动 Linux，而是恢复一个快照：即在启动后立即捕获的机器状态（CPU 寄存器、RAM、文件系统）。恢复一个快照只需远不到一秒。挂起（Suspend）的工作原理则相反，只有脏内存页会被写回磁盘，因此你可以暂停一个沙箱并在之后恢复它，甚至可以从另一个进程恢复。

提前翻译（AOT）。 纯逐指令仿真速度很慢，而 WebAssembly 又排除了运行时 JIT 的可能。因此，在快照构建时，最热门的客户代码路径会从 RISC‑V 翻译成本机代码，并编译进 WASM 模块本身。在运行时，当客户代码匹配时，仿真器会分派到这些已翻译的代码块；不匹配时则回退到解释器。对于 CPU 密集型工作负载，这大约能带来 5 倍的提升，且对隔离性毫无影响：翻译后的代码与解释执行的代码一样，都要经过相同的 MMU 和内存检查。

WASI 边界。 WASM 组件仅通过 WASI 0.2 与宿主机通信。客户机永远看不到宿主机的文件描述符、套接字或内存：文件系统访问通过显式挂载的目录进行，网络访问则通过组件内部的用户态网络协议栈，该协议栈只会向宿主机请求普通的出站套接字。其他一切（客户内核、进程、内存）都存在于 WASM 线性内存中，并随之消亡。

RV64GC 规范

G（通用扩展）

I：基础 64 位整数指令集。
M：硬件乘法和除法，适用于哈希和加密。
A：原子操作，用于线程安全的程序。
F/D：单精度和双精度浮点，适用于科学计算和机器学习推理。

C（压缩指令） 将代码体积减少 30%，提高指令获取速度和内存效率。在我们内存受限的 WASM 环境中运行完整 Linux 用户空间时，这一点非常重要。

[!NOTE] 未实现 V（向量）扩展。RVV 指令将作为模拟的 RISC-V 执行；没有对宿主机 CPU 的 SIMD 透传。添加 V 会增加仿真开销，而对向量化工作负载没有任何性能收益。

快速开始

Python SDK

pip install vpod

from vpod import Sandbox

# Run a command
sandbox = Sandbox.create()
result = sandbox.commands.run("whoami")
print(result.stdout)  # root
sandbox.close()

# Persistent session — state preserved across calls
with Sandbox.create() as sandbox:
    sandbox.commands.run("export API_KEY=secret")
    result = sandbox.commands.run("echo $API_KEY")
    print(result.stdout)  # secret

# Python REPL — variables persist
with Sandbox.create() as sandbox:
    sandbox.code.run("import requests")
    sandbox.code.run("data = [1, 2, 3]")
    result = sandbox.code.run("print(sum(data))")
    print(result.text)  # 6

[!IMPORTANT] 首次调用 Sandbox.create() 会下载默认快照（alpine），如果本地尚未存在，则会将其缓存到本地。

CLI

curl -fsSL https://install.vpod.sh | sh

或通过 PowerShell（Windows）安装
irm https://install.vpod.sh | iex

# Pull a snapshot
vpod pull alpine:latest

# Start an interactive shell
vpod

文档

访问 Vpod 文档。

限制

仿真开销：WebAssembly 内部没有硬件虚拟化，因此所有客户代码都是模拟执行的。开销完全取决于工作负载：I/O 密集型和网络密集型工作几乎可以达到原生速度，而重度 CPU 密集型工作即使经过 AOT 翻译也会明显变慢。如果你的工作负载主要是“运行工具、读取文件、调用 API”，你不会察觉到差异。
无 GPU 访问：CUDA、Metal 和硬件机器学习加速器不可用。未来可能会通过 wasi-nn 添加支持。

参与贡献

欢迎各种贡献，从 bug 报告到新设备支持。在构建实质性内容之前，请先开启一个 issue 进行讨论。

前置要求

Rust（最新稳定版），包含 wasm32-wasip2 目标：rustup target add wasm32-wasip2
Python 3.10+，用于 SDK
Zig（0.16）和 bsdtar，仅在自己构建快照时需要

开发环境配置

# One-time: generate the AOT stub (a fresh clone has no translated blocks)
./scripts/aot-stub.sh

# Build the WASM component (library + CLI)
./scripts/build-wasm.sh

# Install the host CLI
cargo install --path crates/vpod

# Install the Python SDK in dev mode
pip install -e "sdks/python[dev]"

运行测试

CI 会在每个 PR 上运行这些检查，因此推送前请先运行：

cargo fmt --all -- --check                        # formatting
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all                                  # Rust tests

# Python SDK integration tests (needs the WASM library in place)
cp target/wasm32-wasip2/release/vpod_wasi_lib.wasm sdks/python/vpod/
pytest sdks/python/tests/ -v -m integration

构建快照

该项目使用来自 registry.vpod.sh 的预构建 Alpine 快照，因此通常不需要此步骤。要在本地构建一个：

./scripts/build-default-snapshot.sh   # dist/alpine-3.23.0-256mb.snap
./scripts/build-data-snapshot.sh      # 512 MB variant with numpy/pandas/scipy

[!IMPORTANT] 要使用本地构建的快照，请取消注释 crates/vpod/src/main.rs 中 resolve_snapshot() 里的相关行。

快照构建还可以运行 AOT 处理（scripts/aot-snapshot.sh <snapshot>），该处理会跟踪一个代表性工作负载，翻译热点代码块，并重新构建将这些代码块内嵌的仿真器。这个过程需要一段时间；日常开发使用 aot-stub.sh 生成的存根就足够了，所有功能都一样，只是速度较慢。

拉取请求

保持 PR 聚焦：每个 PR 只做一项更改。
fmt、clippy 和测试套件必须通过（CI 会强制执行这三项）。
如果你修改了仿真器的执行或内存路径，请说明你是如何验证正确性的（至少运行测试套件；对于细微的更改，在客户机内启动引导并运行真实工作负载是一个很好的合理性检查）。

许可证

本项目采用 Apache License 2.0 许可证。详情请参阅 LICENSE 文件。

vpod

最受欢迎

Vpod

什么是 vpod？