# 轻量级高性能高压缩PHP GzKV数据库

**Repository Path**: web/gz_kv_db

## Basic Information

- **Project Name**: 轻量级高性能高压缩PHP GzKV数据库
- **Description**: 一个高性能、高压缩率的PHP键值数据库，支持PHP 5.6-PHP 8，可用于存储TB级别的数据。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-11-24
- **Last Updated**: 2025-12-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GzKV

![GzKV](https://img.shields.io/badge/GzKV-v1.0.0-blue.svg)
![PHP](https://img.shields.io/badge/PHP-5.6%2B-blue.svg)
![License](https://img.shields.io/badge/License-MIT-green.svg)

> 轻量级、高性能的PHP键值存储系统，支持数据加密和高压缩率

## ✨ 特性

- ⚡ **高性能** - 内存缓存 + 写缓冲区，大幅提升IO性能
- 🗜️ **高压缩** - GZIP/BZIP2压缩，最高可节省90%存储空间
- 🔒 **数据加密** - AES-256加密，保护敏感数据安全
- 📦 **大容量** - 自动分片技术，轻松管理TB级数据
- 💾 **低内存** - 索引分片，内存使用可控
- 🛡️ **稳定可靠** - 完整错误处理和事务支持

## 🚀 快速开始

### 基本用法

```php
<?php
require_once 'GzKV.php';

// 创建实例
$kv = new GzKV(['data_dir' => './data']);

// 存储数据
$kv->set('user:1', ['name' => '张三', 'age' => 30]);

// 读取数据
$user = $kv->get('user:1');

// 删除数据
$kv->delete('user:1');
```

### 加密数据存储

```php
// 启用加密
$kv = new GzKV([
    'data_dir' => './secure_data',
    'enable_encryption' => true,
    'encryption_key' => 'your-super-secret-key-32-chars-long',
]);

// 敏感数据自动加密
$kv->set('user:password', password_hash($password, PASSWORD_BCRYPT));
$kv->set('user:ssn', '123-45-6789');
```

## ⚙️ 配置选项

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| **基本配置** | | | |
| `data_dir` | string | './data' | 数据存储目录 |
| `file_size_limit` | int | 1073741824 | 单个数据文件大小限制 |
| `max_value_size` | int | 104857600 | 单个值大小限制（100MB） |
| **加密配置** | | | |
| `enable_encryption` | bool | false | 启用数据加密 |
| `encryption_method` | string | 'AES-256-CBC' | 加密方法 |
| `encryption_key` | string | '' | 加密密钥（32字节） |
| **压缩配置** | | | |
| `compress_algo` | int | 1 (GZIP) | 压缩算法 |
| `compress_level` | int | 9 | 压缩级别（1-9） |
| `adaptive_compression` | bool | false | 自适应压缩算法选择 |
| `compression_threshold` | int | 1024 | 压缩阈值（字节） |
| **索引分片配置** | | | |
| `enable_index_sharding` | bool | false | 启用索引分片（大数据量场景） |
| `index_shard_count` | int | 16 | 索引分片数量 |
| `index_shard_prefix` | string | 'index_' | 索引文件前缀 |
| `index_shard_suffix` | string | '.dat' | 索引文件后缀 |
| `max_keys_per_shard` | int | 100000 | 每个分片最大键数 |
| `index_cache_shard_ratio` | float | 0.1 | 分片缓存比例 |
| **性能配置** | | | |
| `index_cache_size` | int | 10000 | 索引缓存条目数 |
| `enable_cache` | bool | true | 启用内存缓存 |
| `cache_strategy` | int | 1 (LRU) | 缓存策略 |
| `cache_size` | int | 1000 | 内存缓存条目数 |
| `cache_ttl` | int | 3600 | 缓存TTL（秒） |
| `enable_write_buffer` | bool | true | 启用写缓冲区 |
| `write_buffer_size` | int | 1048576 | 写缓冲区大小（1MB） |
| `enable_prefetch` | bool | true | 启用预取 |
| `prefetch_size` | int | 10 | 预取数量 |
| `enable_bulk_optimization` | bool | true | 启用批量操作优化 |
| `bulk_batch_size` | int | 100 | 批量操作批次大小 |
| `enable_performance_stats` | bool | false | 启用性能统计 |

## 🗜️ 压缩算法

| 算法ID | 名称 | 速度 | 压缩率 | 适用场景 |
|--------|------|------|--------|----------|
| 0 | None | 最快 | 无 | 小数据或已压缩的数据 |
| 1 | Gzip | 中等 | 中等 | 通用场景，平衡速度和压缩率 |
| 2 | Bzip2 | 慢 | 最高 | 存储空间优先，静态数据 |

## 📚 API 参考

### 基本操作

| 方法 | 说明 |
|------|------|
| `set($key, $value)` | 设置键值 |
| `get($key)` | 获取值 |
| `delete($key)` | 删除键 |
| `exists($key)` | 检查键是否存在 |
| `keys()` | 获取所有键 |
| `mset($pairs)` | 批量设置(key-value数组) |
| `mget($keys)` | 批量获取(key数组)|
| `mdelete($keys)` | 批量删除(key数组)|

### 加密控制

| 方法 | 说明 |
|------|------|
| `enableEncryption()` | 临时启用加密 |
| `disableEncryption()` | 临时禁用加密 |
| `restoreEncryption()` | 恢复全局设置 |
| `withEncryption($callback)` | 回调中启用加密 |
| `withoutEncryption($callback)` | 回调中禁用加密 |
| `getEncryptionStatus()` | 获取加密状态 |

### 管理操作

| 方法 | 说明 |
|------|------|
| `stats()` | 获取统计信息 |
| `close()` | 关闭数据库 |
| `clear()` | 清空所有数据 |
| `flush()` | 强制刷新缓冲区 |

## 🎯 使用场景

### 用户会话管理

```php
$kv = new GzKV(['data_dir' => './sessions']);
$kv->set(session_id(), $_SESSION);
$session_data = $kv->get(session_id());
```

### 敏感数据存储

```php
$kv = new GzKV([
    'enable_encryption' => true,
    'encryption_key' => getenv('ENCRYPTION_KEY')
]);

// 敏感数据加密存储
$kv->withEncryption(function($db) {
    $db->set('user:password', $hashedPassword);
    $db->set('user:ssn', $socialSecurityNumber);
});

// 公开数据不加密存储
$kv->withoutEncryption(function($db) {
    $db->set('user:profile', $publicProfile);
});
```

### 查询缓存

```php
$kv = new GzKV(['data_dir' => './cache']);

$cache_key = 'user_list_' . md5(serialize($params));
$result = $kv->get($cache_key);

if ($result === null) {
    $result = $db->query($params);
    $kv->set($cache_key, $result);
}
```

## 📊 性能优化

### 大数据量场景

```php
$config = [
    'enable_index_sharding' => true,
    'index_shard_count' => 32,        // 增加分片
    'max_keys_per_shard' => 50000,     // 减少单分片键数
];
```

### 高写入场景

```php
$config = [
    'enable_write_buffer' => true,
    'write_buffer_size' => 10 * 1024 * 1024,  // 10MB缓冲区
];
```

### 高读取场景

```php
$config = [
    'enable_cache' => true,
    'cache_size' => 10000,              // 增大缓存
];
```

## 🔒 安全最佳实践

### 密钥管理

```php
// 推荐：从环境变量获取
$encryption_key = getenv('GZKV_ENCRYPTION_KEY');

// 生成安全密钥
$encryption_key = bin2hex(random_bytes(16)); // 32字符
```

### 数据分类

- **敏感数据**: 密码、SSN、支付信息 → 加密存储
- **配置数据**: API密钥、令牌 → 加密存储
- **缓存数据**: 查询结果、临时数据 → 可选加密
- **公开数据**: 用户资料、应用配置 → 不加密

## 🔧 故障排除

| 问题 | 解决方案 |
|------|----------|
| 内存不足 | 启用索引分片，增加分片数量 |
| 写入性能差 | 增大写缓冲区大小 |
| 磁盘占用大 | 提高压缩级别，使用BZIP2 |
| 解密失败 | 检查密钥长度和一致性 |
| 数据损坏 | 检查文件完整性，重新初始化 |

## 📈 性能基准

| 操作类型 | 性能(约) | 说明 |
|----------|----------|------|
| 写入 | 5,000-10,000 ops/s | 取决于数据大小 |
| 读取 | 20,000-50,000 ops/s | 缓存命中时最高 |
| 存在检查 | 30,000-60,000 ops/s | 纯内存操作 |

## 📁 文件结构

```
data/
├── index.dat          # 索引文件
├── index_0.dat        # 分片索引文件
├── data_0.dat         # 数据文件（可能已加密）
└── ...
```

## 🔄 更新日志

### v1.0.0
- 🎉 初始版本发布
- ✨ 支持基本KV操作
- ✨ 支持数据加密
- ✨ 支持压缩和索引分片
- ✨ 支持内存缓存和写缓冲区

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

---

⭐ 如果这个项目对你有帮助，请给它一个星标！