bdstorage 중복 제거

계층적 BLAKE3 해싱 및 Copy-on-Write (CoW) 리플링크를 사용하여 저장 공간 효율성을 극대화하도록 설계된, 속도 중심의 로컬 파일 중복 제거 엔진입니다.

bdstorage는 대상 디렉터리를 스캔하고 고도로 최적화된 파이프라인을 통해 동일한 파일을 감지하며, 중복 파일을 중앙 집중식 금고(vault)로 가리키는 경량 링크로 대체합니다. 이 도구는 Rust로 작성되었으며 최신 Linux 파일 시스템에 맞게 조정되었습니다.

목차

1. bdstorage를 사용하는 이유
2. 작동 방식 (아키텍처)
3. 시스템 요구 사항
4. 설치
5. 사용 가이드
   • 빠른 시작
   • 일반적인 작업 흐름
   • dedupe 실행이 하는 일
   • 명령어 및 플래그
6. 백그라운드 데몬 (Linux 전용)
   • 개요
   • 설치 및 설정
   • 스캔 간격 구성
   • 데몬 관리
   • 작동 확인 방법
   • 알려진 제한 사항
7. 데이터 위치 및 저장소
8. 안전 보장
9. 라이선스

bdstorage를 사용하는 이유?

기존의 중복 제거 도구들은 모든 파일의 모든 바이트를 읽어 들여 디스크에 부하를 주는 경우가 많습니다. bdstorage는 I/O 오버헤드를 최소화하는, 더 스마트하고 속도 중심적인 접근 방식을 취합니다.

이 엔진은 **계층적 해싱 파이프라인(Tiered Hashing Pipeline)**을 사용합니다:

1. 크기 그룹화 (Size Grouping) (I/O 없음): 파일들은 정확한 바이트 크기별로 그룹화됩니다. 고유한 크기를 가진 파일들은 즉시 중복 제거 풀에서 제외됩니다.
2. 희소 해싱 (Sparse Hashing) (최소 I/O): 12KB보다 큰 파일의 경우, 엔진은 작은 12KB 샘플(시작점 4KB, 중간점, 끝점)을 읽어 같은 크기를 가지지만 내용이 다른 파일을 빠르게 제거합니다. Linux 환경에서는 fiemap ioctl을 활용하여 희소 파일(sparse files)을 지능적으로 처리합니다.
3. 전체 BLAKE3 해싱 (Full BLAKE3 Hashing) (높은 처리량): 희소 해시 검사를 통과한 파일들만이 고성능 128KB 버퍼를 사용하여 전체 BLAKE3 암호화 해싱을 거쳐 내용이 동일함을 확인받습니다.

벤치마크 vs. 경쟁 제품

bdstorage는 jdupes와 rmlint를 대상으로 hyperfine을 사용하여 벤치마킹되었습니다. 모든 테스트는 OS 캐시가 비워진 ext4 파일 시스템과 초기화된 상태 데이터베이스에서 실행되었습니다.

아레나 1: 대규모 희소 파일 (100MB 파일, 1바이트 차이)
bdstorage가 계층적 희소 해싱 파이프라인을 사용하기 때문에, 전체 파일을 읽지 않고도 내용에 차이가 없는 대용량 파일을 거의 즉시 거부합니다.

아레나 2: 작은 파일의 깊은 트리 (100개 디렉토리에 걸친 15,000개 파일)
비동기 데이터베이스 트랜잭션 배치 처리와 다중 스레드 crossbeam 아키텍처 덕분에, bdstorage는 지속적이고 매우 안전한 CAS(Conflict-free Replicated Data Type) 금고를 유지하면서 대규모 소스 코드 및 로그 디렉토리를 효율적으로 관리합니다.

벤치마크 재현하기

투명성은 매우 중요합니다. 저장소에 제공된 스크립트를 사용하여 여러분의 컴퓨터에서도 이 정확한 수치를 재현할 수 있습니다.

1. 벤치마크 디렉터리로 이동합니다:
   복사

   cd benchmarks
   

   1

   2
2. 정확한 테스트 아레나(Sparse Files 및 Deep Trees)를 생성합니다:
   복사

   ./setup_bench.sh
   

   1

   2
3. hyperfine 레이스를 실행합니다 (Arena 3 예시):
   복사

   hyperfine \
     --warmup 1 \
     --prepare 'rm -rf ~/.imprint && rm -rf /tmp/bench_data/arena_tiny/test && cp -r /tmp/bench_data/arena_tiny/pristine /tmp/bench_data/arena_tiny/test'
   

   1

   2

   3

   4

