企业官网建设流程全解析

• Agent 沙箱
• 虚拟化

本文基于 examples/README.md 及其在各语言目录下的配套 README，系统梳理 microsandbox 官方示例矩阵的完整使用方法：如何在 TypeScript、Rust、Python、Go、Ruby 五种语言中创建沙箱、配置 rootfs 来源、打网络策略、注入密钥并修补启动前文件系统，并结合示例源码逐段拆解关键 API 的实际用法。

示例矩阵：五语言、统一场景

microsandbox 的examples/目录提供了同一组核心场景在五种语言下的可运行实现，覆盖沙箱生命周期、三种 rootfs 来源（OCI 镜像 / 本地目录绑定 / qcow2 块设备）、启动前文件系统修补、PID 1 移交、卷管理、文件流式读取、指标订阅、交互式 Shell，以及完整的网络能力面（DNS 过滤、出网策略、端口发布、密钥注入、TLS 拦截）。

示例与语言的对应关系如下（相对路径均以仓库根目录为起点）：

核心示例列表（继承自 examples/README.md）：

各语言目录下的 README 还额外列出了该语言的专属示例，例如 TypeScript / Rust / Python 目录中的cloud-backend（云后端生命周期与实时日志）与snapshot-fork（对已停止沙箱做快照并从中启动新沙箱）；Go 目录则提供了粒度更细的一组示例，包括basic、detached、disk、errors、filesystem、image-cache、metrics、network、patches、ports、secrets、snapshot-fork、streaming、tls、volumes等，完整清单见 sdk/go/examples/README.md。

前提条件：运行时与示例资产

运行任何示例前，需要满足两类前提：

1. microsandbox 运行时可用。核心是msb守护进程与libkrunfw内核固件，各语言的获取方式不同：
   • TypeScript：通过microsandboxnpm 平台的 optional dependencies 自动安装，或通过环境变量MSB_PATH指向一个可用的msb二进制；要求 Node.js >= 22。
   • Rust：通过cargo build配合download-binariesfeature 构建获得，或手动安装；要求 Rust 2024 edition。
   • Python：msb与libkrunfw打包在 wheel 中，或位于~/.microsandbox/；要求 Python 3.10+。
   • Go / Ruby：SDK 内置或随包分发运行时。
2. 示例资产。root-bind与root-block两个示例依赖 git 子模块提供的 Alpine rootfs 与 qcow2 资产（分别位于 examples/typescript/root-bind/rootfs-alpine 与 examples/typescript/root-block/qcow2-alpine 等位置），需要先初始化子模块：

git submodule update --init --recursive

创建语义：replace、connectOrCreate 与严格创建

examples/README.md 中有一段值得单独强调的约定，它解释了所有示例中replace()/connectOrCreate的取舍：

大多数配置导向的示例会刻意替换其固定名称的沙箱（replace 语义），保证每次运行时，实际生效的就是源码中展示的那套镜像、资源、挂载、网络与密钥配置；而交互式示例shell-attach使用connect-or-create，因为保留其工作区在多次运行之间有意义；生成唯一名称的示例则使用严格创建（strict creation）。

这个约定直接影响示例的可复现性：如果你修改了示例源码中的配置后重新运行，replace 语义确保新配置一定生效，而不是连接到旧的、配置不一致的沙箱。阅读各语言示例源码时，注意 TypeScript 的Sandbox.builder(...).replace().create()、Rust/Python 的connect_or_create等对应 API 的语义差异。

代表示例源码深读

root-oci：从 OCI 镜像创建沙箱的最小闭环

examples/typescript/root-oci/main.ts 展示了最小可用的沙箱创建与命令执行流程：

import { Sandbox } from "microsandbox"; await using sandbox = await Sandbox.builder("oci-root") .image("alpine") .cpus(1) .memory(512) .replace() .create(); const output = await sandbox.shell("echo 'Hello from microsandbox!'"); console.log("stdout:", output.stdout()); console.log("stderr:", output.stderr()); console.log("exit code:", output.code); const uname = await sandbox.shell("uname -a"); const osRelease = await sandbox.shell("cat /etc/os-release");

要点：

• builder 第一个参数是沙箱的固定名称（oci-root），配合.replace()实现上文所述的替换语义；
• .image("alpine")指定 OCI 镜像，.cpus(1)/.memory(512)分别设定 vCPU 数与内存（单位 MB）；
• await using是 TypeScript 5.2+ 的显式资源管理语法，作用域结束时自动释放沙箱；
• shell()返回执行结果对象，提供stdout()、stderr()、code三个访问器。

rootfs-patch：启动前的文件系统修补

