1. 概览与设计目标

microsandbox 是一个面向 AI 智能体、用户代码、CI 任务、爬虫等不可信负载的本地 microVM 编排框架，核心目标是：在不到 100 毫秒内启动一台拥有独立 Linux 内核的轻量虚拟机，并以 Docker 风格的工作流暴露 OCI 镜像、卷、命令执行与网络策略等能力。资料来源：README.md:1-30

项目的设计原则可以概括为三点：

• 硬件级隔离：每个 sandbox 都是一台真实 VM，guest 与 host 之间通过 virtio 等机制解耦，而不是共享内核的容器。
• 嵌入式运行时：SDK 可直接嵌入业务进程，无需单独部署守护进程（msb-server 仅作为可选入口）。
• 可组合策略：网络策略、TLS 拦截、密钥占位符替换等能力以 builder/feature flag 的形式暴露给上层。

在多语言生态上，microsandbox 提供了 Rust（核心库 + agent-client）、Python、TypeScript/Node.js、Go 四种官方绑定，分别通过 pyo3、N-API 和 cgo 调用底层的 Rust crate。资料来源：sdk/python/README.md:1-15、sdk/node-ts/README.md:1-20、sdk/go/README.md:1-20

2. 整体架构分层

系统的运行时由若干职责清晰的 Rust crate 组合而成，大致可分为四层。下图给出从用户 API 到硬件的纵向数据流：

flowchart TB
    subgraph L1[SDK 层]
        PY[Python SDK]
        TS[Node.js SDK]
        GO[Go SDK]
        RS[microsandbox Rust SDK]
    end
    subgraph L2[协议与控制面]
        AC[agent-client / agent 协议]
        SRV[msb-server JSON-RPC]
    end
    subgraph L3[运行时核心]
        RT[crates/runtime]
        FS[crates/filesystem]
        IMG[crates/image]
        NET[microsandbox-network]
        MC[crates/metrics-collector]
    end
    subgraph L4[数据与可观测性]
        DB[(crates/db SeaORM)]
        OTEL[OTel exporter]
    end
    subgraph L5[硬件层]
        KRUN[libkrun / KVM / HVF]
    end
    L1 --> L2 --> L3 --> L5
    L3 --> L4

各模块职责如下：

• crates/runtime：负责 microVM 生命周期、启动参数、心跳与空闲超时。资料来源：crates/microsandbox/README.md:30-50
• crates/filesystem：提供 PassthroughFs、MemFs、DualFs 三种可组合的 virtio-fs 后端，guest 看到的 Linux 元数据在 macOS 上也能正确虚拟化。资料来源：crates/filesystem/lib/lib.rs:1-40、crates/filesystem/README.md:1-40
• crates/db：基于 SeaORM 维护 sandbox、image_ref、layer、volume、run、snapshot 等实体的持久化状态。资料来源：crates/db/lib/entity/mod.rs:1-12
• crates/metrics-collector：从共享内存注册表轮询指标，通过 mpsc/broadcast 分发给多个 exporter，并提供 Builder → MetricsCollector → RunningCollector 的强类型生命周期。资料来源：crates/metrics-collector/lib/lib.rs:1-50

3. MicroVM 运行时与隔离机制

microVM 运行时是项目的物理基础。它的关键特性是 使用 libkrun 在 host CPU 上以 KVM（Linux）/ HVF（macOS）启动一台最小化的 guest，并通过 virtio-fs 把上层注入的 rootfs 暴露给 guest。资料来源：crates/filesystem/README.md:1-30、README.md:10-25

在文件系统层面，PassthroughFs::builder().root_dir(...).build() 这样的 API 允许把宿主目录直接交给 guest，而无需 root 权限；其所有权、权限、文件类型被存储在扩展属性（xattr）中，因此 host 的实际文件权限不会被改动。MemFs 则提供一个完全在内存中的临时根文件系统，适合 ephemeral 负载；DualFs 把两者组合成“读自 B、写向 A”的层级，可用于把临时构建结果写回持久卷。资料来源：crates/filesystem/README.md:10-60

运行时还需要处理：

