原始块（Rust）#

一个内置的 L2 适配器，通过 Rust 原始设备 I/O 接口将 KV 对象存储在原始块设备或预设大小文件的固定大小槽位中。它复用现有的原始块元数据检查点模型，并在预取期间直接写入调用方提供的加载缓冲区。

必填字段：

  • device_path: 原始设备路径或预设大小的文件路径。

  • slot_bytes: 固定的槽大小（以字节为单位）。必须与 block_align 对齐。

可选字段：

  • capacity_bytes：可用设备字节的可选上限。默认值 0 表示使用完整的设备/文件大小。

  • use_odirect: true 或 false（默认 true）。

  • block_align: 设备对齐字节数（默认 4096）。

  • header_bytes: 每个槽位的头部预留大小（默认 4096）。

  • meta_total_bytes: 保留的元数据检查点区域（默认 256MiB）。

  • meta_magic / meta_version: 元数据检查点的标识符与版本号调节参数。

  • meta_checkpoint_interval_sec / meta_idle_quiet_ms / meta_enable_periodic / meta_verify_on_load: 从旧版原始块后端沿用的检查点与恢复控制参数。

  • load_checkpoint_on_init: 在启动时加载现有的设备元数据检查点（默认值为 true）。设置为 false 以从空的内存索引开始。

  • enable_zero_copy: 尽可能尝试对齐的直接缓冲区 I/O。

  • io_engine: Rust 原始块 I/O 引擎。有效值为 "posix"（默认同步 pread/pwrite 路径），"io_uring"（直接 Rust io_uring 系统调用路径）。

  • use_uring_cmd: 通过 io_uring 命令接口启用 NVMe 直通以直接访问设备。需要 io_engine="io_uring" 和 NVMe 字符设备节点（例如，/dev/ng0n1）。

  • iouring_queue_depth: io_engine="io_uring" 的队列深度。

  • max_data_transfer_size: use_uring_cmd=true 的最大数据传输大小。大数据传输会被拆分成适合设备限制的小块。

  • num_store_workers / num_lookup_workers / num_load_workers: 每种操作类型的工作线程数量。

注意：

  • raw_block 是一个由服务端管理的 MP 适配器。它 不 支持 MP 模式下按 TP 粒度配置设备路径映射。

  • raw_block 在所有支持的引擎中保持 "type": "raw_block"。

  • raw_block 负责设备上的槽分配、检查点和通过 RawBlockCore 的恢复。槽回收由共享/全局 L2 逐出控制器或显式的 delete() 调用驱动。

  • 如果启用了 use_odirect，则服务器的 --l1-align-bytes 应至少为 block_align。

  • persist_enabled 对此适配器必须保持为 true。

  • 对于 use_uring_cmd=true，device_path 必须使用 NVMe 字符设备节点（例如，/dev/ng0n1），而不是块设备节点（/dev/nvme0n1）。字符设备提供直接的 NVMe 命令直通。

  • use_uring_cmd 需要设置 io_engine="io_uring"。

  • 当 use_uring_cmd=true 时，NVMe 命名空间字符设备将忽略 use_odirect。

配置示例：

# Basic raw_block with posix I/O
--l2-adapter '{"type": "raw_block", "device_path": "/dev/nvme0n1", "slot_bytes": 1048576, "block_align": 4096, "header_bytes": 4096, "meta_total_bytes": 268435456, "use_odirect": true, "num_store_workers": 2, "num_lookup_workers": 1, "num_load_workers": 4}'

# With io_uring
--l2-adapter '{"type": "raw_block", "device_path": "/dev/nvme0n1", "slot_bytes": 1048576, "io_engine": "io_uring", "iouring_queue_depth": 256, "use_odirect": true}'

# With io_uring_cmd (NVMe passthrough)
--l2-adapter '{"type": "raw_block", "device_path": "/dev/ng0n1", "slot_bytes": 1048576, "io_engine": "io_uring", "use_uring_cmd": true, "iouring_queue_depth": 256, "max_data_transfer_size": 131072, "use_odirect": false}'

# With eviction
--l2-adapter '{"type": "raw_block", "device_path": "/dev/nvme0n1", "slot_bytes": 1048576, "load_checkpoint_on_init": false, "eviction": {"eviction_policy": "LRU", "trigger_watermark": 0.9, "eviction_ratio": 0.1}}'