SyncFlow (싱크플로우) 동기화 프로그램

다운로드 1번 포터볼

다운로드 2번 설치형

## 📖 목차

1. [프로젝트 소개](#-프로젝트-소개)
2. [주요 기능](#-주요-기능)
3. [시스템 구조 및 동작 원리](#-시스템-구조-및-동작-원리)
4. [설치 및 실행](#-설치-및-실행)
5. [프로토콜별 연결 설정 가이드](#-프로토콜별-연결-설정-가이드)
6. [빌드 및 개발 환경](#-빌드-및-개발-환경)
7. [프로젝트 구조](#-프로젝트-구조)
8. [라이선스](#-라이선스)

---

## 📌 프로젝트 소개

**SyncFlow (싱크플로우)**는 로컬 디스크와 다양한 원격 서버(Samba/SMB, FTP/FTPS, SFTP, WebDAV 등) 간의 대용량 파일 동기화를 안정적이고 신속하게 처리하는 Windows 데스크톱 동기화 솔루션입니다.

로컬과 원격지의 메타데이터를 각각 **독립된 SQLite 데이터베이스**에 인덱싱하고, 동기화 실행 전 상호 DB를 사전 대조(Diff)하여 **불필요한 중복 전송을 원천 차단**합니다. 양방향 동기화 시 **로컬 우선(Local Priority)** 정책을 적용하면서도 원격지의 기존 작업 파일은 _conflict_날짜_시간 형식으로 안전하게 원격지에 보존하여 **데이터 유실 없는(Zero-Data-Loss)** 동기화를 보장합니다.

---

## ✨ 주요 기능

### 1. 다양한 원격 프로토콜 완벽 지원

- **로컬 디렉터리 (Local FileSystem)**: 드라이브 간 고속 파일 복사 및 타임스탬프 보존.
- **삼바 / 네트워크 공유 (Samba / SMB)**: \\서버명\공유명 또는 \\IP\공유명 직접 연결 지원, 파일 잠금 방지(FileShare.ReadWrite).
- **FTP / FTPS**: 일반 FTP 및 보안 FTPS(Explicit / Implicit TLS, 포트 21/990 등 커스텀 포트 지원).
- **SFTP (SSH File Transfer)**: SSH 기반 보안 파일 전송(기본 포트 22).
- **WebDAV**: HTTP/HTTPS 기반 WebDAV 지원, PROPFIND 403 Forbidden 방지 및 MKCOL 자동 디렉터리 생성.

### 2. 독립 듀얼 SQLite 데이터베이스 (Dual SQLite Architecture)

- **로컬 DB (syncflow_sync_local.db)**: 로컬 동기화 폴더(LocalPath)에 직접 저장되며, 오직 로컬 파일 메타데이터 및 기준선(Baseline)만 관리.
- **원격 DB (syncflow_sync_remote.db)**: 원격지 1차 대상 폴더(예: Z:\Backup 또는 /Backup)에 직접 저장되며, 원격 파일 메타데이터 전담.
- **정밀 메타데이터 인덱싱**: 폴더 구조, 파일명, 확장자(예: Xshell-8.0.0107p.exe), 파일 크기(Bytes), 최종 수정 일시(UTC) 기록.
- **DB 파일 자체 격리**: syncflow_sync_*.db*, twinpoint_sync_*.db*, koken_sync_*.db*, .db-wal, .db-shm, .db-journal 파일이 일반 파일로 전송되거나 동기화 대상에 포함되지 않도록 필터링 엔진 내장.

### 3. 상호 DB 비교분석 및 사전 검증 (Pre-Sync Check)

- 동기화 시작 시 로컬 DB와 원격 DB 데이터를 조회하여 정밀 Diff 수행.
- 변경 사항(추가, 수정, 삭제)이 없는 경우 불필요한 네트워크 스캔 및 파일 전송 없이 **0초 만에 즉시 완료(Skip)** 처리.
- 변경 감지 시 작업 내역(업로드, 다운로드, 원격 삭제, 로컬 삭제)을 명확하게 집계하여 사전 안내 후 작업 진행.

### 4. 양방향 동기화 - 로컬 우선 및 무손실 충돌 보존

- **로컬 우선(Local Priority)**: 로컬 파일의 최신 작업본을 원격지에 정식 파일명으로 업로드 반영.
- **서버 사이드 고속 충돌 보존 (MoveFileAsync)**:
- 충돌 발생 시 원격지 원본 파일은 _conflict_yyyyMMdd_HHmmss.확장자 형태로 원격지 서버 내에서 즉시 이동/보존.
- 삼바(SMB) 및 FTP, SFTP, WebDAV 서버 내에서 직접 이동하여 대용량 파일도 0.001초 만에 즉시 보존.
- 서버 사이드 이동 불가 환경 시 로컬 임시 다운로드 후 보존 업로드하는 자동 대체(Fallback) 메커니즘 내장.
- **로컬 격리**: 원격지에 생성된 _conflict_ 보존 파일은 로컬 디렉터리로 절대 다운로드되지 않아 로컬 작업 환경을 깨끗하게 유지.
- **로컬 삭제의 원격 전파**: SQLite Baseline 분석을 통해 로컬에서 삭제된 파일은 원격지에서도 정확히 자동 삭제.

### 5. 실시간 파일 감시 및 동기화 제어

- FileSystemWatcher 기반 실시간 변경 감시 및 디바운싱(DebounceQueue) 처리로 연속된 파일 저장 시 중복 동기화 방지.
- 동기화 진행 중 언제든지 즉시 멈출 수 있는 **동기화 중지(Cancel)** 기능.

### 6. 날짜/시간별 자동 회전 로그

- 프로그램 실행 디렉터리 내 logs/ 폴더에 syncflow_sync_yyyy-MM-dd_HH-mm-ss.log 형식으로 자동 기록.
- 실시간 밀리초 단위 로그 및 UI 로그 뷰어 제공.

---

## 🏗 시스템 구조 및 동작 원리

```mermaid
sequenceDiagram
autonumber
participant UI as 사용자 / SyncFlow App
participant Engine as SyncEngine
participant Local as 로컬 디스크 (syncflow_sync_local.db)
participant Remote as 원격 서버 (syncflow_sync_remote.db)
UI->>Engine: 동기화 시작 (수동/실시간)
Engine->>Remote: 원격 1차 폴더에서 syncflow_sync_remote.db 로드
Engine->>Local: 로컬 파일 스캔 및 Local DB Upsert
Engine->>Remote: 원격 파일 스캔 및 Remote DB Upsert
Engine->>Engine: Local DB vs Remote DB 상호 비교분석 (Cross-DB Diff)

alt 변경 사항 없음 (0 Actions)
Engine->>UI: 동기화 불필요 확인 -> 즉시 완료 (Skip)
else 변경 사항 감지
alt 충돌 발생 (양방향)
Engine->>Remote: 원격 원본을 conflict파일명으로 보존 (서버 내 고속 이동)
Engine->>Remote: 로컬 파일 업로드 (로컬 우선 반영)
else 일반 업로드 / 다운로드 / 삭제
Engine->>Remote: 파일 전송 및 동기화 수행
end
Engine->>Local: Local DB 기준선(Baseline) 갱신
Engine->>Remote: 최신 Remote DB를 원격 1차 폴더에 업로드/저장
Engine->>UI: 동기화 완료 통보
end

```

---

## 🚀 설치 및 실행

사용자 환경에 맞는 최적의 설치 방식을 선택하실 수 있습니다.

### 방법 1. 정식 Windows 설치 마법사 (추천)

- 파일: [dist/SyncFlow_Setup.exe](dist/SyncFlow_Setup.exe) (약 5.4 MB)
- 기본 설치 경로: C:\Program Files\SyncFlow (64비트 시스템 표준 설치)
- 더블 클릭 후 설치 마법사의 안내에 따라 [다음]을 클릭하면 설치가 완료됩니다.
- 한국어 설치 인터페이스, 관리자 권한 자동 요청, 전체 사용자 바탕화면 바로가기 아이콘 생성, 시작 프로그램 등록 옵션, 제어판 프로그램 추가/제거 지원.

### 방법 2. 원클릭 간편 설치 (배치 스크립트)

- 파일: [install.bat](install.bat) 또는 [dist/install.bat](dist/install.bat)
- 더블 클릭 시 관리자 권한으로 자동 승격되어 C:\Program Files\SyncFlow에 자동 복사되고 전체 사용자 바탕화면 및 시작 메뉴 바로가기(SyncFlow.lnk)가 즉시 생성됩니다.

### 방법 3. 포터블 무설치 실행

- 파일: [dist/SyncFlow.App.exe](dist/SyncFlow.App.exe) (단일 실행 파일)
- 별도 설치 과정 없이 원하는 폴더에 복사 후 바로 실행할 수 있습니다.

---

## ⚙ 프로토콜별 연결 설정 가이드

동기화 작업 추가/수정 화면에서 다음과 같이 설정합니다:

> **하위 폴더 자동 매핑 (Auto Subfolder Mapping)**: 로컬 폴더명이 dev_koken이고 원격 대상 경로가 /Backup인 경우, 원격지에 /Backup/dev_koken 폴더가 자동 매핑되어 생성됩니다. 이미 폴더명이 일치할 경우 중복 폴더(/Backup/dev_koken/dev_koken) 생성을 방지합니다.

---

## 🛠 빌드 및 개발 환경

### 개발 환경 요구사항

- **OS**: Windows 10 버전 1809 이상 또는 Windows 11 (x64)
- **SDK**: [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) 이상
- **IDE**: Visual Studio 2022 / VS Code / JetBrains Rider
- **설치 파일 컴파일러 (선택)**: [Inno Setup 6 / 7](https://jrsoftware.org/isdl.php) (winget install JRSoftware.InnoSetup)

### 빌드 및 테스트 실행

```powershell

# 1. 전체 단위 및 통합 테스트 실행 (106개 테스트)

dotnet test tests/SyncFlow.Core.Tests/SyncFlow.Core.Tests.csproj

# 2. 단일 실행 파일 릴리스 배포 빌드

dotnet publish src/SyncFlow.App -c Release -r win-x64 --self-contained false -p:PublishSingleFile=true -o dist/

# 3. Windows 설치 프로그램(Setup.exe) 생성

.\build_installer.bat

```

---

## 📂 프로젝트 구조

```text

SyncFlow/
├── src/
│ ├── SyncFlow.App/ # WPF UI 애플리케이션
│ │ ├── Views/ # 메인 윈도우, 작업 편집, 로그 뷰 등
│ │ ├── App.xaml / MainWindow.xaml # UI 리소스 및 다크 테마 디자인
│ │ └── Program.cs # 진입점 및 인스턴스 중복 실행 제어
│ └── SyncFlow.Core/ # 핵심 비즈니스 로직 및 라이브러리
│ ├── Database/ # SQLite 데이터베이스 엔진
│ │ ├── IndependentSyncDatabase.cs # 개별 SQLite DB 관리 (file_index, baseline)
│ │ ├── DualSyncDatabaseManager.cs # 로컬/원격 듀얼 DB 통합 관리
│ │ └── SyncDatabaseService.cs # 레거시 데이터베이스 서비스 호환 계층
│ ├── Engine/ # 동기화 및 비교 엔진
│ │ ├── SyncEngine.cs # 동기화 실행 파이프라인 및 제어
│ │ ├── DiffEngine.cs # 로컬-원격-기준선 3-Way 비교분석
│ │ ├── ConflictResolver.cs # conflict 무손실 타임스탬프 명명기
│ │ └── FilterEngine.cs # DB 파일 격리 및 제외 패턴 필터링
│ ├── Models/ # 동기화 설정, 작업 모델, DTO
│ ├── Providers/ # 스토리지 프로바이더 구현체
│ │ ├── IStorageProvider.cs # 공통 스토리지 인터페이스 (MoveFileAsync 포함)
│ │ ├── LocalStorageProvider.cs # 로컬 디스크 프로바이더
│ │ ├── SmbStorageProvider.cs # 삼바(SMB / UNC) 프로바이더
│ │ ├── FtpStorageProvider.cs # FTP / FTPS 프로바이더
│ │ ├── SftpStorageProvider.cs # SFTP (SSH.NET) 프로바이더
│ │ └── WebDavStorageProvider.cs # WebDAV (HttpClient) 프로바이더
│ └── ViewModels/ # MVVM 뷰모델 (MainViewModel 등)
├── tests/
│ └── SyncFlow.Core.Tests/ # 106개 자동화 단위/통합 테스트
├── installer/
│ └── SyncFlow.iss # Inno Setup 한국어 설치 마법사 정의 스크립트
├── dist/ # 배포 바이너리 및 Setup.exe 산출물
├── build_installer.bat / .ps1 # 설치 프로그램 자동 빌드 스크립트
├── install.bat / .ps1 # 원클릭 간편 설치 스크립트
├── icon.ico # 애플리케이션 공식 아이콘
├── SyncFlow.sln # Visual Studio 솔루션 파일
└── README.md # 프로젝트 안내 문서
```
---

## 📄 라이선스
본 프로젝트는 [MIT License](LICENSE)를 따릅니다.

댓글 0

게시물 신고