• 资源约束：rlimit（nofile 等）在容器内加载复杂库时容易触顶，社区中曾出现“Too many open files — 1024/4096”类问题（issue #284），需要由执行器显式抬高。
• 可写 overlay 大小：默认 4 GiB 的 upper.ext4 容量对工具链类镜像偏紧，社区已经在 issue #762 中讨论暴露 Ext4FormatOptions::size_bytes 的配置入口。
• 时钟同步：v0.5.3 起强化了 guest 与 host 的时钟同步，避免长时间运行沙箱出现时间漂移。

4. 网络、安全与可观测性

网络与安全是 microsandbox 与普通容器最大的差异点之一。microsandbox-network 提供三种预设策略：public-only（默认，仅允许访问公网）、allow-all 与完全 airgapped；用户也可以附加 Destination::Domain 形式的精细放行规则。资料来源：crates/microsandbox/README.md:30-50

在 TLS 拦截路径上，运行时充当透明 MITM 代理：当 guest 进程发起 HTTPS 请求时，network 组件会终止 TLS、按域名进行策略匹配，并在出站时把 Secret.env("...") 占位符替换为真实凭据，再向上游重建 TLS。需要注意两点已知的限制：

• 明文 HTTP 不经过替换路径：Secret.env(...) 仅在 TLS 拦截时生效，issue #646 已记录该行为。
• HTTPS_PROXY 走明文 80 端口会绕过：当 HTTPS_PROXY="http://proxy.corporate.com:80" 时，TLS 代理不会生效，issue #752 报告了 secret substitution 失败。

可观测性方面，metrics-collector 周期性采集 CPU、内存、磁盘 I/O、网络 I/O 与 uptime，并支持 OTel exporter。指标名称如 microsandbox.cpu.utilization、microsandbox.memory.usage、microsandbox.disk.bytes_read 等以 gauge 形式发出绝对累计值，吞吐量由下游的 rate() 查询派生。资料来源：crates/metrics-collector/lib/exporters/otel.rs:1-50

跨语言 SDK 通过统一的 agent 协议 与 runtime 通信：协议帧为 [len:u32 BE][id:u32 BE][flags:u8][CBOR Message]，其中 Message 包含 v（协议版本）、t（消息类型）、p（载荷）。agent-client 负责传输适配、握手、关联 ID 分配与版本协商；上层 Rust crate 默认启用 uds 特性以走本机 Unix 域套接字，TypeScript 版则区分浏览器安全入口与 Node 专用入口。资料来源：agent-client/rust/README.md:1-40

5. 常见限制与故障模式

根据社区反馈与源码注释，运行 microsandbox 时需要注意以下几类问题：

See Also

• Network Policies & Egress Control — Destination::Domain 规则与 TLS 拦截的细节
• Filesystem Backends — PassthroughFs / MemFs / DualFs 的配置示例
• Agent Protocol Reference — CBOR 帧、版本协商、关联 ID
• SDK Overview — Rust / Python / Node.js / Go 的入口与安装方式
• Observability & Metrics — OTel 指标列表与采集器生命周期

概述与架构定位

Networking、TLS 拦截、DNS 过滤、Secrets 占位符替换和 Egress Policy 是 microsandbox 在 guest VM 边界提供的核心网络治理能力。其核心思想是：guest 内部不可信，所有出站流量必须经过 host 端的策略与拦截层，由 host 在透明代理路径上完成"判定-替换-转发"。

SDK 层面的网络模型由四个相互独立又可叠加的组件构成：

• NetworkPolicy —— 出站访问控制（默认拒绝、可设为 Public-only / Allow-all / Airgapped）
• TlsConfig —— HTTPS 透明拦截（CA 注入、bypass 列表、拦截端口）
• DnsConfig —— DNS 解析行为（nameservers、超时）
• Secrets —— 占位符机制，真实凭据永远不进入 VM

资料来源：sdk/python/README.md、sdk/node-ts/README.md

flowchart LR
  G[Guest VM] -->|TCP/UDP| HG[Host netstack<br/>microsandbox-network]
  HG --> P{Policy engine}
  P -->|deny| DROP[丢弃]
  P -->|allow| TLS{TLS?}
  TLS -->|yes| I[TLS 拦截器]
  TLS -->|no| FWD[直连]
  I -->|placeholder| S[Secrets 替换]
  S -->|真实凭据| UP[上行到 Internet]

网络策略与 Egress 规则

每个 sandbox 创建时必须选择一个 NetworkPolicy。当前暴露的工厂方法覆盖四种常见安全姿态：

