markbase/docs/HYBRID_IMPLEMENTATION_GUIDE.md

SQLite + Sled 混合架构实施指南

实施日期： 2026-05-29
实施目标： 6天POC实施 + 生产部署评估

---

实施路线图

Phase 1: 基础架构 (Day 1-2)

Day 1: HybridRouter 实现
├── HybridRouter基础框架
├── 数据路由逻辑
└── 基础查询API

Day 2: 缓存机制实现
├── metadata_cache Tree
├── 缓存查询逻辑
└── 缓存失效机制

Phase 2: 数据同步 (Day 3-4)

Day 3: 双写机制实现
├── 双写同步逻辑
├── 一致性检查
└── 自动修复机制

Day 4: 缓存优化实现
├── hot_files_cache Tree
├── LRU淘汰机制
└── TTL过期清理

Phase 3: 性能验证 (Day 5-6)

Day 5: 性能测试
├── 混合架构性能测试
├── 缓存命中率测试
└── 并发性能测试

Day 6: 优化调优
├── 缓存配置优化
├── 并发配置优化
└── 性能对比验证

---

核心代码框架

HybridRouter 核心

pub struct HybridRouter {
    sqlite_conn: Connection,
    sled_db: sled::Db,
}

impl HybridRouter {
    pub fn route_query(&self, query_type: QueryType) -> DatabaseType {
        match query_type {
            // SQL查询 → SQLite
            QueryType::ParentChildren => DatabaseType::SQLite,
            QueryType::FileUuidJoin => DatabaseType::SQLite,
            QueryType::WhereFilter => DatabaseType::SQLite,
            
            // KV查询 → Sled
            QueryType::ContentHashLookup => DatabaseType::Sled,
            QueryType::HotFileCache => DatabaseType::Sled,
            QueryType::MetadataCache => DatabaseType::Sled,
            
            // 混合查询 → 优先缓存
            QueryType::NodeLookup => DatabaseType::Hybrid,
        }
    }
    
    pub fn get_node(&self, node_id: &str) -> Result<Option<FileNode>> {
        // 混合策略：
        // 1. Check Sled cache (fast)
        // 2. If not found, query SQLite (slow)
        // 3. Update Sled cache
        
        let cache_tree = self.sled_db.open_tree("metadata_cache")?;
        
        // Step 1: Check cache
        if let Some(cache_data) = cache_tree.get(node_id.as_bytes())? {
            let cache: CachedMetadata = serde_json::from_slice(&cache_data)?;
            if cache.ttl > 0 {
                return Ok(Some(cache.to_file_node()));
            }
        }
        
        // Step 2: Query SQLite
        let node = self.sqlite_query_node(node_id)?;
        
        // Step 3: Update cache
        if let Some(n) = &node {
            let cache = CachedMetadata::from_node(n);
            cache_tree.insert(node_id.as_bytes(), serde_json::to_vec(&cache)?)?;
        }
        
        Ok(node)
    }
}

---

快速启动命令

POC 测试

# 1. 创建混合架构模块
mkdir -p filetree-hybrid/src

# 2. 编译运行
cargo build --release --package filetree-hybrid
cargo run --release --bin hybrid-poc-test

# 3. 性能对比测试
cargo run --release --bin hybrid-benchmark

---

监控指标

缓存命中率目标

Target Cache Hit Rate:
┌─────────────────────────────────┐
│  Level 5: FUSE hot path         │ → 95%+ hit rate
│  Level 4: Frequently accessed   │ → 90%+ hit rate
│  Level 3: Normal accessed       │ → 80%+ hit rate
│  Level 2: Rarely accessed       │ → 60%+ hit rate
│  Level 1: Cold files            │ → 40%+ hit rate
│  Level 0: Archive files         │ → 20%+ hit rate
└─────────────────────────────────┘

Overall Target: 85%+ cache hit rate

性能目标

Performance Targets:
├── Query latency: <1ms (cache hit) / <5ms (cache miss)
├── Import throughput: >100K/sec (Sled batch)
├── Concurrent reads: >1M/sec (Sled MVCC)
└── Cache hit rate: >85%

---

部署决策矩阵

触发条件	当前状态	阈值	决策
并发用户	1-3	>10	开始POC
导入吞吐	14K/sec	>50K/sec	开始POC
查询延迟	<1ms	>10ms	开始优化
缓存需求	无	>80%命中率	开始POC

---

一句话总结

6天POC实施，保留SQLite SQL优势 + 利用Sled性能优势，达到85%+缓存命中率。