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 + 索引

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: 连接池

// Cargo.toml
r2d2 = "0.8"
r2d2_sqlite = "0.22"

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

Day 3: 批量插入优化

let tx = conn.transaction()?;
for chunk in nodes.chunks(1000) {
    for node in chunk {
        stmt.execute(params![...])?;
    }
}
tx.commit()?;

Day 4: 性能测试

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()
• 实现批量事务
• 测试导入速度

周五：性能测试

• 运行所有测试
• 性能基准测试
• 生成测试报告

---

监控指标

关键监控指标

性能指标：

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