在 SDK 中，规则的最小单位是 Rule，由动作（Action）、方向（Direction，如 Egress）、协议（Protocol）、目标（Destination）和端口（PortRange）组合而成。Destination 是带判别式的联合类型，常见形态包括：

Rule 同时支持 allow 与 deny 两种动作，并允许通过 Rule.allowAny(...) 一次性放通多种目标。多个规则通过 RuleSet 组合：默认 deny-by-default，叠加规则时按"先 deny 后 allow"的短路逻辑评估。资料来源：sdk/python/README.md、sdk/node-ts/README.md

社区已知问题：在 microsandbox-network 0.5.4 下，带 Destination::Domain 允许规则的首条出站 HTTPS 存在约 1/3 概率的 guest 挂起，见 issue #894。

TLS 拦截与 Port Publishing

TLS 拦截是 Secrets 替换能生效的前提——只有经过 host 的 TLS 中继路径才能在密文之外进行占位符替换。TlsBuilder 提供以下可配置项：

• bypass 列表 —— 不做拦截、保持原 TLS 握手的域名或 IP
• intercepted_ports —— 仅对这些端口进行 TLS 中继（默认通常是 443）
• ca_cert_pem —— 自定义 CA，PEM 内联；与系统信任链叠加，用于企业私有 CA
• client cert pinning —— 可选，要求客户端证书

Port publishing 与网络策略正交：它只关心 host→guest 方向的入站映射。Python SDK 中通过 ports={8080: 80} 即可声明 host:8080 → guest:80 的 TCP 端口转发，策略引擎不会对入站已发布端口再次评估。资料来源：sdk/python/README.md、examples/typescript/net-tls/package.json

DNS 配置与过滤

DNS 配置通过 DnsBuilder 暴露，主要字段包括 nameservers 和 query_timeout。在 deny-by-default 策略下，DNS 查询本身也会被策略引擎审计：

• 命中 deny 规则的域名 → 解析失败，guest 看到 NXDOMAIN 或超时
• 仅命中 allow 规则的域名 → 解析走 host 的 upstream resolver
• 后缀通配规则（domainSuffix(".internal")）会在内部策略匹配阶段展开

由于 DNS 解析由 host 端代理执行，guest 不会直接与外部 resolver 通信，这从根本上消除了 DNS exfiltration 风险。资料来源：sdk/node-ts/README.md、examples/typescript/net-dns/package.json

Secrets 占位符替换

Secrets 是网络层与文件系统层的桥梁，但真实值永远不会进入 guest VM。其工作流为：

1. 宿主在创建 sandbox 时为每个 Secret 生成一个随机占位符（例如 $MSB_OPENAI_API_KEY），写入 guest 环境变量
2. guest 中运行的进程只能看到占位符；真实凭据保留在 host 侧
3. 当 guest 发起 HTTPS 请求且目标 host 在 allow_hosts 列表中时，TLS 拦截器在解密请求后把占位符替换为真实值
4. 若请求目标不在 allow_hosts，即便携带占位符也会被策略拦截

Secrets 的配置字段包括：

资料来源：sdk/python/README.md、examples/typescript/net-secrets/package.json

已知限制

• 明文 HTTP 不支持 Secret 替换：占位符替换只发生在 TLS 拦截路径，plain HTTP 会原样转发占位符至目标服务端（issue #646）
• 企业 HTTPS Proxy 兼容性问题：当环境使用 HTTPS_PROXY=http://proxy:80（HTTP 协议但承担 HTTPS 代理）时，TLS 拦截链不会走该代理，导致 Secrets 替换失败（issue #752）
• IPv6 出站异常：guest 侧 IPv6 地址 fd42:6d73:62:N::2/64 会停留在 tentative 状态，出站 IPv6 包被内核丢弃，根因疑在虚拟网关的 ND 处理（issue #948）

故障排查速查

See Also

• msb exec 与 rootfs patches（用于在 VM 启动前注入文件）
• Image.load() / Image.save() 本地归档能力（issue #973）
• GPU passthrough 计划（issue #291）
• Windows 原生支持路线（issue #47）

SDKs (Rust、Python、TypeScript、Go) 与 msb CLI

概述与定位

microsandbox 提供了一组面向不同语言的客户端入口以及一个统一的命令行界面 msb，让开发者可以在不部署额外基础设施的情况下，将轻量级 microVM 沙箱嵌入到自己的应用或脚本中。整体设计遵循"Rust 内核 + 多语言绑定 + CLI 前端"的思路：

