# https://github.com/superradcompany/microsandbox 项目说明书 生成时间：2026-06-14 15:41:32 UTC ## 目录 - [System Architecture and MicroVM Runtime](#page-1) - [Networking, TLS, DNS, Secrets, and Egress Policy](#page-2) - [SDKs (Rust, Python, TypeScript, Go) and the msb CLI](#page-3) - [Images, Root Filesystems, Snapshots, Volumes, and Storage Limits](#page-4) ## System Architecture and MicroVM Runtime ### 相关页面 相关主题：[Networking, TLS, DNS, Secrets, and Egress Policy](#page-2), [SDKs (Rust, Python, TypeScript, Go) and the msb CLI](#page-3), [Images, Root Filesystems, Snapshots, Volumes, and Storage Limits](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/superradcompany/microsandbox/blob/main/README.md) - [crates/microsandbox/README.md](https://github.com/superradcompany/microsandbox/blob/main/crates/microsandbox/README.md) - [crates/db/lib/entity/mod.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/db/lib/entity/mod.rs) - [crates/filesystem/lib/lib.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/lib/lib.rs) - [crates/filesystem/README.md](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/README.md) - [crates/metrics-collector/lib/lib.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/metrics-collector/lib/lib.rs) - [crates/metrics-collector/lib/exporters/otel.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/metrics-collector/lib/exporters/otel.rs) - [agent-client/rust/README.md](https://github.com/superradcompany/microsandbox/blob/main/agent-client/rust/README.md) - [sdk/python/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/python/README.md) - [sdk/node-ts/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/node-ts/README.md) - [sdk/go/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/go/README.md)
# System Architecture and MicroVM Runtime ## 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 到硬件的纵向数据流： ```mermaid 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` 时需要注意以下几类问题： | 类别 | 现象 | 触发条件 / 说明 | |---|---|---| | glibc 兼容 | Rust 静态二进制在低 glibc 系统上无法启动 | libkrun 相关二进制默认动态链接，需在兼容容器中构建（issue #931） | | IPv6 路由 | guest IPv6 地址长期 tentative | 网关 ND（Neighbor Discovery）处理有缺陷（issue #948） | | TLS Egress 挂起 | 首条出站 HTTPS 在 `Destination::Domain` 规则下偶发挂死 | 0.5.x 在 deny-by-default 策略下存在竞态（issue #894） | | 资源耗尽 | 容器内 `Too many open files` | 来自默认 rlimit 较小（issue #284） | | 平台 | Windows 原生支持 | 当前仅 Linux/macOS，issue #47 长期跟踪 | ## 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, and Egress Policy ### 相关页面 相关主题：[System Architecture and MicroVM Runtime](#page-1)
相关源码文件 以下源码文件用于生成本页说明： - [sdk/python/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/python/README.md) - [sdk/go/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/go/README.md) - [sdk/node-ts/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/node-ts/README.md) - [crates/microsandbox/README.md](https://github.com/superradcompany/microsandbox/blob/main/crates/microsandbox/README.md) - [agent-client/typescript/README.md](https://github.com/superradcompany/microsandbox/blob/main/agent-client/typescript/README.md) - [agent-client/rust/README.md](https://github.com/superradcompany/microsandbox/blob/main/agent-client/rust/README.md) - [examples/typescript/net-tls/package.json](https://github.com/superradcompany/microsandbox/blob/main/examples/typescript/net-tls/package.json) - [examples/typescript/net-secrets/package.json](https://github.com/superradcompany/microsandbox/blob/main/examples/typescript/net-secrets/package.json) - [examples/typescript/net-dns/package.json](https://github.com/superradcompany/microsandbox/blob/main/examples/typescript/net-dns/package.json) - [examples/typescript/net-policy/package.json](https://github.com/superradcompany/microsandbox/blob/main/examples/typescript/net-policy/package.json) - [examples/typescript/net-basic/package.json](https://github.com/superradcompany/microsandbox/blob/main/examples/typescript/net-basic/package.json)
# Networking, TLS, DNS, Secrets, and Egress Policy ## 概述与架构定位 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](https://github.com/superradcompany/microsandbox/blob/main/sdk/python/README.md)、[sdk/node-ts/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/node-ts/README.md) ```mermaid flowchart LR G[Guest VM] -->|TCP/UDP| HG[Host netstack
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`。当前暴露的工厂方法覆盖四种常见安全姿态： | 策略 | 行为 | |---|---| | `NetworkPolicy.publicOnly()` | 仅允许到公网（非 RFC1918）的出站 | | `NetworkPolicy.allowAll()` | 允许任意出站 | | `NetworkPolicy.none()` / Airgapped | 完全禁止任何出站 | | `NetworkPolicy.nonLocal()` | 允许非本机回环流量 | 在 SDK 中，规则的最小单位是 `Rule`，由动作（`Action`）、方向（`Direction`，如 `Egress`）、协议（`Protocol`）、目标（`Destination`）和端口（`PortRange`）组合而成。`Destination` 是带判别式的联合类型，常见形态包括： | Destination 形态 | 语义 | |---|---| | `Destination.domain("api.openai.com")` | 精确域名匹配 | | `Destination.domainSuffix(".github.com")` | 后缀通配 | | `Destination.ip("1.2.3.4")` | 精确 IP | | `Destination.cidr("10.0.0.0/8")` | CIDR 段 | | `Destination.publicNetwork()` | 任意公网 IP | `Rule` 同时支持 allow 与 deny 两种动作，并允许通过 `Rule.allowAny(...)` 一次性放通多种目标。多个规则通过 `RuleSet` 组合：默认 deny-by-default，叠加规则时按"先 deny 后 allow"的短路逻辑评估。资料来源：[sdk/python/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/python/README.md)、[sdk/node-ts/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/node-ts/README.md) 社区已知问题：在 `microsandbox-network 0.5.4` 下，带 `Destination::Domain` 允许规则的首条出站 HTTPS 存在约 1/3 概率的 guest 挂起，见 [issue #894](https://github.com/superradcompany/microsandbox/issues/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](https://github.com/superradcompany/microsandbox/blob/main/sdk/python/README.md)、[examples/typescript/net-tls/package.json](https://github.com/superradcompany/microsandbox/blob/main/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](https://github.com/superradcompany/microsandbox/blob/main/sdk/node-ts/README.md)、[examples/typescript/net-dns/package.json](https://github.com/superradcompany/microsandbox/blob/main/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 的配置字段包括： | 字段 | 含义 | |---|---| | `name` | guest 端环境变量名 | | `value` | host 侧真实凭据（不出 VM） | | `allow_hosts` | 仅对这些 host 触发替换 | | `injection` | 注入位置：`env` / `header` / `cookie` 等 | 资料来源：[sdk/python/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/python/README.md)、[examples/typescript/net-secrets/package.json](https://github.com/superradcompany/microsandbox/blob/main/examples/typescript/net-secrets/package.json) ### 已知限制 - **明文 HTTP 不支持 Secret 替换**：占位符替换只发生在 TLS 拦截路径，plain HTTP 会原样转发占位符至目标服务端（[issue #646](https://github.com/superradcompany/microsandbox/issues/646)） - **企业 HTTPS Proxy 兼容性问题**：当环境使用 `HTTPS_PROXY=http://proxy:80`（HTTP 协议但承担 HTTPS 代理）时，TLS 拦截链不会走该代理，导致 Secrets 替换失败（[issue #752](https://github.com/superradcompany/microsandbox/issues/752)） - **IPv6 出站异常**：guest 侧 IPv6 地址 `fd42:6d73:62:N::2/64` 会停留在 tentative 状态，出站 IPv6 包被内核丢弃，根因疑在虚拟网关的 ND 处理（[issue #948](https://github.com/superradcompany/microsandbox/issues/948)） ## 故障排查速查 | 症状 | 可能原因 | 处置 | |---|---|---| | 出站 HTTPS 挂起 | `Destination::Domain` 规则首连竞态（0.5.4） | 升级到 0.5.6 或改用 IP/CIDR 规则 | | `Secret.env(...)` 对 http 无效 | 仅 TLS 路径支持替换 | 将 endpoint 改为 https 或接受明文 | | 企业代理下 Secrets 不替换 | 代理协议为 http 而非 https | 在 SDK 中显式指定代理或绕过 | | `Failed to connect to portal` | portal 端口被策略拦截 | 检查 `NetworkPolicy.publicOnly()` 是否允许 portal host | | 大量文件描述符耗尽 | 镜像内进程文件句柄过大 | 调整镜像内 ulimit 或用 `ExecOptions.rlimit` 显式收紧 | ## See Also - `msb exec` 与 rootfs patches（用于在 VM 启动前注入文件） - `Image.load()` / `Image.save()` 本地归档能力（[issue #973](https://github.com/superradcompany/microsandbox/issues/973)） - GPU passthrough 计划（[issue #291](https://github.com/superradcompany/microsandbox/issues/291)） - Windows 原生支持路线（[issue #47](https://github.com/superradcompany/microsandbox/issues/47)） --- ## SDKs (Rust, Python, TypeScript, Go) and the msb CLI ### 相关页面 相关主题：[System Architecture and MicroVM Runtime](#page-1), [Images, Root Filesystems, Snapshots, Volumes, and Storage Limits](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/superradcompany/microsandbox/blob/main/README.md) - [examples/README.md](https://github.com/superradcompany/microsandbox/blob/main/examples/README.md) - [examples/rust/README.md](https://github.com/superradcompany/microsandbox/blob/main/examples/rust/README.md) - [crates/microsandbox/README.md](https://github.com/superradcompany/microsandbox/blob/main/crates/microsandbox/README.md) - [sdk/python/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/python/README.md) - [sdk/node-ts/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/node-ts/README.md) - [sdk/node-ts/package.json](https://github.com/superradcompany/microsandbox/blob/main/sdk/node-ts/package.json) - [sdk/go/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/go/README.md) - [sdk/go/examples/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/go/examples/README.md) - [agent-client/rust/README.md](https://github.com/superradcompany/microsandbox/blob/main/agent-client/rust/README.md) - [crates/filesystem/lib/lib.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/lib/lib.rs) - [examples/typescript/init-handoff/package.json](https://github.com/superradcompany/microsandbox/blob/main/examples/typescript/init-handoff/package.json) - [examples/typescript/net-basic/package.json](https://github.com/superradcompany/microsandbox/blob/main/examples/typescript/net-basic/package.json)
# 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]()。 ## 架构与各语言入口 ```mermaid flowchart LR A[msb CLI] --> R[microsandbox runtime
Rust binary] B[Rust SDK
crates/microsandbox] --> R C[Python SDK
PyO3/maturin] --> R D[TypeScript SDK
napi-rs] --> R E[Go SDK
CGO/FFI] --> R R --> F[libkrun microVM
KVM / Hypervisor.framework] R --> G[agentd
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]()。 ### 语言入口对比 | 入口 | 构建方式 | 运行时依赖 | 典型安装命令 | |------|----------|------------|---------------| | Rust SDK | `cargo` workspace | `msb` + `libkrunfw` | `cargo install microsandbox` | | Python SDK | `maturin develop --release` | `uv` 工具链 + `msb` | `uv tool install microsandbox` | | TypeScript SDK | napi 预编译二进制 | Node `>= 22` | `npm i -g microsandbox` | | Go SDK | `go build`，FFI 内嵌或 `microsandbox_ffi_path` tag | 同 Rust | `go get github.com/.../microsandbox-go` | | `msb` CLI | Homebrew / npm / uv / cargo 四种分发 | libkrunfw | `brew install superradcompany/tap/microsandbox` | 资料来源：[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` / `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](agent-client-rust.md) - [Network Policies & TLS Interception](network-policies.md) - [Volumes, Mounts & Rootfs Sources](volumes-and-mounts.md) - [Image Lifecycle: Pull / Save / Load / Cache](image-lifecycle.md) --- ## Images, Root Filesystems, Snapshots, Volumes, and Storage Limits ### 相关页面 相关主题：[System Architecture and MicroVM Runtime](#page-1), [SDKs (Rust, Python, TypeScript, Go) and the msb CLI](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [crates/microsandbox/README.md](https://github.com/superradcompany/microsandbox/blob/main/crates/microsandbox/README.md) - [README.md](https://github.com/superradcompany/microsandbox/blob/main/README.md) - [crates/filesystem/lib/lib.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/lib/lib.rs) - [crates/filesystem/lib/backends/shared/mod.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/lib/backends/shared/mod.rs) - [crates/filesystem/lib/backends/dualfs/policy.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/lib/backends/dualfs/policy.rs) - [crates/filesystem/lib/backends/dualfs/materialize.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/lib/backends/dualfs/materialize.rs) - [crates/filesystem/lib/backends/dualfs/create_ops.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/lib/backends/dualfs/create_ops.rs) - [crates/filesystem/lib/backends/passthroughfs/create_ops.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/lib/backends/passthroughfs/create_ops.rs) - [crates/filesystem/lib/backends/memfs/create_ops.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/lib/backends/memfs/create_ops.rs) - [crates/filesystem/lib/backends/shared/dir_snapshot.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/filesystem/lib/backends/shared/dir_snapshot.rs) - [crates/db/lib/entity/mod.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/db/lib/entity/mod.rs) - [crates/db/lib/entity/flat_rootfs.rs](https://github.com/superradcompany/microsandbox/blob/main/crates/db/lib/entity/flat_rootfs.rs) - [examples/README.md](https://github.com/superradcompany/microsandbox/blob/main/examples/README.md) - [examples/rust/README.md](https://github.com/superradcompany/microsandbox/blob/main/examples/rust/README.md) - [sdk/go/examples/README.md](https://github.com/superradcompany/microsandbox/blob/main/sdk/go/examples/README.md)
# Images, Root Filesystems, Snapshots, Volumes, and Storage Limits ## 概述 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]() ```mermaid flowchart LR A[OCI 镜像
RootfsSource::Oci] --> R[Rootfs] B[主机目录
RootfsSource::Bind] --> R C[磁盘镜像
RootfsSource::DiskImage] --> R R --> D{DualFs 调度
policy.rs} D -->|UseBackendA| M[MemFs
内存 inode] D -->|UseBackendB| P[PassthroughFs
主机 fs] R --> V[VolumeMount
Bind / Named / Tmpfs] R --> S[Snapshot / Fork
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](https://github.com/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]() --- --- ## Doramagic 踩坑日志 项目：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