# uraid

**Repository Path**: cdevel/uraid

## Basic Information

- **Project Name**: uraid
- **Description**: No description available
- **Primary Language**: C
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-15
- **Last Updated**: 2025-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# uRAID - 高性能分布式存储库

## 项目概述

uRAID 是一个基于Pool的分片映射架构的高性能分布式存储库，支持多种RAID级别和分布式副本，通过NVMe-oF实现高性能远程存储访问。

## 架构设计

### 库结构层次

```
┌─────────────────────────────────────────────────────────────┐
│                    客户端API层 (Public)                      │
├─────────────────────────────────────────────────────────────┤
│  C API  │  C++ API  │  Python API  │  Go API  │  Java API │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    核心API层 (Public)                        │
├─────────────────────────────────────────────────────────────┤
│  POSIX接口  │  管理接口  │  监控接口  │  配置接口              │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    内部实现层 (Private)                      │
├─────────────────────────────────────────────────────────────┤
│  RAID算法  │  分片管理  │  Pool管理  │  后端抽象  │  存储管理  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    系统接口层 (Private)                      │
├─────────────────────────────────────────────────────────────┤
│  etcd  │  XNVMe  │  libnfs  │  pthread  │  系统调用          │
└─────────────────────────────────────────────────────────────┘
```

### 事务保障机制

#### 1. 事务模型
uRAID采用基于日志的事务保障机制，确保存储操作的原子性和持久性。核心特性包括：
- **原子操作**：所有元数据操作和数据写入操作通过预写日志(WAL)保证原子性
- **一致性检查**：通过CRC校验和版本号验证确保数据完整性
- **崩溃恢复**：系统重启时自动通过WAL日志恢复未完成的事务

#### 2. 实现细节
- **日志分区**：每个存储池独立维护WAL日志
- **写入流程**：
  1. 先写入WAL日志
  2. 更新内存中的元数据
  3. 刷盘确认
  4. 清理日志

#### 3. 错误处理
- 支持`ErrorCode::IO_ERROR`和`ErrorCode::OUT_OF_SPACE`错误码
- 提供`Result<T>.is_ok()`方法检查操作状态
- 通过`Result<T>.error_message()`获取详细错误信息

### 回滚机制

#### 1. 触发条件
- 检测到存储空间不足
- 遇到不可恢复的IO错误
- 数据校验失败

#### 2. 实现方式
- **检查点机制**：定期保存一致性状态
- **补偿日志**：记录逆向操作用于回滚
- **版本快照**：保留数据多版本用于恢复

#### 3. 限制条件
- 仅保证最近N个事务的可回滚性
- 不支持跨Pool操作的原子性
- 最大回滚深度受WAL日志大小限制

### 头文件组织

#### 公共头文件 (Public Headers)
- `include/uraid.h` - 主要API头文件
- `include/uraid_posix.h` - POSIX兼容接口
- `include/uraid_management.h` - 管理接口
- `include/uraid_monitoring.h` - 监控接口
- `include/uraid_config.h` - 配置接口

#### 内部头文件 (Private Headers)
- `src/internal/backend_manager.h` - 后端管理
- `src/internal/pool_manager.h` - Pool管理
- `src/internal/shard_manager.h` - 分片管理
- `src/internal/raid_manager.h` - RAID管理
- `src/internal/storage_manager.h` - 存储管理
- `src/internal/utils/logger.h` - 日志系统
- `src/internal/utils/config.h` - 配置管理

## 编译系统

### 支持的平台
- Linux (Ubuntu 20.04+, CentOS 8+)
- Windows (通过WSL2)
- macOS (开发环境)

### 依赖库
- **必需依赖**
  - pthread (线程支持)
  - etcd (分布式存储)
  - XNVMe (NVMe-oF支持)
  - libnfs (NFS支持)

- **可选依赖**
  - libcurl (HTTP客户端)
  - libssl (加密支持)
  - libjson-c (JSON解析)

### 编译选项
```bash
# 基础编译
mkdir build && cd build
cmake ..
make

# 调试编译
cmake -DCMAKE_BUILD_TYPE=Debug ..
make

# 发布编译
cmake -DCMAKE_BUILD_TYPE=Release ..
make

# 安装
sudo make install
```

## API设计原则

### 1. 分层设计
- **客户端API**: 面向最终用户，简洁易用
- **核心API**: 提供完整功能，支持高级特性
- **内部API**: 仅供库内部使用，不对外暴露

### 2. 错误处理
- 统一错误码定义
- 详细的错误信息
- 错误恢复机制

### 3. 线程安全
- 所有公共API都是线程安全的
- 内部使用适当的锁机制
- 支持多线程并发访问

### 4. 内存管理
- 明确的内存所有权
- 自动内存管理
- 防止内存泄漏

## 多语言支持

### C API (核心)
```c
// 基础操作
int uraid_init(const char *config_file);
int uraid_cleanup(void);

// POSIX兼容接口
int uraid_open(const char *path, int flags);
int uraid_read(int fd, void *buf, size_t count);
int uraid_write(int fd, const void *buf, size_t count);
int uraid_close(int fd);
```

### C++ API (封装)
```cpp
namespace uraid {
    class Storage {
    public:
        Storage(const std::string& config);
        ~Storage();
        
        int open(const std::string& path, int flags);
        int read(int fd, void* buf, size_t count);
        int write(int fd, const void* buf, size_t count);
        int close(int fd);
    };
}
```

### Python API (绑定)
```python
import uraid

# 初始化
storage = uraid.Storage("config.json")

# 文件操作
fd = storage.open("/data/test", "rw")
storage.write(fd, b"Hello World")
data = storage.read(fd, 1024)
storage.close(fd)
```

### Go API (绑定)
```go
package main

import "github.com/uraid/go-uraid"

func main() {
    storage := uraid.NewStorage("config.json")
    defer storage.Close()
    
    fd, err := storage.Open("/data/test", "rw")
    if err != nil {
        panic(err)
    }
    
    _, err = storage.Write(fd, []byte("Hello World"))
    if err != nil {
        panic(err)
    }
    
    storage.Close(fd)
}
```

## 版本管理

### 版本号格式
- 主版本号.次版本号.修订号 (如: 1.0.0)
- 主版本号: 不兼容的API变更
- 次版本号: 向后兼容的功能性新增
- 修订号: 向后兼容的问题修正

### ABI兼容性
- 保证向后兼容性
- 提供版本检查机制
- 支持多版本共存

## 开发指南

### 代码规范
- 遵循C99标准
- 使用统一的命名规范
- 完整的注释和文档
- 单元测试覆盖

### 贡献流程
1. Fork项目
2. 创建功能分支
3. 编写代码和测试
4. 提交Pull Request
5. 代码审查和合并

## 许可证

本项目采用 MIT 许可证，详见 LICENSE 文件。

## 联系方式

- 项目主页: https://github.com/uraid/uraid
- 问题反馈: https://github.com/uraid/uraid/issues
- 文档: https://uraid.readthedocs.io