• msb CLI：提供 run / create / exec / image / volume 等子命令，负责拉取镜像、启动 sandbox、执行命令、管理镜像与卷资料来源：README.md。
• Rust SDK (crates/microsandbox)：核心高层异步 API，直接以子进程方式引导 microVM 启动，并暴露 Sandbox::builder("...").create() 链式构造器；底层协议由 agent-client crate 通过 Unix domain socket 与 relay 通信，框架是 [len: u32 BE][id: u32 BE][flags: u8][CBOR] 长度前缀二进制帧，资料来源：crates/microsandbox/README.md 与 agent-client/rust/README.md。
• Python SDK：使用 PyO3 + maturin 构建本地扩展，并把运行时依赖封装到 is_installed() / install() 辅助函数中，资料来源：sdk/python/README.md。
• TypeScript SDK (sdk/node-ts)：基于 napi-rs 输出预编译 .node 原生模块，targets 包含 aarch64-apple-darwin、x86_64-unknown-linux-gnu、aarch64-unknown-linux-gnu，并要求 Node >= 22，资料来源：sdk/node-ts/package.json。
• Go SDK：在构建时嵌入 FFI 共享库（libmicrosandbox_go_ffi.so / .dylib），可通过 microsandbox_ffi_path 构建标签切换到本地 target/debug 产物，便于迭代 FFI shim，资料来源：sdk/go/README.md。

四种语言 SDK 共用同一套 Rust 运行时与代理协议，因此 Sandbox、ExecOutput、ExecHandle、Patch、Secret、NetworkPolicy、Mount 等类型在所有绑定中语义保持一致，资料来源：sdk/go/README.md 与 sdk/node-ts/README.md。

架构与各语言入口

flowchart LR
  A[msb CLI] --> R[microsandbox runtime<br/>Rust binary]
  B[Rust SDK<br/>crates/microsandbox] --> R
  C[Python SDK<br/>PyO3/maturin] --> R
  D[TypeScript SDK<br/>napi-rs] --> R
  E[Go SDK<br/>CGO/FFI] --> R
  R --> F[libkrun microVM<br/>KVM / Hypervisor.framework]
  R --> G[agentd<br/>in-guest agent]
  G -->|UDS length-prefixed CBOR| R

四种绑定只是语言层"门面"，底层调用栈统一为：SDK 调用 → msb/agent-client → sandbox 进程 → libkrun 引导 microVM → 内部 agentd 处理请求 → 长度前缀 CBOR 帧返回。这意味着无论用户从 Rust、Python、Node 还是 Go 入口操作，看到的 sandbox 生命周期、流式 exec、文件系统、metrics、secrets、TLS 拦截等行为都是一致的，资料来源：crates/microsandbox/README.md、agent-client/rust/README.md 与 sdk/node-ts/README.md。

语言入口对比

资料来源：README.md、sdk/python/README.md、sdk/node-ts/package.json、sdk/go/README.md。

关键能力与示例目录

各语言示例目录共享一组主题，覆盖从镜像拉取到网络与安全配置的完整路径：

• 根文件系统来源：root-oci（OCI 镜像）、root-bind（本地目录绑定）、root-block（qcow2 磁盘镜像）；底层 RootfsSource 枚举为 Oci / Bind / DiskImage，资料来源：crates/microsandbox/README.md。
• 预启动文件系统变更：rootfs-patch 示例演示 Patch.Text / Patch.File / Patch.Dir 等预启动修改，资料来源：examples/README.md。
• 卷与挂载：volume-named、volume-disk 对应 VolumeMount::{Bind, Named, Tmpfs}，社区反馈希望补充 ro、nosuid、noexec 等挂载标志，见 Issue #249 "Volume mount flags like :ro"。
• 网络与 TLS：net-basic、tls、secrets 示例覆盖 NetworkPolicy 默认 public-only、allow-all 与全 airgapped 三档，并演示 TLS 拦截与占位符替换。
• 生命周期与流式执行：streaming、detach、snapshot-fork 演示 ExecHandle（AsyncIterable<ExecEvent> / recv() / wait()）以及停止态快照派生新 sandbox，资料来源：sdk/node-ts/README.md 与 sdk/go/examples/README.md。

社区关注的问题与边界

