Obsidian Self-hosted LiveSync, 신규 기기 최초 동기화가 761/23585에서 계속 멈출 때 (Fast fetch heartbeat 버그 #953)

환경: Obsidian 1.12.7(Kubuntu 26.04) · Self-hosted LiveSync(CouchDB 백엔드) · 노트 300여 개(CouchDB 문서 23,000+)

TL;DR / 빠른 해결

받을 문서(노트+청크)가 수천~수만 개인 볼트에 신규 기기를 붙일 때 최초 fetch가 매번 같은 자리에서 멈춘다면, LiveSync Fast fetch의 heartbeat 부재(≈60초 컷) 문제다. Setup URI 자동 fetch를 쓰지 말고, "이 장치의 동기화 상태 재설정"(Reset and Resume Synchronisation) 마법사로 받는다 — batch 방식이라 스트리밍 타임아웃을 안 탄다.

증상

Obsidian 볼트를 Self-hosted LiveSync(CouchDB)로 굴린다. 기존 4대(윈도우·폰·라즈베리파이·미니PC)는 이미 동기화가 끝나 문제없었는데, 새로 세팅한 쿠분투 데스크탑을 처음 붙이니 최초 동기화(cold fetch)가 매번 같은 자리에서 멈췄다.

Setup URI로 붙이면 자동으로 "Fast fetch"가 도는데, 진행률이 매번 761~781 / 23585 근처에서 멈췄다고 사용자가 콘솔 로그를 보내왔다.

여기서 "문서 23,585개"는 노트 개수가 아니다. 실제 노트는 300여 개인데, LiveSync가 각 노트 내용을 여러 청크로 쪼개 저장하고 거기에 고아 청크·플러그인 거대 청크(아래 "부수 정리" 참고)까지 쌓여서 CouchDB 문서 수가 이만큼 불어난 것이다. 그리고 받을 문서가 많을수록 아래의 60초 컷에 더 잘 걸린다.

Starting initial synchronisation. ... Total documents to fetch: 23585
Fast fetch progress: 25 / 23585
Fast fetch progress: 50 / 23585
...
All documents fetched. Stopping the stream…
Error during vault initialisation process

23,585개를 받아야 하는데 700개대에서 갑자기 "다 받았다(All documents fetched)"며 스트림을 닫고, 미완성 데이터로 볼트를 초기화하려다 Error during vault initialisation process를 뱉는다. 그리고 리셋 → 재시도 → 같은 자리에서 또 멈춤이 무한 반복돼 완주가 안 됐다.

오진 배제 (여기서 시간 다 날림)

멈추는 지점이 항상 비슷해서 처음엔 "761번째 근처의 특정 문서가 손상됐나?"를 의심했다. 아래는 전부 원인이 아니었다 — 같은 걸로 헤맬 사람을 위해 남긴다.

• 플러그인 버전: 0.25.83 ↔ 0.25.73 교체해도 둘 다 똑같이 실패. 무관.
• E2EE 알고리즘: 폰·리눅스 모두 V2로 일치. 무관.
• 전송 문제(tailscale): 스트리밍 _changes 응답 23,560줄·버퍼 46MB가 전부 정상 전달. localhost로 직접 받은 바이트와 동일 → 중간에 잘린 게 아님.
• 로컬 캐시 cruft: 완전히 새로 만든 빈 볼트에서도 동일하게 실패 → 클라이언트 캐시 문제 아님.
• 손상·거대·미암호화 문서: CouchDB 전수검사 → 매달린 참조 0, 미암호화 leaf 청크 0, 손상된 삭제 엔트리 0. 특정 문서 문제 아님.

즉 "특정 문서"나 "데이터 청소"로 접근하는 방향은 전부 헛발질이었다.

근본 원인: 특정 문서가 아니라 시간 기반 컷(heartbeat 부재)

멈추는 지점이 761~781로 매번 비슷했던 건 사실 두 겹이 겹쳐 있었다. 처음엔 플러그인 거대 청크(아래 "부수 정리" 참고)가 761 부근에서 fetch를 먼저 틀어막았고, 그걸 치우자 멈춤이 781로 밀렸다 — 남은 건 **특정 문서가 아니라 "약 60초 동안 받은 문서 수"**에서 끊기는 순수 시간 기반 컷이었다. 이게 핵심이다.

LiveSync의 Fast fetch가 CouchDB _changes 스트리밍 연결을 heartbeat 없이 연다. 그러면 연결이 열린 지 약 60초 뒤에 CouchDB가 그 연결을 유휴(idle)로 보고 끊어버린다. 클라이언트는 이 정상 종료를 "모든 문서를 다 받았다"로 오인하고 스트림을 닫은 뒤, 700여 개짜리 미완성 데이터로 볼트를 초기화하려다 실패한다. 받을 문서가 많을수록(60초 안에 다 못 받을수록) 반드시 걸린다 — 여기선 노트가 300여 개여도 청크로 문서가 2만 개 넘게 불어나 60초 안에 못 끝냈다. 문서가 적어 60초 안에 완주하면 이 버그는 안 보인다.

업스트림에 이미 보고돼 있다 — GitHub vrtmrz/obsidian-livesync #953.

해결: detailed flow (Fast fetch 쓰지 말 것)

신규 기기 최초 동기화 때 Setup URI가 자동으로 돌리는 fast fetch를 쓰지 말고, 수동 재설정 마법사로 받으면 된다. 이건 batch 방식이라 스트리밍 타임아웃을 안 탄다.

플러그인 설정에서 "이 장치의 동기화 상태 재설정" → "Reset and Resume Synchronisation" 마법사를 열고, 사용자에게 이렇게 고르도록 안내했다.

• 볼트 상태: "This Vault is empty, or contains only new files that are not on the server."(빈 볼트로 새로 붙이는 상황)
• 백업 확인: "I have created a backup of my Vault."
• Advanced의 "Prevent fetching configuration from server"는 체크하지 말 것(서버의 E2EE 설정을 받아와야 함).

이렇게 받으니 23,000개가 넘는 문서를 끝까지 완주했다. 팁: 정식 볼트명(예: 원하는 폴더명)으로 빈 폴더를 새로 만들어 이 절차로 붙이면 깔끔하다.

부수 정리: Customization Sync는 꺼두기

진단 중 별개로, DB가 실제 볼트(2.8MB) 대비 26배까지 부풀어 있는 것도 발견했다. 원인은 LiveSync의 Customization Sync가 플러그인 main.js를 통짜 거대 단일 청크로 저장해둔 것 — 이 거대 청크가 fetch를 앞에서 먼저 틀어막기도 했다. 사용자에게 CouchDB에서 이 문서·거대 청크를 정리하고 컴팩션하도록 안내했다.

재발 방지: 모든 기기에서 LiveSync "사용자 설정 동기화(Customization Sync)"는 OFF로 유지한다. 켜두면 플러그인 바이너리가 거대 청크로 다시 쌓여 DB를 부풀리고 fetch를 막는다. 테마·스니펫·appearance 동기화는 무방하고, 플러그인은 각 기기에 따로 설치하면 된다.

교훈 / 체크리스트

• 받을 CouchDB 문서(노트+청크)가 수천~수만 개인 볼트에 신규 기기를 붙일 땐 무조건 detailed flow(Reset and Resume)로 받는다. Fast fetch는 heartbeat가 없어 ≈60초 컷에 걸려 실패한다(업스트림 #953이 고쳐지기 전까지). ★노트 수가 적어도 청크·고아청크로 문서 수가 부풀면 걸릴 수 있다.
• 멈춤 지점이 "매번 비슷한 숫자"면 특정 문서가 아니라 **시간 기반 컷(타임아웃)**을 의심하라. "N번째 문서"가 아니라 "N초 동안 받은 양"일 수 있다.
• DB 비대화(고아 청크·플러그인 바이너리)는 이 버그와 별개로 관리한다 — Customization Sync를 꺼서 애초에 안 쌓이게.