WebDAV 동기화
개요
WebDAV 동기화는 사용 중단된 Git 동기화를 대체하는 Synthesis Workbench의 크로스 디바이스 동기화 메커니즘입니다. WebDAV 프로토콜을 통해 결정론적 영속 상태 번들 스냅샷을 교환합니다.
WebDAV 호환 서버(Nextcloud, ownCloud, Synology 등)와 함께 작동합니다. Git은 필요하지 않습니다.
사전 요구 사항
- 접근 가능한 WebDAV 서버
- WebDAV 자격 증명 (사용자 이름 + 비밀번호 또는 앱별 토큰)
구성
Zotero → 설정 → Zotero Agents → WebDAV Sync
| 설정 | 유형 | 기본값 | 설명 |
|---|---|---|---|
| WebDAV 동기화 활성화 | boolean | false | 마스터 토글 |
| Base URL | string | "" | WebDAV 서버 URL, 예: https://nextcloud.example.com/remote.php/dav/files/user/ |
| 원격 경로 | string | "zotero-agents" | Base URL 하위의 원격 디렉토리 |
| 사용자 이름 | string | "" | WebDAV 사용자 이름 (선택 사항) |
| 비밀번호 / 앱 토큰 | encrypted | "" | 비밀번호 또는 토큰 (AES-256-GCM 암호화) |
| 자동 동기화 | boolean | false | Synthesis 변경 후 자동으로 동기화 트리거 |
| 자동 재시도 | boolean | false | 일시적 실패 자동 재시도 |
작업 버튼:
- 설정 저장: 자격 증명을 제외한 설정을 저장
- 자격 증명 저장: 비밀번호/토큰을 암호화하여 저장
- 연결 테스트: PROPFIND 요청을 보내 연결을 확인
원격 파일 레이아웃
<remotePath>/
├── HEAD.json # 현재 스냅샷 포인터
└── snapshots/
└── <snapshotId>/
├── manifest.json # 영속 번들 매니페스트
└── bundles/ # 결정론적 영속 번들 파일
HEAD.json에는 snapshot_id, manifest_hash, updated_at, producer_version이 포함됩니다. 스냅샷은 HEAD가 업데이트되기 전에 완전히 업로드됩니다 — 중단된 동기화는 원격 데이터를 손상시키지 않습니다.
동기화 대상
| 동기화됨 | 동기화되지 않음 |
|---|---|
| 토픽 | SQLite 런타임 데이터베이스 |
| 개념 (개념, 의미, 별칭, 관계) | 런타임 로그 |
| 토픽 그래프 (노드, 엣지) | 작업 공간 파일 |
| 참고문헌 (바인딩, 리다이렉트) | 큐 및 잠금 상태 |
| 리뷰 항목 | 재구축 가능한 프로젝션 (인용 레이아웃, 지표, 캐시) |
| 태그 (제어된 어휘) | 자격 증명 |
| 관련 항목 | 임시 파일 |
동기화 흐름
idle → queued → syncing → idle
├── blocked_conflict (수동 해결 필요)
└── failed_retryable / failed_permanent
| 단계 | 설명 |
|---|---|
| 1. HEAD | 원격 HEAD.json 읽기 |
| 2. 다운로드 | 더 최신 스냅샷이 있으면 매니페스트 + 번들 다운로드 |
| 3. 미리보기 | 가져온 스냅샷 검증, 엔티티 해시 비교 |
| 4. 충돌 확인 | 양방향 변경 감지 |
| 5. 적용 | 원격 스냅샷을 로컬 Canonical Store로 가져오기 |
| 6. 내보내기 | 현재 로컬 상태를 번들로 내보내기 |
| 7. 업로드 | 매니페스트 + 번들 업로드 |
| 8. HEAD 업데이트 | HEAD.json을 마지막으로 업데이트 (동시성 안전을 위한 ETag/If-Match) |
충돌 처리
충돌 감지는 엔티티 수준의 해시 비교를 기반으로 합니다. 동일한 엔티티가 로컬과 원격 양쪽에서 변경되었을 때 충돌이 발생합니다.
충돌 유형:
- 양방향 엔티티 수정
- 업데이트 vs. 툼스톤 충돌
- 리뷰 항목 불일치
- 참고문헌 바인딩/리다이렉트 대상 불일치
해결 작업:
| 작업 | 설명 |
|---|---|
keep_local | 로컬 상태 유지, 충돌 게이트 닫기, 다음 내보내기 큐에 추가 |
clear_after_manual_edit | 수동 병합 후 재검증; 해결되면 충돌 마커 제거 |
Workbench 홈 페이지의 동기화 패널에 충돌 상세 정보와 작업 버튼이 표시됩니다.
보안
- 자격 증명 암호화: AES-256-GCM, Host Bridge 마스터 토큰 기반 키 (PBKDF2-SHA256, 100,000 반복)
- 평문 반환 안됨: 저장 후 자격 증명을 읽을 수 없음
- URL 청소: 로그 출력에서 자격 증명이 제거됨
- HTTP Basic Auth: HTTPS를 통한 표준 Basic 인증
제한 사항
| 제한 사항 | 상세 |
|---|---|
| 기본적으로 수동 | 자동 동기화 및 자동 재시도는 기본적으로 꺼져 있음 |
| 압축 없음 | v1 스냅샷은 원시 JSON 번들 |
| 오래된 스냅샷 정리 없음 | 원격 스냅샷이 누적됨; 수동 정리 필요 |
| 필드 수준 병합 없음 | 충돌은 엔티티 수준에서 발생 |
| 단일 디바이스 가정 | 여러 디바이스의 동시 쓰기는 충돌을 일으킬 수 있음 |