QCOW2 文件数据结构详细介绍

原创

已于 2025-09-23 11:43:53 修改 · 987 阅读

13 ·

CC 4.0 BY-SA版权

文章标签：

#服务器

于 2025-09-20 09:59:37 首次发布

一、总体结构 (General)

基本单元：QCOW2 镜像文件由固定大小的簇 (Cluster) 组织而成。簇是进行所有分配（包括客户机数据和镜像元数据）的基本单位。
字节序：所有数字均使用大端序 (Big Endian) 字节顺序存储。

二、文件头 (Header)

文件的第一簇包含文件头，定义了镜像的全局属性。

关键字段：
- magic：魔数字符串 'QFI\xfb'。
- version：版本号（有效值为 2 和 3）。
- backing_file_offset/size：指向后备文件（基础镜像）名称的偏移和长度。
- cluster_bits：用于计算簇大小 (1 << cluster_bits)。簇大小最小为 512 字节，QEMU 实现限制最大为 2MB。
- size： 虚拟磁盘的大小（以字节为单位）。这是我们升级操作的目标。
- crypt_method：加密方法（0 表示无加密，1 表示 AES 加密）。
- l1_size, l1_table_offset： 活跃 L1 表的大小和文件偏移量。这是升级操作需要修改的核心元数据之一。
- refcount_table_offset, refcount_table_clusters： 引用计数表的位置和大小。升级操作需要更新此结构。
- nb_snapshots, snapshots_offset： 快照数量和快照表的起始位置。升级操作需要遍历和修改所有快照的元数据。
V3 版本新增字段：
- incompatible_features：不兼容功能位掩码（例如，Dirty bit, Corrupt bit）。
- compatible_features：兼容功能位掩码（例如，Lazy refcounts）。
- autoclear_features：自动清除功能位掩码（例如，Bitmaps extension bit）。
- refcount_order：引用计数位宽（V2 固定为 4，即 16 位）。
- header_length：头部长度的字节数（V2 为 72 字节）。
头部扩展 (Header Extensions)：头部之后可以存储可选扩展节，如后备文件格式名、功能名称表、位图扩展 (Bitmaps extension) 等。

三、主机簇管理 (Host cluster management)

QCOW2 通过维护每个主机簇的引用计数来管理其分配。

两级结构：
1. 引用计数表 (Refcount Table)：第一级，可变大小，在文件中连续。表中的条目指向引用计数块。
2. 引用计数块 (Refcount Block)：第二级，每个块正好一个簇大小。块中的条目存储具体簇的引用计数。
查找流程：给定文件偏移量，通过计算 refcount_table_index 和 refcount_block_index 来找到对应的引用计数值。

四、簇映射 (Cluster mapping)

用于将客户簇偏移映射到主机簇偏移，同样采用两级结构。

两级结构：
1. L1 表：第一级，可变大小，在文件中连续。表中的条目指向 L2 表。快照的核心就是切换活跃的 L1 表。
2. L2 表：第二级，每个表正好一个簇大小。表中的条目是簇描述符 (Cluster Descriptor)。
查找流程：给定虚拟磁盘偏移量，通过计算 l1_index 和 l2_index 来找到对应的主机簇偏移量。
簇描述符类型：
- 标准簇：包含主机簇偏移量。Bit 63 指示其引用计数是否为 1（仅活跃 L1 表准确）。
- 压缩簇：包含非对齐的偏移量和压缩后的大小。
- 全零簇： Bit 0 被设置，该簇读操作返回全零，无需分配实际空间或读取后备文件。

五、快照 (Snapshots)

QCOW2 支持内部快照，其基本原理是切换活跃的 L1 表。

创建快照：复制当前的 L1 表，并增加所有由此 L1 表可访问的 L2 表和簇的引用计数，以实现写时复制 (COW)。
快照表 (Snapshot Table)：存储在 snapshots_offset，包含所有快照的元数据。
快照表条目：包含快照的 L1 表偏移量、L1 表大小、唯一 ID、名称、时间戳、VM 状态大小等信息。升级工具需要读取并修改每个快照条目中的 l1_table_offset 字段。

六、位图 (Bitmaps) - (V3 功能)

位图扩展用于存储与虚拟磁盘相关的位图，目前主要是脏跟踪位图 (Dirty Tracking Bitmap)。

位图扩展头：包含位图数量 (nb_bitmaps) 和位图目录 (Bitmap Directory) 的位置和大小。
位图目录：包含每个位图的元数据（头信息），如位图表偏移量、标志位、类型、粒度、名称等。
位图表 (Bitmap Table)：一级结构，用于将位图数据映射到主机簇。条目结构类似于 L2 表条目。
脏跟踪位图：类型为 1。当启用时（auto 标志位设置），所有对虚拟磁盘的写入操作都会反映在位图中（设置对应的位）。

https://github.com/zchee/go-qcow2/blob/master/docs/specification.md#header

General

A qcow2 image file is organized in units of constant size, which are called (host) clusters. A cluster is the unit in which all allocations are done, both for actual guest data and for image metadata.

Likewise, the virtual disk as seen by the guest is divided into (guest) clusters of the same size.

All numbers in qcow2 are stored in Big Endian byte order.

Header

The first cluster of a qcow2 image contains the file header:

Byte  0 -  3:   magic
                QCOW magic string ("QFI\xfb")

      4 -  7:   version
                Version number (valid values are 2 and 3)

      8 - 15:   backing_file_offset
                Offset into the image file at which the backing file name
                is stored (NB: The string is not null terminated). 0 if the
                image doesn't have a backing file.

     16 - 19:   backing_file_size
                Length of the backing file name in bytes. Must not be
                longer than 1023 bytes. Undefined if the image doesn't have
                a backing file.

     20 - 23:   cluster_bits
                Number of bits that are used for addressing an offset
                within a cluster (1 << cluster_bits is the cluster size).
                Must not