# onyx-snapshotter

**Repository Path**: wangtsingx/onyx-snapshotter

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-09
- **Last Updated**: 2025-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# onyx-snapshotter

高性能容器镜像快照器，支持按需下载、块级去重和 lazy pull。

## 特性

- **按需下载**：使用 fanotify + ublk 实现高性能块级按需下载
- **块级去重**：固定大小（默认 4MB）块哈希索引，支持高并发
- **OCI Registry 兼容**：支持标准 OCI registry，兼容 estargz 格式
- **元数据分离**：块数据（CAS）与文件映射元数据独立存放
- **可回滚**：支持快照回滚，兼容 BuildKit 生成的 estargz 镜像
- **预取服务**：基于访问模式和构建跟踪自动预取

## 依赖

- containerd >= v2.1.4
- Go >= 1.25.1
- Linux kernel >= 5.1（支持 fanotify）
- ublk 支持（Linux kernel >= 6.0）

## 构建

```bash
make build
make docker-build
```

## 配置

编辑 `config.yaml`：

```yaml
root: /var/lib/onyx-snapshotter
grpc_address: unix:///run/onyx-snapshotter/snapshotter.sock
log_level: info
chunk_size: 4194304  # 4MB
db_backend: rocksdb  # or boltdb
fanotify_enabled: true
ublk_enabled: true
dedup_rate: 0.75
prefetch_enabled: true
prefetch_threads: 4
```

## 快速开始

```bash
# 构建二进制
make install

# 启动 snapshotter
onyx-snapshotter --root /var/lib/onyx-snapshotter

# 配置 containerd 使用 onyx snapshotter
# 编辑 /etc/containerd/config.toml
[plugins."io.containerd.snapshotter.v1.onyx"]
  root_path = "/var/lib/onyx-snapshotter"
```

## 架构

```
┌─────────────────────────────────────────────────┐
│ containerd gRPC Plugin (onyx-snapshotter)      │
└────────────────┬────────────────────────────────┘
                 │
    ┌────────────┼────────────┐
    │            │            │
    ▼            ▼            ▼
 ┌─────┐    ┌────────┐   ┌──────────┐
 │ OCI │    │fanotify│   │  ublk    │
 │Regy │    │Listener│   │  Backend │
 └────┘    └────┬───┘   └──────────┘
    │           │           │
    └────────────┼───────────┘
                 │
         ┌───────▼────────┐
         │  Dedup Engine  │
         └───┬────────┬───┘
             │        │
         ┌───▼─┐  ┌──▼────┐
         │Pebble   │Downloader
         │ DB │    │Service│
         └────┘    └───────┘
```

## API

### Snapshotter 接口

实现 containerd Snapshotter 接口：

- `Prepare(ctx, key, parent)` - 准备快照
- `Commit(ctx, name, key)` - 提交快照
- `Remove(ctx, key)` - 删除快照
- `Stat(ctx, key)` - 获取快照状态
- `Walk(ctx, fn)` - 遍历快照

### 统计 API

`GET /stats/metrics` - 获取当前指标

```json
{
  "timestamp": "2025-10-09T10:30:00Z",
  "snapshot_count": 42,
  "total_size": 1099511627776,
  "cached_size": 549755813888,
  "dedup_ratio": 0.75,
  "download_count": 1024,
  "download_bytes": 10737418240,
  "cache_hit_rate": 0.85,
  "average_fetch_time": "125ms"
}
```

## 开发

运行测试：

```bash
make test
make test-short
```

代码格式化：

```bash
make fmt
make lint
```