围绕 SDK 与 CLI 的社区反馈主要集中在三类：

1. 网络与 Secret 替换——Secret.env(...) 仅在 TLS 拦截路径生效，因此 plain HTTP 端点的占位符会被原样转发（Issue #646，已关闭）；同时在 HTTPS_PROXY="http://proxy:80" 这种"HTTP 协议但承载 HTTPS"的代理场景下 secret 替换会失败（Issue #752）；0.5.x 在 Destination::Domain 允许规则下的首次出站 TLS 存在约 1/3 概率挂起（Issue #894）。这些限制在使用 Rust/Python/Go/TS SDK 构造网络策略时都会复现，需要在网络层显式选择 allow-all 或 full airgapped 来规避。
2. 运行时与镜像边界——Issue #931 表明 libkrun 后端难以静态（musl）构建，社区通过旧版 glibc 容器（debian9 → ubuntu18 → debian10）才得以打包；Issue #948 指出 IPv6 网关 ND 协议处理有缺陷，导致 guest 地址一直处于 tentative；Issue #762 希望把 upper.ext4 可写 overlay 容量做成可配置（Ext4FormatOptions::size_bytes 已存在）；Issue #284 反馈 Python 数据科学镜像在容器内文件描述符受限。
3. 平台与生态——Windows（无 WSL）尚未官方支持（Issue #47）；GPU passthrough 处于中期路线图（Issue #291）；Python SDK 仍未暴露 Image.load() / Image.save()（Issue #973，CLI 的 msb load / msb save 已通过 PR #862 在 Rust crates/image/lib/archive/ 中实现）；CLI 在 v0.5.6 引入了"显式挂载类型标志"（v0.5.6 release notes），用以解决类型推断歧义。

See Also

• Agent Protocol & Relay Transport
• Network Policies & TLS Interception
• Volumes, Mounts & Rootfs Sources
• Image Lifecycle: Pull / Save / Load / Cache

概述

microsandbox 通过分层抽象管理沙箱的存储与文件系统:上层通过配置类型(RootfsSource、VolumeMount、Patch、PullPolicy)描述镜像、rootfs 与挂载来源;中层在 crates/filesystem/lib/ 中实现三种可组合文件系统后端(DualFs、MemFs、PassthroughFs);下层依赖 crates/db/lib/entity/ 中 SeaORM 实体将清单、层、rootfs 与卷元数据持久化。理解这些层次对于正确选型镜像、调整存储上限以及排查常见的容量与文件描述符限制至关重要。

资料来源：crates/microsandbox/README.md、crates/filesystem/lib/lib.rs

flowchart LR
  A[OCI 镜像<br/>RootfsSource::Oci] --> R[Rootfs]
  B[主机目录<br/>RootfsSource::Bind] --> R
  C[磁盘镜像<br/>RootfsSource::DiskImage] --> R
  R --> D{DualFs 调度<br/>policy.rs}
  D -->|UseBackendA| M[MemFs<br/>内存 inode]
  D -->|UseBackendB| P[PassthroughFs<br/>主机 fs]
  R --> V[VolumeMount<br/>Bind / Named / Tmpfs]
  R --> S[Snapshot / Fork<br/>dir_snapshot.rs]
  S --> F[新沙箱分支]

镜像与根文件系统

RootfsSource 三种来源

RootfsSource 枚举定义沙箱的根文件系统来源(crates/microsandbox/README.md):

• Oci:从 Docker/OCI 注册中心拉取的镜像,经 crates/image/lib/pull.rs 与 registry/client.rs 下载,清单解析在 registry/manifest.rs。
• Bind:直接将主机目录绑定为根,适合调试或复用本地文件系统。
• DiskImage:加载 qcow2/raw 磁盘镜像作为根。

通过 Patch / PatchBuilder 可在启动前对 rootfs 进行文件、目录或追加内容的修改,这是在不重新构建镜像的前提下快速生成镜像变体的轻量手段。

拉取策略与本地归档

