{"id":31274096,"url":"https://github.com/0ldm0s/melange_db","last_synced_at":"2026-01-20T17:36:45.057Z","repository":{"id":315001354,"uuid":"1057658137","full_name":"0ldm0s/melange_db","owner":"0ldm0s","description":"基于 sled 架构深度优化的下一代高性能嵌入式数据库","archived":false,"fork":false,"pushed_at":"2025-09-16T04:35:43.000Z","size":146,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-09-16T06:27:47.570Z","etag":null,"topics":["arm64","b-plus-tree","bloom-filter","cache","caching-layer","concurrent-programming","database","edge-computing","embedded-database","iot-database","key-value-store","low-latency","memory-management","performance","real-time-database","rust","simd","sled","storage-engine"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0ldm0s.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-16T03:23:31.000Z","updated_at":"2025-09-16T04:35:46.000Z","dependencies_parsed_at":"2025-09-16T06:27:54.734Z","dependency_job_id":"3d38f097-bd6a-4a35-8033-3d5b75f4cd62","html_url":"https://github.com/0ldm0s/melange_db","commit_stats":null,"previous_names":["0ldm0s/melange_db"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/0ldm0s/melange_db","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0ldm0s%2Fmelange_db","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0ldm0s%2Fmelange_db/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0ldm0s%2Fmelange_db/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0ldm0s%2Fmelange_db/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0ldm0s","download_url":"https://codeload.github.com/0ldm0s/melange_db/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0ldm0s%2Fmelange_db/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276662038,"owners_count":25682025,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-23T02:00:09.130Z","response_time":73,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arm64","b-plus-tree","bloom-filter","cache","caching-layer","concurrent-programming","database","edge-computing","embedded-database","iot-database","key-value-store","low-latency","memory-management","performance","real-time-database","rust","simd","sled","storage-engine"],"created_at":"2025-09-23T22:36:11.388Z","updated_at":"2026-01-20T17:36:45.047Z","avatar_url":"https://github.com/0ldm0s.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Melange DB 🪐\n\n\u003e 基于 sled 架构深度优化的下一代高性能嵌入式数据库\n\n[![Crates.io](https://img.shields.io/crates/v/melange_db.svg)](https://crates.io/crates/melange_db)\n[![Documentation](https://docs.rs/melange_db/badge.svg)](https://docs.rs/melange_db)\n[![License](https://img.shields.io/badge/license-LGPLv3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0.en.html)\n\n## 🌍 语言版本\n- [中文版](README.md) | [English](README_en.md) | [日本語版](README_ja.md)\n\n## 项目简介\n\nMelange DB 是一个基于 sled 架构进行深度性能优化的嵌入式数据库，专注于超越 RocksDB 的性能表现。通过 SIMD 指令优化、智能缓存系统和布隆过滤器等技术，实现极致的读写性能。\n\n### 🎭 创意来源\n\n项目名称和设计理念深受弗兰克·赫伯特的经典科幻小说《沙丘》(Dune) 启发：\n\n- **Melange (美琅脂)**: 沙丘宇宙中最珍贵的物质，是宇宙航行的关键，象征着数据的珍贵和价值\n- **恐惧是思维杀手**: 正如沙丘中的经典台词 \"I must not fear. Fear is the mind-killer\"，我们的设计哲学是消除对性能的恐惧，追求极致优化\n- **香料之路**: 如同沙丘中的香料运输路线，Melange DB 构建了高效的数据流和存储路径\n- **弗雷曼人精神**: 沙漠中的生存专家，代表着在资源受限环境下的极致性能优化\n\n这种灵感来源反映了我们对数据库设计的核心理念：**在有限的资源中创造无限的价值**。\n\n## 核心特性\n\n### 🚀 极致性能优化\n- **SIMD 优化的 Key 比较**: 基于 ARM64 NEON 指令集的高性能比较\n- **多级块缓存系统**: 热/温/冷三级缓存，LRU 淘汰策略\n- **智能布隆过滤器**: 1% 误判率，快速过滤不存在查询\n- **预取机制**: 智能预取算法提升顺序访问性能\n\n### 🔒 并发安全\n- **无锁数据结构**: 基于 concurrent-map 的高并发设计\n- **线程安全**: 完全的 Send + Sync trait 实现\n- **原子性保证**: ACID 兼容的事务支持\n\n### 🔥 原子操作统一架构 (重大性能升级)\n\n\u003e **版本 v0.2.0**: 引入了全新的原子操作统一架构，彻底解决了高并发场景下的 EBR 冲突问题。\n\n#### 🚀 破坏性升级说明\n\n**这是一个破坏性的性能升级**，包含以下重大改进：\n\n✅ **解决的问题**:\n- **EBR RefCell 冲突**: 彻底解决了多线程高并发操作时的 `RefCell already borrowed` panic\n- **数据竞争**: 消除了原子操作和数据库操作之间的竞争条件\n- **性能瓶颈**: 通过 Worker 间通信大幅提升并发性能\n\n⚠️ **API 变更**:\n- `atomic_operations_manager::AtomicOperationsManager` - 全新统一路由器设计\n- `atomic_worker::AtomicWorker` - 重构为完全独立的原子操作组件\n- `database_worker::DatabaseWorker` - 新增专用数据库操作 Worker\n\n#### 🏗️ 新架构设计\n\n**SegQueue 统一架构**:\n```\nAtomicOperationsManager (纯路由器)\n    ├── SegQueue A ↔ AtomicWorker (DashMap + AtomicU64)\n    │   └── 自动发送持久化指令 → DatabaseWorker队列\n    └── SegQueue B ↔ DatabaseWorker (所有数据库操作)\n```\n\n#### ✅ 核心优势\n\n1. **完全解耦**:\n   - AtomicOperationsManager 只负责路由，不操作任何数据结构\n   - AtomicWorker 专门处理原子操作，不直接访问数据库\n   - DatabaseWorker 专门处理所有数据库操作\n\n2. **Worker间通信**:\n   - AtomicWorker 完成操作后自动向 DatabaseWorker 发送持久化指令\n   - 完全避免了同一线程中的 EBR 冲突\n\n3. **统一使用 SegQueue**:\n   - 所有 Worker 都使用相同的并发队列机制\n   - 与现有架构保持一致性\n\n#### 📊 性能验证\n\n**12线程高压力测试结果**:\n- ✅ **285次原子操作**: 160 + 50 + 40 + 35次页面访问\n- ✅ **570条数据库记录**: 300 + 150 + 120条\n- ✅ **零 EBR 冲突**: 12线程同时运行完全安全\n- ✅ **100%数据一致性**: 所有计数器和记录数据完全准确\n\n#### 🚀 快速开始\n\n想要快速上手 Melange DB？请查看以下最新的示例文件：\n\n**混合管理器架构（推荐）**：\n- `cargo run --example hybrid_manager_guide` - 完整使用教程\n- `cargo run --example hybrid_best_practices` - 生产环境最佳实践\n\n**性能测试**：\n- `cargo run --example high_pressure_segqueue_test` - 高并发压力测试\n- `cargo run --example performance_demo` - 基础性能演示\n\n所有示例文件都包含详细的代码注释和使用说明，确保您能够快速理解和使用 Melange DB。\n\n#### 🧪 测试用例\n\n```bash\n# 高压力并发测试 (12线程)\ncargo run --example high_pressure_segqueue_test\n\n# 混合管理器最佳实践\ncargo run --example hybrid_best_practices\n\n# 混合管理器使用指南\ncargo run --example hybrid_manager_guide\n```\n\n#### 🔄 迁移指南\n\n**旧版本 (v0.1.4 及以下)**:\n```rust\n// ❌ 已废弃 - 会产生EBR冲突\nlet db = Arc::new(config.open()?);\n// 多线程直接操作db会导致RefCell冲突\n```\n\n**新版本 (v0.2.0+)**:\n```rust\n// ✅ 推荐使用 - 无EBR冲突\nlet manager = Arc::new(AtomicOperationsManager::new(Arc::new(config.open()?)));\n// 通过统一路由器操作，完全线程安全\n```\n\n📖 **详细迁移指南**: 查看 [docs/migration_guide_v0.2.0.md](docs/migration_guide_v0.2.0.md) 获取完整的升级步骤和故障排除指南。\n\n#### ⚡ 性能提升\n\n- **并发安全**: 支持任意数量的并发线程\n- **零冲突**: 彻底消除 EBR RefCell 借用问题\n- **自动持久化**: 原子操作完成后自动持久化\n- **数据一致性**: 保证高并发下的数据完整性\n\n### 📦 高效内存管理\n- **增量序列化**: 减少 IO 开销的序列化策略\n- **智能缓存策略**: 自适应缓存替换算法\n- **内存映射优化**: 高效的文件映射机制\n\n## 快速开始\n\n### 📚 学习路径\n\n**新用户推荐学习顺序**：\n\n1. **入门教程**: `cargo run --example hybrid_manager_guide`\n   - 学习混合管理器的基本使用\n   - 了解原子操作和数据库操作的统一接口\n   - 掌握数据持久化和计数器使用\n\n2. **最佳实践**: `cargo run --example hybrid_best_practices`\n   - 学习生产环境的最佳实践\n   - 掌握用户管理、会话处理等实际场景\n   - 了解性能优化和错误处理\n\n3. **性能测试**: `cargo run --example performance_demo`\n   - 了解Melange DB的性能特性\n   - 学习缓存配置和flush策略\n   - 掌握性能监控方法\n\n4. **高级功能**: `cargo run --example rat_logger_demo`\n   - 学习日志系统集成\n   - 了解调试和监控方法\n\n所有示例文件都是完整可运行的程序，包含详细的中文注释，帮助您快速掌握 Melange DB 的各种功能。\n\n### 🔥 可用示例概览\n\n**混合管理器架构（推荐）**：\n- `cargo run --example hybrid_manager_guide` - 完整使用教程和API介绍\n- `cargo run --example hybrid_best_practices` - 生产环境最佳实践\n- `cargo run --example high_pressure_segqueue_test` - 12线程高并发压力测试\n\n**性能测试和分析**：\n- `cargo run --example performance_demo` - 基础性能演示\n- `cargo run --example accurate_timing_demo` - 精确计时分析（P50/P95/P99）\n- `cargo run --example best_practices` - 传统API最佳实践\n\n**系统集成**：\n- `cargo run --example rat_logger_demo` - 日志系统集成\n- `cargo run --example no_logger_test` - 无日志环境测试\n\n**平台性能测试**：\n- `cargo run --example macbook_air_m1_compression_none --features compression-none --release`\n- `cargo run --example macbook_air_m1_compression_lz4 --features compression-lz4 --release`\n- `cargo run --example macbook_air_m1_compression_zstd --features compression-zstd --release`\n\n### 📊 性能和功能测试\n- **性能基准测试**: `cargo run --example performance_demo`\n  - 基本性能演示和智能flush策略展示\n  - 包含读写性能统计和缓存命中率分析\n\n- **精确计时分析**: `cargo run --example accurate_timing_demo`\n  - 详细的性能分析，包含P50/P95/P99统计\n  - 展示不同操作类型的延迟分布\n\n- **最佳实践演示**: `cargo run --example best_practices`\n  - 完整的生产环境使用示例\n  - 包含用户数据管理、会话处理、事务操作等\n\n- **日志系统集成**: `cargo run --example rat_logger_demo`\n  - 展示如何集成rat_logger高性能日志系统\n  - 演示日志配置和性能调试输出\n\n- **无日志测试**: `cargo run --example no_logger_test`\n  - 验证未初始化日志时的安全行为\n  - 展示库的向后兼容性\n\n### 🖥️ 平台性能测试\n- **M1 MacBook Air性能测试**:\n  ```bash\n  # 无压缩版本（最佳性能）\n  cargo run --example macbook_air_m1_compression_none --features compression-none --release\n\n  # LZ4压缩版本（平衡性能）\n  cargo run --example macbook_air_m1_compression_lz4 --features compression-lz4 --release\n\n  # Zstd压缩版本（高压缩率）\n  cargo run --example macbook_air_m1_compression_zstd --features compression-zstd --release\n  ```\n\n### 🔄 迁移建议\n\n**推荐使用最新的混合管理器架构**:\n```bash\n# 学习基础使用\ncargo run --example hybrid_manager_guide\n\n# 生产环境参考\ncargo run --example hybrid_best_practices\n\n# 性能压力测试\ncargo run --example high_pressure_segqueue_test\n```\n\n### 压缩配置\n\nMelange DB 支持通过编译时特性选择压缩算法，以适应不同的性能需求：\n\n#### 无压缩模式（默认，最佳性能）\n```rust\nuse melange_db::{Db, Config, CompressionAlgorithm};\n\nfn main() -\u003e anyhow::Result\u003c()\u003e {\n    // 无压缩配置 - 追求极致性能\n    let config = Config::new()\n        .path(\"/path/to/database\")\n        .compression_algorithm(CompressionAlgorithm::None)  // 无压缩\n        .cache_capacity_bytes(512 * 1024 * 1024); // 512MB 缓存\n\n    let db: Db\u003c1024\u003e = config.open()?;\n\n    // 读写操作将获得最佳性能，无压缩开销\n    let tree = db.open_tree(\"high_performance_tree\")?;\n    tree.insert(b\"key\", b\"value\")?;\n\n    Ok(())\n}\n```\n\n#### LZ4压缩模式（平衡性能与压缩率）\n```rust\nuse melange_db::{Db, Config, CompressionAlgorithm};\n\nfn main() -\u003e anyhow::Result\u003c()\u003e {\n    // LZ4压缩配置 - 平衡性能和存储效率\n    let config = Config::new()\n        .path(\"/path/to/database\")\n        .compression_algorithm(CompressionAlgorithm::Lz4)  // LZ4压缩\n        .cache_capacity_bytes(512 * 1024 * 1024); // 512MB 缓存\n\n    let db: Db\u003c1024\u003e = config.open()?;\n\n    // 获得良好的压缩率，同时保持较高性能\n    let tree = db.open_tree(\"balanced_tree\")?;\n    tree.insert(b\"key\", b\"value\")?;\n\n    Ok(())\n}\n```\n\n#### Zstd压缩模式（高压缩率）\n```rust\nuse melange_db::{Db, Config, CompressionAlgorithm};\n\nfn main() -\u003e anyhow::Result\u003c()\u003e {\n    // Zstd压缩配置 - 追求最大压缩率\n    let config = Config::new()\n        .path(\"/path/to/database\")\n        .compression_algorithm(CompressionAlgorithm::Zstd)  // Zstd压缩\n        .cache_capacity_bytes(512 * 1024 * 1024); // 512MB 缓存\n\n    let db: Db\u003c1024\u003e = config.open()?;\n\n    // 获得最高的压缩率，适合存储受限场景\n    let tree = db.open_tree(\"storage_efficient_tree\")?;\n    tree.insert(b\"key\", b\"value\")?;\n\n    Ok(())\n}\n```\n\n#### 特性选择和验证\n```rust\nuse melange_db::config::CompressionAlgorithm;\n\nfn main() -\u003e anyhow::Result\u003c()\u003e {\n    // 检查启用的压缩特性\n    let features = CompressionAlgorithm::detect_enabled_features();\n    println!(\"启用的压缩特性: {:?}\", features);\n\n    // 验证特性配置\n    if let Some(warning) = CompressionAlgorithm::validate_feature_config() {\n        println!(\"警告: {}\", warning);\n    }\n\n    // 获取实际使用的算法\n    let (algorithm, reason) = CompressionAlgorithm::get_active_algorithm_with_reason();\n    println!(\"使用压缩算法: {:?}, 原因: {}\", algorithm, reason);\n\n    Ok(())\n}\n```\n\n### 最佳实践配置\n\n```rust\nuse melange_db::{Db, Config};\n\nfn main() -\u003e anyhow::Result\u003c()\u003e {\n    // 生产环境推荐配置\n    let mut config = Config::new()\n        .path(\"/path/to/database\")\n        .cache_capacity_bytes(1024 * 1024 * 1024) // 1GB 缓存\n        .flush_every_ms(Some(1000)); // 1秒 flush 间隔\n\n    // 启用智能 flush 策略\n    config.smart_flush_config.enabled = true;\n    config.smart_flush_config.base_interval_ms = 1000;\n    config.smart_flush_config.min_interval_ms = 100;\n    config.smart_flush_config.max_interval_ms = 5000;\n    config.smart_flush_config.write_rate_threshold = 5000;\n    config.smart_flush_config.accumulated_bytes_threshold = 8 * 1024 * 1024; // 8MB\n\n    let db: Db\u003c1024\u003e = config.open()?;\n\n    // 使用有意义的树名\n    let users_tree = db.open_tree(\"users\")?;\n    let sessions_tree = db.open_tree(\"sessions\")?;\n\n    Ok(())\n}\n```\n\n## 示例代码\n\n我们提供了多个示例来帮助您更好地使用 Melange DB：\n\n### 📊 性能测试示例\n- **`performance_demo.rs`** - 基本性能演示和智能 flush 策略展示\n- **`accurate_timing_demo.rs`** - 精确计时分析，包含 P50/P95/P99 统计\n\n### 🎯 最佳实践示例\n- **`best_practices.rs`** - 完整的生产环境使用示例，包含：\n  - 用户数据管理\n  - 会话处理\n  - 事务操作\n  - 批量插入\n  - 范围查询\n  - 数据清理\n\n### 📝 日志系统集成示例\n- **`rat_logger_demo.rs`** - 展示如何集成 rat_logger 日志系统：\n  - 日志初始化配置\n  - 性能调试输出\n  - 由调用者控制日志行为\n\n### ⚠️ 重要说明\n\n**示例代码优化目标**: 当前示例主要针对 Apple M1 等高端 ARM64 设备优化，配置了较大的缓存（1GB）和适用于高性能场景的参数。\n\n**低端设备优化建议**: 如果您需要在 Intel Celeron J1800 等低端 x86 设备上运行，请参考：\n- **测试文件**: `tests/low_end_x86_perf_test.rs`\n- **专用配置**: 针对 2GB 内存和 SSE2 指令集优化\n- **性能目标**: 写入 9-15 µs/条，读取 2-5 µs/条\n\n### 运行示例\n\n```bash\n# 运行基本性能演示\ncargo run --example performance_demo\n\n# 运行精确计时分析\ncargo run --example accurate_timing_demo\n\n# 运行最佳实践示例\ncargo run --example best_practices\n\n# 运行日志系统集成示例\ncargo run --example rat_logger_demo\n\n# 运行压缩算法性能对比（需要指定压缩特性）\ncargo run --example macbook_air_m1_compression_none --features compression-none --release\ncargo run --example macbook_air_m1_compression_lz4 --features compression-lz4 --release\ncargo run --example macbook_air_m1_compression_zstd --features compression-zstd --release\n```\n\n### 低端设备配置参考\n\n```rust\n// 针对 Intel Celeron J1800 + 2GB 内存的优化配置\nlet mut config = Config::new()\n    .path(\"low_end_db\")\n    .flush_every_ms(None)  // 禁用传统自动flush，使用智能flush\n    .cache_capacity_bytes(32 * 1024 * 1024);  // 32MB缓存，适应2GB内存\n\n// 优化智能flush配置\nconfig.smart_flush_config = crate::smart_flush::SmartFlushConfig {\n    enabled: true,\n    base_interval_ms: 100,     // 100ms基础间隔\n    min_interval_ms: 30,        // 30ms最小间隔\n    max_interval_ms: 1500,     // 1.5s最大间隔\n    write_rate_threshold: 4000, // 4K ops/sec阈值\n    accumulated_bytes_threshold: 2 * 1024 * 1024, // 2MB累积阈值\n};\n```\n\n### 示例亮点\n\n✅ **配置优化**: 展示如何根据应用场景调整缓存和 flush 参数\n✅ **数据建模**: 演示结构化数据的存储和查询模式\n✅ **批量操作**: 介绍高效的数据插入和处理技巧\n✅ **查询优化**: 展示范围查询和前缀查询的最佳实践\n✅ **事务处理**: 演示如何保证数据一致性\n✅ **性能监控**: 提供性能统计和监控建议\n\n## 性能表现\n\n### 性能测试数据\n\n详细的性能测试数据和硬件环境信息请查看：[docs/test_data/index.md](docs/test_data/index.md)\n\n### 性能亮点\n\n- **高端设备表现**: 在Apple M1上达到写入1.23 µs/条，读取0.42 µs/条的优异性能\n- **低端设备优化**: 在Intel Celeron J1800上通过智能flush优化实现写入9.13 µs/条，读取2.56 µs/条\n- **低功耗设备适配**: 在树莓派3B+上实现写入39.04 µs/条，读取9.06 µs/条，成功适配1GB内存+SD卡存储环境\n- **对比优势**: 相比RocksDB最高提升4倍写入性能\n- **跨平台支持**: 优化了ARM64和x86_64架构的性能表现\n\n### 测试覆盖\n\n- **硬件多样性**: 从高端Apple M1、低端Intel Celeron到树莓派3B+的完整测试覆盖\n- **系统兼容**: macOS和Linux多平台验证\n- **优化验证**: SIMD指令集、智能flush、缓存策略等多维度优化效果验证\n- **持续测试**: 定期性能回归测试确保性能稳定性\n\n## 优化技术详解\n\n### 1. SIMD 优化\n- **多平台支持**: 同时支持 ARM64 NEON 和 x86_64 SSE2/AVX2 指令集\n- **ARM64 NEON**: 支持 Apple M1 和树莓派 3b+ 等ARM64设备\n- **x86_64 SSE2**: 支持Intel Celeron等不支持AVX2的低端x86设备\n- **x86_64 AVX2**: 支持现代Intel/AMD处理器，32字节向量处理\n- **自适应检测**: 运行时自动检测CPU支持的指令集并选择最优实现\n- **小key优化**: 针对≤16字节的key使用快速64位整数比较\n- **批量处理**: 支持批量key比较操作，提升缓存命中率\n- **降级策略**: 不支持SIMD时使用优化的标量比较算法\n\n### 2. 布隆过滤器\n- **多级过滤器**: 支持热/温/冷数据分层\n- **可配置误判率**: 默认 1%，可按需调整\n- **并发安全**: 支持多线程同时访问\n\n### 3. 块缓存系统\n- **三级缓存架构**: 热/温/冷数据分层存储\n- **智能预取**: 基于访问模式的预取算法\n- **压缩支持**: 自动压缩大块数据\n- **100% 命中率**: 在测试场景下的完美表现\n\n## 架构设计\n\n### 核心组件\n\n1. **Tree**: B+ 树索引结构，支持范围查询\n2. **Leaf**: 叶子节点，存储实际数据\n3. **ObjectCache**: 对象缓存系统，集成优化组件\n4. **Heap**: 堆管理器，负责内存分配\n5. **Index**: 并发索引，支持高并发访问\n\n### 优化集成\n\n- **透明优化**: 用户无需修改现有代码即可获得性能提升\n- **向后兼容**: 完全兼容 sled 的 API 设计\n- **渐进式优化**: 可以选择性启用特定优化功能\n\n## 适用场景\n\n- **高频交易系统**: 低延迟读写需求\n- **实时数据分析**: 高吞吐量数据处理\n- **嵌入式设备**: 资源受限环境下的高性能存储\n- **缓存系统**: 作为分布式缓存的后端存储\n\n## 最佳实践指南\n\n### 🎯 配置优化\n\n1. **缓存大小设置**\n   - 小型应用/低端设备: 32MB - 256MB\n   - 中型应用: 512MB - 1GB\n   - 大型应用/高性能设备: 2GB - 4GB+\n\n2. **智能 Flush 策略**\n   - 启用智能 flush 以平衡性能和数据安全\n   - 根据写入负载调整 flush 间隔\n   - 设置合理的累积字节阈值\n   - **低端设备优化**: 减少基础间隔，提高频率，降低累积阈值\n   - **树莓派3B+特殊优化**: 增加flush间隔到200ms，降低写入阈值到2000 ops/sec，适应SD卡存储特性\n\n3. **树的设计**\n   - 使用有意义的树名\n   - 合理设计键的前缀结构\n   - 避免单个树过大\n\n4. **硬件适配建议**\n   - **高端设备 (Apple M1等)**: 使用示例中的1GB缓存配置\n   - **低端设备 (Intel Celeron等)**: 参考 `tests/low_end_x86_perf_test.rs` 配置\n   - **树莓派3B+等低功耗ARM设备**: 参考 `tests/raspberry_pi_perf_test.rs` 配置\n   - **内存受限环境**: 减少缓存大小，优化flush策略，考虑使用增量序列化\n\n### 📊 性能优化\n\n1. **批量操作**\n   - 大量数据插入使用批量操作\n   - 避免频繁的单条插入\n   - 利用预热优化性能\n\n2. **查询优化**\n   - 使用范围查询获取连续数据\n   - 利用前缀查询过滤数据\n   - 避免全表扫描\n\n3. **数据管理**\n   - 定期清理过期数据\n   - 使用事务保证数据一致性\n   - 监控数据库大小和性能\n\n### 🔧 开发建议\n\n1. **开发环境**\n   - 使用较小的缓存大小进行开发\n   - 启用调试日志监控性能\n   - 定期进行性能测试\n\n2. **生产环境**\n   - 根据实际负载调整配置参数\n   - 监控关键性能指标\n   - 建立数据备份机制\n\n3. **测试策略**\n   - 进行压力测试验证性能\n   - 测试故障恢复能力\n   - 验证数据一致性\n\n## 开发路线\n\n### ✅ 已完成优化\n- [x] SIMD 优化的 key 比较\n- [x] 多级布隆过滤器\n- [x] 智能块缓存系统\n- [x] 增量序列化优化\n- [x] 内存使用优化\n- [x] 智能自适应 flush 策略\n- [x] 完整的示例代码和文档\n- [x] 智能预取算法（基于访问模式）\n- [x] 完整的多平台SIMD支持（ARM64 NEON + x86_64 SSE2/AVX2）\n- [x] LZ4压缩算法支持（特性可选，提供更快的压缩速度）\n- [x] 多压缩算法特性选择（无压缩/LZ4/Zstd，编译时特性控制）\n- [x] 压缩算法性能优化和测试数据收集\n- [x] Apple Silicon M1专项优化和性能验证\n- [x] 集成 rat_logger 高性能日志系统，支持调用者配置\n\n### 🔄 进行中\n- [ ] 自适应压缩策略（运行时根据数据特征选择压缩算法）\n\n### 📋 下一阶段开发计划（v0.2.0）\n\n#### 🎯 性能优化\n- [x] **自适应压缩策略** - 运行时根据数据特征自动选择最优压缩算法\n- [ ] **热点数据识别** - 智能识别高频访问数据，优化缓存策略\n- [ ] **内存压缩** - 对冷数据进行内存压缩，提高内存利用率\n- [ ] **IO优化** - 异步IO支持，减少阻塞等待时间\n- [ ] **批量操作优化** - 进一步优化批量插入和查询性能\n\n#### 🛠️ 功能增强\n- [ ] **事务支持** - 完整的ACID事务支持\n- [ ] **范围查询优化** - 更高效的范围查询和迭代器\n- [ ] **二级索引** - 支持创建和管理二级索引\n- [ ] **数据TTL** - 自动过期数据清理\n- [ ] **备份恢复** - 数据备份和恢复机制\n\n#### 🔧 架构改进\n- [ ] **插件系统** - 可扩展的插件架构\n- [ ] **配置管理** - 更灵活的配置系统\n- [ ] **监控指标** - 详细的性能监控和指标收集\n- [ ] **日志系统** - 结构化日志和审计功能\n\n#### 🌐 平台支持\n- [ ] **Windows优化** - Windows平台专项优化\n- [ ] **Android支持** - Android平台适配\n- [ ] **iOS支持** - iOS平台适配\n- [ ] **WebAssembly** - WASM支持，浏览器环境使用\n\n#### 📊 工具生态\n- [ ] **CLI工具** - 命令行管理工具\n- [ ] **Web界面** - 基于Web的管理界面\n- [ ] **性能分析** - 性能分析和调优工具\n- [ ] **数据迁移** - 数据导入导出工具\n\n### 🚀 长期规划（v1.0+）\n\n#### 分布式版本\n- [ ] **集群支持** - 多节点集群部署\n- [ ] **数据分片** - 自动数据分片和负载均衡\n- [ ] **故障转移** - 自动故障检测和转移\n- [ ] **一致性协议** - 分布式一致性保证\n\n#### 高级查询优化\n- [ ] **查询计划** - 智能查询计划优化\n- [ ] **索引优化** - 自适应索引策略\n- [ ] **缓存策略** - 多级缓存优化\n- [ ] **预计算** - 查询结果预计算\n\n#### 机器学习集成\n- [ ] **访问模式预测** - 基于ML的访问模式预测\n- [ ] **自动调优** - 基于ML的参数自动调优\n- [ ] **异常检测** - 数据访问异常检测\n- [ ] **容量规划** - 智能容量规划建议\n\n## 技术栈\n\n### 开发环境\n- **核心语言**: Rust 1.70+\n- **基础架构**: 基于 sled 代码库\n- **并发控制**: concurrent-map, parking_lot\n- **SIMD 优化**:\n  - std::arch::aarch64 (ARM64 NEON指令集)\n  - std::arch::x86_64 (x86_64 SSE2/AVX2指令集)\n- **压缩**: zstd, lz4_flex（特性可选）\n- **日志**: rat_logger（高性能异步日志系统）\n- **测试**: criterion, tokio-test\n\n### 日志系统集成\n\nMelange DB 现已集成 rat_logger 高性能日志系统，提供灵活的日志配置选项：\n\n#### 主要特性\n- **高性能异步日志**: 基于 rat_logger 的高性能异步日志架构\n- **调用者配置**: 库本身不初始化日志，由调用者控制日志行为\n- **多种输出方式**: 支持终端输出、文件记录、网络传输等多种日志方式\n- **性能优化**: 在 release 模式下，调试级别日志完全零成本\n- **安全设计**: 未初始化日志时静默忽略，不会影响程序正常运行\n\n#### 基本使用示例\n```rust\nuse melange_db::{Db, Config};\nuse rat_logger::{LoggerBuilder, LevelFilter, handler::term::TermConfig};\n\nfn main() -\u003e anyhow::Result\u003c()\u003e {\n    // 初始化日志系统 - 由调用者配置\n    LoggerBuilder::new()\n        .add_terminal_with_config(TermConfig::default())\n        .with_level(LevelFilter::Debug)\n        .init()?;\n\n    // 配置并打开数据库\n    let config = Config::new()\n        .path(\"example_db\")\n        .cache_capacity_bytes(1024 * 1024); // 1MB 缓存\n\n    let db: Db\u003c1024\u003e = config.open()?;\n\n    // 数据库操作将自动输出日志\n    let tree = db.open_tree(\"my_tree\")?;\n    tree.insert(b\"key\", b\"value\")?;\n\n    Ok(())\n}\n```\n\n#### 日志级别说明\n- **ERROR**: 严重错误，总是记录\n- **WARN**: 警告信息，总是记录\n- **INFO**: 重要信息，在 debug 模式下记录\n- **DEBUG**: 调试信息，在 debug 模式下记录\n- **TRACE**: 追踪信息，在 debug 模式下记录\n\n#### 高级配置示例\n```rust\nuse rat_logger::{LoggerBuilder, LevelFilter, handler::{\n    term::TermConfig,\n    file::FileConfig,\n    composite::CompositeHandler\n}};\n\n// 同时输出到终端和文件\nlet mut handler = CompositeHandler::new();\nhandler.add_handler(Box::new(TermProcessor::new(TermConfig::default())?));\nhandler.add_handler(Box::new(FileProcessor::new(FileConfig {\n    file_path: \"melange_db.log\".to_string(),\n    rotation_size_mb: 100,\n    max_files: 5,\n})?));\n\nLoggerBuilder::new()\n    .add_custom_handler(handler)\n    .with_level(LevelFilter::Info)\n    .init()?;\n```\n\n#### ⚠️ 安全保证\n\n**未初始化日志时的行为**:\n- ✅ **完全安全**: 如果调用者没有初始化日志系统，所有日志调用会被静默忽略\n- ✅ **零异常**: 不会产生panic、错误或任何运行时异常\n- ✅ **正常执行**: 程序会完全正常运行，只是没有日志输出\n- ✅ **零开销**: 在release模式下，调试级别日志本来就是零成本的\n- ✅ **向后兼容**: 旧代码不初始化日志也能正常运行\n\n这种设计确保了:\n- **渐进式采用**: 可以选择性为特定模块启用日志\n- **生产环境友好**: 在不需要日志时完全零开销\n- **调用者完全控制**: 完全由调用者决定是否需要日志功能\n\n```rust\n// 即使不初始化日志，以下代码也能正常运行\nuse melange_db::{Db, Config};\n\nfn main() -\u003e anyhow::Result\u003c()\u003e {\n    // 注意：这里没有初始化rat_logger！\n\n    let config = Config::new()\n        .path(\"example_db\")\n        .cache_capacity_bytes(1024 * 1024);\n\n    let db: Db\u003c1024\u003e = config.open()?;\n    let tree = db.open_tree(\"my_tree\")?;\n    tree.insert(b\"key\", b\"value\")?;  // 日志调用被静默忽略\n    Ok(())\n}\n```\n\n### 压缩算法选择（编译时特性）\n\nMelange DB 支持通过编译时特性选择压缩算法，以适应不同的性能需求：\n\n#### 无压缩（默认）\n```bash\ncargo build --release\n```\n- **适用场景**: 低端设备（如树莓派）、追求极致性能\n- **特点**: 零CPU开销，最快读写速度\n\n#### LZ4压缩\n```bash\ncargo build --release --features compression-lz4\n```\n- **适用场景**: 中等性能设备，需要较好的压缩速度和压缩率平衡\n- **特点**: 极快的压缩/解压缩速度，适度压缩率\n\n#### Zstd压缩\n```bash\ncargo build --release --features compression-zstd\n```\n- **适用场景**: 存储空间受限，需要高压缩率\n- **特点**: 高压缩率，但CPU开销相对较大\n\n#### 特性优先级\n如果同时启用多个压缩特性，将按以下优先级选择：**none \u003e lz4 \u003e zstd**\n\n#### 配置验证\n```rust\nuse melange_db::config::CompressionAlgorithm;\n\n// 检查启用的压缩特性\nlet features = CompressionAlgorithm::detect_enabled_features();\nprintln!(\"启用的压缩特性: {:?}\", features);\n\n// 验证特性配置\nif let Some(warning) = CompressionAlgorithm::validate_feature_config() {\n    println!(\"警告: {}\", warning);\n}\n\n// 获取实际使用的算法\nlet (algorithm, reason) = CompressionAlgorithm::get_active_algorithm_with_reason();\nprintln!(\"使用压缩算法: {:?}, 原因: {}\", algorithm, reason);\n```\n\n### 目标平台\n- **ARM64平台**: Apple M1, Raspberry Pi 3b+ 等ARM64设备\n- **x86_64平台**: Intel/AMD处理器，从低端到高端全覆盖\n- **编译目标**:\n  - aarch64-apple-darwin, aarch64-unknown-linux-gnu\n  - x86_64-apple-darwin, x86_64-unknown-linux-gnu\n- **指令集支持**:\n  - ARM64: ARMv8.4-A with NEON SIMD\n  - x86_64: SSE2 (基础), AVX2 (现代处理器)\n- **运行时检测**: 自动检测CPU特性并选择最优SIMD实现\n\n## 贡献指南\n\n欢迎提交 Issue 和 Pull Request！\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/amazing-feature`)\n3. 提交更改 (`git commit -m 'Add amazing feature'`)\n4. 推送到分支 (`git push origin feature/amazing-feature`)\n5. 创建 Pull Request\n\n## 许可证\n\n本项目采用 GNU Lesser General Public License v3.0 (LGPLv3) 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。\n\n### 许可证说明\n\n选择 LGPLv3 的原因：\n\n- **商业友好**: 允许将 Melange DB 用于商业软件和闭源项目\n- **动态链接**: 通过动态链接方式使用时，主程序可以保持闭源\n- **开源义务**: 仅对库本身的修改需要开源，不影响使用方代码\n- **社区贡献**: 确保改进和优化能够回馈给开源社区\n\n### 使用场景\n\n- ✅ **商业软件**: 可以在闭源商业软件中使用\n- ✅ **开源项目**: 完全兼容其他开源许可证\n- ✅ **动态链接**: 推荐的使用方式，主程序保持闭源\n- ✅ **修改贡献**: 对 Melange DB 的改进需要开源\n\n## 致谢\n\n- 基于优秀的 [sled](https://github.com/spacejam/sled) 数据库架构\n- 灵感来自弗兰克·赫伯特的《沙丘》宇宙\n- 感谢所有提供反馈和建议的贡献者和用户\n\n\u003e \"I must not fear. Fear is the mind-killer.\" - Frank Herbert, Dune","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0ldm0s%2Fmelange_db","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0ldm0s%2Fmelange_db","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0ldm0s%2Fmelange_db/lists"}