...

*(참고: 실행하기 전에 시스템에 `hyperfine`, `rmlint`, 그리고 `jdupes`가 설치되어 있는지 확인하십시오).* 

---

## 작동 방식 (아키텍처)

동일한 파일이 확인되면, `bdstorage`는 **콘텐츠 주소 지정 가능 스토리지(Content-Addressable Storage, CAS) 볼트**를 사용합니다.

1. **볼팅(Vaulting):** 파일의 첫 번째 인스턴스(

**메타데이터 보존 (Metadata Preservation):** reflinks를 사용할 때, `bdstorage`는 각 파일의 원래 권한(permissions), 수정 시간(modification times), 확장 속성(extended attributes)을 자동으로 보존하여 중복 제거가 애플리케이션에 완전히 투명하게 이루어지도록 합니다. 

## 시스템 요구 사항 (System Requirements)

* **운영 체제 (Operating System):** Linux (`fiemap` ioctl sparse file 최적화에 필요).
* **파일 시스템 (Filesystem):** 최대 성능과 안전성을 위해 **reflinks**를 지원하는 파일 시스템(예: Btrfs, XFS)을 강력히 권장합니다.
* **Rust:** 최신 안정 도구 체인 (소스에서 빌드할 경우).

### ZFS 지원 (ZFS Support)
`bdstorage`는 **OpenZFS 2.2+**의 네이티브 블록 클로닝(block-cloning)을 지원합니다. 

* **OpenZFS 2.2 및 이후 버전:** 네이티브 CoW reflinks를 지원합니다. `bdstorage`는 독립적인 파일 메타데이터(타임스탬프, 권한)를 보존하면서 즉각적이고 공간 효율적인 중복 제거를 위해 자동으로 `LinkType::Reflink`를 사용합니다.
* **OpenZFS < 2.2:** 명시적인 블록 클로닝을 지원하지 않습니다. 기본적으로 `bdstorage`는 이러한 파일을 건너뛰고 reflinks가 지원되지 않음을 보고합니다.
* **구형 ZFS의 해결책 (Workaround for older ZFS):** 구형 버전의 ZFS를 사용하면서 공간을 절약하고 싶다면, `--allow-unsafe-hardlinks` 플래그를 사용하십시오. **경고:** 이것은 하드 링크(hard links)를 사용하므로, 모든 중복 파일이 동일한 inode와 메타데이터를 공유하게 됩니다. 한 복사본을 수정하면 다른 모든 복사본에 영향을 미칩니다.

---

## 설치 (Installation)

### 옵션 1: Cargo를 통해 설치 (crates.io)
```bash
cargo install bdstorage

옵션 2: 소스에서 빌드 (Build from Source)

git clone https://github.com/Rakshat28/bdstorage.git
cd bdstorage
cargo build --release

사용 가이드 (Usage Guide)

빠른 시작 (Quick start)

1. 설치(Install) (참고 설치). 소스 빌드에서 생성된 바이너리는 target/release/bdstorage이며, 이를 PATH에 추가하거나 전체 경로로 호출해야 합니다.
2. 기본 동작을 원한다면 reflinks를 지원하는 파일 시스템의 디렉터리 트리를 선택하십시오 (참고 시스템 요구사항). reflinks가 없는 ext4에서는 --allow-unsafe-hardlinks 옵션을 사용하지 않는 한 파일이 건너뛰어지므로, 먼저 메타데이터에 미치는 영향을 이해해야 합니다.
3. 미리보기(Preview) 후 **적용(apply)**합니다:

bdstorage dedupe /path/to/tree -n    # dry-run: 쓰기 없음
bdstorage dedupe /path/to/tree       # 실제 실행

4. 첫 사용 시 $HOME/.imprint/ 아래에 **상태(State)**와 **금고(vault)**가 생성됩니다 (옵션으로 --vault-dir 또는 $BDSTORAGE_VAULT를 통해 변경 가능; 참고 데이터 위치 및 저장소).

전체 CLI 사용법은 **bdstorage --help**와 **bdstorage <하위 명령어> --help**를 이용하십시오.

일반적인 워크플로우

dedupe 실행 한 번이 하는 일

종합적으로, 단일 **bdstorage dedupe <경로>**는 다음을 수행합니다:

1. 트리를 순회하며 일반 파일들을 수집합니다 (예: *.imprint_tmp와 같은 임시 이름은 무시됩니다).
2. 크기별로 그룹화합니다 — 크기가 한 번만 나타나는 파일은 동일한 크기의 중복 파일을 가질 수 없으므로, 추가적인 읽기 작업 없이 다음 단계에서 제외됩니다.
3. 희소 샘플 해시(Sparse sample hash) — 더 큰 파일의 경우, 작은 샘플(시작점 / 중간 지점 / 끝점)을 읽어내어 내용이 다르다면 전체 파일을 읽지 않고도 종종 거부될 수 있습니다.
4. 전체 BLAKE3 해시(Full BLAKE3) — 남은 후보 파일들은 전체 파일에 대한 해시를 얻고, 일치하는 해시는 실질적으로 동일한 내용을 의미합니다.
5. 볼트(Vault) — 두 개 이상의 경로를 가진 각 그룹에 대해, 하나의 파일이 ~/.imprint/store/ 내의 마스터가 되며, 이는 해시로 주소 지정됩니다 (reflink vs hard link는 Architecture를 참조하세요).
6. 중복 파일을 대체합니다 — 그룹 내 다른 경로들은 볼트된 마스터에 대한 링크로 대체되며, 내장된 redb 데이터베이스가 경로, 해시, 참조 횟수(refcounts), 그리고 볼트된 inode 마커를 기록하여 나중에 실행하거나 **restore**할 때 일관성을 유지합니다.

실행이 중단된 경우에도 반쯤 연결된 파일들이 볼트 사본 없이 남는 일이 없도록 설계되었습니다. Safety Guarantees를 참조하세요.

명령어 및 플래그

Scan (읽기 전용 분석):

bdstorage scan /path/to/directory

Dedupe (볼트 + 링크 작성):

bdstorage dedupe /path/to/directory

bdstorage restore /path/to/directory

볼트 객체의 참조 횟수(refcount)가 복원 과정에서 0에 도달하면 제거됩니다 (가비지 컬렉션).

Status (수동 볼트 검사):

bdstorage status [--json]

예시 출력:

Vault 위치   : ~/.imprint/store/
Objects in vault : 124
Total vault size : 1.2 GB
...

전역 플래그 (Global flags)

진행률은 stderr에 그려지며, 이는 bdstorage 출력을 소비하는 스크립트와 도구를 위해 stdout을 깨끗하게 유지합니다.

백그라운드 데몬 (Background Daemon) (Linux 전용)

개요 (Overview)

bdstorage는 systemd를 사용하여 특정 폴더(및 모든 하위 폴더)를 설정된 시간 간격으로 자동으로 중복 제거하며 지속적으로 백그라운드에서 실행될 수 있습니다.

중요 참고 사항: 설치에는 sudo를 사용합니다. 이는 systemd 유닛 파일이 시스템 레벨이기 때문이지만, bdstorage는 계정을 동적으로 감지하고 데몬을 일반 사용자 권한으로 실행되도록 구성합니다. 이 데몬은 root vault가 아닌 사용자의 일반 ~/.imprint/ vault와 상태 데이터베이스를 사용합니다.

설치 및 설정 (Installation & Setup)

1단계: 서비스 설치

sudo bdstorage daemon install --target /path/to/watch --interval-secs 60

2단계: 파일 시스템 관련 참고 사항 (중요)

중요: 대상 폴더가 ext4와 같은 표준 파일 시스템(CoW reflinks 없음)인 경우, 설치 명령어에 --allow-unsafe-hardlinks를 추가해야 합니다. 그렇지 않으면 데몬은 파일을 보호하기 위해 지원되지 않는 파일 시스템에서는 의도적으로 중복 제거를 건너뜁니다.

sudo bdstorage daemon install --target /path/to/watch --interval-secs 60 

3단계: 활성화 및 시작

sudo systemctl daemon-reload
sudo systemctl enable --now bdstorage-dedupe.service

스캔 간격 구성 (Configuring the Scan Interval)

--interval-secs를 사용하여 데몬이 깨어나 중복 제거를 실행하는 빈도를 제어합니다.

짧은 간격 (예: 5초에서 30초)

• 장점(Pros): 거의 즉각적인 중복 제거가 가능합니다. 파일을 다운로드하거나 복사한 직후에 파일들이 연결되고 공간이 거의 즉시 회수됩니다.
• 단점(Cons): 유휴 CPU 사용량이 높고 디스크 웨이크업(disk wake-ups)이 더 자주 발생하여 노트북 배터리를 더 빨리 소모할 수 있습니다.

긴 간격 (Long Intervals) (예: 3600초 / 1시간)