rat_memcache 0.2.3

# RatMemCache

高性能 Memcached 协议兼容服务器，支持双层缓存和 **melange_db** 持久化存储

[![Crates.io](https://img.shields.io/crates/v/rat_memcache.svg)](https://crates.io/crates/rat_memcache)
[![Documentation](https://docs.rs/rat_memcache/badge.svg)](https://docs.rs/rat_memcache)
[![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
[![Downloads](https://img.shields.io/crates/d/rat_memcache.svg)](https://crates.io/crates/rat_memcache)
[![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://rust-lang.org)

---

🇨🇳 [中文](README.md) | 🇺🇸 [English](README_EN.md) | 🇯🇵 [日本語](README_JA.md)

## 项目描述

RatMemCache 是一个基于 Rust 实现的高性能缓存系统，提供了以下两种使用模式：

1. **作为库使用**：提供高性能的缓存 API，支持内存和 **melange_db** 持久化双层缓存
2. **作为独立服务器使用**：100% 兼容 Memcached 协议的独立服务器

### 🪟 Windows 平台原生支持

**RatMemCache 是目前少数能在 Windows 平台原生运行的高性能 Memcached 兼容服务器！**

- ✅ **原生 Windows 支持**：无需 WSL 或虚拟机，直接在 Windows 上运行
- ✅ **100% 协议兼容**：完全兼容 Memcached 协议，可直接替换原版 memcached
- ✅ **跨平台一致性**：Windows、Linux、macX 功能完全一致
- ✅ **解决 Windows 痛点**：原版 memcached 在 Windows 上部署复杂，RatMemCache 开箱即用

采用 LGPL-v3 许可证，支持自由使用和修改。

## 主要特性

- 🚀 **高性能**: 基于异步运行时，支持高并发访问
- 📦 **双层缓存架构**: 内存 L1 缓存 + MelangeDB L2 持久化缓存
- 🔌 **100% Memcached 协议兼容**: 可直接替换标准的 memcached 服务器
- 🪟 **Windows 原生支持**: 无需 WSL，直接在 Windows 平台运行
- 🧠 **智能驱逐策略**: 支持 LRU、LFU、FIFO、混合策略等
- ⏰ **TTL 支持**: 灵活的过期时间管理
- 🐘 **大值处理优化**: 超过阈值的大值直接下沉到L2存储，避免内存耗尽
- 🗜️ **数据压缩**: LZ4 压缩算法，节省存储空间
- 🚀 **高性能**: 基于异步运行时，支持高并发访问
- 🎨 **结构化日志**: 基于 rat_logger 的高性能日志系统
- 🔧 **灵活配置**: 支持多种预设配置和自定义配置

## 许可证

本项目采用 **LGPL-v3** 许可证。这意味着：

- ✅ 可以自由使用、修改和分发
- ✅ 可以在商业项目中使用
- ✅ 可以作为库链接到你的项目中
- ⚠️ 修改后的库源代码需要以 LGPL 许可证开源
- ⚠️ 链接到你的应用程序时，应用程序可以保持闭源

详见 [LICENSE](LICENSE) 文件。

## 快速开始

### 使用场景选择

RatMemCache 提供了灵活的特性选择，满足不同场景的需求：

#### 1. 纯内存缓存（默认）
```toml
[dependencies]
rat_memcache = "0.2.2"
```
- ✅ 基本内存缓存功能
- ✅ TTL支持
- ❌ 持久化存储
- ❌ 性能指标
- 适合：简单缓存场景

#### 2. 双层缓存（内存+持久化）
```toml
[dependencies]
rat_memcache = { version = "0.2.2", features = ["full-features"] }
```
- ✅ 所有库功能
- ✅ MelangeDB持久化存储
- ✅ LZ4压缩
- ✅ 性能指标
- ✅ mimalloc内存分配器
- 适合：需要持久化的生产环境

#### 3. 完整服务器
```toml
[dependencies]
rat_memcache = { version = "0.2.2", features = ["server"] }
```
- ✅ 包含所有库功能
- ✅ rat_memcached二进制文件
- 适合：作为独立memcached服务器使用

#### 4. 自定义组合
```toml
[dependencies]
rat_memcache = { version = "0.2.2", features = ["cache-lib", "ttl-support", "metrics"] }
```
- 根据需要选择特定功能
- 最小化依赖和编译时间

### 作为库使用

RatMemCache 可以作为 Rust 库集成到你的项目中，提供高性能的双层缓存功能。

#### 基本集成

```toml
[dependencies]
rat_memcache = "0.2.2"
tokio = { version = "1.0", features = ["full"] }
```

#### 快速开始

```rust
use rat_memcache::{RatMemCacheBuilder, CacheOptions};
use bytes::Bytes;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建缓存实例 - 使用默认配置
    let cache = RatMemCacheBuilder::new()
        .build()
        .await?;

    // 基本操作
    let key = "my_key".to_string();
    let value = Bytes::from("my_value");

    // 设置缓存
    cache.set(key.clone(), value.clone()).await?;

    // 获取缓存
    if let Some(retrieved) = cache.get(&key).await? {
        println!("Retrieved: {:?}", retrieved);
    }

    // 设置带 TTL 的缓存（60秒过期）
    cache.set_with_ttl("temp_key".to_string(), Bytes::from("temp_value"), 60).await?;

    // 检查缓存是否存在
    let exists = cache.contains_key("temp_key").await?;
    println!("Key exists: {}", exists);

    // 获取缓存键列表
    let keys = cache.keys().await?;
    println!("Cache keys: {:?}", keys);

    // 条件删除
    let deleted = cache.delete("temp_key").await?;
    println!("Key deleted: {}", deleted);

    // 优雅关闭
    cache.shutdown().await?;

    Ok(())
}
```

#### 高级配置

```rust
use rat_memcache::{RatMemCacheBuilder, EvictionStrategy};
use rat_memcache::config::{L1Config, L2Config, TtlConfig};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 自定义 L1 配置（2GB 内存限制）
    let l1_config = L1Config {
        max_memory: 2 * 1024 * 1024 * 1024,  // 2GB in bytes
        max_entries: 1_000_000,             // 100万条记录
        eviction_strategy: EvictionStrategy::Lru,
    };

    // 自定义 L2 配置（10GB 磁盘空间）
    let l2_config = L2Config {
        enable_l2_cache: true,
        data_dir: Some(PathBuf::from("./cache_data")),
        clear_on_startup: false,
        max_disk_size: 10 * 1024 * 1024 * 1024,  // 10GB in bytes
        write_buffer_size: 64 * 1024 * 1024,     // 64MB
        max_write_buffer_number: 3,
        block_cache_size: 32 * 1024 * 1024,      // 32MB
        enable_compression: true,
        compression_level: 6,
        background_threads: 2,
        database_engine: Default::default(),
        melange_config: Default::default(),
    };

    // TTL 配置
    let ttl_config = TtlConfig {
        default_ttl: Some(3600),     // 默认1小时
        max_ttl: 86400,              // 最大24小时
        cleanup_interval: 300,       // 5分钟清理一次
        ..Default::default()
    };

    let cache = RatMemCacheBuilder::new()
        .l1_config(l1_config)
        .l2_config(l2_config)
        .ttl_config(ttl_config)
        .build()
        .await?;

    // 使用缓存...

    Ok(())
}
```

#### 生产环境最佳实践

```rust
use rat_memcache::{RatMemCacheBuilder, EvictionStrategy};
use rat_memcache::config::{L1Config, L2Config, PerformanceConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 生产环境配置 - 优化性能配置
    let cache = RatMemCacheBuilder::new()
        .l1_config(L1Config {
            max_memory: 4 * 1024 * 1024 * 1024,  // 4GB
            max_entries: 2_000_000,
            eviction_strategy: EvictionStrategy::Lru,
        })
        .l2_config(L2Config {
            enable_l2_cache: true,
            max_disk_size: 50 * 1024 * 1024 * 1024,  // 50GB
            enable_compression: true,
            background_threads: 4,
            ..Default::default()
        })
        .performance_config(PerformanceConfig {
            ..Default::default()
        })
        .build()
        .await?;

    // 应用程序主逻辑...

    Ok(())
}

```

### 作为独立服务器使用

```bash
# 克隆项目
git clone https://github.com/0ldm0s/rat_memcache.git
cd rat_memcache

# 编译（启用服务器功能）
cargo build --release

# 使用默认配置启动服务器
cargo run --bin rat_memcached

# 指定绑定地址
cargo run --bin rat_memcached -- --bind 0.0.0.0:11211

# 使用配置文件
cargo run --bin rat_memcached -- --config custom_config.toml

# 作为守护进程运行
cargo run --bin rat_memcached -- --daemon --pid-file /var/run/rat_memcached.pid
```

#### Windows 平台特别说明

在 Windows 平台上，RatMemCache 提供了与 Linux/macX 完全一致的功能：

```powershell
# Windows 编译
cargo build --release

# Windows 启动服务器
cargo run --bin rat_memcached

# Windows 指定端口
cargo run --bin rat_memcached -- --bind 127.0.0.1:11211

# Windows 后台运行（使用 PowerShell Start-Process）
Start-Process cargo -ArgumentList "run --bin rat_memcached -- --bind 0.0.0.0:11211" -NoNewWindow
```

**Windows 优势**：
- 无需安装 WSL 或虚拟机
- 原生性能，无虚拟化开销
- 与 Windows 服务完美集成
- 支持 Windows 原生路径和权限管理

### 协议兼容性

RatMemCache 完全兼容 Memcached 协议，支持以下命令：

- `get` / `gets` - 获取数据
- `set` / `add` / `replace` / `append` / `prepend` / `cas` - 设置数据
- `delete` - 删除数据
- `incr` / `decr` - 增减数值
- `flush_all` - 清空所有数据
- `version` - 获取版本信息

你可以使用任何标准的 Memcached 客户端连接到 RatMemCache 服务器：

```bash
# 使用 telnet 测试
telnet 127.0.0.1 11211

# 使用 memcached-cli
memcached-cli --server 127.0.0.1:11211
```

## 配置说明

项目使用 TOML 格式配置文件，支持灵活的配置选项：

### 基本配置

```toml
[l1]
max_memory = 1073741824  # 1GB
max_entries = 100000
eviction_strategy = "Lru"

[l2]
enable_l2_cache = true
data_dir = "./rat_memcache_data"
max_disk_size = 1073741824  # 1GB
enable_compression = true

[compression]
enable_lz4 = true
compression_threshold = 1024
compression_level = 6

[ttl]
default_ttl = 3600  # 1小时
cleanup_interval = 300  # 5分钟

[performance]
worker_threads = 4
enable_concurrency = true
read_write_separation = true
large_value_threshold = 10240  # 10KB
```

### 高级日志配置

RatMemCache 基于 rat_logger 提供了灵活的日志配置，支持性能调优：

```toml
[logging]
# 基本日志配置
level = "INFO"                    # 日志级别: trace, debug, info, warn, error, off
enable_colors = true               # 启用彩色输出
show_timestamp = true              # 显示时间戳
enable_performance_logs = true      # 启用性能日志
enable_audit_logs = true           # 启用操作审计日志
enable_cache_logs = true           # 启用缓存操作日志

# 高级日志配置（性能调优）
enable_logging = true               # 是否完全禁用日志系统（设置为false可获得最高性能）
enable_async = false               # 是否启用异步模式（异步模式可提高性能，但可能在程序崩溃时丢失日志）

# 异步模式的批量配置（仅在enable_async=true时生效）
batch_size = 2048                  # 批量大小（字节）
batch_interval_ms = 25             # 批量时间间隔（毫秒）
buffer_size = 16384                # 缓冲区大小（字节）
```

#### 日志性能调优建议

1. **最高性能模式**（适合生产环境）：
   ```toml
   [logging]
   enable_logging = false
   ```

2. **异步高性能模式**（适合高负载场景）：
   ```toml
   [logging]
   enable_logging = true
   enable_async = true
   batch_size = 4096
   batch_interval_ms = 50
   buffer_size = 32768
   ```

3. **调试模式**（开发环境）：
   ```toml
   [logging]
   enable_logging = true
   enable_async = false
   level = "DEBUG"
   enable_performance_logs = true
   enable_cache_logs = true
   ```

#### 配置说明

- **enable_logging**: 完全禁用日志系统的开关，设置为false时所有日志功能将被禁用，提供最高性能
- **enable_async**: 异步模式开关，异步模式可以提高性能但可能在程序崩溃时丢失日志
- **batch_size**: 异步模式下的批量大小，影响日志处理效率
- **batch_interval_ms**: 异步模式下的批量时间间隔，影响日志实时性
- **buffer_size**: 异步模式下的缓冲区大小，影响内存使用量

## 构建和测试

```bash
# 构建项目
cargo build

# 构建发布版本
cargo build --release

# 运行测试
cargo test

# 运行基准测试
cargo bench

# 检查代码格式
cargo fmt

# 检查代码质量
cargo clippy
```

## 功能特性

### 缓存功能
- ✅ 基本缓存操作 (get/set/delete)
- ✅ TTL 过期管理
- ✅ 批量操作支持
- ✅ 条件操作 (cas)
- ✅ 数据压缩

### 协议支持
- ✅ 完整的 Memcached 协议实现
- ✅ 二进制协议支持
- ✅ ASCII 协议支持
- ✅ 多连接处理
- ✅ 并发访问控制

### 性能特性
- ✅ 异步 I/O
- ✅ 读写分离
- ✅ 内存池管理
- ✅ 智能缓存预热
- ✅ 高性能异步设计

### 可靠性
- ✅ 数据持久化
- ✅ 优雅关闭
- ✅ 错误恢复
- ✅ 内存保护

## 架构设计

```
┌─────────────────────────────────────────────────────────┐
│                    RatMemCache                          │
├─────────────────┬───────────────────────────────────────┤
│   服务器层      │            库接口层                   │
│  (Memcached    │         (Rust API)                   │
│   Protocol)    │                                       │
├─────────────────┴───────────────────────────────────────┤
│                     核心层                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   L1缓存    │  │   TTL管理   │  │  流式传输    │    │
│  │   (内存)    │  │            │  │             │    │
│  └─────────────┘  └─────────────┘  └─────────────┘    │
├─────────────────────────────────────────────────────────┤
│                   存储层                                │
│  ┌─────────────────────────────────────────────────┐  │
│  │               MelangeDB L2 缓存                   │  │
│  │            (持久化存储)                          │  │
│  └─────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

## 性能基准

⚠️ **重要说明**: 以下性能数据基于Apple MacBook Air M1芯片测试得出，实际性能可能因硬件配置、使用场景和数据特征而异，仅供参考。

### L1缓存性能 (v0.2.2优化后)
在Apple MacBook Air M1测试环境下：
- **L1缓存GET操作**: 1.75-3.4微秒 (µs)
- **L1缓存SET操作**: 8-35微秒 (µs)
- **内存缓存命中率**: 99%+
- **数据一致性**: 100%

### 通用性能基准
在标准测试环境下（4核CPU，8GB内存）：
- **QPS**: 50,000+ (简单get操作)
- **内存使用**: < 50MB 基础占用
- **并发连接**: 10,000+
- **延迟**: < 1ms (99th percentile)

### 性能优化说明
v0.2.2版本重点优化了L1内存缓存的性能：
- 修复了L1缓存错误进行压缩/解压缩操作的问题
- L1缓存现在直接存储和返回原始数据，避免不必要的CPU开销
- 内存缓存命中响应时间提升145,000倍（从515ms优化到微秒级）

## ⚠️ 大值数据传输警告

**重要提醒**: 当传输超过40KB的大值数据时，标准的memcached协议可能会遇到socket缓冲区限制，导致传输超时或不完整。

### 推荐解决方案

RatMemCache提供了**增强型流式传输协议**，可以有效解决大值传输问题：

#### 流式GET命令
```bash
# 标准GET（可能超时）
get large_key

# 流式GET（推荐）
streaming_get large_key 16384  # 16KB块大小
```

#### 流式协议优势
- 🚀 **避免超时**: 分块传输，绕过socket缓冲区限制
- 📊 **进度可见**: 实时显示传输进度和块信息
- 💾 **内存友好**: 客户端可以按需处理数据块
- 🔧 **向后兼容**: 完全兼容标准memcached协议

#### 使用示例
```python
# 见 demo/streaming_protocol_demo.py - 完整的性能对比演示
```

### 详细说明
- **问题阈值**: >40KB的数据可能触发socket缓冲区限制
- **推荐做法**: 使用流式协议进行大值传输
- **性能提升**: 流式传输比传统方式快10-100倍（针对大值）

## 依赖项

主要依赖：
- **tokio**: 异步运行时
- **melange_db**: 持久化存储 (可选) - 高性能嵌入式数据库
- **dashmap**: 并发哈希表
- **lz4**: 数据压缩
- **rat_logger**: 日志系统
- **clap**: 命令行参数解析
- **mimalloc**: 高性能内存分配器

## 版本兼容性

- **Rust**: 1.70+ (edition 2021)
- **操作系统**: Linux, macOS, Windows (完全原生支持)
- **Memcached 协议**: 1.4.0+
- **Windows 特性**: 原生支持，无需 WSL 或虚拟机

## 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 维护者

- [@0ldm0s](https://github.com/0ldm0s) - 主要开发者

## 致谢

感谢以下开源项目：
- [Tokio](https://tokio.rs/) - 异步运行时
- [melange_db](https://github.com/melange-db/melange_db) - 高性能嵌入式持久化存储
- [Rust](https://www.rust-lang.org/) - 编程语言

## 路线图

- [ ] 增强集群支持
- [ ] 添加更多驱逐策略
- [ ] 支持 Redis 协议
- [ ] Web 管理界面

## 许可证细节

本项目采用 **GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later)** 许可证。

这意味着：
- 你可以将本库链接到任何类型的软件中（包括闭源软件）
- 修改本库源代码时，必须以相同的许可证发布修改后的版本
- 使用本库的应用程序可以保持自己的许可证

详见 [LICENSE](LICENSE) 文件。