markbase/docs/DATABASE_DECISION.md

# MDC 数据库决策总结

**决策日期：** 2026-05-29  
**决策依据：** DATABASE_EVALUATION.md 深度评估报告

---

## 决策结论

### ✅ 立即行动：保持 SQLite + 优化

**理由：**
1. 功能完全匹配 MarkBase 需求 (95/100)
2. 性能足够满足当前规模 (14,243 nodes/sec)
3. 迁移成本最低 (4天优化 vs 13天 RocksDB迁移)
4. 运维成本最低 (零配置，无专业知识要求)

### 📊 核心数据对比

| 关键指标 | SQLite | RocksDB | Sled |
|----------|--------|---------|------|
| **当前适用性** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
| **导入速度** | 14,243/sec | 50,000+/sec | 30,000/sec |
| **查询延迟** | <1ms | <5ms | <2ms |
| **并发写入** | ❌ 单writer | ✅ 多writer | ✅ 多writer |
| **迁移成本** | 0天 | 13天 | 8天 |

### 🚀 优化计划 (本周执行)

**Day 1: WAL Mode + 索引**
```sql
PRAGMA journal_mode=WAL;
PRAGMA synchronous=NORMAL;
PRAGMA cache_size=10000;
CREATE INDEX idx_parent_id ON file_nodes(parent_id);
CREATE INDEX idx_sha256 ON file_nodes(sha256);
```

**Day 2: 连接池**
```rust
// Cargo.toml
r2d2 = "0.8"
r2d2_sqlite = "0.22"

// 使用
let pool = r2d2::Pool::new(manager)?;
let conn = pool.get()?;
```

**Day 3: 批量插入优化**
```rust
let tx = conn.transaction()?;
for chunk in nodes.chunks(1000) {
    for node in chunk {
        stmt.execute(params![...])?;
    }
}
tx.commit()?;
```

**Day 4: 性能测试**
```bash
cargo test --release
cargo bench
```

---

## 未来决策触发点

### 🔍 评估条件 (6个月后)

**触发 RocksDB/Sharding 评估的条件：**

| 条件 | 当前状态 | 触发阈值 | 行动 |
|------|----------|----------|------|
| **数据规模** | 13MB (12K nodes) | > 100GB | 评估 Sharding |
| **并发用户** | 1-3 users | > 10 users | 评估 RocksDB |
| **写入吞吐** | 14K/sec | > 50K/sec | 评估 RocksDB |
| **查询延迟** | <1ms | > 10ms | 优化索引 |

### 📈 混合架构蓝图 (12+ months)

```
MarkBase Hybrid Architecture:
┌─────────────────────────────────┐
│  Metadata Layer (SQLite)        │ ← 复杂查询
│  - file_nodes, file_registry    │
│  - user_auth, sync_log          │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│  Content Layer (RocksDB/Sled)   │ ← 高并发读写
│  - file_content_hash → path     │
│  - file_metadata_hash → meta    │
└─────────────────────────────────┘
         ↓
┌─────────────────────────────────┐
│  Cache Layer (Redis/Sled)       │ ← FUSE hot path
│  - hot_files_cache              │
│  - LRU eviction                 │
└─────────────────────────────────┘
```

---

## 技术风险

### SQLite 限制

**已知限制：**
- ❌ 单点写入 (WAL mode)
- ❌ 扩展性差 (无法分布式)
- ❌ 大文件性能下降 (>100GB)
- ❌ Schema 变更代价高

**缓解措施：**
- ✅ 用户分库 (Sharding)
- ✅ WAL mode (并发读取)
- ✅ 监控告警 (提前预警)
- ✅ 定期归档 (清理历史数据)

### RocksDB 风险

**已知风险：**
- ⚠️ 配置复杂 (200+ 参数)
- ⚠️ Compaction 开销 (CPU/IO密集)
- ⚠️ 学习曲线陡 (LSM-Tree原理)
- ⚠️ Rust绑定不稳定 (版本更新慢)

**缓解措施：**
- ✅ 使用默认配置 (先跑起来)
- ✅ SSD 存储 (避免 HDD seek)
- ✅ 团队培训 (学习 LSM-Tree)
- ✅ 监控 Compaction (调整策略)

---

## 成本估算

### SQLite 优化成本

| 项目 | 工作量 | 风险 | 收益 |
|------|--------|------|------|
| WAL Mode | 1天 | 低 | 读取并发提升 |
| 索引优化 | 1天 | 低 | 查询速度提升 |
| 连接池 | 1天 | 低 | 并发处理提升 |
| 批量插入 | 1天 | 低 | 导入速度提升 |
| **总计** | **4天** | **低** | **性能提升50%** |

### RocksDB 迁移成本

| 项目 | 工作量 | 风险 | 收益 |
|------|--------|------|------|
| Schema设计 | 2天 | 中 | 数据模型重构 |
| 数据导出 | 1天 | 低 | 数据迁移准备 |
| 数据导入 | 2天 | 中 | 数据迁移执行 |
| 代码重写 | 5天 | 高 | API适配 |
| 测试验证 | 3天 | 中 | 功能验证 |
| **总计** | **13天** | **高** | **并发写入支持** |

### 投资回报分析

**SQLite 优化 ROI:**
- 投入：4天开发时间
- 收益：性能提升50%，零风险
- ROI：立即见效，持续受益

**RocksDB 迁移 ROI:**
- 投入：13天开发时间 + 高风险
- 收益：并发写入支持，压缩节省空间
- ROI：长期受益，短期高成本

---

## 行动计划

### 本周任务 (2026-05-29 ~ 2026-06-04)

**周一：WAL Mode**
- [ ] 修改 `filetree/mod.rs:init_user_db()`
- [ ] 添加 PRAGMA 设置
- [ ] 测试并发读取

**周二：索引优化**
- [ ] 添加 `idx_parent_id`
- [ ] 添加 `idx_sha256`
- [ ] 测试查询速度

**周三：连接池**
- [ ] 添加 `r2d2` 依赖
- [ ] 实现连接池管理
- [ ] 测试并发连接

**周四：批量插入**
- [ ] 修改 `scan.rs:insert_nodes()`
- [ ] 实现批量事务
- [ ] 测试导入速度

**周五：性能测试**
- [ ] 运行所有测试
- [ ] 性能基准测试
- [ ] 生成测试报告

---

## 监控指标

### 关键监控指标

**性能指标：**
```rust
pub struct DbMetrics {
    pub query_latency_avg: f64,     // 平均查询延迟 (目标: <1ms)
    pub write_throughput: u64,      // 写入吞吐 (目标: >14K/sec)
    pub db_size: u64,               // 数据库大小 (阈值: <100GB)
    pub connection_count: u32,      // 连接数 (阈值: <100)
}
```

**告警规则：**
```
if db_size > 100GB → 建议评估 Sharding
if query_latency > 10ms → 建议优化索引
if concurrent_users > 10 → 建议评估 RocksDB
if write_throughput < 10K/sec → 建议批量优化
```

---

## 总结

**核心决策：保持 SQLite + 优化**

**关键理由：**
1. ✅ 功能完全匹配
2. ✅ 性能足够满足
3. ✅ 成本最低 (4天 vs 13天)
4. ✅ 风险最低 (优化 vs 重构)

**未来路径：**
- 6个月后评估 Sharding
- 12个月后评估混合架构
- 持续监控，按需调整

---

**决策确认：** ✅ SQLite Optimization Path  
**执行负责人：** Warren  
**执行日期：** 2026-05-29 ~ 2026-06-04