From 246fe62c2f5767a3a295673cf70a7ad10b1e3b7c Mon Sep 17 00:00:00 2001
From: GatewayJ <835269233@qq.com>
Date: Sat, 28 Feb 2026 00:39:14 +0800
Subject: [PATCH 1/7] =?UTF-8?q?doc:=20=E7=BB=86=E5=8C=96=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
docs/DESIGN.md | 720 +++++++++++
docs/README.md | 28 +
docs/modules/01-access-layer.md | 122 ++
docs/modules/02-protocol-adapter.md | 157 +++
docs/modules/03-metadata-cluster.md | 1163 ++++++++++++++++++
docs/modules/04-cache-layer.md | 668 +++++++++++
docs/modules/05-scheduler-layer.md | 789 ++++++++++++
docs/modules/06-tape-layer.md | 1012 ++++++++++++++++
docs/modules/07-consistency-performance.md | 765 ++++++++++++
docs/modules/08-observability.md | 1250 ++++++++++++++++++++
docs/modules/09-admin-console.md | 1054 +++++++++++++++++
docs/modules/README.md | 34 +
12 files changed, 7762 insertions(+)
create mode 100644 docs/DESIGN.md
create mode 100644 docs/README.md
create mode 100644 docs/modules/01-access-layer.md
create mode 100644 docs/modules/02-protocol-adapter.md
create mode 100644 docs/modules/03-metadata-cluster.md
create mode 100644 docs/modules/04-cache-layer.md
create mode 100644 docs/modules/05-scheduler-layer.md
create mode 100644 docs/modules/06-tape-layer.md
create mode 100644 docs/modules/07-consistency-performance.md
create mode 100644 docs/modules/08-observability.md
create mode 100644 docs/modules/09-admin-console.md
create mode 100644 docs/modules/README.md
diff --git a/docs/DESIGN.md b/docs/DESIGN.md
new file mode 100644
index 0000000..ad9d533
--- /dev/null
+++ b/docs/DESIGN.md
@@ -0,0 +1,720 @@
+# ColdStore 详细设计方案
+
+> 版本：1.1
+> 更新日期：2025-02-27
+
+## 1. 文档概述
+
+本文档描述 ColdStore 冷存储系统的详细技术设计方案，重点涵盖：
+
+> **模块设计文档**：各层独立设计详见 [modules/](modules/) 目录。
+
+1. **协议层**：兼容 S3 冷归档协议（Glacier 语义）
+2. **集群元数据**：基于 [OpenRaft](https://github.com/databendlabs/openraft) + RocksDB 持久化
+3. **数据缓存层**：基于 [async-spdk](https://github.com/madsys-dev/async-spdk) 的高性能用户态缓存
+
+### 1.1 核心技术选型（已确定）
+
+| 组件 | 库/方案 | 说明 |
+|------|---------|------|
+| Raft 共识 | **openraft** | [databendlabs/openraft](https://github.com/databendlabs/openraft)，异步 Raft，Tokio 驱动 |
+| Raft 存储 | **openraft-rocksstore** | RocksDB 后端，RaftLogStorage + RaftStateMachine |
+| SPDK 绑定 | **async-spdk** | [madsys-dev/async-spdk](https://github.com/madsys-dev/async-spdk)，原生 async/await |
+| 磁带 SDK | **自研抽象层** | 前期对接 Linux SCSI（st 驱动 + MTIO ioctl），后期可扩展厂商 SDK |
+
+---
+
+## 2. 系统架构总览
+
+### 2.1 物理部署模型
+
+ColdStore 由五类节点组成。**Scheduler Worker 是唯一的业务中枢**，
+Gateway 仅连接 Scheduler Worker，Console 仅连接 Metadata。
+
+```
+┌────────────────┐ ┌────────────────┐
+│ Gateway (N台) │ │ Console (1台) │
+│ S3 HTTP 前端 │ │ 管控面 Web UI │
+│ 无状态 │ │ 无状态 │
+└──────┬─────────┘ └──────┬─────────┘
+ │ gRPC (配置: Scheduler 地址) │ gRPC (配置: Metadata 地址)
+ ▼ ▼
+ ┌─────────────────────────────┐ ┌──────────────────────────┐
+ │ 同一物理节点 │ │ Metadata 节点 (3/5 台) │
+ │ ┌─────────────────────────┐ │ │ Raft 共识 + RocksDB │
+ │ │ Scheduler Worker │─┼───►│ 元数据 + Worker 注册中心 │
+ │ │ 业务中枢：调度编排 │ │ └──────────────────────────┘
+ │ ├─────────────────────────┤ │ ▲
+ │ │ Cache Worker │ │ │ 心跳
+ │ │ SPDK Blobstore 缓存 │ │ ┌──────────┴───────────────┐
+ │ └─────────────────────────┘ │ │ Tape Worker (独立物理节点) │
+ └─────────────────────────────┘ │ 磁带驱动 /dev/nst* │
+ │ 带库 /dev/sg* │
+ └────────────────────────────┘
+```
+
+| 节点类型 | 职责 | 数量 | 连接对象 |
+|----------|------|------|----------|
+| **Metadata** | Raft 共识、元数据存储、Worker 注册中心 | 3/5 | 三类 Worker 心跳；Console 管控 |
+| **Scheduler Worker** | **业务中枢**：调度编排、对接全部层（与 Cache 同机） | 1~N | Metadata、Cache Worker、Tape Worker、Gateway |
+| **Cache Worker** | SPDK NVMe 数据缓存（与 Scheduler 同机） | 1~N | Scheduler Worker (gRPC)、Metadata (心跳) |
+| **Tape Worker** | 磁带驱动管理、数据读写（独立物理节点） | 1~N | Scheduler Worker (gRPC)、Metadata (心跳) |
+| **Gateway** | S3 HTTP 接入 + 协议适配（无状态） | N | **仅 Scheduler Worker** |
+| **Console** | 管控面 Web UI + Admin API（无状态） | 1 | **仅 Metadata** |
+
+**关键设计决策**：
+
+- **Gateway 不直连 Metadata**：Gateway 是纯粹的 S3 协议前端，所有业务请求（包括元数据查询）
+ 都通过 Scheduler Worker 代理。Gateway 配置文件中只需写 Scheduler Worker 地址。
+- **Scheduler Worker 是唯一业务中枢**：持有 MetadataClient，编排 Cache Worker 和 Tape Worker，
+ 接受 Gateway 的全部请求。
+- **Console 仅连 Metadata**：管控面直接查询/操作元数据集群，管理 Worker 的增删。
+- **Scheduler ↔ Cache 使用 gRPC**：虽然同机部署，仍通过 gRPC 跨网络连接，
+ 保持架构一致性，未来可独立扩展。
+
+### 2.2 逻辑分层架构
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ S3 接入层 (Axum) — Gateway │
+│ PUT / GET / HEAD / DELETE / RestoreObject / ListBuckets ... │
+│ S3 冷归档协议适配层 │
+│ StorageClass 映射 | RestoreRequest 解析 | x-amz-restore 响应 | 错误码映射 │
+└─────────────────────────────────────────────────────────────────────────────┘
+ │ gRPC (全部请求)
+ ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ 归档/取回调度器 — Scheduler Worker（业务中枢） │
+│ 接受 Gateway 请求 │ 编排 Cache 和 Tape │ 读写 Metadata │
+└─────────────────────────────────────────────────────────────────────────────┘
+ │ │ │
+ ▼ gRPC ▼ gRPC (同机) ▼ gRPC (远程)
+┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐
+│ 元数据集群 (Raft) │ │ 数据缓存层 (SPDK) │ │ 磁带管理层 (Tape) │
+│ Metadata 节点 │ │ Cache Worker │ │ Tape Worker │
+│ RocksDB 持久化 │ │ 用户态 NVMe 缓存 │ │ 自研 SDK + SCSI │
+└───────────────────────┘ └───────────────────────┘ └───────────────────────┘
+```
+
+### 2.3 交互模式
+
+**Scheduler Worker 是唯一的元数据读写入口**（Console 管控除外）。
+Gateway、Cache Worker、Tape Worker 均不直接访问 Metadata。
+
+```
+ Console ──管控读写──▶ Metadata
+ ▲
+Gateway ──全部请求──▶ Scheduler Worker ──读+写──────────┘
+ │
+ ├──gRPC──▶ Cache Worker (纯数据存储)
+ └──gRPC──▶ Tape Worker (纯硬件抽象)
+```
+
+| 层 | 与 Metadata 的关系 | 与 Scheduler 的关系 | 说明 |
+|------|------|------|------|
+| Gateway | **无直接连接** | gRPC 客户端 | 所有请求代理给 Scheduler |
+| Scheduler Worker | 读 + 写 | — | 唯一业务中枢 |
+| Cache Worker | 仅心跳注册 | gRPC 服务端 | 纯数据存储 |
+| Tape Worker | 仅心跳注册 | gRPC 服务端 | 纯硬件抽象 |
+| Console | 管控读写 | 无 | Worker 增删、元数据查询 |
+
+---
+
+## 3. S3 冷归档协议兼容设计
+
+### 3.1 协议兼容目标
+
+ColdStore 是**纯冷归档系统**，设计模型与 AWS S3 Glacier Deep Archive 一致：
+所有对象写入即排队归档到磁带，不提供在线热存储层。外部热存储系统在需要冷归档时调用 ColdStore 的 PutObject API，迁移决策由外部系统负责。
+
+在协议层面兼容 AWS S3 Glacier 冷归档语义，使现有 S3 客户端、SDK 及业务系统无需改造即可接入。
+
+### 3.2 存储类别映射
+
+ColdStore 仅有两种内部存储状态：
+
+| S3 Storage Class | ColdStore 内部状态 | 说明 |
+|------------------|-------------------|------|
+| 任意（`GLACIER` / `DEEP_ARCHIVE` / `STANDARD` 等） | `ColdPending` | 写入即排队归档（统一冷存储入口） |
+| 归档完成 | `Cold` | 已归档到磁带 |
+
+### 3.3 RestoreObject API 规范
+
+#### 3.3.1 请求格式
+
+```
+POST /{Bucket}/{Key}?restore&versionId={VersionId} HTTP/1.1
+Host: {endpoint}
+Content-Type: application/xml
+
+
+ integer
+
+ Expedited|Standard|Bulk
+
+
+```
+
+**关键参数：**
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `Days` | 是 | 解冻数据保留天数，最小 1 天 |
+| `GlacierJobParameters.Tier` | 否 | 取回优先级：Expedited / Standard / Bulk |
+| `versionId` | 否 | 对象版本，缺省为当前版本 |
+
+#### 3.3.2 取回层级 (Tier) 语义
+
+| Tier | 预期完成时间 | ColdStore 实现策略 |
+|------|-------------|-------------------|
+| **Expedited** | 1–5 分钟 | 高优先级队列，可配置预留容量 |
+| **Standard** | 3–5 小时 | 默认队列，常规调度 |
+| **Bulk** | 5–12 小时 | 低优先级，批量合并取回 |
+
+#### 3.3.3 响应规范
+
+| 场景 | HTTP 状态码 | 说明 |
+|------|------------|------|
+| 首次解冻请求 | `202 Accepted` | 任务已接受，等待处理 |
+| 已解冻且未过期 | `200 OK` | 可延长 Days，仅更新过期时间 |
+| 解冻进行中 | `409 Conflict` | 错误码 `RestoreAlreadyInProgress` |
+| Expedited 容量不足 | `503 Service Unavailable` | 错误码 `GlacierExpeditedRetrievalNotAvailable` |
+| 对象尚未归档 | `409 Conflict` | ColdPending 状态对象不可 Restore |
+
+### 3.4 HEAD Object 与 x-amz-restore 响应头
+
+对冷对象执行 HEAD 时，需返回 `x-amz-restore` 头以表示解冻状态：
+
+```
+x-amz-restore: ongoing-request="true"
+```
+或
+```
+x-amz-restore: ongoing-request="false", expiry-date="Fri, 28 Feb 2025 12:00:00 GMT"
+```
+
+### 3.5 GET Object 冷对象访问控制
+
+| 对象状态 | GET 行为 |
+|----------|----------|
+| ColdPending（排队中） | 返回 `403 InvalidObjectState`，对象尚未归档 |
+| Cold + 未解冻 | 返回 `403 InvalidObjectState`，提示需先 Restore |
+| Cold + 解冻中 | 返回 `403 InvalidObjectState` |
+| Cold + 已解冻 | 从 SPDK 缓存读取并返回 |
+| Cold + 解冻已过期 | 返回 `403 InvalidObjectState`，需重新 Restore |
+
+### 3.6 错误码映射
+
+| AWS 错误码 | HTTP 状态 | ColdStore 实现 |
+|------------|-----------|----------------|
+| `InvalidObjectState` | 403 | 冷对象未解冻时 GET |
+| `RestoreAlreadyInProgress` | 409 | 重复 Restore 请求 |
+| `GlacierExpeditedRetrievalNotAvailable` | 503 | Expedited 容量不足 |
+### 3.7 归档触发模型
+
+ColdStore 是纯冷归档系统（类似 AWS Glacier Deep Archive），所有对象 PutObject 写入即标记为 `ColdPending`，
+自动排队等待调度器聚合写入磁带。不支持 Hot/Warm 存储类别和生命周期规则。
+
+外部热存储系统在需要冷归档时，直接调用 ColdStore 的 PutObject API 写入对象。
+迁移决策（何时归档）由外部系统负责，ColdStore 不做生命周期管理。
+
+---
+
+## 4. 集群元数据：Raft + RocksDB 设计
+
+### 4.1 设计目标
+
+- **强一致性**：元数据读写通过 Raft 达成共识
+- **高可用**：多数节点存活即可服务
+- **持久化**：RocksDB 作为 Raft 日志与状态机的存储引擎
+- **可扩展**：支持 3/5/7 节点集群
+
+### 4.2 架构图
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ColdStore 元数据节点 │
+├─────────────────────────────────────────────────────────────────┤
+│ ┌─────────────────────────────────────────────────────────────┐ │
+│ │ Raft Core (openraft) │ │
+│ │ - databendlabs/openraft │ │
+│ │ - 异步事件驱动，Tokio 运行时 │ │
+│ └─────────────────────────────────────────────────────────────┘ │
+│ │ │
+│ │ RaftLogStorage / RaftStateMachine │
+│ ▼ │
+│ ┌─────────────────────────────────────────────────────────────┐ │
+│ │ openraft-rocksstore (RocksStore) │ │
+│ │ - Raft 日志 + 状态机持久化 │ │
+│ │ - RocksDB 单实例，可扩展 CF 存储业务元数据 │ │
+│ └─────────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 4.3 技术选型（已确定）
+
+| 组件 | 选型 | 说明 |
+|------|------|------|
+| Raft 实现 | **openraft** | [databendlabs/openraft](https://github.com/databendlabs/openraft)，异步 Raft，Tokio 驱动 |
+| Raft 存储 | **openraft-rocksstore** | [crates.io/openraft-rocksstore](https://crates.io/crates/openraft-rocksstore)，RocksDB 后端 |
+| 存储引擎 | RocksDB | 通过 openraft-rocksstore 封装 |
+
+### 4.3.1 OpenRaft 集成要点
+
+- **依赖**：`openraft = "0.9"`，`openraft-rocksstore = "0.9"`
+- **TypeConfig**：定义 `NodeId`、`Node`、`AppData`、`AppDataResponse` 等类型
+- **RocksRequest**：扩展 `AppData`，定义 `PutObject`、`DeleteObject`、`PutRecallTask` 等命令
+- **RocksStateMachine**：实现 `apply` 逻辑，将命令写入 RocksDB 业务 CF
+- **线性读**：`raft.ensure_linearizable().await` 保证读到已提交状态
+
+### 4.4 RocksDB 数据模型
+
+#### 4.4.1 Column Family 设计
+
+| CF 名称 | Key 格式 | Value 格式 | 说明 |
+|---------|----------|-----------|------|
+| `objects` | `obj:{bucket}:{key}` | ObjectMetadata (JSON/Protobuf) | 对象元数据 |
+| `object_versions` | `objv:{bucket}:{key}:{version}` | ObjectMetadata | 多版本对象 |
+| `bundles` | `bundle:{uuid}` | ArchiveBundle | 归档包 |
+| `tapes` | `tape:{tape_id}` | TapeInfo | 磁带信息 |
+| `recall_tasks` | `recall:{uuid}` | RecallTask | 取回任务 |
+| `archive_tasks` | `archive:{uuid}` | ArchiveTask | 归档任务 |
+| `index_bundle_objects` | `idx_b:{archive_id}:{bucket}:{key}` | 空 | 归档包→对象反向索引 |
+| `index_tape_bundles` | `idx_t:{tape_id}:{bundle_id}` | 空 | 磁带→归档包索引 |
+
+#### 4.4.2 Raft 日志存储 (raftdb)
+
+- **Key**: `{log_index}` (8 bytes)
+- **Value**: Raft 日志条目序列化
+- **用途**: 仅存储 Raft 共识日志，与业务 KV 分离
+
+### 4.5 Raft 状态机命令（AppData / RocksRequest 扩展）
+
+参考 openraft-rocksstore 的 `RocksRequest` 模式，扩展 ColdStore 专用命令：
+
+```rust
+// 实现 openraft::AppData
+#[derive(Clone, Debug, Serialize, Deserialize)]
+enum ColdStoreRequest {
+ PutObject(ObjectMetadata),
+ DeleteObject { bucket: String, key: String },
+ UpdateStorageClass { bucket: String, key: String, class: StorageClass },
+ PutArchiveBundle(ArchiveBundle),
+ PutTape(TapeInfo),
+ PutRecallTask(RecallTask),
+ UpdateRecallTask { id: Uuid, status: RestoreStatus },
+ PutArchiveTask(ArchiveTask),
+}
+```
+
+可基于 `openraft-rocksstore` 的 `RocksStore` 进行扩展，或实现自定义 `RaftStorage` 以支持上述业务命令。
+
+### 4.6 读写路径
+
+| 操作类型 | 路径 |
+|----------|------|
+| **写** | Client → Leader → Raft Propose → 多数派 Append → Apply → RocksDB Write |
+| **读** | Client → 任意节点 → 本地 RocksDB Read（需保证 ReadYourWrites 时可选走 Leader） |
+| **线性读** | 通过 Raft 的 ReadIndex 保证读到已提交状态 |
+
+### 4.7 集群部署
+
+- **推荐配置**：3 或 5 节点
+- **Leader 选举**：Raft 自动选举
+- **网络**：节点间 gRPC 或自定义 RPC
+- **持久化路径**：`/var/lib/coldstore/metadata/{raftdb|kvdb}`
+
+### 4.8 与现有代码集成
+
+- 新增 `MetadataBackend::RaftRocksDB` 枚举变体
+- `MetadataService` 通过 Raft 客户端代理写请求
+- 读请求可直接访问本地 RocksDB（Follower 只读）
+
+---
+
+## 5. 数据缓存层：async-spdk 设计
+
+### 5.1 设计目标
+
+- **高性能**：用户态 I/O，绕过内核，降低延迟
+- **高吞吐**：Poll 模式、零拷贝，充分发挥 NVMe 性能
+- **解冻数据缓存**：承载从磁带取回的数据，供 GET 快速响应
+- **原生 async/await**：与 Tokio 无缝集成，无需回调桥接
+
+### 5.2 技术选型：async-spdk + SPDK Blob
+
+采用 [madsys-dev/async-spdk](https://github.com/madsys-dev/async-spdk)：
+
+- **异步 Rust 绑定**：原生 `async`/`await`，基于 Tokio
+- **存储方式**：**SPDK Blobstore (Blob)**，非 raw bdev；Blobstore 构建于 bdev 之上
+- **优势**：Blob 提供持久化块分配、xattrs 元数据、thin provisioning，适合对象缓存
+
+### 5.3 架构概览
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ColdStore 缓存服务进程 │
+├─────────────────────────────────────────────────────────────────┤
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │ Cache Manager (Rust) │ │
+│ │ - cache_key → blob_id 索引 │ │
+│ │ - LRU/LFU/TTL 淘汰策略 │ │
+│ │ - 容量与并发控制 │ │
+│ └─────────────────────────────────────────────────────────┘ │
+│ │ │
+│ ▼ │
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │ async-spdk (SPDK Blobstore / Blob API) │ │
+│ │ - 1 对象 = 1 Blob，xattrs 存 bucket/key/expire_at │ │
+│ │ - blob_write / blob_read 按 page 读写 │ │
+│ │ - 构建于 bdev 之上 │ │
+│ └─────────────────────────────────────────────────────────┘ │
+│ │ │
+│ ▼ │
+│ ┌─────────────────────────────────────────────────────────┐ │
+│ │ SPDK Bdev (Blobstore 底层) │ │
+│ │ - Malloc0: 测试用内存 bdev │ │
+│ │ - Nvme0n1: 生产 NVMe 设备 │ │
+│ └─────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 5.4 集成方式与启动模型
+
+async-spdk 采用 **SPDK 事件循环 + Tokio** 的混合模型：
+
+```rust
+use async_spdk::{event::AppOpts, bdev::*, env};
+
+fn main() {
+ event::AppOpts::new()
+ .name("coldstore_cache")
+ .config_file(&std::env::args().nth(1).expect("config file"))
+ .block_on(async_main())
+ .unwrap();
+}
+
+async fn async_main() -> Result<()> {
+ // Blobstore 方式：先加载/初始化 Blobstore，再通过 Blob API 读写
+ // let bs = Blobstore::load("Malloc0").await?;
+ // let blob_id = bs.create_blob().await?;
+ // bs.blob_write(blob_id, offset_pages, buf).await?;
+ // bs.blob_read(blob_id, offset_pages, buf).await?;
+ app_stop();
+ Ok(())
+}
+```
+
+**注意**：ColdStore 主进程若已使用 Tokio（Axum），需将 async-spdk 作为**独立子模块**或**专用线程**运行，因 SPDK 需独占 reactor。可选方案：
+
+- **方案 A**：缓存服务作为独立二进制，通过 gRPC/HTTP 与主服务通信
+- **方案 B**：主进程在 SPDK `block_on` 内启动 Axum（需调整启动顺序）
+- **方案 C**：缓存层先使用文件后端，待架构稳定后再接入 async-spdk
+
+### 5.5 SPDK JSON 配置示例
+
+**测试用 Malloc bdev**（`cache_spdk.json`）：
+
+```json
+{
+ "subsystems": [
+ {
+ "subsystem": "bdev",
+ "config": [
+ {
+ "method": "bdev_malloc_create",
+ "params": {
+ "name": "Malloc0",
+ "num_blocks": 32768,
+ "block_size": 512
+ }
+ }
+ ]
+ }
+ ]
+}
+```
+
+**生产 NVMe**：根据 [async-spdk README](https://github.com/madsys-dev/async-spdk)，需配置对应 bdev 名称（如 `Nvme0n1`），并确保：
+
+- 以 root 运行
+- 大页内存：`echo "1024" > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages`
+- SPDK 编译：`./configure --without-isal` 可避免部分 isa-l 错误
+
+### 5.6 缓存数据布局（SPDK Blob 方式）
+
+| 层级 | 存储介质 | 用途 |
+|------|----------|------|
+| L1 | NVMe SSD (SPDK Blobstore on bdev) | 热解冻数据，低延迟 |
+| L2 (可选) | 文件系统 | 兼容旧实现，温数据 |
+
+对象与 Blob 的对应：
+
+- **1 对象 = 1 Blob**：每个解冻对象对应一个 Blobstore Blob
+- **元数据**：Blob xattrs 存储 bucket、key、size、checksum、expire_at
+- **索引**：自维护 `cache_key → blob_id` 映射（Blobstore 不提供按名查找）
+- **读写单位**：Page（4KB），Cluster（1MB）为分配单元
+
+### 5.7 缓存策略
+
+| 策略 | 说明 |
+|------|------|
+| **LRU** | 淘汰最久未访问对象 |
+| **LFU** | 淘汰访问频率最低对象 |
+| **TTL** | 按解冻过期时间淘汰 |
+| **容量** | 总容量上限，超限触发淘汰 |
+
+### 5.8 配置项
+
+```yaml
+cache:
+ backend: "spdk" # spdk | file (兼容旧实现)
+ spdk:
+ enabled: true
+ config_file: "/etc/coldstore/cache_spdk.json"
+ bdev_name: "Malloc0" # 测试用; 生产改为 "Nvme0n1"
+ max_size_gb: 100
+ block_size: 4096
+ ttl_secs: 86400
+ eviction_policy: "Lru"
+```
+
+### 5.9 Cargo 依赖
+
+```toml
+[dependencies]
+async-spdk = { git = "https://github.com/madsys-dev/async-spdk" }
+# 或发布到 crates.io 后: async-spdk = "0.1"
+```
+
+---
+
+## 6. 磁带管理层：自研 SDK 抽象层
+
+### 6.1 设计目标
+
+- **自研 SDK 抽象层**：不依赖厂商闭源 SDK，统一磁带、驱动、库的访问接口
+- **前期对接 Linux SCSI**：基于 Linux 内核 SCSI 磁带驱动（st/ sg）实现
+- **可扩展**：后期可替换为厂商 SDK、LTFS 等实现，无需改动上层调度逻辑
+
+### 6.2 架构分层
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ TapeManager (调度层) │
+│ - 磁带库抽象、驱动调度、归档包聚合、取回合并 │
+└─────────────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Tape SDK 抽象层 (自研) │
+│ - TapeDrive trait: read, write, seek, status, eject │
+│ - TapeLibrary trait: list_slots, load, unload, inventory │
+│ - 与具体实现解耦 │
+└─────────────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ 实现层 (前期) │
+│ Linux SCSI: st 驱动 (/dev/nst0) + MTIO ioctl │
+│ - 顺序读写、定位、状态查询 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 6.3 前期实现：Linux SCSI 协议
+
+#### 6.3.1 设备与接口
+
+| 接口 | 设备节点 | 说明 |
+|------|----------|------|
+| **st 驱动** | `/dev/nst0` | 非自动回卷，推荐用于顺序读写（避免每次操作回卷） |
+| **st 驱动** | `/dev/st0` | 自动回卷，操作后回卷到 BOT |
+| **SCSI Generic** | `/dev/sg*` | 透传 SCSI 命令，用于高级控制（可选） |
+
+#### 6.3.2 MTIO 控制接口
+
+基于 ``，主要 ioctl：
+
+| ioctl | 用途 |
+|-------|------|
+| `MTIOCTOP` | 执行磁带操作：`MTFSF`(前进文件)、`MTBSF`(后退文件)、`MTFSR`(前进记录)、`MTBSR`(后退记录)、`MTREW`(回卷)、`MTEOM`(到卷尾) |
+| `MTIOCGET` | 获取驱动状态 |
+| `MTIOCPOS` | 获取当前磁带位置 |
+
+#### 6.3.3 数据读写
+
+- **块模式**：可变块或固定块（通过 ioctl 设置）
+- **读写**：标准 `read()` / `write()` 系统调用
+- **顺序性**：磁带必须顺序写入，随机读需 seek 后再读
+
+#### 6.3.4 依赖与工具
+
+- `mt-st`：mt 命令，用于控制磁带（可选，SDK 自实现 ioctl）
+- 内核：`st` 模块（`modprobe st`）
+- 权限：设备节点需可读写（通常 root 或 tape 组）
+
+### 6.4 SDK 抽象接口定义
+
+```rust
+/// 磁带驱动抽象
+pub trait TapeDrive: Send + Sync {
+ fn drive_id(&self) -> &str;
+ async fn read(&self, offset: u64, length: u64) -> Result>;
+ async fn write(&self, data: &[u8]) -> Result<()>;
+ async fn seek(&self, position: u64) -> Result<()>;
+ async fn status(&self) -> Result;
+ async fn rewind(&self) -> Result<()>;
+ async fn eject(&self) -> Result<()>;
+}
+
+/// 磁带库抽象（带机械臂的库，后期扩展）
+pub trait TapeLibrary: Send + Sync {
+ async fn list_slots(&self) -> Result>;
+ async fn load(&self, slot_id: &str, drive_id: &str) -> Result<()>;
+ async fn unload(&self, drive_id: &str) -> Result<()>;
+ async fn inventory(&self) -> Result>;
+}
+
+/// Linux SCSI 实现（前期）
+pub struct ScsiTapeDrive {
+ device_path: PathBuf, // e.g. /dev/nst0
+ // ...
+}
+impl TapeDrive for ScsiTapeDrive { ... }
+```
+
+### 6.5 实现路径
+
+| 阶段 | 实现 | 说明 |
+|------|------|------|
+| **前期** | `ScsiTapeDrive` | 基于 st 驱动 + MTIO，单驱动直连 |
+| **中期** | `ScsiTapeLibrary` | 带库场景，通过 sg 或厂商 MMC 协议控制机械臂 |
+| **后期** | `VendorTapeDrive` | 可选对接厂商 SDK（如 IBM、HP 等） |
+
+### 6.6 配置项
+
+```yaml
+tape:
+ sdk:
+ backend: "scsi" # scsi | vendor (后期)
+ scsi:
+ device: "/dev/nst0"
+ block_size: 262144 # 256KB，LTO 常用
+ buffer_size_mb: 64
+ library_path: null # 带库场景时配置
+ supported_formats:
+ - "LTO-9"
+ - "LTO-10"
+```
+
+### 6.7 模块结构
+
+```
+src/tape/
+├── mod.rs
+├── sdk/ # 自研 SDK 抽象层
+│ ├── mod.rs
+│ ├── drive.rs # TapeDrive trait
+│ ├── library.rs # TapeLibrary trait (可选)
+│ └── types.rs # DriveStatus, SlotInfo 等
+├── scsi/ # Linux SCSI 实现
+│ ├── mod.rs
+│ ├── drive.rs # ScsiTapeDrive
+│ └── mtio.rs # MTIO ioctl 封装
+├── manager.rs # TapeManager
+└── driver.rs # 兼容旧接口，委托给 sdk
+```
+
+---
+
+## 7. 模块交互与数据流
+
+### 7.1 Restore 完整流程
+
+```
+1. Client: POST /bucket/key?restore + RestoreRequest
+2. S3 Handler: 解析 Days/Tier，校验对象为 Cold
+3. Metadata (Raft): 检查是否已有进行中 Restore，写入 RecallTask
+4. Recall Scheduler: 按 archive_id 合并任务，调度磁带读取
+5. Tape: 顺序读取 → 数据块
+6. Cache (SPDK): 写入 SPDK bdev，更新索引
+7. Metadata (Raft): 更新 ObjectMetadata.restore_status=Completed, restore_expire_at
+8. Client: HEAD 可见 x-amz-restore: expiry-date="..."
+9. Client: GET 从 SPDK 缓存返回数据
+```
+
+### 7.2 Archive 完整流程
+
+```
+1. PutObject → 对象直接标记 ColdPending（写入即归档）
+2. Archive Scheduler: 扫描 ColdPending，按策略聚合为 ArchiveBundle
+3. Tape: 顺序写入磁带
+4. Metadata (Raft): 写入 ArchiveBundle, 更新 ObjectMetadata (Cold, archive_id, tape_id)
+5. 清理缓存层临时数据
+```
+
+---
+
+## 8. 非功能性设计
+
+### 8.1 高可用
+
+- 元数据：Raft 3/5 节点，多数派存活即可
+- 缓存：单点故障时，解冻数据需重新从磁带取回（可接受）
+- S3 接入：无状态，可多实例 + 负载均衡
+
+### 8.2 可观测性
+
+- 日志：tracing + structured logging
+- 指标：归档/取回队列长度、缓存命中率、Raft 提交延迟
+- 追踪：关键路径分布式 trace
+
+### 8.3 安全
+
+- S3 签名 v4 认证
+- 传输加密 TLS
+- 元数据集群节点间 mTLS（可选）
+
+---
+
+## 9. 实施路线图
+
+| 阶段 | 内容 |
+|------|------|
+| **Phase 1** | S3 RestoreObject 协议完整实现，错误码与 x-amz-restore 头 |
+| **Phase 2** | Raft + RocksDB 元数据集群，替换 Postgres/Etcd |
+| **Phase 3** | SPDK 缓存层集成，替换文件系统缓存 |
+| **Phase 4** | 磁带 SDK 抽象层 + Linux SCSI 实现（ScsiTapeDrive） |
+| **Phase 5** | 性能调优、生产就绪 |
+
+---
+
+## 10. Cargo 依赖汇总
+
+```toml
+[dependencies]
+# 元数据集群
+openraft = "0.9"
+openraft-rocksstore = "0.9"
+
+# 数据缓存层
+async-spdk = { git = "https://github.com/madsys-dev/async-spdk" }
+
+# 现有依赖保持不变
+tokio = { version = "1.35", features = ["full"] }
+axum = "0.7"
+rocksdb = "0.22" # openraft-rocksstore 会引入，可按需显式指定版本
+```
+
+---
+
+## 11. 参考资料
+
+- [AWS S3 RestoreObject API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html)
+- [S3 Glacier Retrieval Options](https://docs.aws.amazon.com/AmazonS3/latest/userguide/restoring-objects-retrieval-options.html)
+- [OpenRaft](https://github.com/databendlabs/openraft) - databendlabs/openraft
+- [OpenRaft RocksStore](https://crates.io/crates/openraft-rocksstore)
+- [async-spdk](https://github.com/madsys-dev/async-spdk) - madsys-dev/async-spdk
+- [SPDK Documentation](https://spdk.io/doc/)
+- [Linux st(4) - SCSI tape device](https://man7.org/linux/man-pages/man4/st.4.html)
+- [Linux SCSI tape driver (kernel.org)](https://kernel.org/doc/Documentation/scsi/st.txt)
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..b8ca9fc
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,28 @@
+# ColdStore 设计文档
+
+## 文档索引
+
+| 文档 | 说明 |
+|------|------|
+| [DESIGN.md](./DESIGN.md) | **总架构设计** - 协议、元数据集群、缓存层、磁带层完整设计 |
+| [modules/](./modules/) | **模块设计** - 按架构分层拆分的独立设计文档 |
+
+## 模块设计文档
+
+| 模块 | 文档 |
+|------|------|
+| 接入层 | [01-access-layer.md](./modules/01-access-layer.md) |
+| 协议适配层 | [02-protocol-adapter.md](./modules/02-protocol-adapter.md) |
+| 元数据集群 | [03-metadata-cluster.md](./modules/03-metadata-cluster.md) |
+| 数据缓存层 | [04-cache-layer.md](./modules/04-cache-layer.md) |
+| 归档取回调度层 | [05-scheduler-layer.md](./modules/05-scheduler-layer.md) |
+| 磁带管理层 | [06-tape-layer.md](./modules/06-tape-layer.md) |
+
+## 设计要点摘要
+
+- **协议**：兼容 S3 Glacier 冷归档协议（RestoreObject、x-amz-restore、取回层级）
+- **元数据**：[OpenRaft](https://github.com/databendlabs/openraft) + [openraft-rocksstore](https://crates.io/crates/openraft-rocksstore)，强一致性集群
+- **缓存**：[async-spdk](https://github.com/madsys-dev/async-spdk) 用户态 NVMe 缓存，原生 async/await
+- **磁带**：自研 SDK 抽象层，前期对接 Linux SCSI（st 驱动 + MTIO）
+
+详见 [DESIGN.md](./DESIGN.md) 与 [modules/README.md](./modules/README.md)。
diff --git a/docs/modules/01-access-layer.md b/docs/modules/01-access-layer.md
new file mode 100644
index 0000000..f501d87
--- /dev/null
+++ b/docs/modules/01-access-layer.md
@@ -0,0 +1,122 @@
+# 接入层模块设计
+
+> 所属架构：ColdStore 冷存储系统
+> 参考：[总架构设计](../DESIGN.md)
+
+## 1. 模块概述
+
+接入层是 ColdStore 对外提供对象存储服务的入口，负责接收并分发 S3 兼容的 HTTP 请求。
+
+### 1.1 职责
+
+- 提供 HTTP 服务，监听 S3 端点
+- 路由解析：将请求分发到对应 Handler
+- 请求/响应透传与基础校验
+- 与协议适配层、元数据、缓存、调度器协同
+
+### 1.2 在架构中的位置
+
+```
+ ┌─────────────────────────────────────┐
+ │ S3 接入层 (本模块) │
+ │ PUT / GET / HEAD / RestoreObject │
+ │ ListBuckets / DeleteObject │
+ └─────────────────────────────────────┘
+ │
+ ▼
+ 协议适配层 / 元数据 / 缓存 / 调度器
+```
+
+---
+
+## 2. 技术选型
+
+| 组件 | 选型 | 说明 |
+|------|------|------|
+| HTTP 框架 | **Axum** | 异步、类型安全、与 Tokio 集成 |
+| 运行时 | **Tokio** | 异步运行时 |
+| 中间件 | **Tower** / **tower-http** | 中间件栈、CORS、trace |
+
+---
+
+## 3. 接口清单
+
+### 3.1 对象操作
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| PUT | `/{bucket}/{key}` | 上传对象 |
+| GET | `/{bucket}/{key}` | 下载对象 |
+| HEAD | `/{bucket}/{key}` | 获取对象元数据 |
+| DELETE | `/{bucket}/{key}` | 删除对象 |
+| POST | `/{bucket}/{key}?restore` | 解冻冷对象（RestoreObject） |
+
+### 3.2 桶操作
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/` | ListBuckets |
+| PUT | `/{bucket}` | CreateBucket |
+| GET | `/{bucket}` | ListObjects |
+| DELETE | `/{bucket}` | DeleteBucket |
+
+### 3.3 路由规则
+
+- 路径参数：`bucket`、`key`（支持多级 key）
+- 查询参数：`versionId`、`restore` 等
+- 虚拟主机风格与路径风格均需支持（可配置）
+
+---
+
+## 4. 模块结构
+
+```
+src/
+├── main.rs # 启动 Axum，加载配置
+├── s3/
+│ ├── mod.rs
+│ ├── server.rs # Axum Router 定义、路由注册
+│ ├── handler.rs # 请求处理入口，委托给协议适配/业务逻辑
+│ └── routes.rs # 路由常量、路径解析
+```
+
+---
+
+## 5. 依赖关系
+
+| 依赖模块 | 通信方式 | 用途 |
+|----------|----------|------|
+| 协议适配层 | 本地调用（同进程） | 解析 RestoreRequest、生成 x-amz-restore 响应、错误码映射 |
+| Scheduler Worker | gRPC（配置地址） | **全部**业务请求代理（PUT/GET/HEAD/DELETE/Restore/List） |
+
+> Gateway **不连接 Metadata**，也**不连接 Cache Worker 和 Tape Worker**。
+> 所有业务流量都通过 Scheduler Worker 中转。Gateway 是纯粹的 S3 HTTP → gRPC 协议前端。
+
+---
+
+## 6. 配置项
+
+```yaml
+gateway:
+ s3:
+ host: "0.0.0.0"
+ port: 9000
+ path_style: true
+
+ # 仅需配置 Scheduler Worker 地址
+ scheduler_addrs:
+ - "10.0.2.1:22001"
+ - "10.0.2.2:22001"
+
+ # 多 Scheduler Worker 时的路由策略
+ routing:
+ strategy: "round_robin" # round_robin | hash | least_pending
+```
+
+---
+
+## 7. 非功能性要求
+
+- **无状态**：可水平扩展，多实例 + 负载均衡
+- **可观测**：请求 trace、耗时、错误率
+- **安全**：支持 S3 签名 v4、TLS
diff --git a/docs/modules/02-protocol-adapter.md b/docs/modules/02-protocol-adapter.md
new file mode 100644
index 0000000..6a24ad4
--- /dev/null
+++ b/docs/modules/02-protocol-adapter.md
@@ -0,0 +1,157 @@
+# 协议适配层模块设计
+
+> 所属架构：ColdStore 冷存储系统
+> 参考：[总架构设计](../DESIGN.md)
+
+## 1. 模块概述
+
+协议适配层负责将 S3 冷归档（Glacier）协议语义转换为 ColdStore 内部模型，并生成符合 S3 规范的响应。
+
+### 1.1 职责
+
+- StorageClass 映射（S3 ↔ 内部状态）
+- RestoreRequest 解析（Days、Tier）
+- x-amz-restore 响应头生成
+- 错误码映射（InvalidObjectState、RestoreAlreadyInProgress 等）
+- PutObject 默认 ColdPending 语义
+
+### 1.2 在架构中的位置
+
+```
+S3 接入层 ──► 协议适配层 ──► Scheduler Worker（业务中枢）
+ │
+ ├─ StorageClass 映射
+ ├─ RestoreRequest 解析
+ ├─ x-amz-restore 响应
+ └─ 错误码映射
+```
+
+---
+
+## 2. StorageClass 映射
+
+ColdStore 是纯冷归档系统，所有对象写入即为 `ColdPending`，归档后变为 `Cold`。与 AWS S3 Glacier Deep Archive 模型一致。
+
+| S3 Storage Class | ColdStore 内部 | 说明 |
+|------------------|----------------|------|
+| `GLACIER` / `DEEP_ARCHIVE` / `STANDARD` / 任意 | `ColdPending` | 写入即排队归档（不区分热/冷，统一冷存储） |
+| 归档完成 | `Cold` | 已归档到磁带 |
+
+---
+
+## 3. RestoreObject 协议适配
+
+### 3.1 请求解析
+
+**输入**：`POST /{bucket}/{key}?restore` + XML Body
+
+```xml
+
+ 7
+
+ Standard
+
+
+```
+
+**输出**（内部结构）：
+
+```rust
+pub struct RestoreRequest {
+ pub days: u32, // 最小 1
+ pub tier: RestoreTier, // Expedited | Standard | Bulk
+ pub version_id: Option,
+}
+```
+
+### 3.2 取回层级 (Tier) 映射
+
+| Tier | 内部优先级 | 调度策略 |
+|------|------------|----------|
+| Expedited | 高 | 高优先级队列，可配置预留容量 |
+| Standard | 中 | 默认队列 |
+| Bulk | 低 | 批量合并取回 |
+
+### 3.3 响应规范
+
+| 场景 | HTTP 状态 | 说明 |
+|------|-----------|------|
+| 首次解冻 | 202 Accepted | 任务已接受 |
+| 已解冻且未过期 | 200 OK | 可延长 Days |
+| 解冻进行中 | 409 Conflict | RestoreAlreadyInProgress |
+| Expedited 容量不足 | 503 Service Unavailable | GlacierExpeditedRetrievalNotAvailable |
+| 对象尚未归档（ColdPending） | 409 Conflict | 尚在归档队列中，不可 Restore |
+
+---
+
+## 4. x-amz-restore 响应头
+
+对冷对象执行 HEAD 时，根据解冻状态返回：
+
+| 状态 | 响应头 |
+|------|--------|
+| 解冻中 | `x-amz-restore: ongoing-request="true"` |
+| 已解冻 | `x-amz-restore: ongoing-request="false", expiry-date="Fri, 28 Feb 2025 12:00:00 GMT"` |
+| 未解冻 | 不返回该头（或可省略） |
+
+---
+
+## 5. 错误码映射
+
+| AWS 错误码 | HTTP 状态 | 触发条件 |
+|------------|-----------|----------|
+| InvalidObjectState | 403 | 冷对象未解冻时 GET |
+| RestoreAlreadyInProgress | 409 | 重复 Restore 请求 |
+| GlacierExpeditedRetrievalNotAvailable | 503 | Expedited 容量不足 |
+| ObjectNotYetArchived | 409 | ColdPending 状态对象执行 Restore（尚未归档完成） |
+
+---
+
+## 6. GET Object 冷对象访问控制
+
+| 对象状态 | GET 行为 |
+|----------|----------|
+| Cold + 未解冻 | 403 InvalidObjectState |
+| Cold + 解冻中 | 403 InvalidObjectState |
+| Cold + 已解冻 | 从缓存读取并返回 |
+| Cold + 解冻已过期 | 403 InvalidObjectState |
+
+---
+
+## 7. PutObject 语义
+
+ColdStore 作为纯冷归档系统，PutObject 写入的对象一律标记为 `ColdPending`，
+由调度器扫描后自动归档到磁带。外部热存储系统在需要归档时直接调用 ColdStore 的 PutObject。
+
+---
+
+## 8. 模块结构
+
+```
+src/
+├── s3/
+│ ├── protocol/ # 协议适配（可独立子模块）
+│ │ ├── mod.rs
+│ │ ├── storage_class.rs # StorageClass 映射
+│ │ ├── restore.rs # RestoreRequest 解析、响应生成
+│ │ ├── errors.rs # 错误码映射
+│ │ └── put_object.rs # PutObject → ColdPending 语义
+```
+
+---
+
+## 9. 依赖关系
+
+| 依赖 | 用途 |
+|------|------|
+| Scheduler Worker (gRPC) | 全部业务请求：元数据查询、数据读写、Restore 任务提交 |
+
+> 协议适配层运行在 Gateway 进程内，与接入层同进程。
+> 所有对外通信都经由 Scheduler Worker，不直连 Metadata/Cache/Tape。
+
+---
+
+## 10. 参考资料
+
+- [AWS S3 RestoreObject API](https://docs.aws.amazon.com/AmazonS3/latest/API/API_RestoreObject.html)
+- [S3 Glacier Retrieval Options](https://docs.aws.amazon.com/AmazonS3/latest/userguide/restoring-objects-retrieval-options.html)
diff --git a/docs/modules/03-metadata-cluster.md b/docs/modules/03-metadata-cluster.md
new file mode 100644
index 0000000..5bb35e8
--- /dev/null
+++ b/docs/modules/03-metadata-cluster.md
@@ -0,0 +1,1163 @@
+# 元数据集群模块设计
+
+> 所属架构：ColdStore 冷存储系统
+> 参考：[总架构设计](../DESIGN.md)
+
+## 1. 模块概述
+
+元数据集群提供强一致性的集群元数据存储，基于 OpenRaft + RocksDB 实现，是 ColdStore 的"控制中枢"。
+
+元数据分为两大类：
+
+| 类别 | 内容 | 说明 |
+|------|------|------|
+| **集群元数据** | 节点信息、集群拓扑、Raft 状态 | 集群自身管理 |
+| **归档元数据** | 对象、桶、归档包、磁带、任务 | 业务数据管理 |
+
+### 1.1 职责
+
+- 对象元数据：bucket、key、storage_class、archive_id、tape_id、restore_status 等
+- 桶管理：桶创建/删除
+- 归档包、磁带、取回任务、归档任务索引
+- 集群管理：节点注册、Raft 领导选举、成员变更
+- 强一致性读写、高可用
+
+### 1.2 在架构中的位置
+
+```
+ Console ──管控读写──▶ Metadata
+ ▲
+Gateway ──全部请求──▶ Scheduler Worker ──读+写──────┘
+ │
+ ├──gRPC──▶ Cache Worker (纯数据)
+ └──gRPC──▶ Tape Worker (纯硬件)
+```
+
+> Gateway 不直连 Metadata。Scheduler Worker 是唯一的元数据业务读写入口。
+
+---
+
+## 2. 技术选型
+
+| 组件 | 选型 | 说明 |
+|------|------|------|
+| Raft 共识 | **openraft** | [databendlabs/openraft](https://github.com/databendlabs/openraft) |
+| 存储后端 | **openraft-rocksstore** | RocksDB 后端 |
+| 存储引擎 | RocksDB | LSM-tree，高吞吐 |
+
+---
+
+## 3. 核心数据结构
+
+### 3.1 ObjectMetadata（对象元数据）
+
+系统中最核心的结构，记录每个 S3 对象的完整状态。
+
+```rust
+pub struct ObjectMetadata {
+ pub bucket: String,
+ pub key: String,
+ pub version_id: Option,
+ pub size: u64,
+ pub checksum: String,
+ pub content_type: Option,
+ pub etag: Option,
+ pub storage_class: StorageClass,
+ pub archive_id: Option,
+ pub tape_id: Option,
+ pub tape_set: Option>,
+ pub tape_block_offset: Option,
+ pub restore_status: Option,
+ pub restore_expire_at: Option>,
+ pub created_at: DateTime,
+ pub updated_at: DateTime,
+}
+```
+
+| 字段 | 类型 | 含义 | 写入方 | 消费方 |
+|------|------|------|--------|--------|
+| `bucket` | String | S3 桶名 | 接入层 PutObject | 全部 |
+| `key` | String | S3 对象键 | 接入层 PutObject | 全部 |
+| `version_id` | Option\ | 对象版本 ID | 接入层 PutObject | 协议层、调度层 |
+| `size` | u64 | 对象字节数 | 接入层 PutObject | 调度层（聚合计算）、协议层（Content-Length） |
+| `checksum` | String | SHA256 hex | 接入层 PutObject | 调度层（写磁带/校验）、缓存层（透传） |
+| `content_type` | Option\ | MIME 类型 | 接入层 PutObject | 协议层 GET 响应头、调度层传给缓存层 |
+| `etag` | Option\ | S3 ETag | 接入层 PutObject | 协议层 GET 响应头、调度层传给缓存层 |
+| `storage_class` | StorageClass | 存储类别 | 接入层 PutObject / 调度层归档完成 | 协议层（判断是否可 GET）、调度层（扫描 ColdPending） |
+| `archive_id` | Option\ | 所属 ArchiveBundle ID | 调度层归档完成 | 调度层取回时定位 Bundle |
+| `tape_id` | Option\ | 主副本所在磁带 ID | 调度层归档完成 | 调度层取回时定位磁带 |
+| `tape_set` | Option\\> | 所有副本磁带列表 | 调度层归档完成 | 调度层副本切换 |
+| `tape_block_offset` | Option\ | 对象在磁带上的块偏移 | 调度层归档完成 | 调度层取回时 seek 定位 |
+| `restore_status` | Option\ | 解冻状态 | 调度层取回流程 | 协议层（判断 GET/HEAD 响应） |
+| `restore_expire_at` | Option\\> | 解冻过期时间 | 调度层取回完成 | 协议层（x-amz-restore 头）、缓存层（TTL） |
+| `created_at` | DateTime\ | 创建时间 | 接入层 PutObject | 调度层（聚合排序） |
+| `updated_at` | DateTime\ | 最后更新时间 | 每次写入 | 审计 |
+
+### 3.2 枚举类型
+
+```rust
+pub enum StorageClass {
+ ColdPending, // 待归档（PutObject 写入即标记，等待调度器扫描写入磁带）
+ Cold, // 已归档到磁带
+}
+
+pub enum RestoreStatus {
+ Pending, // 已入队，等待调度
+ WaitingForMedia, // 磁带离线，等待人工上线
+ InProgress, // 正在从磁带读取
+ Completed, // 已写入缓存，可 GET
+ Expired, // 解冻过期
+ Failed, // 取回失败
+}
+
+pub enum RestoreTier {
+ Expedited, // 加急：1-5 分钟
+ Standard, // 标准：3-5 小时
+ Bulk, // 批量：5-12 小时
+}
+```
+
+### 3.3 ArchiveBundle（归档包）
+
+与 05-scheduler-layer §8.3 定义一致。
+
+```rust
+pub struct ArchiveBundle {
+ pub id: Uuid,
+ pub tape_id: String,
+ pub tape_set: Vec,
+ pub entries: Vec,
+ pub total_size: u64,
+ pub filemark_start: u32,
+ pub filemark_end: u32,
+ pub checksum: Option,
+ pub status: ArchiveBundleStatus,
+ pub created_at: DateTime,
+ pub completed_at: Option>,
+}
+```
+
+| 字段 | 类型 | 含义 | 写入方 |
+|------|------|------|--------|
+| `id` | Uuid | 归档包唯一标识 | 调度层 |
+| `tape_id` | String | 主副本磁带 ID | 调度层 |
+| `tape_set` | Vec\ | 所有副本磁带 | 调度层 |
+| `entries` | Vec\ | 包内对象列表与偏移 | 调度层 |
+| `total_size` | u64 | 总字节数 | 调度层 |
+| `filemark_start` | u32 | 起始 FileMark | 调度层（从 WriteResult 获取） |
+| `filemark_end` | u32 | 结束 FileMark | 调度层 |
+| `checksum` | Option\ | 整包 SHA256 | 调度层（可选） |
+| `status` | ArchiveBundleStatus | 状态 | 调度层 |
+| `created_at` | DateTime\ | 创建时间 | 调度层 |
+| `completed_at` | Option\\> | 完成时间 | 调度层 |
+
+```rust
+pub struct BundleEntry {
+ pub bucket: String,
+ pub key: String,
+ pub version_id: Option,
+ pub size: u64,
+ pub offset_in_bundle: u64,
+ pub tape_block_offset: u64,
+ pub checksum: String,
+}
+
+pub enum ArchiveBundleStatus {
+ Pending, Writing, Completed, Failed,
+}
+```
+
+### 3.4 TapeInfo（磁带信息）
+
+与 06-tape-layer §4.6 定义一致。由调度层写入元数据。
+
+```rust
+pub struct TapeInfo {
+ pub id: String,
+ pub barcode: Option,
+ pub format: String,
+ pub status: TapeStatus,
+ pub location: Option,
+ pub capacity_bytes: u64,
+ pub used_bytes: u64,
+ pub remaining_bytes: u64,
+ pub archive_bundles: Vec,
+ pub last_verified_at: Option>,
+ pub error_count: u32,
+ pub registered_at: DateTime,
+}
+```
+
+| 字段 | 类型 | 含义 | 写入方 |
+|------|------|------|--------|
+| `id` | String | 磁带唯一标识 | 调度层（注册时） |
+| `barcode` | Option\ | 条码 | 调度层 |
+| `format` | String | "LTO-9"、"LTO-10" | 调度层 |
+| `status` | TapeStatus | Online/Offline/Error/Retired | 调度层 |
+| `location` | Option\ | 位置描述 | 调度层 |
+| `capacity_bytes` | u64 | 总容量 | 调度层 |
+| `used_bytes` | u64 | 已使用 | 调度层（每次写入后更新） |
+| `remaining_bytes` | u64 | 剩余 | 调度层 |
+| `archive_bundles` | Vec\ | 已写入的归档包列表 | 调度层 |
+| `last_verified_at` | Option\\> | 最近校验时间 | 调度层 |
+| `error_count` | u32 | 累计错误次数 | 调度层 |
+| `registered_at` | DateTime\ | 注册时间 | 调度层 |
+
+```rust
+pub enum TapeStatus {
+ Online, Offline, Error, Retired, Unknown,
+}
+```
+
+### 3.5 RecallTask（取回任务）
+
+与 05-scheduler-layer §8.7 定义一致。
+
+```rust
+pub struct RecallTask {
+ pub id: Uuid,
+ pub bucket: String,
+ pub key: String,
+ pub version_id: Option,
+ pub archive_id: Uuid,
+ pub tape_id: String,
+ pub tape_set: Vec,
+ pub tape_block_offset: u64,
+ pub object_size: u64,
+ pub checksum: String,
+ pub tier: RestoreTier,
+ pub days: u32,
+ pub expire_at: DateTime,
+ pub status: RestoreStatus,
+ pub drive_id: Option,
+ pub retry_count: u32,
+ pub created_at: DateTime,
+ pub started_at: Option>,
+ pub completed_at: Option>,
+ pub error: Option,
+}
+```
+
+### 3.6 ArchiveTask（归档任务）
+
+与 05-scheduler-layer §8.6 定义一致。
+
+```rust
+pub struct ArchiveTask {
+ pub id: Uuid,
+ pub bundle_id: Uuid,
+ pub tape_id: String,
+ pub drive_id: Option,
+ pub object_count: u32,
+ pub total_size: u64,
+ pub bytes_written: u64,
+ pub status: ArchiveTaskStatus,
+ pub retry_count: u32,
+ pub created_at: DateTime,
+ pub started_at: Option>,
+ pub completed_at: Option>,
+ pub error: Option,
+}
+
+pub enum ArchiveTaskStatus {
+ Pending, InProgress, Completed, Failed,
+}
+```
+
+### 3.7 BucketInfo（桶信息）
+
+```rust
+pub struct BucketInfo {
+ pub name: String,
+ pub created_at: DateTime,
+ pub owner: Option,
+ pub versioning_enabled: bool,
+ pub object_count: u64,
+ pub total_size: u64,
+}
+```
+
+| 字段 | 类型 | 含义 | 写入方 |
+|------|------|------|--------|
+| `name` | String | 桶名 | 接入层 CreateBucket |
+| `created_at` | DateTime\ | 创建时间 | 接入层 |
+| `owner` | Option\ | 拥有者 | 接入层 |
+| `versioning_enabled` | bool | 是否启用多版本 | 接入层 |
+| `object_count` | u64 | 对象数 | 写入时增减 |
+| `total_size` | u64 | 总大小 | 写入时增减 |
+
+### 3.8 ListObjectsResult
+
+```rust
+pub struct ListObjectsResult {
+ pub objects: Vec,
+ pub next_marker: Option,
+ pub is_truncated: bool,
+}
+```
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `objects` | Vec\ | 当前页对象列表 |
+| `next_marker` | Option\ | 分页游标（用于下次请求的 marker） |
+| `is_truncated` | bool | 是否还有更多结果 |
+
+### 3.10 集群元数据与部署模型
+
+#### 3.10.1 物理部署模型
+
+ColdStore 由五类节点组成。**Scheduler Worker 是唯一业务中枢**：Gateway 仅连 Scheduler，
+Console 仅连 Metadata，三类 Worker 向 Metadata 注册并上报心跳。
+
+```
+┌────────────────┐ ┌────────────────┐
+│ Gateway (N台) │ │ Console (1台) │
+│ S3 HTTP 前端 │ │ 管控面 Web UI │
+│ 无状态 │ │ 无状态 │
+└──────┬─────────┘ └──────┬─────────┘
+ │ 配置: scheduler_addrs │ 配置: metadata_addrs
+ ▼ ▼
+ ┌─────────────────────────────┐ ┌──────────────────────────┐
+ │ 同一物理节点 │ │ Metadata 节点 (3/5 台) │
+ │ ┌─────────────────────────┐ │ │ Raft 共识 + RocksDB │
+ │ │ Scheduler Worker │─┼──►│ 元数据 + Worker 注册中心 │
+ │ │ 业务中枢：调度编排 │ │ └─────────────────────────┘
+ │ ├─────────────────────────┤ │ ▲
+ │ │ Cache Worker │ │ │ 心跳
+ │ │ SPDK Blobstore 缓存 │ │ ┌──────────┴──────────────┐
+ │ └─────────────────────────┘ │ │ Tape Worker (独立物理节点) │
+ └─────────────────────────────┘ │ 磁带驱动 /dev/nst* │
+ │ 带库 /dev/sg* │
+ └────────────────────────────┘
+```
+
+| 节点类型 | 职责 | 数量 | 连接对象 |
+|----------|------|------|----------|
+| **Metadata** | Raft 共识、元数据存储、Worker 注册中心 | 3/5 | Scheduler (读写)、三类 Worker (心跳)、Console (管控) |
+| **Scheduler Worker** | **业务中枢**：调度编排、对接全部层（与 Cache 同机） | 1~N | Metadata, Cache Worker, Tape Worker, Gateway |
+| **Cache Worker** | SPDK NVMe 数据缓存（与 Scheduler 同机） | 1~N | Scheduler Worker (gRPC)、Metadata (心跳) |
+| **Tape Worker** | 磁带驱动管理、数据读写（独立物理节点） | 1~N | Scheduler Worker (gRPC)、Metadata (心跳) |
+| **Gateway** | S3 HTTP 接入 + 协议适配（无状态） | N | **仅 Scheduler Worker** |
+| **Console** | 管控面 Web UI + Admin API（无状态） | 1 | **仅 Metadata** |
+
+**关键设计决策**：
+
+- **Gateway 不直连 Metadata**：Gateway 是纯 S3 协议前端，所有业务请求都发往 Scheduler Worker。
+ Gateway 配置文件中只需写 Scheduler Worker 地址。
+- **Scheduler Worker 是唯一业务中枢**：持有 MetadataClient，编排 Cache Worker 和 Tape Worker，
+ 接受 Gateway 的全部请求，是唯一的元数据读写业务入口。
+- **Scheduler ↔ Cache 使用 gRPC**：虽然同机部署，仍通过 gRPC 通信，保持架构一致性，
+ 未来可独立扩展。
+- **Console 仅连 Metadata**：管控面直接读写元数据集群，管理 Worker 增删。
+- **Tape Worker 独立部署**：磁带机为独立物理节点，通过 gRPC 接收 Scheduler 的读写指令。
+
+#### 3.10.2 节点间通信拓扑
+
+```
+Gateway Console
+ │ 配置: scheduler_addrs │ 配置: metadata_addrs
+ │ │
+ └──(gRPC)──► Scheduler Worker └──(gRPC)──► Metadata
+ │ ▲
+ ├──(gRPC)──► Metadata ───────────┘ (元数据读写)
+ ├──(gRPC)──► Cache Worker (同机，gRPC)
+ └──(gRPC)──► Tape Worker (远程，gRPC)
+ │
+ 三类 Worker ──(gRPC)──► Metadata (心跳注册)
+```
+
+| 通信路径 | 协议 | 场景 |
+|----------|------|------|
+| Gateway → Scheduler Worker | gRPC | **全部** S3 请求（PUT/GET/HEAD/DELETE/Restore） |
+| Scheduler → Metadata | gRPC | 元数据读写（PutObject、扫描 ColdPending、状态更新等） |
+| Scheduler → Cache Worker | gRPC（同机） | 缓存写入/读取（PutObject 暂存、GET 解冻数据） |
+| Scheduler → Tape Worker | gRPC（远程） | 磁带写入/读取指令下发 |
+| Console → Metadata | gRPC | 集群管理、Worker 增删、元数据查询 |
+| 三类 Worker → Metadata | gRPC | 心跳上报（资源状态） |
+| Metadata ↔ Metadata | Raft RPC | 共识协议 |
+
+> Gateway **不连接** Metadata，也**不连接** Cache Worker 和 Tape Worker。
+> 所有业务流量都经过 Scheduler Worker 中转。
+
+#### 3.10.3 集群全局信息
+
+```rust
+pub struct ClusterInfo {
+ pub cluster_id: String,
+ pub metadata_nodes: Vec,
+ pub scheduler_workers: Vec,
+ pub cache_workers: Vec,
+ pub tape_workers: Vec,
+ pub leader_id: Option,
+ pub term: u64,
+ pub committed_index: u64,
+}
+```
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `cluster_id` | String | 集群唯一标识 |
+| `metadata_nodes` | Vec\ | Raft 元数据节点列表 |
+| `scheduler_workers` | Vec\ | 调度 Worker 列表 |
+| `cache_workers` | Vec\ | 缓存 Worker 列表 |
+| `tape_workers` | Vec\ | 磁带 Worker 列表 |
+| `leader_id` | Option\ | 当前 Raft Leader 节点 ID |
+| `term` | u64 | 当前 Raft 任期 |
+| `committed_index` | u64 | 已提交日志索引 |
+
+> Gateway / Console 不出现在 `ClusterInfo` 中。
+> Gateway 通过配置直连 Scheduler Worker；Console 通过配置直连 Metadata。
+
+#### 3.10.4 公共类型
+
+```rust
+pub enum NodeStatus {
+ Online, // 正常服务
+ Offline, // 失联（心跳超时）
+ Draining, // 排空中（不再分配新任务，等待现有任务完成）
+ Maintenance, // 维护模式（管理员手动设置）
+}
+
+pub enum RaftRole {
+ Leader,
+ Follower,
+ Learner,
+}
+
+pub enum WorkerType {
+ Scheduler,
+ Cache,
+ Tape,
+}
+```
+
+#### 3.10.5 MetadataNodeInfo（元数据节点）
+
+```rust
+pub struct MetadataNodeInfo {
+ pub node_id: u64,
+ pub addr: String, // Raft RPC + gRPC 服务地址
+ pub raft_role: RaftRole,
+ pub last_heartbeat: Option>,
+ pub status: NodeStatus,
+}
+```
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `node_id` | u64 | Raft 节点 ID |
+| `addr` | String | 服务地址（`host:port`），供 Console/Worker 连接 |
+| `raft_role` | RaftRole | 当前 Raft 角色 |
+| `last_heartbeat` | Option\\> | Raft 内部心跳时间 |
+| `status` | NodeStatus | 节点状态 |
+
+#### 3.10.6 SchedulerWorkerInfo（调度 Worker）
+
+调度 Worker 是 ColdStore 的**业务中枢**，接受 Gateway 全部 S3 请求，编排 Cache Worker 和 Tape Worker。
+物理上与 Cache Worker **同机部署**，通过 gRPC 通信（保持架构一致性）。
+
+```rust
+pub struct SchedulerWorkerInfo {
+ pub node_id: u64,
+ pub addr: String, // gRPC 服务地址
+ pub status: NodeStatus,
+ pub last_heartbeat: Option>,
+
+ // ── 调度状态 ──
+ pub is_active: bool, // 主备模式下是否为 active scheduler
+ pub pending_archive_tasks: u64, // 待归档任务数
+ pub pending_recall_tasks: u64, // 待取回任务数
+ pub active_jobs: u64, // 正在执行的作业数
+
+ // ── 关联的 Cache Worker ──
+ pub paired_cache_worker_id: u64, // 同机部署的 Cache Worker ID
+}
+```
+
+| 字段 | 类型 | 含义 | 心跳更新 |
+|------|------|------|:---:|
+| `node_id` | u64 | 全局唯一 ID | 否 |
+| `addr` | String | gRPC 地址 | 否 |
+| `status` | NodeStatus | 节点状态 | 是 |
+| `is_active` | bool | 是否为活跃调度器（多 Scheduler 时仅一个 active） | 是 |
+| `pending_archive_tasks` | u64 | 待归档任务数 | 是 |
+| `pending_recall_tasks` | u64 | 待取回任务数 | 是 |
+| `active_jobs` | u64 | 正在执行作业数 | 是 |
+| `paired_cache_worker_id` | u64 | 同机 Cache Worker 的 ID | 否（注册时固定） |
+
+#### 3.10.7 CacheWorkerInfo（缓存 Worker）
+
+缓存 Worker 运行 SPDK Blobstore，提供高性能 NVMe 数据缓存。
+物理上与 Scheduler Worker **同机部署**。
+
+```rust
+pub struct CacheWorkerInfo {
+ pub node_id: u64,
+ pub addr: String, // gRPC 服务地址（供远程 GET 读取解冻数据）
+ pub status: NodeStatus,
+ pub last_heartbeat: Option>,
+
+ // ── 缓存资源 ──
+ pub bdev_name: String, // SPDK bdev 名称（如 "NVMe0n1"）
+ pub total_capacity: u64, // 总容量 (bytes)
+ pub used_capacity: u64, // 已用容量 (bytes)
+ pub blob_count: u64, // 当前缓存对象数
+ pub io_unit_size: u32, // SPDK io_unit 大小 (bytes)
+}
+```
+
+| 字段 | 类型 | 含义 | 心跳更新 |
+|------|------|------|:---:|
+| `node_id` | u64 | 全局唯一 ID | 否 |
+| `addr` | String | gRPC 地址（Gateway GET 时连接此地址） | 否 |
+| `status` | NodeStatus | 节点状态 | 是 |
+| `bdev_name` | String | SPDK bdev 名称 | 否（注册时固定） |
+| `total_capacity` | u64 | NVMe 总容量 | 否 |
+| `used_capacity` | u64 | 已用容量 | 是 |
+| `blob_count` | u64 | 缓存对象数 | 是 |
+| `io_unit_size` | u32 | SPDK io_unit 大小 | 否 |
+
+#### 3.10.8 TapeWorkerInfo（磁带 Worker）
+
+磁带 Worker 独立部署于挂载磁带驱动和带库的物理节点上，
+通过 gRPC 接收调度器的读写指令。
+
+```rust
+pub struct TapeWorkerInfo {
+ pub node_id: u64,
+ pub addr: String, // gRPC 服务地址
+ pub status: NodeStatus,
+ pub last_heartbeat: Option>,
+
+ // ── 磁带驱动 ──
+ pub drives: Vec,
+
+ // ── 带库（可选，无带库时为 None） ──
+ pub library: Option,
+}
+
+/// 磁带驱动端点
+pub struct DriveEndpoint {
+ pub drive_id: String, // 驱动唯一标识
+ pub device_path: String, // 设备路径 /dev/nst0
+ pub drive_type: String, // 驱动类型 "LTO-9" / "LTO-10"
+ pub status: DriveStatus,
+ pub current_tape: Option, // 当前装载的磁带 ID
+}
+
+pub enum DriveStatus {
+ Idle, // 空闲可分配
+ InUse, // 正在执行读写任务
+ Loading, // 正在装载磁带
+ Unloading, // 正在卸载磁带
+ Error, // 故障
+ Offline, // 离线维护
+}
+
+/// 带库端点
+pub struct LibraryEndpoint {
+ pub device_path: String, // /dev/sg5
+ pub slot_count: u32, // 存储槽位数
+ pub import_export_count: u32, // 进出槽位数（邮箱）
+ pub drive_count: u32, // 带库中驱动数量
+}
+```
+
+| 字段 | 类型 | 含义 | 心跳更新 |
+|------|------|------|:---:|
+| `node_id` | u64 | 全局唯一 ID | 否 |
+| `addr` | String | gRPC 地址（调度器连接此地址下发指令） | 否 |
+| `status` | NodeStatus | 节点状态 | 是 |
+| `drives[].status` | DriveStatus | 每个驱动的当前状态 | 是 |
+| `drives[].current_tape` | Option\ | 驱动中当前磁带 ID | 是 |
+| `drives[].drive_type` | String | 驱动型号 | 否 |
+| `library.slot_count` | u32 | 槽位总数 | 否 |
+
+#### 3.10.9 节点注册、心跳与管理
+
+```
+ Console (添加/下线操作)
+ │
+ ▼
+ ┌──────────────┐ RegisterWorker ┌──────────────────────┐
+ │ Scheduler │ ─────────────────► │ │
+ │ Worker │ Heartbeat (5s) │ Metadata Cluster │
+ ├──────────────┤ ─────────────────► │ (Raft + RocksDB) │
+ │ Cache Worker │ Heartbeat (5s) │ │
+ ├──────────────┤ ─────────────────► │ cf_scheduler_workers │
+ │ Tape Worker │ Heartbeat (5s) │ cf_cache_workers │
+ └──────────────┘ │ cf_tape_workers │
+ └──────────────────────┘
+```
+
+**注册流程**：
+
+1. 管理员通过 Console 添加 Worker（指定类型、地址等基本信息）
+2. Console 调用 Metadata 的 `RegisterXxxWorker` 写入集群信息
+3. Worker 进程启动后连接 Metadata，确认自身已注册，开始心跳上报
+
+**心跳机制**：
+
+- **频率**：每 5s 一次
+- **内容**：各 Worker 上报自身实时状态（队列深度、缓存容量、驱动状态等）
+- **存储**：`last_heartbeat` 由 Metadata Leader 本地内存更新，**不写 Raft 日志**
+- **状态变更走 Raft**：仅当状态发生实质变更时（Online ↔ Offline、驱动状态切换）
+ 才通过 Raft Propose 持久化
+
+**失联检测**：
+
+- Metadata Leader 每 15s 扫描，连续 3 次未收到心跳（>15s）的 Worker 标记为 `Offline`
+- Offline 的 Tape Worker 上的驱动不再被调度器分配任务
+
+**优雅下线**：
+
+1. 管理员通过 Console 发起 Drain（排空）
+2. Worker 状态变为 `Draining`，不再接受新任务
+3. 等待正在执行的任务完成
+4. 管理员确认后通过 Console 执行 Deregister
+
+#### 3.10.10 配置与服务发现
+
+各节点的配置各不相同，遵循"最小知识"原则：
+
+```yaml
+# Gateway 配置 — 仅需 Scheduler Worker 地址
+gateway:
+ scheduler_addrs:
+ - "10.0.2.1:22001"
+ - "10.0.2.2:22001"
+
+# Console 配置 — 仅需 Metadata 地址
+console:
+ metadata_addrs:
+ - "10.0.1.1:21001"
+ - "10.0.1.2:21001"
+ - "10.0.1.3:21001"
+
+# Scheduler Worker 配置 — 需要 Metadata 地址（Cache/Tape 通过 Metadata 发现）
+scheduler_worker:
+ metadata_addrs:
+ - "10.0.1.1:21001"
+ - "10.0.1.2:21001"
+ - "10.0.1.3:21001"
+
+# Cache Worker / Tape Worker 配置 — 仅需 Metadata 地址（用于心跳注册）
+cache_worker:
+ metadata_addrs:
+ - "10.0.1.1:21001"
+ - "10.0.1.2:21001"
+ - "10.0.1.3:21001"
+```
+
+**Scheduler Worker 的服务发现**：Scheduler 启动时通过 Metadata 查询在线的 Cache Worker 和 Tape Worker：
+
+```rust
+async fn discover_workers(metadata: &MetadataClient) -> WorkerTopology {
+ let caches = metadata.list_online_cache_workers().await?;
+ let tapes = metadata.list_online_tape_workers().await?;
+ WorkerTopology { caches, tapes }
+}
+```
+
+| 场景 | 发现路径 |
+|------|----------|
+| Gateway 全部请求 | 配置的 Scheduler 地址 → gRPC 发送请求 |
+| Scheduler 操作缓存 | 查 Metadata → 获取 Cache Worker 地址 → gRPC 读写缓存 |
+| Scheduler 操作磁带 | 查 Metadata → 获取 Tape Worker 地址 → gRPC 下发磁带指令 |
+| Console 管理集群 | 配置的 Metadata 地址 → gRPC 管控操作 |
+
+---
+
+## 4. Column Family 设计
+
+| CF 名称 | Key 格式 | Value 类型 | 说明 |
+|---------|----------|-----------|------|
+| `cf_objects` | `obj:{bucket}:{key}` | ObjectMetadata | 对象元数据（当前版本） |
+| `cf_object_versions` | `objv:{bucket}:{key}:{version_id}` | ObjectMetadata | 多版本对象 |
+| `cf_buckets` | `bkt:{bucket}` | BucketInfo | 桶信息 |
+| `cf_bundles` | `bundle:{uuid}` | ArchiveBundle | 归档包（含 entries） |
+| `cf_tapes` | `tape:{tape_id}` | TapeInfo | 磁带信息 |
+| `cf_recall_tasks` | `recall:{uuid}` | RecallTask | 取回任务 |
+| `cf_archive_tasks` | `archive:{uuid}` | ArchiveTask | 归档任务 |
+| `cf_idx_bundle_objects` | `ibo:{archive_id}:{bucket}:{key}` | 空 | 归档包→对象 反查索引 |
+| `cf_idx_tape_bundles` | `itb:{tape_id}:{bundle_id}` | 空 | 磁带→归档包 反查索引 |
+| `cf_idx_pending` | `pend:{created_at}:{bucket}:{key}` | 空 | ColdPending 对象扫描索引（按时间排序） |
+| `cf_idx_recall_by_tape` | `rbt:{tape_id}:{recall_id}` | 空 | 按磁带查取回任务（合并用） |
+| `cf_scheduler_workers` | `sw:{node_id}` | SchedulerWorkerInfo | 调度 Worker 注册信息 |
+| `cf_cache_workers` | `cw:{node_id}` | CacheWorkerInfo | 缓存 Worker 注册信息 |
+| `cf_tape_workers` | `tw:{node_id}` | TapeWorkerInfo | 磁带 Worker 注册信息 |
+
+---
+
+## 5. MetadataService trait：面向各层的 API
+
+### 5.1 设计原则
+
+MetadataService 拆分为多个子 trait，按消费方组织：
+
+```
+ ┌──────────────────────────────┐
+ │ MetadataService │
+ │ impl ObjectApi │
+ │ impl BucketApi │
+ │ impl ArchiveApi │
+ │ impl RecallApi │
+ │ impl TapeApi │
+ │ impl ClusterApi │
+ └──────────────────────────────┘
+ │ │
+ ┌─────────────┘ └───────────────┐
+ ▼ ▼
+ 接入层/协议层 调度层
+ ObjectApi (读+写) ArchiveApi (读+写)
+ BucketApi (读+写) RecallApi (读+写)
+ RecallApi (只写:创建) TapeApi (读+写)
+ ObjectApi (读+写)
+```
+
+### 5.2 ObjectApi（对象元数据）
+
+```rust
+#[async_trait]
+pub trait ObjectApi: Send + Sync {
+ // ── 接入层使用 ──
+ async fn put_object(&self, meta: ObjectMetadata) -> Result<()>;
+ async fn get_object(&self, bucket: &str, key: &str) -> Result>;
+ async fn get_object_version(
+ &self, bucket: &str, key: &str, version_id: &str,
+ ) -> Result>;
+ async fn delete_object(&self, bucket: &str, key: &str) -> Result<()>;
+ async fn head_object(&self, bucket: &str, key: &str) -> Result>;
+ async fn list_objects(
+ &self, bucket: &str, prefix: Option<&str>, marker: Option<&str>, max_keys: u32,
+ ) -> Result;
+
+ // ── 调度层使用 ──
+ async fn update_storage_class(
+ &self, bucket: &str, key: &str, class: StorageClass,
+ ) -> Result<()>;
+ async fn update_archive_location(
+ &self,
+ bucket: &str,
+ key: &str,
+ archive_id: Uuid,
+ tape_id: &str,
+ tape_set: Vec,
+ tape_block_offset: u64,
+ ) -> Result<()>;
+ async fn update_restore_status(
+ &self,
+ bucket: &str,
+ key: &str,
+ status: RestoreStatus,
+ expire_at: Option>,
+ ) -> Result<()>;
+ async fn scan_cold_pending(
+ &self, limit: u32,
+ ) -> Result>;
+}
+```
+
+| 方法 | 消费方 | 说明 |
+|------|--------|------|
+| `put_object` | Scheduler（代理 Gateway PutObject） | 创建/覆盖对象元数据 |
+| `get_object` | Scheduler（代理 Gateway GET/HEAD） | 查询当前版本 |
+| `get_object_version` | Scheduler | 查询指定版本 |
+| `delete_object` | Scheduler（代理 Gateway DELETE） | 删除对象 |
+| `head_object` | Scheduler（代理 Gateway HEAD） | 返回 storage_class、restore_status |
+| `list_objects` | Scheduler（代理 Gateway ListObjects） | ListObjects |
+| `update_storage_class` | 调度层 | 归档完成后 ColdPending → Cold |
+| `update_archive_location` | 调度层 | 归档完成后写入 archive_id、tape_id、tape_block_offset |
+| `update_restore_status` | 调度层 | 取回状态流转 + expire_at |
+| `scan_cold_pending` | 调度层 | 扫描待归档对象（使用 `cf_idx_pending` 索引） |
+
+### 5.3 BucketApi（桶管理）
+
+```rust
+#[async_trait]
+pub trait BucketApi: Send + Sync {
+ async fn create_bucket(&self, info: BucketInfo) -> Result<()>;
+ async fn get_bucket(&self, name: &str) -> Result>;
+ async fn delete_bucket(&self, name: &str) -> Result<()>;
+ async fn list_buckets(&self) -> Result>;
+}
+```
+
+| 方法 | 消费方 | 说明 |
+|------|--------|------|
+| `create_bucket` | 接入层 | CreateBucket |
+| `delete_bucket` | 接入层 | DeleteBucket（需检查桶为空） |
+| `list_buckets` | 接入层 | ListBuckets |
+
+### 5.4 ArchiveApi（归档元数据）
+
+```rust
+#[async_trait]
+pub trait ArchiveApi: Send + Sync {
+ async fn put_archive_bundle(&self, bundle: ArchiveBundle) -> Result<()>;
+ async fn get_archive_bundle(&self, id: Uuid) -> Result>;
+ async fn update_archive_bundle_status(
+ &self, id: Uuid, status: ArchiveBundleStatus,
+ ) -> Result<()>;
+ async fn list_bundles_by_tape(&self, tape_id: &str) -> Result>;
+
+ async fn put_archive_task(&self, task: ArchiveTask) -> Result<()>;
+ async fn get_archive_task(&self, id: Uuid) -> Result>;
+ async fn update_archive_task(&self, task: ArchiveTask) -> Result<()>;
+ async fn list_pending_archive_tasks(&self) -> Result>;
+}
+```
+
+| 方法 | 消费方 | 说明 |
+|------|--------|------|
+| `put_archive_bundle` | 调度层 | 归档完成后写入 Bundle（含 entries） |
+| `get_archive_bundle` | 调度层 | 取回时获取 Bundle（含 entries、filemark_start） |
+| `list_bundles_by_tape` | 调度层 | 查询磁带上所有 Bundle（使用 `cf_idx_tape_bundles`） |
+| `put_archive_task` | 调度层 | 创建归档任务 |
+| `update_archive_task` | 调度层 | 更新任务状态/进度 |
+
+### 5.5 RecallApi（取回元数据）
+
+```rust
+#[async_trait]
+pub trait RecallApi: Send + Sync {
+ async fn put_recall_task(&self, task: RecallTask) -> Result<()>;
+ async fn get_recall_task(&self, id: Uuid) -> Result>;
+ async fn update_recall_task(&self, task: RecallTask) -> Result<()>;
+ async fn list_pending_recall_tasks(&self) -> Result>;
+ async fn list_recall_tasks_by_tape(&self, tape_id: &str) -> Result>;
+ async fn find_active_recall(
+ &self, bucket: &str, key: &str,
+ ) -> Result>;
+}
+```
+
+| 方法 | 消费方 | 说明 |
+|------|--------|------|
+| `put_recall_task` | Scheduler（代理 Gateway RestoreObject） | 创建取回任务 |
+| `get_recall_task` | Scheduler | 查询任务详情 |
+| `update_recall_task` | Scheduler | 更新状态 Pending → InProgress → Completed |
+| `list_pending_recall_tasks` | Scheduler | 扫描待调度任务 |
+| `list_recall_tasks_by_tape` | Scheduler | 合并同磁带任务（使用 `cf_idx_recall_by_tape`） |
+| `find_active_recall` | Scheduler（代理 RestoreObject 时检测重复） | RestoreAlreadyInProgress |
+
+### 5.6 TapeApi（磁带元数据）
+
+```rust
+#[async_trait]
+pub trait TapeApi: Send + Sync {
+ async fn put_tape(&self, info: TapeInfo) -> Result<()>;
+ async fn get_tape(&self, tape_id: &str) -> Result>;
+ async fn update_tape(&self, info: TapeInfo) -> Result<()>;
+ async fn list_tapes(&self) -> Result>;
+ async fn list_tapes_by_status(&self, status: TapeStatus) -> Result>;
+}
+```
+
+| 方法 | 消费方 | 说明 |
+|------|--------|------|
+| `put_tape` | 调度层 | 注册新磁带 |
+| `get_tape` | 调度层 | 查询磁带信息 |
+| `update_tape` | 调度层 | 更新 used_bytes、status、error_count 等 |
+| `list_tapes_by_status` | 调度层 | 筛选可用磁带（Online + 有剩余空间） |
+
+### 5.7 ClusterApi（集群管理）
+
+```rust
+#[async_trait]
+pub trait ClusterApi: Send + Sync {
+ // ── Raft 状态 ──
+ async fn cluster_info(&self) -> Result;
+ async fn is_leader(&self) -> bool;
+ async fn ensure_linearizable(&self) -> Result<()>;
+
+ // ── Scheduler Worker ──
+ async fn register_scheduler_worker(&self, info: SchedulerWorkerInfo) -> Result<()>;
+ async fn deregister_scheduler_worker(&self, node_id: u64) -> Result<()>;
+ async fn list_online_scheduler_workers(&self) -> Result>;
+ async fn get_scheduler_worker(&self, node_id: u64) -> Result>;
+
+ // ── Cache Worker ──
+ async fn register_cache_worker(&self, info: CacheWorkerInfo) -> Result<()>;
+ async fn deregister_cache_worker(&self, node_id: u64) -> Result<()>;
+ async fn list_online_cache_workers(&self) -> Result>;
+ async fn get_cache_worker(&self, node_id: u64) -> Result>;
+
+ // ── Tape Worker ──
+ async fn register_tape_worker(&self, info: TapeWorkerInfo) -> Result<()>;
+ async fn deregister_tape_worker(&self, node_id: u64) -> Result<()>;
+ async fn list_online_tape_workers(&self) -> Result>;
+ async fn get_tape_worker(&self, node_id: u64) -> Result>;
+
+ // ── 通用 Worker 操作 ──
+ async fn update_worker_status(&self, worker_type: WorkerType, node_id: u64, status: NodeStatus) -> Result<()>;
+ async fn drain_worker(&self, worker_type: WorkerType, node_id: u64) -> Result<()>;
+}
+```
+
+| 方法 | 消费方 | 说明 |
+|------|--------|------|
+| `cluster_info` | Console/Scheduler | 获取集群全局信息 |
+| `register_xxx_worker` | Console（管理员添加） | 注册 Worker 到集群 |
+| `deregister_xxx_worker` | Console（管理员下线） | 从集群移除 Worker |
+| `list_online_xxx_workers` | Scheduler（服务发现） | 获取在线 Cache/Tape Worker 列表 |
+| `update_worker_status` | Metadata Leader | 心跳超时时更新状态 |
+| `drain_worker` | Console | 排空 Worker（不再分配新任务） |
+
+### 5.8 MetadataService（聚合类型）
+
+```rust
+pub struct MetadataService {
+ raft: Arc>,
+ store: Arc,
+}
+
+impl ObjectApi for MetadataService { /* ... */ }
+impl BucketApi for MetadataService { /* ... */ }
+impl ArchiveApi for MetadataService { /* ... */ }
+impl RecallApi for MetadataService { /* ... */ }
+impl TapeApi for MetadataService { /* ... */ }
+impl ClusterApi for MetadataService { /* ... */ }
+```
+
+为方便外部引用，提供类型别名：
+
+```rust
+pub type MetadataClient = MetadataService;
+```
+
+调度层和接入层注入时使用 `Arc`（即 `Arc`）:
+
+```rust
+// 接入层
+pub struct S3Handler {
+ metadata: Arc, // ObjectApi + BucketApi + RecallApi
+ cache: Arc,
+}
+
+// 调度层
+pub struct ArchiveScheduler {
+ metadata: Arc, // ObjectApi + ArchiveApi + TapeApi
+ tape_manager: Arc,
+}
+
+pub struct RecallScheduler {
+ metadata: Arc, // ObjectApi + RecallApi + ArchiveApi + TapeApi
+ tape_manager: Arc,
+ cache: Arc,
+}
+```
+
+---
+
+## 6. Raft 状态机命令
+
+```rust
+pub enum ColdStoreRequest {
+ // ── 对象 ──
+ PutObject(ObjectMetadata),
+ DeleteObject { bucket: String, key: String },
+ UpdateStorageClass { bucket: String, key: String, class: StorageClass },
+ UpdateArchiveLocation {
+ bucket: String, key: String,
+ archive_id: Uuid, tape_id: String, tape_set: Vec, tape_block_offset: u64,
+ },
+ UpdateRestoreStatus {
+ bucket: String, key: String,
+ status: RestoreStatus, expire_at: Option>,
+ },
+
+ // ── 桶 ──
+ CreateBucket(BucketInfo),
+ DeleteBucket { name: String },
+
+ // ── 归档 ──
+ PutArchiveBundle(ArchiveBundle),
+ UpdateArchiveBundleStatus { id: Uuid, status: ArchiveBundleStatus },
+ PutArchiveTask(ArchiveTask),
+ UpdateArchiveTask(ArchiveTask),
+
+ // ── 取回 ──
+ PutRecallTask(RecallTask),
+ UpdateRecallTask(RecallTask),
+
+ // ── 磁带 ──
+ PutTape(TapeInfo),
+ UpdateTape(TapeInfo),
+
+ // ── Worker 注册（三类） ──
+ RegisterSchedulerWorker(SchedulerWorkerInfo),
+ DeregisterSchedulerWorker { node_id: u64 },
+ RegisterCacheWorker(CacheWorkerInfo),
+ DeregisterCacheWorker { node_id: u64 },
+ RegisterTapeWorker(TapeWorkerInfo),
+ DeregisterTapeWorker { node_id: u64 },
+
+ // ── Worker 状态变更 ──
+ UpdateWorkerStatus { worker_type: WorkerType, node_id: u64, status: NodeStatus },
+}
+```
+
+| 命令 | 写入方 | 说明 |
+|------|--------|------|
+| `PutObject` | Scheduler Worker（代理 Gateway 请求） | 创建对象（storage_class = ColdPending） |
+| `DeleteObject` | Scheduler Worker（代理 Gateway 请求） | 删除对象 |
+| `UpdateStorageClass` | Scheduler Worker | ColdPending → Cold |
+| `UpdateArchiveLocation` | Scheduler Worker | 归档完成后写入磁带位置 |
+| `UpdateRestoreStatus` | Scheduler Worker | 取回状态流转（含 expire_at） |
+| `PutArchiveBundle` | Scheduler Worker | 创建归档包 |
+| `PutRecallTask` | Scheduler Worker（代理 Gateway RestoreObject） | 创建取回任务 |
+| `UpdateRecallTask` | Scheduler Worker | 更新取回任务状态 |
+| `PutTape` / `UpdateTape` | Scheduler Worker | 磁带信息管理 |
+| `RegisterXxxWorker` | Console（管理员添加） | 三类 Worker 注册 |
+| `DeregisterXxxWorker` | Console（管理员下线） | 三类 Worker 注销 |
+| `UpdateWorkerStatus` | Metadata Leader | 仅在状态变更时写入（Online ↔ Offline 等） |
+
+> **心跳优化**：三类 Worker 每 5s 上报心跳，但 `last_heartbeat` 仅在 Leader 本地内存更新，
+> 不写 Raft 日志。仅当**状态发生实质变更**（节点上下线、驱动状态切换）时才通过
+> `UpdateWorkerStatus` 走 Raft Propose，避免高频心跳占满日志。
+
+---
+
+## 7. 读写路径
+
+| 操作 | 路径 | 一致性 |
+|------|------|--------|
+| 写 | Client → Leader → Raft Propose → 多数派 Append → Apply → RocksDB | 强一致 |
+| 读（默认） | 任意节点 → 本地 RocksDB | 最终一致 |
+| 线性读 | `raft.ensure_linearizable().await` → 本地 RocksDB | 强一致 |
+
+**写入方使用建议**：
+
+| 操作 | 一致性要求 | 建议 |
+|------|-----------|------|
+| PutObject / DeleteObject | 强一致 | 写入走 Raft |
+| RestoreObject 检查重复 | 强一致 | `find_active_recall` 使用线性读 |
+| GET 查 restore_status | 可容忍短暂延迟 | 默认读即可 |
+| scan_cold_pending | 可容忍短暂延迟 | 默认读 |
+| 归档完成更新 | 强一致 | 写入走 Raft |
+
+---
+
+## 8. 架构图
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ MetadataService │
+│ ┌─────────────────────────────────────────────────────────────────────┐ │
+│ │ ObjectApi | BucketApi | ArchiveApi | RecallApi | TapeApi | ClusterApi │ │
+│ └─────────────────────────────────────────────────────────────────────┘ │
+│ │ │
+│ ┌──────────┴──────────┐ │
+│ ▼ ▼ │
+│ ┌──────────┐ ┌──────────┐ │
+│ │ 写路径 │ │ 读路径 │ │
+│ │ Raft │ │ 本地 │ │
+│ │ Propose │ │ RocksDB │ │
+│ └────┬─────┘ └──────────┘ │
+│ ▼ │
+│ ┌───────────────────────┐ │
+│ │ Raft Core (openraft) │ │
+│ │ 多数派复制 → Apply │ │
+│ └───────────┬───────────┘ │
+│ ▼ │
+│ ┌───────────────────────┐ │
+│ │ RocksDB │ │
+│ │ cf_objects │ │
+│ │ cf_bundles │ │
+│ │ cf_tapes │ │
+│ │ cf_recall_tasks │ │
+│ │ cf_archive_tasks │ │
+│ │ cf_buckets │ │
+│ │ cf_idx_* │ │
+│ └───────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 9. 模块结构
+
+```
+src/metadata/
+├── mod.rs # pub use，MetadataService 导出
+├── service.rs # MetadataService 结构体，聚合所有 trait 实现
+├── traits/ # ─── trait 定义 ───
+│ ├── mod.rs
+│ ├── object.rs # ObjectApi
+│ ├── bucket.rs # BucketApi
+│ ├── archive.rs # ArchiveApi
+│ ├── recall.rs # RecallApi
+│ ├── tape.rs # TapeApi
+│ └── cluster.rs # ClusterApi
+├── models/ # ─── 数据结构 ───
+│ ├── mod.rs
+│ ├── object.rs # ObjectMetadata, StorageClass, RestoreStatus
+│ ├── bundle.rs # ArchiveBundle, BundleEntry, ArchiveBundleStatus
+│ ├── tape.rs # TapeInfo, TapeStatus
+│ ├── task.rs # RecallTask, ArchiveTask, RestoreTier
+│ ├── bucket.rs # BucketInfo
+│ ├── cluster.rs # ClusterInfo, MetadataNodeInfo, RaftRole, NodeStatus, WorkerType
+│ └── worker.rs # SchedulerWorkerInfo, CacheWorkerInfo, TapeWorkerInfo, DriveEndpoint, LibraryEndpoint
+├── raft/ # ─── Raft 实现 ───
+│ ├── mod.rs
+│ ├── client.rs # Raft 客户端（Propose + 线性读）
+│ ├── store.rs # RocksStore 扩展（CF 初始化）
+│ ├── state_machine.rs # ColdStoreRequest Apply 逻辑
+│ └── network.rs # 节点间 RPC
+└── index.rs # 二级索引维护逻辑
+```
+
+---
+
+## 10. 配置项
+
+```yaml
+metadata:
+ backend: "RaftRocksDB"
+ raft:
+ node_id: 1
+ cluster: "1:127.0.0.1:21001,2:127.0.0.1:21002,3:127.0.0.1:21003"
+ data_path: "/var/lib/coldstore/metadata"
+ snapshot_interval: 10000 # 每 10000 条日志做一次 snapshot
+ heartbeat_interval_ms: 200
+ election_timeout_ms: 1000
+ rocksdb:
+ max_open_files: 1024
+ write_buffer_size_mb: 64
+ max_background_jobs: 4
+```
+
+---
+
+## 11. 依赖关系（方案 B）
+
+### 11.1 元数据写入入口
+
+| 写入方 | 使用的 trait | 操作 |
+|--------|-------------|------|
+| **接入层** | ObjectApi, BucketApi | PutObject, DeleteObject, CreateBucket |
+| **协议层** | RecallApi | PutRecallTask（RestoreObject 时创建） |
+| **调度层** | ObjectApi, ArchiveApi, RecallApi, TapeApi | 归档/取回全流程状态流转 |
+
+### 11.2 元数据读取方
+
+| 读取方 | 使用的 trait | 用途 |
+|--------|-------------|------|
+| 接入层/协议层 | ObjectApi, BucketApi, RecallApi | 查询对象状态、桶列表、检测重复 Restore |
+| 调度层 | ObjectApi, ArchiveApi, RecallApi, TapeApi | 扫描 ColdPending、查磁带位置、合并任务 |
+
+### 11.3 不直接依赖的层
+
+| 层 | 关系 |
+|------|------|
+| 缓存层 | **不持有 MetadataService**，由调度层编排 |
+| 磁带层 | **不持有 MetadataService**，由调度层编排 |
+
+---
+
+## 12. 参考资料
+
+- [OpenRaft](https://github.com/databendlabs/openraft)
+- [openraft-rocksstore](https://crates.io/crates/openraft-rocksstore)
+- [RocksDB Column Families](https://github.com/facebook/rocksdb/wiki/Column-Families)
diff --git a/docs/modules/04-cache-layer.md b/docs/modules/04-cache-layer.md
new file mode 100644
index 0000000..a7298bf
--- /dev/null
+++ b/docs/modules/04-cache-layer.md
@@ -0,0 +1,668 @@
+# 数据缓存层模块设计
+
+> 所属架构：ColdStore 冷存储系统
+> 参考：[总架构设计](../DESIGN.md)
+
+## 1. 模块概述
+
+数据缓存层承载从磁带取回的解冻数据，供 GET 请求快速响应，避免重复触发磁带读取。
+
+> **部署模型**：缓存层运行在 **Cache Worker** 节点上，与 **Scheduler Worker** 同机部署。
+> Scheduler 通过 gRPC 与 Cache Worker 通信（虽然同机，仍使用 gRPC 保持架构一致性）。
+> Gateway 不直连 Cache Worker，所有数据读写都由 Scheduler Worker 代理。
+
+### 1.1 职责
+
+- 存储解冻后的对象数据
+- 响应 GET 请求（冷对象已解冻时）
+- 缓存淘汰：LRU、LFU、TTL、容量限制
+- 与 SPDK 集成，实现高性能用户态 I/O
+
+### 1.2 在架构中的位置
+
+```
+取回调度器 ──► 磁带读取 ──► 数据缓存层 ──► 协议层/接入层 ──► GET 响应
+ │
+ └─ async-spdk (SPDK Blobstore on bdev)
+
+注意：缓存层不直接持有元数据 client。
+元数据更新由调度层统一负责（方案 B）。
+```
+
+---
+
+## 2. 技术选型
+
+| 组件 | 选型 | 说明 |
+|------|------|------|
+| SPDK 绑定 | **async-spdk** | [madsys-dev/async-spdk](https://github.com/madsys-dev/async-spdk) |
+| SPDK 存储方式 | **Blobstore (Blob)** | 基于 Blob 的持久化块分配器，非 raw bdev |
+| 底层设备 | NVMe bdev / Malloc (测试) | Blobstore 构建于 bdev 之上 |
+
+---
+
+## 3. 数据布局：SPDK Blob 方式
+
+### 3.1 Blobstore 层级结构
+
+SPDK Blobstore 定义以下抽象（[SPDK Blobstore 文档](https://spdk.io/doc/blob.html)）：
+
+| 层级 | 典型大小 | 说明 |
+|------|----------|------|
+| **Logical Block** | 512B / 4KB | 磁盘暴露的基本单位 |
+| **Page** | 4KB | 固定页，读写最小单位 |
+| **Cluster** | 1MB (256 pages) | 分配单元，Blob 由 cluster 组成 |
+| **Blob** | 可变 | 有序 cluster 列表，持久化，由 blob_id 标识 |
+| **Blobstore** | 整设备 | 拥有底层 bdev，含元数据区 + blob 集合 |
+
+### 3.2 缓存层与 Blob 的对应关系
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Blobstore 布局（整 bdev） │
+├─────────────────────────────────────────────────────────────────────────┤
+│ [ Super Block ] [ Metadata Region ] [ Blob 数据区 ] │
+│ │ │ │ │
+│ Cluster 0 专用 Blob 元数据链表 Cluster 1..N │
+│ 签名/版本/配置 per-blob 元数据 各 Blob 的 cluster │
+└─────────────────────────────────────────────────────────────────────────┘
+
+每个缓存对象 = 1 个 Blob
+ - blob_id: Blobstore 分配的唯一 ID
+ - 数据: 按 page 读写，支持 thin provisioning（首次写时分配 cluster）
+ - xattrs: bucket, key, size, checksum, expire_at, cached_at
+```
+
+### 3.3 对象与 Blob 映射
+
+| 缓存对象 | Blob 表示 |
+|----------|-----------|
+| 1 个 S3 对象 (bucket, key) | 1 个 Blob |
+| 对象数据 | Blob 的 cluster 序列，按 page 读写 |
+| 元数据 | Blob xattrs（见 3.3.1） |
+
+**cache_key → blob_id 索引**：
+
+- Blobstore 不提供按名称查找，需自维护 `cache_key → blob_id` 映射
+- 存储方式：内存 HashMap + 可选持久化（如写入 Super Blob 或独立索引 Blob）
+- `cache_key = format!("{}:{}", bucket, key)` 或含 version_id
+
+### 3.3.1 Blob xattrs 字段定义
+
+xattrs 为 Blob 的扩展属性，键值对形式，用于存储对象级元数据。字段含义与用途如下：
+
+| xattr key | 类型 | 必填 | 含义 | 用途 |
+|-----------|------|------|------|------|
+| `bucket` | string | 是 | S3 桶名 | 与 key 共同唯一标识对象；GET 时校验、淘汰时按桶过滤 |
+| `key` | string | 是 | S3 对象键 | 与 bucket 共同唯一标识对象；重建 cache_key |
+| `size` | u64 (string 序列化) | 是 | 对象字节大小 | 读取时分配缓冲；校验读取长度；淘汰时计算容量 |
+| `expire_at` | i64 Unix 时间戳 (string) | 是 | 解冻过期时间 | 与元数据 restore_expire_at 一致；TTL 淘汰依据 |
+| `cached_at` | i64 Unix 时间戳 (string) | 是 | 写入缓存时间 | LRU 淘汰依据；可观测性（缓存时长） |
+| `checksum` | string (hex) | 否 | 对象校验和 SHA256 | 读后校验数据完整性；可选，调度层传入时写入 |
+| `version_id` | string | 否 | S3 对象版本 ID | 多版本支持；cache_key 含 version 时需存 |
+| `content_type` | string | 否 | 对象 Content-Type | 协议层 GET 响应头；可选透传 |
+| `etag` | string | 否 | 对象 ETag | 协议层 GET 响应头；可选透传 |
+
+**xattrs 用途汇总**：
+
+- **查找与校验**：bucket + key 用于重建 cache_key，与索引一致时确认 Blob 归属
+- **淘汰**：expire_at 驱动 TTL 淘汰，cached_at 驱动 LRU 淘汰，size 参与容量计算
+- **完整性**：checksum 用于读后校验，发现损坏可触发重新 Restore
+- **协议透传**：content_type、etag 供 GET 响应头使用，避免再查元数据
+
+### 3.3.2 cache_key → blob_id 索引条目
+
+内存索引（及可选持久化）中每条目的字段：
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `cache_key` | string | `{bucket}:{key}` 或含 version | 主键，唯一标识缓存对象 |
+| `blob_id` | u64 | Blobstore 分配的 Blob ID | 定位 Blob，执行 open/read/write/delete |
+| `size` | u64 | 对象大小 | 淘汰时容量统计；读时分配缓冲 |
+| `expire_at` | i64 | 过期时间戳 | 快速判断是否过期，无需开 Blob 读 xattr |
+| `cached_at` | i64 | 缓存时间戳 | LRU 排序；避免开 Blob 读 xattr |
+
+**索引与 xattrs 的关系**：索引用于快速查找（cache_key → blob_id）和淘汰决策；xattrs 为 Blob 内持久化元数据，用于校验、重建索引、协议透传。两者需保持一致，写入时同步更新。
+
+### 3.3.3 其他相关字段
+
+| 来源 | 字段 | 含义 | 用途 |
+|------|------|------|------|
+| Blobstore | `blob_id` | Blob 唯一标识 | 所有 Blob 操作的句柄 |
+| Blobstore | `blob_size` (num_clusters × cluster_size) | Blob 逻辑大小 | resize 时设置；与对象 size 对齐到 cluster |
+| 调度层传入 | `data` | 对象原始字节 | 写入 Blob 的 payload |
+| 调度层传入 | `checksum` | 可选 SHA256 | 写入 xattr，读后校验 |
+| 调度层传入 | `expire_at` | 解冻保留截止时间 | 写入 xattr 与索引；来自 RestoreRequest.Days |
+
+### 3.4 Blob 创建与读写流程
+
+```
+创建/写入:
+ 1. 创建 Blob: spdk_bs_create_blob() → blob_id
+ 2. 打开 Blob: spdk_bs_open_blob(blob_id) → blob handle
+ 3. 设置 xattrs: spdk_blob_set_xattr(blob, "bucket", ...) 等
+ 4. 调整大小: spdk_blob_resize(blob, num_clusters)
+ 5. 同步元数据: spdk_blob_sync_md(blob)
+ 6. 写入数据: spdk_blob_io_write(blob, channel, offset, len, buf, cb)
+ 7. 关闭 Blob: spdk_blob_close(blob)
+
+读取:
+ 1. 查索引: cache_key → blob_id
+ 2. 打开 Blob: spdk_bs_open_blob(blob_id) → blob handle
+ 3. 读取: spdk_blob_io_read(blob, channel, offset, len, buf, cb)
+ 4. 关闭 Blob: spdk_blob_close(blob)
+
+注意：set_xattr / resize 需在 open 之后的 blob handle 上调用。
+读写单位为 io_unit（通常 4KB，可通过 spdk_bs_get_io_unit_size() 获取）。
+```
+
+### 3.5 Blob 数据格式
+
+- **读写单位**：io_unit（通常 4KB），`spdk_blob_io_read`/`spdk_blob_io_write` 的 offset 和 length 以 io_unit 为单位
+- **对象数据**：连续写入 Blob，不足一 page 的尾部需填充或按 page 写入
+- **Thin Provisioning**：可创建 thin blob，首次写入时分配 cluster，节省空间
+
+### 3.6 关键参数
+
+| 参数 | 推荐值 | 说明 |
+|------|--------|------|
+| cluster_size | 1MB | Blobstore 创建时指定，Blob 按 cluster 分配 |
+| page_size | 4KB | 读写粒度 |
+| max_object_size | 5GB | 单对象上限，超限不缓存或分块 |
+| blobstore_type | "coldstore_cache" | 用于识别 Blobstore 归属 |
+
+### 3.7 与 async-spdk 的集成
+
+async-spdk 提供 `hello_blob` 示例，使用 Blobstore API。缓存层需：
+
+- 初始化 Blobstore：`spdk_bs_init()` / `spdk_bs_load()` 于指定 bdev
+- 使用 Blob API：`create_blob`、`open_blob`、`resize`、`write`、`read`、`close`、`delete_blob`
+- 通过 xattrs 存储 bucket、key、expire_at 等
+- 自维护 `cache_key → blob_id` 索引（内存 + 可选持久化）
+
+---
+
+## 4. 核心数据结构
+
+### 4.1 CacheManager
+
+缓存层的顶层入口，同时实现 `CacheReadApi` + `CacheWriteApi`。
+
+```rust
+pub struct CacheManager {
+ backend: Box,
+ index: CacheIndex,
+ config: CacheConfig,
+ stats: CacheStats,
+}
+```
+
+| 字段 | 类型 | 含义 | 说明 |
+|------|------|------|------|
+| `backend` | `Box` | 存储后端实例 | 多态：SpdkBlobCacheBackend 或 FileCacheBackend |
+| `index` | `CacheIndex` | cache_key → blob_id 的内存索引 | 所有查找/淘汰决策的入口 |
+| `config` | `CacheConfig` | 缓存配置 | 容量上限、TTL、淘汰策略等 |
+| `stats` | `CacheStats` | 运行时统计 | 命中率、容量使用、淘汰次数等 |
+
+### 4.2 CacheBackend trait
+
+```rust
+#[async_trait]
+pub trait CacheBackend: Send + Sync {
+ async fn write_blob(
+ &self, blob_id: u64, data: &[u8], xattrs: &BlobXattrs,
+ ) -> Result;
+ async fn read_blob(&self, blob_id: u64) -> Result>;
+ async fn delete_blob(&self, blob_id: u64) -> Result<()>;
+ async fn create_blob(&self, xattrs: &BlobXattrs, size: u64) -> Result;
+ async fn read_xattrs(&self, blob_id: u64) -> Result;
+ async fn list_blobs(&self) -> Result>;
+}
+```
+
+| 方法 | 含义 |
+|------|------|
+| `write_blob` | 向已创建的 Blob 写入对象数据 |
+| `read_blob` | 从 Blob 读取对象全部数据 |
+| `delete_blob` | 删除 Blob（淘汰时调用） |
+| `create_blob` | 创建新 Blob、设置 xattrs、resize，返回 blob_id |
+| `read_xattrs` | 读取 Blob 的 xattrs（启动时重建索引用） |
+| `list_blobs` | 列出 Blobstore 中所有 Blob ID（启动时重建索引用） |
+
+### 4.3 BlobXattrs
+
+对应 Blob 上持久化的 xattrs 键值对，Rust 侧的结构化表示。
+
+```rust
+pub struct BlobXattrs {
+ pub bucket: String,
+ pub key: String,
+ pub size: u64,
+ pub expire_at: i64,
+ pub cached_at: i64,
+ pub checksum: Option,
+ pub version_id: Option,
+ pub content_type: Option,
+ pub etag: Option,
+}
+```
+
+| 字段 | 类型 | 必填 | 含义 | 写入时机 |
+|------|------|------|------|----------|
+| `bucket` | String | 是 | S3 桶名 | 调度层 put_restored 传入 |
+| `key` | String | 是 | S3 对象键 | 调度层 put_restored 传入 |
+| `size` | u64 | 是 | 对象原始字节数（非 Blob 占用的 cluster 数） | 调度层传入 data.len() |
+| `expire_at` | i64 | 是 | 解冻过期 Unix 时间戳（秒） | 调度层从 RestoreRequest.Days 计算后传入 |
+| `cached_at` | i64 | 是 | 写入缓存的 Unix 时间戳（秒） | CacheManager 写入时取 Utc::now() |
+| `checksum` | Option\ | 否 | SHA256 hex 字符串 | 调度层传入（若磁带读取时有校验） |
+| `version_id` | Option\ | 否 | S3 对象版本 ID | 调度层传入（多版本场景） |
+| `content_type` | Option\ | 否 | MIME 类型 | 调度层传入（协议层 GET 响应透传） |
+| `etag` | Option\ | 否 | S3 ETag | 调度层传入（协议层 GET 响应透传） |
+
+### 4.4 CacheEntry（内存索引条目）
+
+```rust
+pub struct CacheEntry {
+ pub cache_key: String,
+ pub blob_id: u64,
+ pub size: u64,
+ pub expire_at: i64,
+ pub cached_at: i64,
+ pub last_accessed_at: i64,
+ pub access_count: u64,
+}
+```
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `cache_key` | String | `{bucket}:{key}` 或 `{bucket}:{key}:{version_id}` | 索引主键，唯一标识缓存对象 |
+| `blob_id` | u64 | Blobstore 分配的 Blob 唯一 ID | 所有 Blob 操作的句柄 |
+| `size` | u64 | 对象原始字节数 | 淘汰时计算总容量；读时预分配缓冲 |
+| `expire_at` | i64 | 解冻过期 Unix 时间戳 | TTL 淘汰判断，过期即可删除 |
+| `cached_at` | i64 | 写入缓存 Unix 时间戳 | LRU 兜底排序（若无访问记录则用此值） |
+| `last_accessed_at` | i64 | 最近一次 GET 读取时间 | LRU 淘汰排序，每次 get 时更新 |
+| `access_count` | u64 | 累计 GET 次数 | LFU 淘汰排序（可选策略） |
+
+### 4.5 CacheIndex
+
+```rust
+pub struct CacheIndex {
+ entries: HashMap,
+ total_size: u64,
+}
+```
+
+| 字段 | 类型 | 含义 | 说明 |
+|------|------|------|------|
+| `entries` | HashMap\ | cache_key → CacheEntry | 全量内存索引，O(1) 查找 |
+| `total_size` | u64 | 当前缓存总占用字节 | 每次 put/delete 更新，淘汰时与 max_size 比较 |
+
+### 4.6 CachedObject（读取返回）
+
+```rust
+pub struct CachedObject {
+ pub data: Vec,
+ pub size: u64,
+ pub expire_at: DateTime,
+ pub content_type: Option,
+ pub etag: Option,
+ pub checksum: Option,
+}
+```
+
+| 字段 | 类型 | 含义 | 消费方 |
+|------|------|------|--------|
+| `data` | Vec\ | 对象完整数据 | 协议层写入 HTTP 响应体 |
+| `size` | u64 | 数据字节数 | 协议层 Content-Length |
+| `expire_at` | DateTime\ | 解冻过期时间 | 协议层生成 `x-amz-restore` 头 |
+| `content_type` | Option\ | MIME 类型 | 协议层 Content-Type 响应头 |
+| `etag` | Option\ | ETag | 协议层 ETag 响应头 |
+| `checksum` | Option\ | SHA256 hex | 协议层可选校验数据完整性 |
+
+### 4.7 CacheConfig
+
+```rust
+pub struct CacheConfig {
+ pub backend: CacheBackendType,
+ pub max_size_bytes: u64,
+ pub default_ttl_secs: u64,
+ pub eviction_policy: EvictionPolicy,
+ pub eviction_batch_size: usize,
+ pub eviction_low_watermark: f64,
+ pub bdev_name: String,
+ pub cluster_size_mb: u32,
+}
+```
+
+| 字段 | 类型 | 含义 | 说明 |
+|------|------|------|------|
+| `backend` | CacheBackendType | 后端类型 | `Spdk` / `File`（测试） |
+| `max_size_bytes` | u64 | 缓存总容量上限 | 超过此值触发淘汰 |
+| `default_ttl_secs` | u64 | 默认 TTL | 未指定 expire_at 时的兜底值 |
+| `eviction_policy` | EvictionPolicy | 淘汰策略 | `Lru` / `Lfu` / `TtlFirst` |
+| `eviction_batch_size` | usize | 单次淘汰个数 | 批量删除，减少淘汰频率 |
+| `eviction_low_watermark` | f64 | 淘汰水位线 | 0.8 表示淘汰到 80% 容量后停止 |
+| `bdev_name` | String | SPDK bdev 名称 | 如 `"Malloc0"` 或 NVMe bdev |
+| `cluster_size_mb` | u32 | Blobstore cluster 大小 | 如 1MB |
+
+### 4.8 CacheStats
+
+```rust
+pub struct CacheStats {
+ pub total_size: u64,
+ pub object_count: u64,
+ pub hit_count: AtomicU64,
+ pub miss_count: AtomicU64,
+ pub put_count: AtomicU64,
+ pub evict_count: AtomicU64,
+ pub evict_bytes: AtomicU64,
+}
+```
+
+| 字段 | 类型 | 含义 |
+|------|------|------|
+| `total_size` | u64 | 当前缓存数据总字节 |
+| `object_count` | u64 | 当前缓存对象数 |
+| `hit_count` | AtomicU64 | 累计缓存命中次数 |
+| `miss_count` | AtomicU64 | 累计缓存未命中次数 |
+| `put_count` | AtomicU64 | 累计写入次数 |
+| `evict_count` | AtomicU64 | 累计淘汰对象次数 |
+| `evict_bytes` | AtomicU64 | 累计淘汰字节数 |
+
+---
+
+## 5. 缓存策略
+
+| 策略 | 说明 |
+|------|------|
+| LRU | 淘汰最久未访问 |
+| LFU | 淘汰访问频率最低 |
+| TTL | 按 expire_at 淘汰（独立后台扫描） |
+| 容量 | 总容量上限，超限触发淘汰 |
+
+```rust
+pub enum EvictionPolicy {
+ Lru, // 按 last_accessed_at 排序淘汰
+ Lfu, // 按 access_count 排序淘汰
+ TtlFirst, // 优先淘汰已过期对象，再按 LRU
+}
+```
+
+**淘汰逻辑**：
+
+1. **TTL 扫描**（独立后台任务）：定期扫描 `expire_at < now` 的 CacheEntry，直接删除对应 Blob
+2. **容量淘汰**：当 `total_size > max_size_bytes` 时，按 `EvictionPolicy` 选择淘汰对象，批量删除 `eviction_batch_size` 个，直到 `total_size ≤ max_size_bytes × eviction_low_watermark`
+
+---
+
+## 6. 与调度层的对接
+
+### 5.1 接口定义
+
+```rust
+/// 缓存层提供给调度层的接口
+#[async_trait]
+pub trait CacheWriteApi: Send + Sync {
+ async fn put_restored(&self, item: RestoredItem) -> Result<()>;
+ async fn put_restored_batch(&self, items: Vec) -> Result<()>;
+ async fn delete(&self, bucket: &str, key: &str, version_id: Option<&str>) -> Result<()>;
+}
+
+pub struct RestoredItem {
+ pub bucket: String,
+ pub key: String,
+ pub version_id: Option,
+ pub data: Vec,
+ pub checksum: Option, // SHA256 hex
+ pub expire_at: DateTime,
+ pub content_type: Option, // 调度层从元数据获取后传入
+ pub etag: Option, // 调度层从元数据获取后传入
+}
+```
+
+| 字段 | 类型 | 含义 | 来源 |
+|------|------|------|------|
+| `bucket` | String | S3 桶名 | 调度层传入 |
+| `key` | String | S3 对象键 | 调度层传入 |
+| `version_id` | Option\ | 对象版本 | 调度层从元数据获取 |
+| `data` | Vec\ | 对象原始数据 | 磁带读取 |
+| `checksum` | Option\ | SHA256 hex 字符串 | 调度层校验后传入 |
+| `expire_at` | DateTime\ | 解冻过期时间 | 调度层从 RestoreRequest.Days 计算 |
+| `content_type` | Option\ | MIME 类型 | 调度层从元数据获取，用于 GET 响应透传 |
+| `etag` | Option\ | S3 ETag | 调度层从元数据获取，用于 GET 响应透传 |
+
+> `delete` 方法用于接入层 DeleteObject 时清理缓存（由接入层调用）。
+
+### 5.2 调用时机与流程
+
+缓存层自身**不**触发元数据更新。写入完成后返回 `Result<()>` 给调度层，由调度层统一负责后续元数据变更。
+
+```
+取回调度器执行 TapeReadJob （调度层职责）
+ │
+ ├─ 1. 从磁带顺序读取对象 A, B, C
+ │
+ ├─ 2. 每读完一个对象:
+ │ cache.put_restored(bucket, key, data, checksum, expire_at).await
+ │ 若失败: 重试或标记 RecallTask 失败
+ │
+ └─ 3. 全部写入缓存后: （调度层负责更新元数据）
+ metadata.update_restore_status(Completed, restore_expire_at)
+```
+
+> **关键原则**：缓存层是纯数据存储，不持有 MetadataClient。元数据写入入口收敛在调度层。
+
+### 5.3 数据流与校验
+
+| 步骤 | 负责方 | 说明 |
+|------|--------|------|
+| 磁带读取 | 调度器 | 带 checksum 校验 |
+| 写入缓存 | 缓存层 | 存储 data + checksum，纯数据操作 |
+| 更新元数据 | **调度器** | restore_status=Completed, restore_expire_at |
+| GET 时校验 | 协议层/缓存层 | 可选读后校验 checksum |
+
+### 5.4 失败与重试
+
+- 缓存写入失败：调度器重试 2 次，仍失败则 RecallTask 标记 Failed，**不更新元数据**
+- 缓存层空间不足：先触发淘汰，再写入；若仍不足则返回错误，调度器不更新元数据
+- 缓存写入成功但元数据更新失败：缓存有数据但 GET 仍返回未解冻状态，调度器需重试元数据更新
+
+---
+
+## 7. 与元数据层的关系（方案 B：缓存层不直接依赖元数据）
+
+### 6.1 设计原则
+
+**缓存层不持有 MetadataClient，不直接读写元数据。**
+
+元数据的写入入口收敛为两个：
+- **接入层**：`PutObject`、`DeleteObject`
+- **调度层**：归档/取回状态流转（`UpdateStorageClass`、`UpdateRestoreStatus` 等）
+
+缓存层是纯粹的数据存储层，只暴露 `CacheReadApi` 和 `CacheWriteApi`。
+
+### 6.2 缓存层对元数据的间接关系
+
+| 场景 | 依赖 | 说明 |
+|------|------|------|
+| GET 前 | 无直接依赖 | 协议层先查元数据，若 Completed 再调缓存 |
+| 淘汰时 | 无 | 基于自身 xattrs 中的 expire_at 判断，无需查元数据 |
+| 写入时 | 无 | 调度层传入 expire_at，缓存层直接写入 xattr |
+| 启动时 | 无 | 从 Blobstore xattrs 重建内存索引，不依赖元数据 |
+
+### 6.3 一致性保证（由调度层负责）
+
+| 顺序 | 操作 | 负责方 |
+|------|------|--------|
+| 1 | 磁带读取完成 | 调度器 |
+| 2 | `cache.put_restored(...)` 成功 | 调度器 → 缓存层 |
+| 3 | `metadata.update_restore_status(Completed)` | **调度器** → 元数据层 |
+| 4 | GET：查元数据 → Completed → 从缓存读 | 协议层 |
+
+若 2 成功、3 失败：缓存有数据但元数据未更新，GET 仍返回未解冻。调度器需重试元数据更新（补偿机制）。
+
+---
+
+## 8. 与协议层/接入层的对接
+
+### 7.1 接口定义
+
+```rust
+/// 缓存层提供给协议层/接入层的接口
+#[async_trait]
+pub trait CacheReadApi: Send + Sync {
+ async fn get(
+ &self,
+ bucket: &str,
+ key: &str,
+ version_id: Option<&str>,
+ ) -> Result>;
+
+ async fn contains(
+ &self,
+ bucket: &str,
+ key: &str,
+ version_id: Option<&str>,
+ ) -> Result;
+}
+```
+
+> `CachedObject` 定义见 §4.6，包含 data、size、expire_at、content_type、etag、checksum。
+
+### 7.2 协议层调用流程
+
+```
+GET /{bucket}/{key}
+ │
+ ├─ 协议层/Handler: metadata.get_object(bucket, key)
+ │
+ ├─ if storage_class != Cold:
+ │ 从热存储读取，返回
+ │
+ ├─ if storage_class == Cold:
+ │ if restore_status != Completed:
+ │ 返回 403 InvalidObjectState
+ │ if restore_expire_at < now:
+ │ 返回 403 InvalidObjectState（已过期）
+ │
+ └─ cache.get(bucket, key)
+ if Some(obj): 返回 obj.data，附带 x-amz-restore 头
+ if None: 返回 404 或 503（缓存丢失，需重新 Restore）
+```
+
+### 7.3 缓存未命中处理
+
+| 情况 | 协议层行为 |
+|------|------------|
+| 元数据 Completed 但缓存无数据 | 返回 503，提示重新 Restore；或触发异步取回 |
+| 缓存已淘汰（TTL 内） | 同上，元数据 restore_expire_at 未过期但缓存已删 |
+| 缓存损坏 | 校验失败时返回 500，建议重新 Restore |
+
+### 7.4 响应头
+
+GET 命中缓存时，协议层需附加：
+
+```
+x-amz-restore: ongoing-request="false", expiry-date="Fri, 28 Feb 2025 12:00:00 GMT"
+```
+
+---
+
+## 9. 对接汇总图（方案 B）
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ 协议层 / 接入层 │
+│ GET: metadata.get_object → if Completed → cache.get → 返回 data │
+│ HEAD: metadata.get_object → 生成 x-amz-restore 头 │
+│ PUT/DELETE: metadata.put_object / delete_object │
+└─────────────────────────────────────────────────────────────────────────┘
+ │ 读 │ 读
+ ▼ ▼
+┌───────────────────┐ ┌───────────────────────────────┐
+│ 元数据层 │ │ 缓存层（纯数据存储） │
+│ restore_status │ │ CacheReadApi: get/contains │
+│ restore_expire_at│ │ CacheWriteApi: put_restored │
+└───────────────────┘ │ ⚡ 不持有 MetadataClient │
+ ▲ └───────────────────────────────┘
+ │ 写（唯一写入协调者） ▲
+ │ │ 写
+ │ ┌───────────────────────────┘
+ │ │
+┌───────┴──────────────┴───────────────────────────────┐
+│ 调度层（归档/取回） │
+│ 1. 磁带读取 → 2. cache.put_restored → 3. 更新元数据 │
+│ 元数据写入的唯一协调者（除接入层 PUT/DELETE 外） │
+└──────────────────────────────────────────────────────┘
+ │
+ ▼
+┌──────────────────┐
+│ 磁带层（纯硬件） │
+│ 不持有 │
+│ MetadataClient │
+└──────────────────┘
+```
+
+---
+
+## 10. 集成方式
+
+- **方案 A**：缓存服务独立二进制，通过 gRPC/HTTP 与主服务通信
+- **方案 B**：主进程在 SPDK block_on 内启动 Axum（需调整启动顺序）
+- **方案 C**：缓存层先使用文件后端，待架构稳定后再接入 async-spdk
+
+---
+
+## 11. 模块结构
+
+```
+src/cache/
+├── mod.rs
+├── manager.rs # CacheManager，实现 CacheReadApi + CacheWriteApi
+├── index.rs # cache_key → blob_id 索引（内存 + 可选持久化）
+├── spdk/
+│ ├── mod.rs
+│ ├── blob_backend.rs # SpdkBlobCacheBackend，Blobstore/Blob API 封装
+│ └── config.rs
+└── file/ # 文件后端（兼容/测试）
+ └── backend.rs
+```
+
+---
+
+## 12. 配置项
+
+```yaml
+cache:
+ backend: "spdk"
+ spdk:
+ enabled: true
+ config_file: "/etc/coldstore/cache_spdk.json"
+ bdev_name: "Malloc0"
+ blobstore_type: "coldstore_cache"
+ cluster_size_mb: 1
+ max_size_gb: 100
+ ttl_secs: 86400
+ eviction_policy: "Lru"
+```
+
+---
+
+## 13. 依赖关系
+
+| 对接方 | 方向 | 接口 | 说明 |
+|--------|------|------|------|
+| 调度层 | 调度 → 缓存 | `CacheWriteApi`: `put_restored` / `put_restored_batch` | 取回后写数据 |
+| 接入层 | 接入 → 缓存 | `CacheWriteApi`: `delete` | DeleteObject 时清理缓存 |
+| 协议层/接入层 | 协议 → 缓存 | `CacheReadApi`: `get` / `contains` | GET 读数据 |
+| 元数据层 | **无依赖** | — | 缓存层不持有 MetadataClient |
+
+> **方案 B 原则**：缓存层是纯数据存储，不感知元数据。元数据写入由调度层统一协调。
+
+---
+
+## 14. 参考资料
+
+- [async-spdk](https://github.com/madsys-dev/async-spdk)（含 hello_blob 示例）
+- [SPDK Blobstore Programmer's Guide](https://spdk.io/doc/blob.html)
+- [SPDK blob.h API](https://spdk.io/doc/blob_8h.html)
diff --git a/docs/modules/05-scheduler-layer.md b/docs/modules/05-scheduler-layer.md
new file mode 100644
index 0000000..d063911
--- /dev/null
+++ b/docs/modules/05-scheduler-layer.md
@@ -0,0 +1,789 @@
+# 归档取回调度层模块设计
+
+> 所属架构：ColdStore 冷存储系统
+> 参考：[总架构设计](../DESIGN.md)
+
+## 1. 模块概述
+
+归档取回调度层负责冷数据的归档与取回调度，是 ColdStore 的核心业务逻辑层。设计需充分考虑**磁带的顺序读写特性**，通过聚合与合并策略最大化吞吐、减少换带与 seek。
+
+> **部署模型**：调度层运行在 **Scheduler Worker** 节点上，是 ColdStore 的**唯一业务中枢**。
+> Gateway 的全部 S3 请求都发往 Scheduler Worker 处理。
+> Scheduler 通过 gRPC 对接 Cache Worker（同机）和 Tape Worker（远程），
+> 通过 gRPC 读写 Metadata 集群。Cache/Tape Worker 不直接接受 Gateway 请求。
+>
+> **元数据写入协调原则（方案 B）**：Scheduler Worker 是元数据读写的**唯一业务入口**。
+> Gateway 不直连 Metadata。缓存层和磁带层不持有 MetadataClient，
+> 所有元数据变更由 Scheduler 统一负责。Console 仅用于管控操作（Worker 增删等）。
+
+### 1.1 职责
+
+- **归档调度**：扫描 ColdPending 对象，聚合为 ArchiveBundle，调度磁带顺序写入
+- **取回调度**：管理 Restore 队列，按 archive/tape 合并请求，调度磁带顺序读取
+- 合并同磁带/同归档包的请求，减少换带与定位
+- 控制并发、优先级、超时，保证性能与数据质量
+
+### 1.2 磁带特性约束
+
+| 特性 | 约束 | 调度影响 |
+|------|------|----------|
+| 顺序写入 | 必须顺序写，不可随机写 | 归档聚合需保证一次写入流 |
+| 顺序读取 | 随机读需 seek，成本高 | 取回合并需按物理位置排序 |
+| 换带成本 | 机械臂加载/卸载约 30s–2min | 同磁带任务优先合并 |
+| 块大小 | 256KB–1MB 常用，LTO 支持 64KB–8MB | 归档块对齐，缓冲匹配 |
+| 吞吐 | LTO-9 约 400 MB/s，LTO-10 更高 | 流式写入，避免小 IO |
+
+---
+
+## 2. 归档调度器：写入聚合逻辑
+
+### 2.1 聚合目标
+
+- **适配顺序写入**：一次 ArchiveBundle 对应磁带上一段连续写入
+- **最大化吞吐**：聚合足够多对象，避免小 IO、填满驱动流水线
+- **块对齐**：与磁带 block_size（如 256KB）对齐，减少驱动内部缓冲碎片
+
+### 2.2 ArchiveBundle 构建策略
+
+#### 2.2.1 聚合维度
+
+| 维度 | 策略 | 说明 |
+|------|------|------|
+| **大小** | `min_archive_size_mb` ~ `max_archive_size_mb` | 单 Bundle 总大小范围，避免过小（浪费换带）或过大（单任务过长） |
+| **对象数** | `batch_size` | 单 Bundle 最大对象数，控制元数据与索引开销 |
+| **时间窗口** | `aggregation_window_secs` | 同一窗口内 ColdPending 对象可聚合，避免长时间等待 |
+| **桶/前缀** | 可选同 bucket 聚合 | 便于后续按桶管理，非强制 |
+
+#### 2.2.2 聚合算法（伪代码）
+
+```
+1. 扫描 ColdPending 对象，按 created_at 或 size 排序
+2. 初始化当前 Bundle = []
+3. for each object:
+ if 加入后 total_size <= max_archive_size_mb AND count <= batch_size:
+ Bundle.append(object)
+ else:
+ 提交当前 Bundle 为 ArchiveBundle
+ 重置 Bundle，将 object 加入
+4. 若剩余 Bundle 且 total_size >= min_archive_size_mb: 提交
+5. 若剩余 Bundle 且 total_size < min_archive_size_mb: 等待下一轮或超时强制提交
+```
+
+#### 2.2.3 磁带上的物理布局
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ 磁带物理布局 (一个 ArchiveBundle) │
+├─────────────────────────────────────────────────────────────────┤
+│ [FileMark] [Obj1 Header][Obj1 Data] [FileMark] [Obj2 Header]... │
+│ │ │ │ │ │
+│ │ │ │ └─ 对象边界，便于定位 │
+│ │ │ └─ 块对齐（256KB）连续写入 │
+│ │ └─ 元数据：bucket, key, size, checksum, offset │
+│ └─ 归档包边界，MTFSF/MTBSF 可跳过 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+- **FileMark**：MTIO 文件标记，用于 seek 时按“文件”定位
+- **对象块**：固定或可变块，与 `block_size` 对齐
+- **索引**：每个对象在 Bundle 内的逻辑偏移写入 Bundle 头部或独立索引区，供取回定位
+
+### 2.3 顺序写入流水线
+
+```
+┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
+│ 对象读取 │───▶│ 块对齐 │───▶│ 双缓冲 │───▶│ 磁带写入 │
+│ (热存储) │ │ 填充 │ │ 流水线 │ │ (顺序) │
+└──────────┘ └──────────┘ └──────────┘ └──────────┘
+```
+
+- **块对齐**：不足 block_size 的对象尾部填充（padding），或使用可变块（需驱动支持）
+- **双缓冲**：预读下一批数据，写入当前批，保持驱动持续流式写入
+- **背压**：若热存储读取慢于磁带写入，可降低并发或增大缓冲
+
+### 2.4 归档流程（细化）
+
+1. **调度层**：从元数据扫描 ColdPending，按策略聚合为 ArchiveBundle
+2. **调度层**：选定目标磁带（当前写入头或新磁带）
+3. **调度层 → 磁带层**：申请磁带驱动，获取独占
+4. **磁带层**：顺序写入：FileMark → [Obj1 Header + Data] → FileMark → [Obj2...]
+5. **调度层**：写入完成后计算并存储 Bundle 校验和（可选）
+6. **调度层 → 元数据层**：更新 ObjectMetadata（Cold, archive_id, tape_id, tape_block_offset）、ArchiveBundle、TapeInfo
+7. **调度层 → 磁带层**：释放驱动；释放在线存储空间
+
+> 步骤 6 由调度层统一负责，磁带层不直接写元数据。
+
+### 2.5 归档关键参数
+
+| 参数 | 推荐值 | 说明 |
+|------|--------|------|
+| block_size | 262144 (256KB) | 与 LTO 常用块对齐 |
+| min_archive_size_mb | 100 | 单 Bundle 最小，避免过小 |
+| max_archive_size_mb | 10240 (10GB) | 单 Bundle 最大，控制单任务时长 |
+| batch_size | 500–2000 | 单 Bundle 对象数 |
+| write_buffer_mb | 64–128 | 写入缓冲，匹配驱动流水线 |
+| target_throughput_mbps | 300 | 目标吞吐，LTO-9 可达 400 |
+
+---
+
+## 3. 取回调度器：拉取聚合逻辑
+
+### 3.1 聚合目标
+
+- **减少换带**：同磁带上的多个请求合并为一次加载、一次顺序读取
+- **减少 seek**：同 archive 内按物理偏移排序，顺序读取
+- **合并同对象请求**：同一对象被多次 Restore 时只读一次，多路分发
+
+### 3.2 取回合并策略
+
+#### 3.2.1 合并层次
+
+```
+Level 1: 同 archive_id 的多个对象
+ → 一次磁带读取，按 tape_block_offset 排序，顺序读
+
+Level 2: 同 tape_id 的多个 archive
+ → 一次换带，按 archive 在磁带上的物理顺序排序
+
+Level 3: 同对象的多个 RecallTask（重复请求）
+ → 合并为一个读取，结果分发给多个请求方
+```
+
+#### 3.2.2 合并算法（伪代码）
+
+```
+1. 从队列取出待调度 RecallTask 集合
+2. 按 tape_id 分组
+3. for each tape_id:
+ tasks = 该磁带上的所有任务
+ 按 (archive_id, tape_block_offset) 排序，保证顺序读
+ 若存在同 (bucket, key) 的多个 task，去重，保留一个读取
+ 生成 TapeReadJob: { tape_id, [(archive_id, [objects])] }
+4. 按优先级（Expedited > Standard > Bulk）排序 TapeReadJob
+5. 分配可用驱动，执行 TapeReadJob
+```
+
+#### 3.2.3 磁带读取顺序
+
+```
+磁带物理顺序: Archive1 → Archive2 → Archive3 → ...
+
+取回请求: Obj_A∈Archive2, Obj_B∈Archive1, Obj_C∈Archive2
+
+优化后读取顺序:
+ 1. Seek 到 Archive1 起始
+ 2. 读取 Obj_B
+ 3. Seek 到 Archive2 起始（或顺序经过则无需 seek）
+ 4. 顺序读取 Obj_A, Obj_C
+```
+
+- 同一 Archive 内对象按 `tape_block_offset` 排序，尽量顺序读
+- 跨 Archive 时，按磁带物理顺序排列 Archive，减少回退（MTBSF 成本高于 MTFSF）
+
+### 3.3 取回流程（细化）
+
+1. **协议层 → 调度层**：接收 Restore 请求；协议层查询 ObjectMetadata 获取 `archive_id`、`tape_id`、`tape_block_offset`、`object_size`、`checksum` 等，构造 RecallTask 后提交给调度层入队
+2. **调度层**：从队列取任务，按 tape_id + archive_id 合并
+3. **调度层 → 磁带层**：检查磁带状态，ONLINE → 继续；OFFLINE → 通知并等待
+4. **调度层 → 磁带层**：申请驱动，加载磁带（若未加载）
+5. **磁带层**：按物理顺序执行读取：Seek → Read → 返回数据
+6. **调度层 → 缓存层**：`cache.put_restored(bucket, key, data, checksum, expire_at)`
+7. **调度层 → 元数据层**：更新 restore_status=Completed，restore_expire_at
+8. **调度层 → 磁带层**：释放驱动
+
+> 步骤 6-7 体现方案 B 的核心原则：调度层先写缓存，再更新元数据。缓存层和磁带层均不持有 MetadataClient。
+
+### 3.4 取回关键参数
+
+| 参数 | 推荐值 | 说明 |
+|------|--------|------|
+| queue_size | 10000 | 队列容量 |
+| max_concurrent_restores | 驱动数 | 每驱动一个取回流水线 |
+| restore_timeout_secs | 3600 | 单任务超时 |
+| min_restore_interval_secs | 300 | 最小取回间隔（5 分钟 SLA） |
+| read_buffer_mb | 64 | 读取缓冲 |
+| merge_window_secs | 60 | 合并窗口，窗口内同磁带任务可合并 |
+
+---
+
+## 4. 调度机制
+
+### 4.1 驱动分配与竞争
+
+| 资源 | 策略 |
+|------|------|
+| 磁带驱动 | 归档与取回共享驱动池，可配置比例（如 2:1 或独立池） |
+| 优先级 | 取回 Expedited > 归档 > 取回 Standard > 取回 Bulk |
+| 抢占 | 一般不抢占，当前任务完成后按优先级分配 |
+| 预留 | Expedited 可预留 1 个驱动，保证高优先级 |
+
+### 4.2 队列模型
+
+```
+ ┌─────────────────────────────────┐
+ │ Recall 优先级队列 │
+ │ Expedited | Standard | Bulk │
+ └─────────────────────────────────┘
+ │
+ ┌───────────────────┼───────────────────┐
+ ▼ ▼ ▼
+ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐
+ │ 合并器 │ │ 合并器 │ │ 合并器 │
+ │ (按 tape 聚合) │ │ (按 tape 聚合) │ │ (按 tape 聚合) │
+ └───────┬───────┘ └───────┬───────┘ └───────┬───────┘
+ │ │ │
+ └───────────────────┼───────────────────┘
+ ▼
+ ┌─────────────────────────────────┐
+ │ 驱动调度器 │
+ │ Drive 1 | Drive 2 | Drive 3 │
+ └─────────────────────────────────┘
+```
+
+### 4.3 归档调度周期
+
+- **扫描周期**：`scan_interval_secs`（如 3600s）
+- **触发条件**：定时 + 可选事件触发（ColdPending 积累达阈值）
+- **并发**：多驱动时可并行执行多个 ArchiveTask，每个 Task 独占一驱动
+
+---
+
+## 5. 性能设计
+
+### 5.1 吞吐目标
+
+| 场景 | 目标 | 实现要点 |
+|------|------|----------|
+| 归档写入 | ≥ 300 MB/s | 块对齐、双缓冲、流式写入 |
+| 取回 | ≥ 1 任务/5 分钟 | 合并减少换带，多驱动并行 |
+
+### 5.2 性能优化
+
+| 手段 | 说明 |
+|------|------|
+| 块对齐 | 256KB 块，减少驱动内部碎片 |
+| 大缓冲 | 64–128MB 写入/读取缓冲 |
+| 预读 | 归档时预读下一批对象 |
+| 合并 | 取回时同磁带、同 archive 合并 |
+| 并行 | 多驱动时归档与取回可并行 |
+
+### 5.3 背压与限流
+
+- 归档：若热存储读取慢，可暂停新 Bundle 提交
+- 取回：队列满时拒绝新 Restore，返回 503
+- Expedited：可配置最大并发，超限返回 GlacierExpeditedRetrievalNotAvailable
+
+---
+
+## 6. 质量与可靠性
+
+### 6.1 数据完整性
+
+| 机制 | 说明 |
+|------|------|
+| 对象校验和 | 归档时写入 CRC32/SHA256，取回时校验 |
+| Bundle 校验和 | 可选，整 Bundle 校验 |
+| 写入后验证 | 可选，归档完成后读回校验（成本高） |
+
+### 6.2 失败与重试
+
+| 场景 | 策略 |
+|------|------|
+| 归档写入失败 | 重试 3 次，仍失败则标记 Bundle Failed，对象回退 ColdPending |
+| 取回读取失败 | 重试 2 次，仍失败则 RecallTask Failed，通知用户 |
+| 驱动故障 | 切换备用驱动，重新加载磁带 |
+| 磁带不可读 | 若有副本，切换副本；否则通知人工 |
+
+### 6.3 一致性（调度层统一协调）
+
+调度层作为元数据写入的唯一协调者，需保证以下写入顺序：
+
+**归档**：
+
+| 顺序 | 操作 | 失败处理 |
+|------|------|----------|
+| 1 | 磁带层顺序写入完成 | 重试/换带 |
+| 2 | **调度层 → 元数据层**：更新 ObjectMetadata、ArchiveBundle、TapeInfo | 重试/补偿任务 |
+
+**取回**：
+
+| 顺序 | 操作 | 失败处理 |
+|------|------|----------|
+| 1 | 磁带层读取完成 | 重试/切换副本 |
+| 2 | **调度层 → 缓存层**：put_restored | 重试/标记 Failed |
+| 3 | **调度层 → 元数据层**：restore_status=Completed | 重试；若持续失败，缓存有数据但 GET 不可用，需补偿 |
+
+> 缓存层和磁带层均为被编排方，不主动写元数据。
+
+---
+
+## 7. 离线磁带处理
+
+- 磁带状态：ONLINE / OFFLINE / UNKNOWN
+- 取回命中 OFFLINE 磁带：
+ 1. 生成通知事件（tape_id、槽位、archive_id、请求方）
+ 2. 任务进入等待队列，不占用驱动
+ 3. 人工加载磁带并确认 ONLINE 后，调度器自动重试
+- 合并：多个请求命中同一离线磁带时，合并为一次通知，加载后批量处理
+
+---
+
+## 8. 核心数据结构
+
+### 8.1 ArchiveScheduler
+
+```rust
+pub struct ArchiveScheduler {
+ metadata: Arc,
+ tape_manager: Arc,
+ config: ArchiveConfig,
+ running: AtomicBool,
+}
+```
+
+| 字段 | 类型 | 含义 | 说明 |
+|------|------|------|------|
+| `metadata` | Arc\ | 元数据客户端 | 扫描 ColdPending、写入 ArchiveBundle、更新 ObjectMetadata |
+| `tape_manager` | Arc\ | 磁带管理器 | 申请驱动、选磁带、顺序写入 |
+| `config` | ArchiveConfig | 归档配置 | 聚合参数、块大小、缓冲等 |
+| `running` | AtomicBool | 运行状态标记 | 优雅停止扫描循环 |
+
+### 8.2 RecallScheduler
+
+```rust
+pub struct RecallScheduler {
+ metadata: Arc,
+ tape_manager: Arc,
+ cache: Arc,
+ queue: RecallQueue,
+ config: RecallConfig,
+}
+```
+
+| 字段 | 类型 | 含义 | 说明 |
+|------|------|------|------|
+| `metadata` | Arc\ | 元数据客户端 | 读取 RecallTask、更新 restore_status |
+| `tape_manager` | Arc\ | 磁带管理器 | 申请驱动、加载磁带、定位读取 |
+| `cache` | Arc\ | 缓存写接口 | put_restored 写入解冻数据 |
+| `queue` | RecallQueue | 取回优先级队列 | 三级优先级 + 合并窗口 |
+| `config` | RecallConfig | 取回配置 | 队列大小、超时、合并窗口等 |
+
+### 8.3 ArchiveBundle（归档包）
+
+一批对象在磁带上的连续写入单元，是归档调度的基本粒度。
+
+```rust
+pub struct ArchiveBundle {
+ pub id: Uuid,
+ pub tape_id: String,
+ pub tape_set: Vec,
+ pub entries: Vec,
+ pub total_size: u64,
+ pub filemark_start: u32,
+ pub filemark_end: u32,
+ pub checksum: Option,
+ pub status: ArchiveBundleStatus,
+ pub created_at: DateTime,
+ pub completed_at: Option>,
+}
+```
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `id` | Uuid | 归档包唯一标识 | 全局唯一，元数据 CF `bundles` 的 key |
+| `tape_id` | String | 主副本所在磁带 ID | 取回时定位磁带 |
+| `tape_set` | Vec\ | 所有副本磁带 ID 列表 | 双副本场景：`["TAPE001", "TAPE002"]` |
+| `entries` | Vec\ | 包内对象列表（含偏移信息） | 取回时按 offset 定位单个对象 |
+| `total_size` | u64 | 包内所有对象总字节 | 选磁带时判断剩余空间 |
+| `filemark_start` | u32 | Bundle 起始 FileMark 编号 | 磁带 seek 时 `MTFSF(filemark_start)` 快速定位 |
+| `filemark_end` | u32 | Bundle 结束 FileMark 编号 | 标记 Bundle 边界 |
+| `checksum` | Option\ | 整个 Bundle 的 SHA256（可选） | 写入后可选验证 |
+| `status` | ArchiveBundleStatus | 状态 | `Pending` → `Writing` → `Completed` / `Failed` |
+| `created_at` | DateTime\ | 创建时间 | 聚合窗口计算 |
+| `completed_at` | Option\\> | 完成时间 | 审计与可观测性 |
+
+### 8.4 BundleEntry（Bundle 内单个对象条目）
+
+描述一个对象在 Bundle 内的物理位置，用于取回时精确定位。
+
+```rust
+pub struct BundleEntry {
+ pub bucket: String,
+ pub key: String,
+ pub version_id: Option,
+ pub size: u64,
+ pub offset_in_bundle: u64,
+ pub tape_block_offset: u64,
+ pub checksum: String,
+}
+```
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `bucket` | String | S3 桶名 | 与 key 唯一标识对象 |
+| `key` | String | S3 对象键 | 取回后写缓存、更新元数据时需要 |
+| `version_id` | Option\ | 对象版本 ID | 多版本场景 |
+| `size` | u64 | 对象原始字节数 | 读取时分配缓冲 |
+| `offset_in_bundle` | u64 | 对象在 Bundle 内的字节偏移 | 取回时计算磁带读取偏移 |
+| `tape_block_offset` | u64 | 对象在磁带上的块偏移（相对 FileMark） | `MTFSR(tape_block_offset)` 精确定位 |
+| `checksum` | String | SHA256 hex | 取回时校验数据完整性 |
+
+### 8.5 ObjectHeader（磁带上对象头）
+
+写入磁带时，每个对象前写入 Header，采用**定长前缀 + 变长 bucket/key** 的混合格式。解析时先读定长部分获取 `bucket_len`/`key_len`，再按长度读取变长字符串。
+
+> ObjectHeader 与 BundleEntry 存在冗余：BundleEntry 在元数据中记录同样信息。ObjectHeader 的作用是**磁带端自描述**——用于边界检测（magic）、取回时校验（checksum）、以及元数据丢失后的数据恢复。
+
+```rust
+pub struct ObjectHeader {
+ pub magic: [u8; 4],
+ pub version: u8,
+ pub bucket_len: u16,
+ pub bucket: String,
+ pub key_len: u16,
+ pub key: String,
+ pub size: u64,
+ pub checksum: [u8; 32],
+ pub flags: u8,
+ pub reserved: [u8; 16],
+}
+```
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `magic` | [u8; 4] | 魔数 `0x43 0x53 0x4F 0x48`（"CSOH"） | 标识 Header 起始，校验格式正确 |
+| `version` | u8 | Header 格式版本号 | 向前兼容，当前 `1` |
+| `bucket_len` | u16 | bucket 字符串字节长度 | 解析定位 |
+| `bucket` | String | S3 桶名 | 取回时还原对象归属 |
+| `key_len` | u16 | key 字符串字节长度 | 解析定位 |
+| `key` | String | S3 对象键 | 取回时还原对象标识 |
+| `size` | u64 | 对象数据字节数 | 取回时读取确切长度 |
+| `checksum` | [u8; 32] | SHA256 原始字节 | 取回时逐字节校验 |
+| `flags` | u8 | 标志位（bit 0: 压缩, bit 1: 加密） | 预留，当前全 0 |
+| `reserved` | [u8; 16] | 保留字段 | 未来扩展，写入时全 0 |
+
+### 8.6 ArchiveTask（归档任务）
+
+```rust
+pub struct ArchiveTask {
+ pub id: Uuid,
+ pub bundle_id: Uuid,
+ pub tape_id: String,
+ pub drive_id: Option,
+ pub object_count: u32,
+ pub total_size: u64,
+ pub bytes_written: u64,
+ pub status: ArchiveTaskStatus,
+ pub retry_count: u32,
+ pub created_at: DateTime,
+ pub started_at: Option>,
+ pub completed_at: Option>,
+ pub error: Option,
+}
+```
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `id` | Uuid | 任务唯一标识 | 元数据 CF `archive_tasks` 的 key |
+| `bundle_id` | Uuid | 关联的 ArchiveBundle ID | 追踪任务与 Bundle 的关系 |
+| `tape_id` | String | 目标磁带 ID | 记录写入的磁带 |
+| `drive_id` | Option\ | 分配的驱动 ID | 执行中才有值 |
+| `object_count` | u32 | 本次归档对象数 | 进度监控 |
+| `total_size` | u64 | 总字节数 | 进度百分比 = bytes_written / total_size |
+| `bytes_written` | u64 | 已写入字节数 | 进度追踪、断点续传参考 |
+| `status` | ArchiveTaskStatus | 任务状态 | `Pending` → `InProgress` → `Completed` / `Failed` |
+| `retry_count` | u32 | 已重试次数 | 超过 max_retries 则标记 Failed |
+| `created_at` | DateTime\ | 任务创建时间 | 审计 |
+| `started_at` | Option\\> | 开始执行时间 | 获取驱动后设置 |
+| `completed_at` | Option\\> | 完成时间 | 计算耗时 |
+| `error` | Option\ | 错误信息 | Failed 时记录原因 |
+
+### 8.7 RecallTask（取回任务）
+
+```rust
+pub struct RecallTask {
+ pub id: Uuid,
+ pub bucket: String,
+ pub key: String,
+ pub version_id: Option,
+ pub archive_id: Uuid,
+ pub tape_id: String,
+ pub tape_set: Vec,
+ pub tape_block_offset: u64,
+ pub object_size: u64,
+ pub checksum: String,
+ pub tier: RestoreTier,
+ pub days: u32,
+ pub expire_at: DateTime,
+ pub status: RestoreStatus,
+ pub drive_id: Option,
+ pub retry_count: u32,
+ pub created_at: DateTime,
+ pub started_at: Option>,
+ pub completed_at: Option>,
+ pub error: Option,
+}
+```
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `id` | Uuid | 任务唯一标识 | 元数据 CF `recall_tasks` 的 key |
+| `bucket` | String | S3 桶名 | 取回后写缓存、更新元数据 |
+| `key` | String | S3 对象键 | 与 bucket 唯一标识对象 |
+| `version_id` | Option\ | 对象版本 | 多版本场景 |
+| `archive_id` | Uuid | 所属 ArchiveBundle ID | 定位 BundleEntry 获取磁带偏移 |
+| `tape_id` | String | 主副本磁带 ID | 默认从此磁带读取 |
+| `tape_set` | Vec\ | 所有副本磁带列表 | 主磁带不可读时切换副本 |
+| `tape_block_offset` | u64 | 对象在磁带上的块偏移 | seek 定位 |
+| `object_size` | u64 | 对象字节数 | 读取时分配缓冲 |
+| `checksum` | String | SHA256 hex | 读取后校验完整性，写缓存时传入 |
+| `tier` | RestoreTier | 取回优先级 | `Expedited` / `Standard` / `Bulk`，影响队列排序 |
+| `days` | u32 | 解冻保留天数 | 计算 expire_at = now + days |
+| `expire_at` | DateTime\ | 解冻过期时间 | 写入缓存 xattr 和元数据 restore_expire_at |
+| `status` | RestoreStatus | 任务状态 | `Pending` → `InProgress` → `Completed` / `Failed` |
+| `drive_id` | Option\ | 分配的驱动 ID | 执行中才有值 |
+| `retry_count` | u32 | 已重试次数 | 超限则标记 Failed |
+| `created_at` | DateTime\ | 任务创建时间 | 排队顺序参考 |
+| `started_at` | Option\\> | 开始执行时间 | 计算 SLA |
+| `completed_at` | Option\\> | 完成时间 | 计算耗时 |
+| `error` | Option\ | 错误信息 | 失败原因 |
+
+### 8.8 RestoreTier（取回优先级）
+
+```rust
+pub enum RestoreTier {
+ Expedited,
+ Standard,
+ Bulk,
+}
+```
+
+| 值 | 含义 | 对应 SLA | 队列优先级 |
+|------|------|----------|-----------|
+| `Expedited` | 加急 | 1–5 分钟 | 最高，可预留驱动 |
+| `Standard` | 标准 | 3–5 小时 | 中 |
+| `Bulk` | 批量 | 5–12 小时 | 最低 |
+
+### 8.9 TapeReadJob（磁带读取作业）
+
+取回合并后的执行单元，一个 TapeReadJob = 一次换带 + 一次顺序读取。
+
+```rust
+pub struct TapeReadJob {
+ pub job_id: Uuid,
+ pub tape_id: String,
+ pub drive_id: Option,
+ pub segments: Vec,
+ pub total_objects: u32,
+ pub total_bytes: u64,
+ pub priority: RestoreTier,
+}
+```
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `job_id` | Uuid | 作业唯一标识 | 日志追踪 |
+| `tape_id` | String | 目标磁带 ID | 加载到驱动 |
+| `drive_id` | Option\ | 分配的驱动 | 执行时填入 |
+| `segments` | Vec\ | 按物理顺序排列的读取段列表 | 顺序执行，避免回退 seek |
+| `total_objects` | u32 | 本次作业对象总数 | 监控 |
+| `total_bytes` | u64 | 总字节数 | 监控 |
+| `priority` | RestoreTier | 作业优先级（取组内最高） | 驱动分配排序 |
+
+### 8.10 ReadSegment（读取段）
+
+```rust
+pub struct ReadSegment {
+ pub archive_id: Uuid,
+ pub filemark: u32,
+ pub objects: Vec,
+}
+```
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `archive_id` | Uuid | 所属 ArchiveBundle ID | 日志追踪 |
+| `filemark` | u32 | 该 Bundle 的起始 FileMark（来自 `ArchiveBundle.filemark_start`） | `MTFSF(filemark)` 定位 |
+| `objects` | Vec\ | 段内对象列表，按 tape_block_offset 升序 | 顺序读取 |
+
+### 8.11 ReadObject（待读取对象）
+
+```rust
+pub struct ReadObject {
+ pub recall_task_id: Uuid,
+ pub bucket: String,
+ pub key: String,
+ pub tape_block_offset: u64,
+ pub size: u64,
+ pub checksum: String,
+ pub expire_at: DateTime,
+}
+```
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `recall_task_id` | Uuid | 关联的 RecallTask ID | 完成后更新任务状态 |
+| `bucket` | String | S3 桶名 | 写缓存时传入 |
+| `key` | String | S3 对象键 | 写缓存时传入 |
+| `tape_block_offset` | u64 | 磁带上块偏移 | `MTFSR(offset)` 精确定位 |
+| `size` | u64 | 对象字节数 | 分配读取缓冲 |
+| `checksum` | String | SHA256 hex | 读取后校验 |
+| `expire_at` | DateTime\ | 解冻过期时间 | 写入缓存 xattr |
+
+### 8.12 TapeWriteJob（磁带写入作业）
+
+```rust
+pub struct TapeWriteJob {
+ pub job_id: Uuid,
+ pub bundle: ArchiveBundle,
+ pub tape_id: String,
+ pub drive_id: Option,
+ pub bytes_written: u64,
+ pub objects_written: u32,
+}
+```
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `job_id` | Uuid | 作业唯一标识 | 日志追踪 |
+| `bundle` | ArchiveBundle | 待写入的归档包 | 含完整对象列表和元数据 |
+| `tape_id` | String | 目标磁带 | 写入到此磁带 |
+| `drive_id` | Option\ | 分配的驱动 | 执行时填入 |
+| `bytes_written` | u64 | 已写字节 | 进度追踪 |
+| `objects_written` | u32 | 已写对象数 | 进度追踪 |
+
+### 8.13 RecallQueue（取回优先级队列）
+
+```rust
+pub struct RecallQueue {
+ expedited: VecDeque,
+ standard: VecDeque,
+ bulk: VecDeque,
+ pending_by_tape: HashMap>,
+ capacity: usize,
+}
+```
+
+| 字段 | 类型 | 含义 | 用途 |
+|------|------|------|------|
+| `expedited` | VecDeque\ | 加急队列 | 最高优先级，优先出队 |
+| `standard` | VecDeque\ | 标准队列 | 中等优先级 |
+| `bulk` | VecDeque\ | 批量队列 | 最低优先级 |
+| `pending_by_tape` | HashMap\\> | tape_id → 待处理 task_id 列表 | 合并时快速按磁带分组 |
+| `capacity` | usize | 队列总容量上限 | 超限拒绝新任务 |
+
+**pending_by_tape 维护规则**：
+- **入队**：将 task_id 加入 `pending_by_tape[tape_id]`
+- **出队/合并**：合并时从 `pending_by_tape` 按 tape 分组取出任务，结合优先级队列做排序
+- **完成/取消**：任务完成或取消后，从 `pending_by_tape` 中移除对应 task_id
+
+### 8.14 枚举汇总
+
+```rust
+pub enum ArchiveBundleStatus {
+ Pending, // 聚合完成，等待写入
+ Writing, // 正在写入磁带
+ Completed, // 写入成功
+ Failed, // 写入失败
+}
+
+pub enum ArchiveTaskStatus {
+ Pending, // 等待驱动
+ InProgress, // 执行中
+ Completed, // 完成
+ Failed, // 失败
+}
+
+pub enum RestoreStatus {
+ Pending, // 已入队，等待调度
+ WaitingForMedia, // 磁带离线，等待人工上线
+ InProgress, // 正在从磁带读取
+ Completed, // 已写入缓存+元数据
+ Expired, // 解冻过期（由定时任务或 GET 时检查 restore_expire_at 触发）
+ Failed, // 失败
+}
+```
+
+---
+
+## 9. 模块结构
+
+```
+src/scheduler/
+├── mod.rs
+├── archive/
+│ ├── mod.rs
+│ ├── aggregator.rs # 归档聚合逻辑
+│ ├── writer.rs # 顺序写入流水线
+│ └── task.rs # ArchiveTask 执行
+├── recall/
+│ ├── mod.rs
+│ ├── merger.rs # 取回合并逻辑
+│ ├── reader.rs # 顺序读取流水线
+│ └── task.rs # RecallTask 执行
+├── queue.rs # 优先级队列
+├── drive_allocator.rs # 驱动分配
+└── types.rs # TapeReadJob, ArchiveBundle 等
+```
+
+---
+
+## 10. 配置项
+
+```yaml
+scheduler:
+ archive:
+ scan_interval_secs: 3600
+ batch_size: 1000
+ min_archive_size_mb: 100
+ max_archive_size_mb: 10240
+ aggregation_window_secs: 3600
+ block_size: 262144
+ write_buffer_mb: 64
+ target_throughput_mbps: 300
+ recall:
+ queue_size: 10000
+ max_concurrent_restores: 10
+ restore_timeout_secs: 3600
+ min_restore_interval_secs: 300
+ merge_window_secs: 60
+ read_buffer_mb: 64
+ expedited_reserved_drives: 1
+ drive:
+ total_drives: 3
+ archive_drives: 2
+ recall_drives: 1
+```
+
+---
+
+## 11. 依赖关系
+
+**调度层主动依赖**：
+
+| 依赖 | 方向 | 协议 | 说明 |
+|------|------|------|------|
+| 元数据层 | Scheduler → Metadata | gRPC | **唯一的元数据业务读写入口** |
+| 缓存层 | Scheduler → Cache Worker | gRPC（同机） | 数据暂存/读取 |
+| 磁带层 | Scheduler → Tape Worker | gRPC（远程） | 磁带读写指令下发 |
+
+**被依赖**：
+
+| 被依赖方 | 协议 | 说明 |
+|----------|------|------|
+| Gateway | gRPC | **全部** S3 请求（PUT/GET/HEAD/DELETE/Restore/List） |
+
+> **架构要点**：Scheduler Worker 是唯一的业务中枢，同时持有 MetadataClient、
+> CacheClient(gRPC)、TapeClient(gRPC) 三个依赖。
+> Gateway 所有请求都发往 Scheduler，Gateway 不直连 Metadata/Cache/Tape。
+> 缓存层和磁带层均为纯功能组件，不感知元数据。
+
+---
+
+## 12. 实施要点
+
+- 归档与取回可独立扩缩容
+- 每个磁带驱动对应一条顺序 I/O 流水线，避免多任务共享同一驱动导致 seek
+- 增加驱动可线性提升并发归档与取回能力
+- 元数据需记录 `tape_block_offset`，供取回时按物理顺序排序
+- **调度层同时注入 MetadataClient + CacheWriteApi + TapeManager**，是系统中唯一的编排者
diff --git a/docs/modules/06-tape-layer.md b/docs/modules/06-tape-layer.md
new file mode 100644
index 0000000..82440a3
--- /dev/null
+++ b/docs/modules/06-tape-layer.md
@@ -0,0 +1,1012 @@
+# 磁带管理层模块设计
+
+> 所属架构：ColdStore 冷存储系统
+> 参考：[总架构设计](../DESIGN.md)
+
+## 1. 模块概述
+
+磁带管理层提供磁带设备与磁带库的完整管理能力，通过自研 SDK 抽象层实现与底层硬件的解耦，前期对接 Linux SCSI 协议。
+
+### 1.1 完整职责
+
+| 功能域 | 说明 |
+|--------|------|
+| 磁带驱动管理 | 驱动发现、状态监控、独占分配、释放 |
+| 磁带介质管理 | 介质注册、容量跟踪、格式化、可读性校验、生命周期 |
+| 磁带库管理 | 槽位管理、机械臂加载/卸载、盘点、条码扫描 |
+| 数据读写 | 顺序写入、顺序/定位读取、FileMark 管理 |
+| 离线磁带协同 | 状态跟踪、通知触发、人工确认流程 |
+| 可靠性 | 双副本、校验、错误处理、坏带替换 |
+| 可观测性 | 驱动利用率、读写吞吐、错误率、换带次数 |
+
+### 1.2 在架构中的位置
+
+```
+归档/取回调度器
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ 磁带管理层 │
+│ ┌────────────────────────────────────────────────────────────────┐ │
+│ │ TapeManager (上层 API，面向调度器) │ │
+│ │ - 驱动分配、磁带选择、介质跟踪、通知 │ │
+│ └────────────────────────────────────────────────────────────────┘ │
+│ │ │
+│ ┌────────────────────────┼────────────────────────┐ │
+│ │ │ │ │
+│ ▼ ▼ ▼ │
+│ ┌──────────┐ ┌───────────────┐ ┌────────────────────┐ │
+│ │ TapeDrive│ │ TapeMedia │ │ TapeLibrary │ │
+│ │ trait │ │ trait │ │ trait │ │
+│ │ (驱动) │ │ (介质) │ │ (带库/机械臂) │ │
+│ └──────────┘ └───────────────┘ └────────────────────┘ │
+│ │ │ │ │
+│ ┌────┴────────────────┴───────────────────────┴────┐ │
+│ │ 具体实现层 │ │
+│ │ ScsiTapeDrive | ScsiTapeMedia | ScsiTapeLibrary │ │
+│ │ (前期 Linux SCSI) │ │
+│ └──────────────────────────────────────────────────┘ │
+│ │ │
+│ ┌────┴─────────────────────────────────────────────┐ │
+│ │ 底层封装 │ │
+│ │ mtio.rs (MTIO ioctl) | sg.rs (SCSI Generic) │ │
+│ └──────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 2. 代码架构分层
+
+### 2.1 分层原则
+
+| 层级 | 职责 | 稳定性 |
+|------|------|--------|
+| **TapeManager** | 面向调度器的业务 API，编排驱动/介质/库 | 最稳定，不随硬件变化 |
+| **SDK 抽象层** (trait) | 定义 TapeDrive / TapeMedia / TapeLibrary 接口 | 稳定，接口不频繁变更 |
+| **实现层** | 具体硬件对接（SCSI、厂商 SDK） | 可替换，不影响上层 |
+| **底层封装** | ioctl / SCSI 命令封装 | 最底层，平台相关 |
+
+### 2.2 扩展策略
+
+- 新硬件后端：实现 TapeDrive / TapeMedia / TapeLibrary trait 即可
+- 上层调度器：仅依赖 TapeManager API，不感知底层实现
+- 配置切换：通过 `tape.sdk.backend` 配置选择实现
+
+---
+
+## 3. SDK 抽象层：trait 定义
+
+### 3.1 TapeDrive trait（磁带驱动）
+
+驱动是数据读写的执行单元，一次绑定一盘磁带。
+
+```rust
+/// 磁带驱动抽象 — 数据 I/O 的执行单元
+#[async_trait]
+pub trait TapeDrive: Send + Sync {
+ // ── 标识 ──
+ fn drive_id(&self) -> &str;
+ fn device_path(&self) -> &str;
+
+ // ── 数据读写 ──
+ async fn write_blocks(&self, data: &[u8]) -> Result;
+ async fn read_blocks(&self, buf: &mut [u8]) -> Result;
+
+ // ── 定位 ──
+ async fn seek_to_filemark(&self, count: i32) -> Result<()>;
+ async fn seek_to_record(&self, count: i32) -> Result<()>;
+ async fn seek_to_end_of_data(&self) -> Result<()>;
+ async fn rewind(&self) -> Result<()>;
+
+ // ── FileMark ──
+ async fn write_filemark(&self, count: u32) -> Result<()>;
+
+ // ── 状态 ──
+ async fn status(&self) -> Result;
+ async fn position(&self) -> Result;
+ async fn is_ready(&self) -> Result;
+
+ // ── 控制 ──
+ async fn eject(&self) -> Result<()>;
+ async fn set_block_size(&self, size: u32) -> Result<()>;
+ async fn set_compression(&self, enabled: bool) -> Result<()>;
+}
+```
+
+### 3.2 TapeMedia trait（磁带介质）
+
+介质管理覆盖单盘磁带的生命周期。
+
+```rust
+/// 磁带介质抽象 — 单盘磁带的元数据与生命周期
+#[async_trait]
+pub trait TapeMedia: Send + Sync {
+ // ── 标识 ──
+ fn media_id(&self) -> &str;
+ fn barcode(&self) -> Option<&str>;
+ fn format(&self) -> &str; // "LTO-9", "LTO-10"
+
+ // ── 容量 ──
+ async fn capacity(&self) -> Result;
+ async fn remaining(&self) -> Result;
+ async fn is_full(&self) -> Result;
+
+ // ── 状态 ──
+ fn status(&self) -> MediaStatus;
+ fn set_status(&mut self, status: MediaStatus);
+ fn location(&self) -> MediaLocation;
+ fn set_location(&mut self, location: MediaLocation);
+
+ // ── 生命周期 ──
+ async fn verify_readable(&self, drive: &dyn TapeDrive) -> Result;
+ async fn erase(&self, drive: &dyn TapeDrive) -> Result<()>;
+
+ // ── 元数据 ──
+ fn label(&self) -> Option<&str>;
+ async fn write_label(&self, drive: &dyn TapeDrive, label: &str) -> Result<()>;
+ fn archive_bundles(&self) -> &[Uuid];
+ fn add_archive_bundle(&mut self, bundle_id: Uuid);
+}
+```
+
+### 3.3 TapeLibrary trait（磁带库）
+
+带库管理覆盖机械臂、槽位、盘点等自动化操作。
+
+```rust
+/// 磁带库抽象 — 含机械臂的自动化磁带库
+#[async_trait]
+pub trait TapeLibrary: Send + Sync {
+ fn library_id(&self) -> &str;
+
+ // ── 槽位管理 ──
+ async fn list_slots(&self) -> Result>;
+ async fn list_drives(&self) -> Result>;
+
+ // ── 机械臂操作 ──
+ // drive_element 为 SCSI Data Transfer Element Address（u32）
+ // TapeManager 负责将字符串 drive_id 映射为 SCSI element address
+ async fn load(&self, slot_id: u32, drive_element: u32) -> Result<()>;
+ async fn unload(&self, drive_element: u32, slot_id: u32) -> Result<()>;
+ async fn transfer(&self, from_slot: u32, to_slot: u32) -> Result<()>;
+
+ // ── 盘点 ──
+ async fn inventory(&self) -> Result;
+
+ // ── 导入/导出 ──
+ async fn list_import_export_slots(&self) -> Result>;
+
+ // ── 状态 ──
+ async fn status(&self) -> Result;
+}
+```
+
+### 3.4 类型定义与字段说明
+
+#### 3.4.1 DriveStatus（驱动状态）
+
+```rust
+pub struct DriveStatus {
+ pub drive_id: String,
+ pub is_ready: bool,
+ pub has_media: bool,
+ pub media_id: Option,
+ pub block_size: u32,
+ pub compression: bool,
+ pub write_protected: bool,
+ pub error: Option,
+}
+```
+
+| 字段 | 类型 | 含义 | 来源 |
+|------|------|------|------|
+| `drive_id` | String | 驱动唯一标识 | 配置文件定义 |
+| `is_ready` | bool | 驱动是否就绪可执行 I/O | MTIOCGET 解析 |
+| `has_media` | bool | 是否已装载磁带 | MTIOCGET `GMT_DR_OPEN` 取反 |
+| `media_id` | Option\