examples/typescript/rootfs-patch/main.ts 演示了在沙箱启动前对 rootfs 做声明式修改：

await using sandbox = await Sandbox.builder("rootfs-patch") .image("alpine") .cpus(1) .memory(512) .patch((p) => p .text("/etc/greeting.txt", "Hello from a patched rootfs!\n") .text("/etc/motd", "Welcome to a patched microsandbox.\n", { replace: true }) .mkdir("/app", { mode: 0o755 }) .text("/app/config.json", '{"version": "1.0", "debug": true}', { mode: 0o644 }) .append("/etc/hosts", "127.0.0.1 myapp.local\n"), ) .replace() .create();

修补操作包含四种原语：text()写入文件（可用{ replace: true }覆盖已有文件，可用{ mode }指定权限位）、mkdir()建目录（可带权限）、append()追加行（示例向/etc/hosts追加本地域名映射）。示例随后用cat、grep、stat -c '%a'逐条验证了写入结果与/app目录的 0755 权限。这类修补适用于在标准 OCI 镜像基础上注入应用配置、挂载点或 host 映射，而无需重新构建镜像。

net-basic 与 net-dns：基础网络与 DNS 过滤

examples/typescript/net-basic/main.ts 在默认网络下验证三条基线能力：nslookup验证 DNS 解析、wget验证 HTTP 出网、ip addr show eth0查看 guest 网卡状态。

examples/typescript/net-dns/main.ts 则展示如何通过 builder 的network回调配置 egress 规则：

import { NetworkPolicy, Sandbox } from "microsandbox"; await using sandbox = await Sandbox.builder("net-dns") .image("alpine") .cpus(1) .memory(512) .network((n) => n.policy( NetworkPolicy.builder() .defaultAllow() .egress((e) => e .denyDomain("blocked.example.com") .denyDomainSuffix(".evil.com"), ), ), ) .replace() .create();

策略语义是defaultAllow打底，egress 层按精确域名（denyDomain）与后缀（denyDomainSuffix）做拒绝。示例通过nslookup对比了四类目标：example.com（放行，应解析出地址）、blocked.example.com（精确拒绝，输出 BLOCKED）、anything.evil.com（后缀拒绝）、cloudflare.com（无规则命中，正常放行），从而完整验证了过滤规则的命中与不命中路径。

其余网络示例遵循相同结构：net-policy组合 public-only / allow-all / no-network 三类策略，net-ports将 guest 端口发布到 host，net-secrets演示密钥占位符注入与 TLS 占位符替换，net-tls配置按域生成证书的 TLS 拦截。更完整的网络行为说明可参考 docs/networking/overview.mdx 与 docs/networking/dns.mdx。

分语言运行指南

TypeScript

每个示例都是独立的 Node.js 项目（含各自的 package.json），先安装依赖再启动：

cd examples/typescript/<example> npm install npm start

例如运行root-oci：

cd examples/typescript/root-oci npm install npm start

Rust

每个示例是工作区中一个独立的二进制 crate，直接在仓库根目录执行：

cargo run -p oci-root cargo run -p net-basic cargo run -p fs-read-stream

注意部分示例的 crate 名与目录名略有差异（如root-oci目录对应oci-rootcrate），完整对应表见 examples/rust/README.md。

Python

Python SDK 需一次性构建（源码位于 sdk/python）：

cd sdk/python uv sync --group dev maturin develop --release

之后从仓库根目录用 uv 运行任意示例：

uv run --project sdk/python python examples/python/root-oci/main.py uv run --project sdk/python python examples/python/net-basic/main.py uv run --project sdk/python python examples/python/fs-read-stream/main.py

Go

Go 示例位于 sdk/go/examples，从sdk/go目录直接运行：

cd sdk/go go run ./examples/basic

Ruby

Ruby 示例位于 sdk/ruby/examples，目前提供了lifecycle_convergence.rb（生命周期收敛与陈旧句柄安全检查），运行方式见 sdk/ruby/README.md。

示例选择建议

• 想验证安装与 SDK 基本通路：从root-oci或 Go 的basic开始；
• 要复现某条网络规则的实际效果：按net-basic→net-dns→net-policy→net-ports→net-secrets/net-tls的顺序递进，每个示例都自带 guest 内的验证命令，运行后即可看到放行/拦截的对比输出；
• 需要给沙箱预置配置而不重建镜像：参考rootfs-patch的text/mkdir/append三种原语组合；
• 关注并发与资源管理边界：lifecycle-convergence覆盖重启、销毁与陈旧句柄身份安全，并输出各阶段耗时指标，适合作为 SDK 生命周期行为的对照基准。

• Agent 沙箱
• 虚拟化