Agent 沙箱虚拟化【免费下载链接】microsandbox fast branchable microVM for any workload项目地址https://gitcode.com/gh_mirrors/mon/microsandbox点击查看免费下载Microsandbox 是一个快速可分叉的 microVM 沙箱系统其最难管理的部分不是新功能而是新旧版本共存新 SDK 连接旧运行时、新二进制打开旧数据库、旧读取器解析新快照。仓库根目录的 COMPATIBILITY.md 系统性地划定了这些非公开的兼容性边界并给出了每条边界对应的源码依据与演进规则。读完本文你将理解 Microsandbox 如何在 Agent 协议、IPC、启动器进程契约、SQLite 迁移、快照格式、磁盘镜像等 17 个边界上执行可验证的向后兼容以及为什么项目刻意把公开 SDK/CLI/HTTP API 排除在这张图之外。为什么要有一张非公开兼容性地图Microsandbox 的公开 APIRust/TypeScript/Go/Python SDK、msbCLI、HTTP 端点有自己的兼容性承诺但这张地图刻意不覆盖它们。COMPATIBILITY.md 聚焦的是让已有安装和已运行沙箱继续工作的底层契约CLI / SDK | | launch JSON inherited descriptors or Windows config file v host runtime ---------- JSON-lines control socket / named pipe | | local agent socket / named pipe | fixed frame header CBOR v relay ---- ring buffers ---- libkrun virtio console agent | v guest agentd | ----------------------------- | | | bootstrap filesystem heartbeat MSB_HOME -- SQLite database and migration history -- sandbox disks and volume data -- snapshots and portable archives -- OCI/materialization cache -- filesystem metadata xattrs, ADS, and sidecars -- sockets, locks, logs, journals, and shared memory这张图揭示了系统的全部跨进程/跨版本表面SDK/CLI 通过 launch JSON 与继承描述符启动宿主运行时宿主运行时与客户端之间有一条 JSON-lines 控制通道宿主与 guest 内agentd之间是固定帧头 CBOR的 Agent 协议而MSB_HOME下的一切数据库、磁盘、快照、缓存、元数据则是跨发行版存活的持久化协议。文档给出了六个必须逐一审查的兼容方向new host --------- old running sandbox / old agentd new release ------ old MSB_HOME / database / runtime state new reader ------- old disk / snapshot / archive / cache / metadata old release ------ state written by the new release exported artifact - another release / platform / architecture new component ---- independently running old component during upgrade核心原则值得所有长生命周期系统借鉴跨越边界时必须提前识别风险禁止悄悄加入 shim、迁移、回退或遗留实现解释清楚涉及的兼容方向、失败模式和可选方案后再实施。同时干净的早期拒绝在持续运行不安全时是合法的兼容行为而静默重解释、拒绝前部分变更、遗留持久化状态和损坏则永远不是可接受的回退。边界一Host-to-Guest Agent 协议——最显式的跨版本边界Agent 协议是宿主 SDK 与 VM 内agentd之间的通道也是版本漂移风险最高的边界。其版本策略独立定义在 crates/protocol/VERSIONING.md 中。不可变的帧结构[length: u32 big-endian][id: u32 big-endian][flags: u8][CBOR envelope] CBOR envelope { v: generation, t: wire message name, p: encoded payload }源码中这些常量可以直接核对crates/protocol/lib/message.rs 定义了当前代际PROTOCOL_VERSION: u8 9、四个标志位FLAG_TERMINAL、FLAG_SESSION_START、FLAG_SHUTDOWN、FLAG_BULK和FRAME_HEADER_SIZE: usize 5即[id: u32 BE][flags: u8]部分crates/protocol/lib/codec.rs 定义MAX_FRAME_SIZE 4 * 1024 * 10244,194,304 字节普通帧上限就是前缀之外的这一长度。这个设计的精髓在于relay 只按 ID 和 flags 路由不解码 CBOR 主体。因此帧头的任何变更头大小、字节序、最大帧长、ID 路由、标志位语义都无法藏在 payload 协商后面——它必须是显式的、全系统可见的变更。演进规则保持外层帧形状稳定只新增消息类型绝不删除、改名或重新定义已发布的 wire 类型每个新消息类型指定引入代际并整体提升协议代际新 payload 字段必须可选或可取默认值不得就地变更已发布字段的语义或类型真正的格式断裂使用版本特定类型加转换器协商取对端较低的代际所有更新操作先做能力门控再发送在兼容地平线有意移动之前保留旧 codec——当前宿主仍理解 pre-0.5 的 codec 与握手新标志位必须让旧 relay 可以安全忽略否则改用能力门控消息。仓库中有一套完整的证据链crates/protocol/lib/message.rs 定义代际、帧常量、标志位、wire 名和消息引入映射crates/protocol/lib/codec.rs 定义当前分帧与校验逻辑packages/agent-client/rust/lib/client.rs 执行 codec 检测、版本协商与宿主侧发送门控crates/runtime/lib/runner/relay.rs 依赖 ID 段与标志语义路由不解析消息体crates/protocol/tests/schema_snapshot.rs 冻结版本化协议表面并检查只增不改的消息演进——生成确定性 JSON 与 crates/protocol/schema/ 下按代际存放的gen-3.json至gen-9.json快照做 diff重签用UPDATE_PROTOCOL_SCHEMA1触发且生成器只写当前代际文件历史文件保持冻结scripts/smoke/cli/pre05-running-sandbox-compat.sh 用真实运行的 pre-0.5 沙箱默认拉取 v0.4.6 发行版二进制与 alpine 镜像要求/dev/kvm可读可写验证当前宿主对旧 guest 的兼容。crates/protocol/VERSIONING.md 还补充了两点实操细节协商代际 min(宿主PROTOCOL_VERSION, ready 帧回显代际)每个MessageType通过min_protocol_version()声明引入代际且该函数没有通配分支——新增消息类型不指定代际就无法编译。发送门控在宿主客户端执行面向过旧沙箱的发送以类型化UnsupportedOperation错误单独失败不牵连无关流。需要注意schema 快照保护的是协议清单并不冻结每个 payload 的编码表示序列化变更时必须附带 golden 编码字节作为评审材料。边界二Bootstrap、Init 与 Guest 运行时契约Agent 协议的第一帧就是契约本身当前协议宿主的首帧是消息 ID 为 0、无标志的core.bootstrap随后 guest 回报解析后的 init 状态、relay 安装身份映射、宿主确认 initguest 才允许变为 readyhost guest agentd |---- core.bootstrap ------| |--- core.init.resolved ---| |---- core.init.ack --------| |--- core.ready -----------|兼容敏感要素包括bootstrap 字段默认值与 tagged 变体、首消息顺序、root/mount/network/security 编码、bind 身份交换、hostname 与环境变量行为、handoff 状态、以及遗留 boot-environment 拼写。此外还有一组稳定的 guest/VMM 标识符与路径构成隐式契约virtio-console 端口名agentvirtiofs 标签msb_runtimeguest 内运行时挂载点/.msb及其下的脚本、TLS、heartbeat 路径根块设备/dev/vda附加磁盘通过/dev/disk/by-id/virtio-id查找并保留 sysfs 回退以及用于正常终止和 handoff 的特有 host/guest 关机延迟。源码依据见 crates/protocol/lib/bootstrap.rs、crates/protocol/lib/lib.rs、crates/agentd/lib/agent.rs、crates/agentd/lib/init.rs 与 crates/runtime/lib/runner/vm.rs。边界三本地 Agent IPC 与 Relay 路由Unix 客户端和运行时同时识别三种 socket 路径形态规范的哈希路径、遗留的扁平哈希路径、以及更老的一层深沙箱路径Windows 使用由遗留哈希派生的命名管道。运行时在安全时发布兼容符号链接但绝不能覆盖一个活端点。兼容敏感要素包括哈希输入与截断、目录与 socket 命名、Unix 路径长度回退、Windows 管道名、兼容符号链接、陈旧端点清理顺序、生命周期锁路径与锁所有权relay 一侧则依赖客户端 ID 段分配、最大客户端数、终端路由、断连清理和关机标志。源码在 crates/runtime/lib/client/ipc.rs、crates/runtime/lib/runner/relay.rs 和 sdk/rust/lib/runtime/spawn.rs。两条铁律路径变更必须在支持期内保留旧路径探测或别名在通过既有锁与端点检查确认存活与所有权之前永远不要改路径哈希或删除 socket。边界四Live-Control 协议宿主运行时另开一条 Unix socketWindows 为命名管道用于运行中修改每条连接交换一行 JSON 请求与一行 JSON 响应当前操作覆盖能力发现、CPU/内存状态与目标、密钥更新等。兼容敏感要素包括换行分帧、taggedop名、响应变体、资源字段语义、能力发现以及端点不存在 / 操作不支持 / 操作失败三者的区分——旧运行时早于能力发现机制调用方刻意使用逐操作的回退行为。源码crates/runtime/lib/runner/control/ 与 sdk/rust/lib/sandbox/modify.rs。Windows 客户端在发送前会重试 missing-pipeERROR_FILE_NOT_FOUND与 busy-pipe 错误总连接预算 1 秒restore 剩余启动截止可能提前取消该等待其他错误立即失败已建立的请求永不重放。这让端点确实不存在的报告可能耗时最多 1 秒而非立即失败但不改变协议字节、端点身份或旧运行时能力语义。文档给出了三条重要的具体契约磁盘独占快照使用独立的disk_checkpoint_create操作与能力位可在 crates/runtime/lib/runner/control/executor.rs 中见到它与optional_disk_integrity、guest_flush_policy一起被运行时声明。能力缺失即视为 false调用方在捕获前拒绝而不是悄悄捕获 RAM 或复制可写磁盘运行时把磁盘 rollover 与其他控制变更串行化并保留用户的暂停状态。Resident 暂停/恢复只发一次权威性变更而不是先观察暂停状态再查询能力运行时在变更包括幂等请求前检查支持性客户端要求响应携带期望状态未知操作与不完整回复一律失败。演进规则统一为加操作、加可选字段而不是重定义已有操作凡是缺失时旧客户端无法安全解读的行为必须走能力门控。边界五Launcher 到 Runtime 的进程协议启动一个沙箱就跨过了一条私有进程边界这是文档篇幅最大的边界。命令形态v0.7.0 中私有启动器是msb machinemsb sandbox是公开命令组别名sbxSDK 为历史可执行文件选择经测试的 v0.6.x 启动契约历史内部msb sandbox启动与msb run等公开顶层动词仍然被识别。完整历史调用走独立的 boot-only 解码器msb machine保留严格的执行意图校验。描述符契约在 Unix 上launch JSON 经继承描述符 96 传入父看门狗用 97启动 JSON 用 98生命周期锁用 99Windows 改用短命 launch-config 文件加平台启动管道。detach 应答字节、优雅停机信号、密钥传输、父子清理顺序都属契约范围。TCP 限额沿用序列化键max_connections虽然规范 SDK 字段名是max_tcp_connectionsUDP 用max_udp_connections历史启动保留固定 256 会话的 UDP 预算显式 UDP 限额需要当前启动契约会在启动旧运行时前被拒绝——防止任一方向的 SDK/运行时版本偏斜悄悄放宽历史限额。恢复意图的严格校验launch JSON 要求显式execution意图boot或restore并拒绝未知字段restore 还传内部msb machine --restore参数——早于该契约的运行时拒绝未知参数而不是忽略 JSON restore 源后冷启动。不支持的恢复行为是错误永远不是冷启动回退。各平台的停机证据是这一边界最细致的部分Windowsv0.6.16 之前的运行时不持有当前生命周期锁SDK 在 guest ready 后把进程创建令牌、PID、sandbox/run ID 与所有权模式原子写入sandbox/runtime/sdk-process.json旧运行时/SDK 忽略该文件。终止前用保留句柄验证命名管道服务端并等待同一进程对象退出PID 复用不会导致误判。Linuxstop/kill 用pidfd需要 Linux 5.3钉住离场运行时先验证其继承的生命周期描述符等待整个线程组而非把僵尸主进程或锁释放当作磁盘拆除完成。macOS通过kqueue退出注册观察离场进程检查出生身份与生命周期描述符竞态时退化为按出生身份观察kern.proc.pid直至僵尸/消失进程查询失败不被视为清理完成。Windows 磁盘锁交接启动器把不可继承的 sidecar 句柄复制进确切的目标进程通过受限于启动阶段的 stdin 消息发送其值由隐藏标志msb machine --disk-locks-stdin触发运行时在打开 guest 磁盘前接管交接失败或取消在存储清理前终止子进程。Unix 侧磁盘锁描述符在 SDK 父进程中保持 close-on-exec只在目标子进程 pre-exec 回调中变为可继承——父进程副本关闭并不解锁子进程共享的 open-file description。创建回滚启动器在等待初始 PID 应答与 agent ready 期间都持有子进程所有权取消即请求终止该确切子进程有界终止无法证明退出时持久化恢复意图与存储保留不承诺无限制的内存保留。启动进度复用既有私有启动通道无新 socketPreparation EOF 有序地跟在结构化 boot-error 发布之后完整 restore 只有在 RAM、CPU、设备都到达构造暂停后才宣告 Activating。源码依据crates/runtime/lib/client/launch.rs、crates/runtime/lib/runner/vm.rs、sdk/rust/lib/runtime/spawn.rs、crates/cli/lib/machine_cmd.rs。边界六数据库、配置与迁移历史MSB_HOME下的 SQLite 数据库是跨版本的持久协议宿主与运行时进程必须在 WAL、busy timeout、外键、synchronous、写者设置上达成一致。兼容敏感要素包括迁移 ID 与顺序、迁移语义、schema 列与约束、持久化枚举/tag 拼写、JSON 配置形状、期望配置与激活配置的区分、安装/维护租约、分配状态、恢复日志、以及降级下限。演进规则永不重排、改名或复用已发布迁移 ID不编辑已应用迁移以产生不同的历史结果——新增迁移要求已应用迁移构成规范前缀拒绝领先于当前二进制的 schema转换变更状态的所有持久化表示含期望与激活配置多制品操作持久地记日志未完成时拒绝启动或降级降级要么精确重建旧表示要么在变更状态前拒绝升级期间保留仍在运行时的 SQL 与活动文件契约。仓库中 crates/migration/lib/ 现存 27 个带时间戳的迁移文件从m20260305_000001_create_image_tables到m20260910_000001_snapshot_groups与 crates/migration/lib/schema_metadata.rs、crates/migration/lib/lib.rs、crates/db/lib/pool.rs、sdk/rust/lib/backend/local/mod.rs 共同构成证据链。几个关键机制值得注意迁移锁串行化。本地启动用既有msb.db.migration.lock文件加共享进程锁助手Unix 为flockWindows 为LockFileEx串行化数据库打开、迁移与快照协调。SDK 与面向用户的 CLI 目录打开会在迁移锁与安装租约下应用待处理迁移即使旧运行时进程仍在活动私有msb machine启动则不做迁移直接开运行时池。升级事务先预留 SQLite 写者再做迁移读并发生命周期写不会与部分 schema 变更交错。目录访问 ≠ 活 VM 存活。旧版 SDK/CLI 可能因迁移历史更新而拒绝重开升级后的目录保留其目录访问与让其已运行 VM 继续存活不是同一个保证。当前读取器继续解码历史配置 JSON即使连接的行早于升级。降级操作的所有权使用既有db/self-downgrade/msb.db.migration.lock路径竞争命令立即失败而非排队等待下载或确认提示降级在制品变更前被拒绝时其日志退役为隐藏.cancelled-operation-id目录保留诊断文件而不阻塞普通命令。Windows 的遗弃租约恢复检查进程是否已退出而非仅 PID 能否打开——另一个进程可能仍持有已终止所有者的句柄。配置层的新旧分层用户/托管配置读取器把省略的版本默认 1 并拒绝非法/不支持版本用户写入器输出version: 1。旧二进制忽略用户版本字段且不实现托管配置。托管配置在 Unix 上现在拒绝非 root 所有或组/全局可写的文件权限检查错误同样拒绝加载缺失的托管文件仍是可选的。sandbox_defaults.outbound_proxy加入可选全局默认旧读取器忽略新设置——缺失字段保持原行为。Rust 侧的LocalBackend::lazy()改为返回Result、补丁类型改名SandboxSpecPatch取代旧共享SandboxConfigPatch等均为源码 API 变更明确不影响配置文件、持久化沙箱或 host/guest wire 格式。测试要求很具体打开真实旧数据库的副本、迁移它们、演练受影响行为、并测试每个受支持的逆向迁移或拒绝路径。边界七至十二路径布局、磁盘格式、OCI 缓存、文件元数据MSB_HOME 路径布局边界七目录名是跨版本二进制共用的持久定位符涵盖数据库、缓存、sandboxes、volumes、snapshots、logs、secrets、TLS 材料、SSH 状态、sockets、locks、journals 与配置文件。crates/utils/lib/lib.rs 中可直接看到SANDBOXES_SUBDIR、VOLUMES_SUBDIR、SNAPSHOTS_SUBDIR等常量以及非空MSB_HOME原样使用、不加.microsandbox后缀的解析规则。改名必须伴随迁移或旧位置探测且永不推断未识别的旧路径可安全删除。磁盘与文件系统镜像格式边界八磁盘字节比产生它们的二进制活得久。ext4 的兼容面包括 superblock 特性标志、组描述符、校验和、inode 大小、64 位布局、JBD2 日志状态、resize-inode 行为、干净/脏状态与重放要求EROS 与 VMDK 的常量、描述符、块大小、extent、设备表、适配器与对齐规则同样是持久格式。源码在 crates/image/lib/ext4、crates/image/lib/erofs/format.rs 与 crates/image/lib/stitch/vmdk.rs。硬性要求解析器与变更器在第一次写入前验证完整支持的特性集不支持的状态必须干净失败而不部分更新元数据变更器测试必须覆盖多种历史布局、脏/日志化镜像、边界尺寸、失败注入、文件系统检查器与操作后挂载验证。OCI 缓存与 Materializer ABI边界十缓存可重建但缓存条目与闭包会经由MSB_HOME和快照归档跨发行版存活。OCI 语义是外部定义的压缩描述符摘要、未压缩 diff ID、有序层、whiteout、opaque 目录、硬链接、xattr、非 UTF-8 路径、特殊文件与权限必须保持原义。平铺文件系统缓存的身份包含一个 materializer ABI——只要输出的文件系统字节或解释可能变化就必须提升该 ABI让不兼容条目未命中而非被复用。依据见 crates/image/MATERIALIZATION.md、crates/image/lib/cache/store.rs 与 crates/image/lib/flat.rs。宿主文件系统元数据边界十一bind 挂载与卷在 guest 外持久化虚拟 Linux stat 信息——Linux 用user.msb.override_statxattr 携带固定打包的版本化负载Windows 用 ADS 或.msb_override_statsidecar隐藏的init.krun合成条目是注入 agentd 的保留文件系统契约。敏感要素包括 xattr/ADS/sidecar 名、负载版本/宽度/字节序、uid/gid/mode/rdev 解释、符号链接表示、路径编码、隐藏元数据过滤、保留 inode/handle 值、whiteout 免疫。源码crates/filesystem/lib/backends/shared/stat_override.rs、crates/filesystem/lib/backends/passthroughfs/windows、crates/filesystem/lib/backends/shared/init_binary.rs。新元数据布局需要新的解码器版本以及当旧写入者必须消费该状态时迁移或变更前的干净拒绝。运行时/固件捆绑边界十二运行时、内嵌 agentd、精确的msb_krun版本当前 Cargo.toml 中锁定msb_krun 0.1.39、libkrun ABI、固件与补丁内核构成一个发行单元。接口面包括 virtio 特性位、设备配置布局、控制台行为、metrics 与 CPU 容量设备、vsock/TSI 行为、固件文件名、平台 VMM 后端。规则是不要因上游 ABI看起来兼容而单独替换或升级任一组件必须按单元在所有支持的 OS 与架构上验证。近期一个具体案例常规 x86 启动现在在 libkrun 默认内核命令行中声明krun.poweroffi8042匹配的 libkrunfw 注册低优先级最终 poweroff 处理器缺任何一半Linux 可能 halt 而不释放 VMM 所有权StopWithTimeout报告超时但不杀进程。已运行 guest 与完整快照保留其捕获的内核需要重新引导/捕获才能获得新处理器。边界九快照、Manifest 与可移植归档这是持久格式最复杂的边界核心对象是快照描述符的规范字节。描述符身份快照描述符携带稳定的随机snap_...ID但其规范字节而非该 ID决定描述符摘要。敏感要素包括字段顺序、必需的null值、map 顺序、重复键处理、tag 拼写、schema 与完整性标识、payload 名、父身份、state/scope/format 变体、扩展要求、翻译图行为。归档兼容面包括压缩检测、archive.json、规范清单顺序、传输摘要、接受的路径文法、遗留路径、缓存闭包条目以及重复/缺失/逃逸路径的拒绝。磁盘完整性模型磁盘代际 manifest 携带精确file_size与可选integrity_root新完整检查点与本地分支的根磁盘和复制的外部/命名磁盘默认做结构校验而非内容哈希显式完整性捕获才记录 root 并在可移植准入时校验。RAM 对象 ID 与校验保持不变。控制能力optional_disk_integrity门控完整/分支捕获SDK 启动或根磁盘日志初始化都不隐式计算缺失的磁盘哈希。几何记录未发布的完整检查点要求checkpoint.json中显式geometry记录原始 CPU 数/容量与初始 RAM/容量live resize 目标不能替代原始 guest 物理布局恢复在 RAM 准备前拒绝不一致。CPU 与 virtio-mem 状态把实际/请求计数与已插块位图分开保存。缺记录的旧开发检查点被拒绝而非猜测或迁移。分组存储与 CLI 变化安装快照现位于snapshots/group/snapshot_id/group.json选头、group-member.json存本地友好名裸选择器指组头group:member选精确成员既有扁平制品仍可按显式路径读取目录不被静默移动。snapshot load接受多个归档路径原来的位置参数目的地改为--dest DIR。批量头选择与输入顺序无关单一可证明的谱系尖端走既有快进规则歧义尖端保留现有头或让新组无头--set-head拒绝歧义批量。分支的内存快速路径Linux 临时分支使用能力门控的branch_create_memfd操作——启动器创建空的可密封 memfd通过既有控制 socket 上的 SCM_RIGHTS 随第一个 JSON 字节传输源在捕获前验证它只有精确几何与 RAM 准入允许时才填充随后施加 write/grow/shrink/seal 密封子进程在描述符 95 继承只读句柄。严格恢复信封的memory_descriptor字段要求显式的描述符感知读取器缺失描述符、几何不匹配、未密封的 backing 都失败而非退化为路径恢复或冷启动。注意/tmp/microsandbox-memory-uid/下只放小规模的 owner-only 记账记录与稳定的 handoff 锁guest RAM 不在那里——这是可交换的本地 backing不是持久存储也不构成全宿主准入保证或跨代零拷贝共享。捕获一致性捕获发布与源删除/替换共享run_dir/locks/lifecycle-hash.snapshot-lineage.lock这把稳定锁位于可删除的沙箱目录之外需要多重所有权的调用方按 transition → lineage → 运行时生命周期顺序获取。演进规则包括对携带身份的字节做语义无害的序列化变更时必须当身份格式变更处理保持遗留描述符翻译显式新增扩展用排序的 must-understand 要求或新 schema 加双向翻译payload 先发布、经临时文件 fsync 原子 rename 最后发布已验证描述符降级拒绝保持到持久逆向制品迁移完成。guest 刷新策略独立一节捕获请求携带可选guest_flush字段由guest_flush_policy能力门控缺失字段保留历史的崩溃一致策略显式auto要求写回才允许 live 磁盘独占捕获。既有 guest 冻结协议携带path:/与捕获的存储选择器并确认同步成功停止 guest 上的 Required 写回或未刷新的暂停 guest 会在磁盘 rollover 前失败运行时从不隐式恢复暂停的 guest。Rust 公开捕获配置新增带 serde 默认值的guest_flush字段Go native ABI 增加可选的显式策略暂停符号作为支持探测——新 Go 客户端拒绝不具备该语义的旧 native 库而不是让旧库悄悄忽略字段。一次性捕获分支批处理branch --names与 SDK 批量方法复用既有本地分支捕获/恢复信封批量保留进程本地 RAM pin 与临时 owner-only 链接每个子进程获得自己的链接、RAM 句柄、可写磁盘与 VM 代际身份没有任何新东西被序列化进 launch JSON、数据库或可移植快照。批启动在指定生产者发布捕获后有界并发结果保持输入顺序但运行时可见性、资源竞争与就绪顺序不保证有序。源码依据crates/image/lib/snapshot/manifest.rs、crates/image/lib/snapshot/migration.rs快照迁移与路径治理含.snapshot-migration.lock等保留名、sdk/rust/lib/snapshot/api.rs 等快照模块。边界十三至十六网络、Vsock/SSH、Metrics 共享内存、运行诊断网络边界十三可观察的网络行为本身是有效兼容契约——默认 MTU、沙箱槽位地址派生、IPv4 子网尺寸、guest/网关偏移、IPv6 前缀、确定性 MAC、接口名eth0、host.microsandbox.internal、DNS UDP/TCP 行为、DNS-over-TLS、TLS 拦截与信任路径、发布端口绑定、TCP 半关闭、UDP 对端生命周期、目的地策略、宿主侧密钥占位符替换。地址或 MAC 变更会造成冲突或悄悄改变策略身份协议变更必须用真实 TCP/UDP/DNS/TLS/HTTP CONNECT/发布端口/密钥替换客户端测试覆盖分片、半关闭、取消与被拒目的地。源码crates/network/lib/lib.rs、crates/network/lib/engine/network.rs 及 crates/network/lib 其余模块。Vsock 与 SSH 适配器边界十四vsock stream 与 datagram 路由有不同的消息边界与关闭语义平台后端为 Unix socket 与 Windows 命名管道SSH 把 exec 通道映射到 agent exec、SFTP 映射到 agent 文件系统消息、直接 TCP 转发映射到 agent TCP 消息——这些映射继承 Agent 协议代际要求。敏感要素包括端口/路由配置、stream 半关闭、datagram 边界、后端可用性、SSH 主机密钥与 known-host 持久化、认证行为、退出码与信号映射、SFTP 文件语义、direct-tcpip 能力门控。源码crates/vsock/lib/stream.rs、crates/vsock/lib/dgram.rs、sdk/rust/lib/sandbox/ssh.rs。改适配器到 agent 的映射时要用标准合规客户端并对旧运行中 agentd 版本实测。Metrics 共享内存 ABI边界十五metrics 是跨独立进程的二进制共享内存结构——固定尺寸头与槽位、magic、注册表版本、ABI、原子性、seqlock 顺序、代际计数器、生命周期状态、保留字节。规则不重排字段、不变宽度/对齐、不弱化原子顺序、不在同一 ABI 下重定义槽位状态不兼容变更必须提升注册表版本或 ABI避免新旧进程映射同一对象。除总尺寸断言外优先使用签入的偏移与二进制布局 fixture。源码crates/metrics/lib/layout.rs、crates/metrics/lib/registry.rs。心跳、启动错误、日志边界十六/.msb/heartbeat.json、boot-error.json、exec.log、运行时与内核日志、临时文件名、JSON 字段名、序列号、时间戳、源标签、轮转后缀、原子 rename 行为都跨进程消费并可能影响生命周期决策。语义要点心跳数据缺失或陈旧本身不是沙箱死亡的证据而活动会话影响空闲关机boot 错误必须在 agent ready 之前可用日志 schema 与轮转顺序必须保持当前 SDK 消费者可读。源码crates/protocol/lib/heartbeat.rs、crates/runtime/lib/runner/heartbeat.rs、crates/runtime/lib/client/boot_error.rs、crates/runtime/lib/runner/exec_log.rs。加可选字段给宽容的读取者重命名文件或字段必须带双读或迁移行为。边界十七生命周期、锁、租约与顺序即使序列化形状不变操作顺序本身也可以是兼容契约。生命周期锁、数据库运行行、PID 所有权、端点、metrics 槽位、CPU 与写回分配、心跳状态、维护租约、信号、关机延迟与清理共同决定沙箱是否活着、谁可以变更它。必须审查的顺序包括替换或删除端点前先解析锁与进程所有权不兼容运行时仍活动时阻止数据库与制品迁移共享资源按既定顺序预留、激活、标陈旧、释放;强制 VMM 终止前允许 agentd 与 guest 文件系统排空;payload 写入并验证后原子发布其携带身份的描述符;恢复日志在首次变更前持久化仅在持久完成之后清除。两个具体语义TCP 完成跟随两次有序的半关闭单独首个 EOF 保持对向可用graceful Stop 现在等待终结状态加上所选本地运行的生命周期所有权释放其有界变体消耗一个总预算含锁获取与派发零预算在派发前过期超时/取消永不升级为 Kill——旧运行时与保留旧 agent 代码的完整快照仍持有旧停机实现。并发与崩溃点必须显式审查同版本快乐路径测试不证明跨版本或崩溃兼容。源码crates/runtime/lib/client/ipc.rs、sdk/rust/lib/backend/local/mod.rs、sdk/rust/lib/runtime/handle.rs。差异评审触发器把风险识别前置到 diff 阶段COMPATIBILITY.md 把代码评审时的触发器显式列出这些模式出现即应视为兼容性绊线serde的 rename/tag/default/flatten/deny-unknown-fields/enum/数字类型变更magic 值、协议版本、特性标志、消息名、操作名、ID、保留位、帧限变更;路径常量、文件名、扩展名、哈希、截断长度、挂载标签、接口名、设备名、xattr 键、ADS 名、环境变量变更;规范序列化、字段顺序、排序、哈希域、摘要算法、UUID 派生、父身份、归档清单变更;编辑既有迁移而非追加新迁移;ext4、EROS、VMDK、OCI、日志、inode、块、描述符或校验和逻辑变更;repr(C)结构、共享内存字段、原子顺序、槽位状态、virtio 特性位、设备配置布局变更;启动、就绪、关机、超时、信号、锁、租约、rename、fsync、清理顺序变更;精确内部依赖 pin、内嵌 agent 选择、固件版本、soname、捆绑 URL、平台制品名变更;删除遗留解析器、codec、路径探测、翻译、回退、迁移或兼容性测试。声明兼容安全之前需要的证据文档最后给出一个按边界与失败风险成比例的证据清单针对解析、校验、能力门控、变更前干净拒绝的单元测试wire/规范/二进制布局/携带身份格式的 golden 字节或签入 fixture如 packages/protocol-fixtures/control-v1.json、crates/protocol/tests/control_contract.rs 生成的 26 个 generation-1 fixture 与精确字节比较、crates/protocol/tests/legacy_json_contract.rs 固定 v0.6.4 至 v0.6.18 的历史 JSON 契约受支持旧版本产生的制品副本数据库、ext4 镜像、manifest、归档、缓存条目、元数据树真实旧二进制用于 live host-agent、本地 IPC、启动器/运行时与捆绑互操作如 scripts/smoke/cli/pre05-running-sandbox-compat.sh正向迁移加上受支持的逆向迁移或降级拒绝测试围绕日志、元数据写入、fsync、rename、发布、清理的崩溃与失败注入;外部校验器文件系统检查器与标准合规的 SSH、SFTP、DNS、TLS、TCP、UDP、OCI、归档读取器平台与架构覆盖Linux/KVM、macOS/HVF、Windows/WHP、Unix socket、命名管道、固件、打包运行时制品。若某方向无法在本地测试必须写明什么仍未验证、需要哪个 CI/平台/历史二进制/fixture——不确定性被要求显式化而非掩盖。结语COMPATIBILITY.md 展示了一套可复用的跨版本工程方法论把兼容从模糊承诺变成有源码出处、有冻结 fixture、有真实旧二进制演练、有明确降级下限的 17 条可评审边界用只增不改 能力门控 干净拒绝三条主线约束演进用迁移前缀、恢复日志、原子发布保证持久状态可恢复。对维护任何长生命周期系统数据库、虚拟机监控器、格式化工具的团队这份文档本身就是比任何单条规则都更有价值的参考它规定的不只是做什么更是声称兼容安全前必须出示什么证据。赞分享Agent 沙箱虚拟化【免费下载链接】microsandbox fast branchable microVM for any workload项目地址https://gitcode.com/gh_mirrors/mon/microsandbox点击查看免费下载相关推荐Paseo 协议兼容性工程实践App 与 Daemon 跨版本共存的契约设计Paseo 协议兼容性工程实践App 与 Daemon 跨版本共存的契约设计 导读 Paseo 的桌面端/移动端 App 与后台 Daemon 是 分开发布深入解读 microsandbox 的 AGENTS.mdAI 协作工程规范、项目地图与跨版本兼容性防线深入解读 microsandbox 的 AGENTS.mdAI 协作工程规范、项目地图与跨版本兼容性防线 microsandbox 的 AGENTS.md hAgent 沙箱虚拟化Databend-meta 跨版本协议兼容性测试指南从快照复制到投票请求的完整验证方案Databend meta 跨版本协议兼容性测试指南从快照复制到投票请求的完整验证方案 导读 本文围绕 Databend 仓库中 tests/compat/m数据库数据分析向量数据库全文检索云原生AI 应用上一篇终极免费窗口强制调整工具轻松突破Windows窗口尺寸限制下一篇终极3DS自制软件管理指南Universal-Updater完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考