PullPolicy 控制镜像拉取时机,可选 Always、IfMissing、Never(crates/microsandbox/README.md)。社区已记录 Python SDK 缺少 Image.load() / Image.save() 绑定的问题(issue #973):目前仅 msb load / msb save CLI 与 Rust archive 模块支持本地归档,Python 用户需要绕行或改用 CLI。

资料来源：crates/microsandbox/README.md、crates/image/lib/lib.rs

文件系统后端

crates/filesystem/lib/lib.rs 导出三种后端,共享 backends/shared/mod.rs 中的 handle_table、inode_table、name_validation、platform、stat_override 等基础设施。

DualFs:跨后端的策略调度与物化

DualFs 在两个后端之间按策略路由读写。policy.rs 中的 DualDispatchPlan 决定单次操作的路由,包含:

• UseBackendA / UseBackendB:直接路由到单一后端
• MergeLookup / MergeReaddir:合并两个后端的目录视图
• MaterializeToBackendThen:先跨后端物化,再执行原操作
• Synthetic / Deny:不调用后端,合成响应或拒绝

materialize.rs 的 do_materialize 负责跨后端块级流式拷贝,流程包括 chunked read/write、释放源/目标句柄、复制 xattrs 与时间戳,最后通过 rename 将暂存条目安装到目标父目录(参见 do_materialize 与 materialize_symlink、materialize_special)。

PassthroughFs:主机文件转发与特殊文件虚拟化

passthroughfs/create_ops.rs 描述:由于宿主机进程通常不具备 CAP_MKNOD,mknod 总是创建普通文件,真实类型(S_IFBLK、S_IFCHR、S_IFIFO、S_IFSOCK)写入 override xattr 后通过 patched_stat 报告给 guest。此外,Linux 上 user.* xattr 无法挂在 symlink 上,因此 symlink 以"目标字符串作为内容 + S_IFLNK 模式"的文件形式存储;macOS 则直接创建真实 symlink 并使用 XATTR_NOFOLLOW。

MemFs:纯内存 inode 表

memfs/create_ops.rs 在 InodeContent 上维护 children 映射、xattrs 与时间戳,适用于临时或测试沙箱,无需与宿主机文件系统交互。

资料来源：crates/filesystem/lib/lib.rs、crates/filesystem/lib/backends/shared/mod.rs、crates/filesystem/lib/backends/dualfs/policy.rs、crates/filesystem/lib/backends/dualfs/materialize.rs、crates/filesystem/lib/backends/passthroughfs/create_ops.rs、crates/filesystem/lib/backends/memfs/create_ops.rs

卷、快照与挂载

VolumeMount 类型

VolumeMount 区分三种挂载方式(crates/microsandbox/README.md):

• Bind:主机路径直接绑定到 guest 路径
• Named:由 microsandbox 管理的命名卷,可在多个沙箱间共享,持久化到 db/entity/volume.rs
• Tmpfs:内存临时文件系统

社区长期请求更细粒度的挂载控制,如 :ro、nosuid、noexec(issue #249);v0.5.6 引入了 msb exec 的显式 mount kind 标志以解决该问题。

快照与分支

crates/filesystem/lib/backends/shared/dir_snapshot.rs 提供 SnapshotEntry trait 与 serve_snapshot_entries 辅助函数,在目录读取路径上服务后端持有的快照视图,典型用法是停止沙箱后导出快照并从该快照启动新沙箱。Rust 示例 snapshot-fork 与 Go SDK 中的 snapshot-fork 均演示该流程(参见 examples/README.md、examples/rust/README.md、sdk/go/examples/README.md)。

持久化实体

crates/db/lib/entity/mod.rs 列出的 SeaORM 实体中,与存储相关的主要包括:

• manifest / layer / manifest_layer:镜像清单与层记录
• image_ref:已缓存的镜像引用
• flat_rootfs / sandbox_rootfs:扁平化与每沙箱 rootfs,flat_rootfs.rs 通过 Related trait 关联到 manifest 与 sandbox_rootfs
• volume / sandbox_label:卷与标签元数据

资料来源：crates/db/lib/entity/mod.rs、crates/db/lib/entity/flat_rootfs.rs、crates/filesystem/lib/backends/shared/dir_snapshot.rs、sdk/go/examples/README.md

存储限制与故障模式

以下为社区已记录的与存储相关的限制与故障模式:

• 可写 overlay 容量:目前 upper.ext4 默认上限 4 GiB,Ext4FormatOptions::size_bytes 已存在但尚未公开为可配置项,长时间运行的工具链沙箱容易触顶(issue #762)。
• 打开文件上限:在 1024/4096 默认 ulimit 下,包含 scikit 等库的 Python 镜像在 guest 内报 "Too many open files"(issue #284),需要在 rootfs 补丁或 ExecOptions.rlimits 中调整。
• Linux glibc 兼容性:Rust 二进制以 musl 静态构建困难,建议在旧发行版容器中交叉编译(issue #931)。
• Docker 中运行:需要在容器内映射 /dev/kvm 以启用 KVM 加速(issue #264)。
• 镜像归档:Python SDK 暂未暴露 Image.load() / Image.save() 绑定(issue #973)。
• Windows 支持:目前仅 Linux 与 macOS,Windows 原生支持仍待实现(issue #47)。

资料来源：crates/microsandbox/README.md、examples/README.md、examples/rust/README.md、README.md

相关链接

• GitHub 仓库:superradcompany/microsandbox
• 镜像模块:crates/image/lib/(含 pull.rs、registry/、archive/)
• 文件系统模块:crates/filesystem/lib/(含 dualfs/、memfs/、passthroughfs/)
• 数据库实体:crates/db/lib/entity/
• v0.5.6 发布说明:引入显式 mount kind 标志,改善 VolumeMount 控制粒度

资料来源：crates/microsandbox/README.md、README.md

Pitfall Log / 踩坑日志

项目：superradcompany/microsandbox

摘要：发现 28 个潜在踩坑项，其中 8 个为 high/blocking；最高优先级：安装坑 - 来源证据：Python SDK: expose Image.load() and Image.save() for local image archives。

1. 安装坑 · 来源证据：Python SDK: expose Image.load() and Image.save() for local image archives

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Python SDK: expose Image.load() and Image.save() for local image archives
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/superradcompany/microsandbox/issues/973 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Support a much low glibc version in Linux

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Support a much low glibc version in Linux
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/superradcompany/microsandbox/issues/931 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：Intermittent (~1/3) indefinite guest hang on first outbound TLS under a `Destination::Domain` egress rule (0.5.x; not 0…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Intermittent (~1/3) indefinite guest hang on first outbound TLS under a Destination::Domain egress rule (0.5.x; not 0.4.6)
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/superradcompany/microsandbox/issues/894 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

4. 安全/权限坑 · 失败模式：security_permissions: Secret substitution fails with HTTPS_PROXY that uses http:// and port 80

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Secret substitution fails with HTTPS_PROXY that uses http:// and port 80
• 对用户的影响：Developers may expose sensitive permissions or credentials: Secret substitution fails with HTTPS_PROXY that uses http:// and port 80
• 证据：failure_mode_cluster:github_issue | https://github.com/superradcompany/microsandbox/issues/752 | Secret substitution fails with HTTPS_PROXY that uses http:// and port 80

5. 安全/权限坑 · 失败模式：security_permissions: Windows Support (without WSL)

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Windows Support (without WSL)
• 对用户的影响：Developers may expose sensitive permissions or credentials: Windows Support (without WSL)
• 证据：failure_mode_cluster:github_issue | https://github.com/superradcompany/microsandbox/issues/47 | Windows Support (without WSL)

6. 安全/权限坑 · 失败模式：security_permissions: support secret substitution for plain http

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: support secret substitution for plain http
• 对用户的影响：Developers may expose sensitive permissions or credentials: support secret substitution for plain http
• 证据：failure_mode_cluster:github_issue | https://github.com/superradcompany/microsandbox/issues/646 | support secret substitution for plain http

7. 安全/权限坑 · 来源证据：Secret substitution fails with HTTPS_PROXY that uses http:// and port 80

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Secret substitution fails with HTTPS_PROXY that uses http:// and port 80
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/superradcompany/microsandbox/issues/752 | 来源类型 github_issue 暴露的待验证使用条件。

8. 安全/权限坑 · 来源证据：Windows Support (without WSL)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Windows Support (without WSL)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/superradcompany/microsandbox/issues/47 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

9. 安装坑 · 失败模式：installation: v0.4.4

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.4.4
• 对用户的影响：Upgrade or migration may change expected behavior: v0.4.4
• 证据：failure_mode_cluster:github_release | https://github.com/superradcompany/microsandbox/releases/tag/v0.4.4 | v0.4.4

10. 安装坑 · 失败模式：installation: v0.5.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.5.0
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.0
• 证据：failure_mode_cluster:github_release | https://github.com/superradcompany/microsandbox/releases/tag/v0.5.0 | v0.5.0

11. 安装坑 · 失败模式：installation: v0.5.2

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.5.2
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.2
• 证据：failure_mode_cluster:github_release | https://github.com/superradcompany/microsandbox/releases/tag/v0.5.2 | v0.5.2

12. 安装坑 · 失败模式：installation: v0.5.3

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.5.3
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.3
• 证据：failure_mode_cluster:github_release | https://github.com/superradcompany/microsandbox/releases/tag/v0.5.3 | v0.5.3

13. 安装坑 · 失败模式：installation: v0.5.4

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.5.4
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.4
• 证据：failure_mode_cluster:github_release | https://github.com/superradcompany/microsandbox/releases/tag/v0.5.4 | v0.5.4

14. 安装坑 · 失败模式：installation: v0.5.5

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.5.5
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.5
• 证据：failure_mode_cluster:github_release | https://github.com/superradcompany/microsandbox/releases/tag/v0.5.5 | v0.5.5

15. 安装坑 · 失败模式：installation: v0.5.6

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v0.5.6
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.6
• 证据：failure_mode_cluster:github_release | https://github.com/superradcompany/microsandbox/releases/tag/v0.5.6 | v0.5.6

16. 配置坑 · 失败模式：configuration: Intermittent (~1/3) indefinite guest hang on first outbound TLS under a `Destination::Domain`...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Intermittent (~1/3) indefinite guest hang on first outbound TLS under a Destination::Domain egress rule (0.5.x; not 0.4.6)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Intermittent (~1/3) indefinite guest hang on first outbound TLS under a Destination::Domain egress rule (0.5.x; not 0.4.6)
• 证据：failure_mode_cluster:github_issue | https://github.com/superradcompany/microsandbox/issues/894 | Intermittent (~1/3) indefinite guest hang on first outbound TLS under a Destination::Domain egress rule (0.5.x; not 0.4.6)

17. 配置坑 · 失败模式：configuration: Python SDK: expose Image.load() and Image.save() for local image archives

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Python SDK: expose Image.load() and Image.save() for local image archives
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Python SDK: expose Image.load() and Image.save() for local image archives
• 证据：failure_mode_cluster:github_issue | https://github.com/superradcompany/microsandbox/issues/973 | Python SDK: expose Image.load() and Image.save() for local image archives

18. 配置坑 · 失败模式：configuration: v0.4.6

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v0.4.6
• 对用户的影响：Upgrade or migration may change expected behavior: v0.4.6
• 证据：failure_mode_cluster:github_release | https://github.com/superradcompany/microsandbox/releases/tag/v0.4.6 | v0.4.6

19. 配置坑 · 来源证据：support secret substitution for plain http

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：support secret substitution for plain http
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/superradcompany/microsandbox/issues/646 | 来源类型 github_issue 暴露的待验证使用条件。

20. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | github_repo:867192625 | https://github.com/superradcompany/microsandbox | README/documentation is current enough for a first validation pass.

21. 运行坑 · 失败模式：runtime: v0.4.5

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: v0.4.5
• 对用户的影响：Upgrade or migration may change expected behavior: v0.4.5
• 证据：failure_mode_cluster:github_release | https://github.com/superradcompany/microsandbox/releases/tag/v0.4.5 | v0.4.5

22. 维护坑 · 失败模式：migration: GPU Support

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: GPU Support
• 对用户的影响：Developers may hit a documented source-backed failure mode: GPU Support
• 证据：failure_mode_cluster:github_issue | https://github.com/superradcompany/microsandbox/issues/291 | GPU Support

23. 维护坑 · 失败模式：migration: v0.5.1

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v0.5.1
• 对用户的影响：Upgrade or migration may change expected behavior: v0.5.1
• 证据：failure_mode_cluster:github_release | https://github.com/superradcompany/microsandbox/releases/tag/v0.5.1 | v0.5.1

24. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | github_repo:867192625 | https://github.com/superradcompany/microsandbox | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | github_repo:867192625 | https://github.com/superradcompany/microsandbox | no_demo; severity=medium

26. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | github_repo:867192625 | https://github.com/superradcompany/microsandbox | no_demo; severity=medium

27. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | github_repo:867192625 | https://github.com/superradcompany/microsandbox | issue_or_pr_quality=unknown

28. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | github_repo:867192625 | https://github.com/superradcompany/microsandbox | release_recency=unknown