# MoonQCOW 只读兼容范围

MoonQCOW 的目标是为声明支持的 QCOW2 配置提供只读逻辑数据访问和可复现导出。它不承诺打开每一个规范允许的镜像；规范有效但超出下表范围的镜像会明确报不支持，不会伪造为零数据或报告完整成功。

| 镜像特性 | 状态 | 读取行为 |
| --- | --- | --- |
| QCOW2 v2/v3、512 字节至 2 MiB 簇 | 支持 | 校验头部和边界后读取逻辑扇区/字节。 |
| 标准 L1/L2、扩展 L2、显式零簇 | 支持 | 解析活动映射；未分配区段按 backing 规则回退，否则补零。 |
| raw / qcow2 backing 链 | 有条件支持 | 核心 API 由调用方显式提供 backing source；Node CLI 仅在 `--allow-backing` 时跟随镜像路径，并要求格式扩展明确写为 raw 或 qcow2。 |
| DEFLATE 压缩簇 | 支持 | 解压单个 raw DEFLATE 簇，并校验解压长度。 |
| Zstandard（zstd）压缩簇 | 支持 | 仅接受 v3 compression type 标志与类型字段一致的 zstd 镜像；按单簇解压、限制窗口和输出长度，并在簇帧结束处停止，以容忍规范允许的扇区尾部共享。 |
| AES / LUKS 或其他非零加密方法 | 不支持 | 在头部检查时返回 `Unsupported`；不请求密钥、不解密、不把密文当作客户机明文。 |
| 外部数据文件 | 不支持 | 检测到 external-data 不兼容特性位时返回 `Unsupported`；不依据头扩展自动打开旁路数据文件。 |
| dirty、corrupt 或未知不兼容特性位 | 不支持 | 拒绝读取，不尝试修复或忽略状态。 |
| 未知压缩类型、压缩数据损坏或解压尺寸不符 | 不支持 / 无效镜像 | 未知类型返回 `Unsupported`；损坏帧或尺寸不符返回格式错误，不输出补零替代内容。 |
| 内部快照 | 支持 | 可枚举并按快照 ID 读取客户机虚拟磁盘内容；快照保存的 VM 运行状态不作为磁盘字节读取。 |

## 场景处理

- **普通或 DEFLATE 镜像：**直接读取或使用 CLI 导出；数据与 QEMU 导出的 RAW 结果做逐字节对照。
- **zstd 镜像：**支持标准 v3 zstd 压缩簇，互操作测试使用 QEMU 生成镜像，并逐字节比较读取/导出结果。
- **含 backing 文件的差分镜像：**库调用者必须显式传入 backing source；Node CLI 需要 `--allow-backing`。缺文件、链循环、格式未声明或深度超限时返回错误；只有合法 backing 文件短于虚拟磁盘的尾部按 QCOW2 规则补零。
- **加密或外部数据镜像：**当前读取目标不覆盖这两类镜像。程序在访问客户机数据前报出不支持原因；用户应先用具备相应密钥/外置数据文件的 QEMU 等工具解密或合并为受支持的普通 QCOW2/RAW 输入。
- **活动中或损坏镜像：**dirty/corrupt 标记会被拒绝；请先停止写入镜像，并由 QEMU 工具完成一致性检查或修复后再读取。

资源上限（簇大小、读取块、链深度、扫描数量等）由 `Limits` 控制。达到上限时操作失败，不会截断数据并冒充成功。该兼容声明是只读功能范围，不代表写入、修复或与所有 QCOW2 特性完全一致。
