# xos

**Repository Path**: cdevel/xos

## Basic Information

- **Project Name**: xos
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# XSpace - 高性能本地对象存储引擎

一个基于 Rust 实现的高性能、低延迟、高可靠性的本地对象存储引擎。

## 特性

- **XOS 对象存储**: RADOS 风格的对象存储接口，支持网络访问
- **三层存储架构**: NVMe（热层）→ SATA SSD（温层）→ HDD（冷层）
- **高性能**: 基于 io_uring 的异步 I/O，零拷贝设计
- **字节级操作**: 支持范围读写、追加操作
- **扩展属性**: Key-Value 形式的对象元数据
- **对象锁**: 支持排他锁和共享锁
- **网络访问**: TCP 协议支持远程访问
- **高可靠**: WAL 持久化，Crash-safe 设计

## 架构设计

```
┌─────────────────────────────────────────────────────────────────┐
│                         XOS API Layer                            │
│  XosClient, Pool, Namespace, ObjectOperations                   │
├─────────────────────────────────────────────────────────────────┤
│                      Network Transport (可选)                    │
│  TcpServer, TcpClient, Protocol, ConnectionPool                 │
├─────────────────────────────────────────────────────────────────┤
│                      TieredStorage Backend                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │  NVMe/Hot   │  │  SATA/Warm  │  │  HDD/Cold   │              │
│  │  ~1.5M IOPS │  │  ~100K IOPS │  │  ~200 IOPS  │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
├─────────────────────────────────────────────────────────────────┤
│                      Cache & Index Layer                         │
│  ShardedCache (256 shards), ShardedIndex, WriteBuffer           │
├─────────────────────────────────────────────────────────────────┤
│                      Reliability Layer                           │
│  WAL, Group Commit, Checkpoint, Recovery                        │
└─────────────────────────────────────────────────────────────────┘
```

## 快速开始

### 安装

```bash
git clone https://gitee.com/cdevel/xos.git
cd xos
cargo build --release
```

### 基本使用

```rust
use xspace::xos::{XosClient, XosConfig, PoolConfig, ObjectId};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建 XOS 客户端
    let client = XosClient::new(XosConfig::new("/data/xos"))?;

    // 创建存储池
    let pool = client.create_pool("my_pool", PoolConfig::default())?;

    // 写入对象
    let oid = ObjectId::from_string("user:1001");
    pool.write(&oid, b"Hello, XOS!")?;

    // 读取对象
    if let Some(data) = pool.read(&oid)? {
        println!("Data: {:?}", String::from_utf8_lossy(&data));
    }

    // 字节级操作
    pool.append(&oid, b" Appended data")?;
    if let Some(data) = pool.read_range(&oid, 0, 5)? {
        println!("First 5 bytes: {:?}", data);
    }

    Ok(())
}
```

## 核心功能

### Pool 管理

```rust
// 创建存储池
let pool = client.create_pool("images", PoolConfig {
    max_objects: 1_000_000,
    max_size: 100 * 1024 * 1024 * 1024, // 100GB
    ..Default::default()
})?;

// 列出所有存储池
let pools = client.list_pools();

// 删除存储池
client.delete_pool("images")?;
```

### 字节级操作

```rust
// 范围读取
let data = pool.read_range(&oid, 100, 50)?;

// 范围写入
pool.write_range(&oid, 100, b"new data")?;

// 追加数据
let new_len = pool.append(&oid, b"more data")?;
```

### 扩展属性

```rust
// 设置扩展属性
pool.set_xattr(&oid, "content-type", b"image/jpeg")?;
pool.set_xattr(&oid, "author", b"admin")?;

// 获取扩展属性
let value = pool.get_xattr(&oid, "content-type")?;

// 列出所有扩展属性
let xattrs = pool.list_xattrs(&oid)?;
```

### 对象锁

```rust
// 锁定对象
let cookie = pool.lock_object(&oid, "write_lock", "client-1")?;

// 检查锁定状态
if pool.is_locked(&oid, "write_lock") {
    println!("Object is locked");
}

// 解锁
pool.unlock_object(&oid, "write_lock", "client-1")?;
```

### 网络访问

```rust
use xspace::xos::{TcpServer, TcpConfig};

// 启动服务端
let mut server = TcpServer::new(TcpConfig {
    bind_address: "0.0.0.0:6789".to_string(),
    max_connections: 10000,
    ..Default::default()
});
server.bind().await?;
server.start(handler).await?;

// 客户端连接
let client = TcpClient::new(TcpConfig::default());
let conn = client.connect("127.0.0.1:6789").await?;
```

## 性能指标

| 指标 | NVMe/Hot | SATA/Warm | HDD/Cold |
|------|----------|-----------|----------|
| IOPS | ~1,500,000 | ~100,000 | ~200 |
| 延迟 | 10-20μs | 50-100μs | 5-10ms |
| 吞吐 | 3+ GB/s | 500+ MB/s | 150+ MB/s |

## 文档

- [架构设计文档](docs/architecture.md)
- [API 文档](docs/api.md)
- [XOS 设计文档](docs/xos_design.md)
- [XOS 用户指南](docs/xos_user_guide.md)
- [性能调优指南](docs/performance_tuning.md)

## 构建

```bash
# 开发构建
cargo build

# 发布构建
cargo build --release

# 运行测试
cargo test

# 运行性能测试
cargo bench
```

## 项目结构

```
xspace/
├── src/
│   ├── xstore/
│   │   ├── xos/              # XOS 对象存储
│   │   │   ├── api.rs        # 核心客户端 API
│   │   │   ├── pool.rs       # Pool 管理
│   │   │   ├── object.rs     # 对象类型定义
│   │   │   └── transport/    # 网络传输层
│   │   ├── tiered_engine/    # 三层存储引擎
│   │   ├── store/            # 核心存储引擎
│   │   ├── index/            # 索引层
│   │   ├── cache/            # 缓存层
│   │   ├── wal/              # 预写日志
│   │   └── gc/               # 垃圾回收
│   └── bin/                  # 可执行程序
├── docs/                     # 文档
└── benches/                  # 性能测试
```

## License

Apache-2.0