cornerstone

TL;DR: 콘텐츠 저장소(Google Drive)와 배포 파이프라인(Git 저장소)을 분리하면서도 변경 사항을 자동으로 동기화하고 배포하는 아키텍처는, API 기반 접근과 적절한 워커(worker) 계층 설계를 통해 가능하며, 이를 이해하면 '진실의 원천(Source of Truth)'과 '운영 환경' 사이의 간극을 안정적으로 메우는 시스템을 구축할 수 있다.

이 아키텍처는 정적 사이트 생성기나 문서 기반 애플리케이션에서 콘텐츠를 Google Drive와 같은 친숙한 도구로 관리하면서도, 변경 시 자동으로 Git 저장소에 반영되고 배포까지 트리거되는 완전 자동화 흐름을 목표로 한다. 핵심은 Google Drive의 변경을 감지(Watch)하고, Drive API를 통해 실제 콘텐츠를 가져와(Fetch), 미리 정의된 규칙에 따라 로컬 또는 원격 Git 저장소의 특정 경로에 동기화(Sync)한 후, 변경이 있으면 커밋하고 푸시하여 CI/CD 파이프라인을 가동시키는 것이다.

직접적인 구현 시 가장 흔히 마주하는 함정은, 기존의 로컬 파일 시스템 마운트에 의존하는 동기화 스크립트를 클라우드 호스팅된 애플리케이션 서버(예: Vercel에 배포된 Next.js 서버) 내에서 실행하려는 시도다. 이 방식은 여러 근본적인 제약에 부딪힌다. 애플리케이션 서버는 일반적으로 Google Drive Desktop이 마운트한 로컬 경로에 접근할 수 없으며, 특히 서버리스 환경에서는 파일 시스템이 일시적(ephemeral)이고 Git 작업 공간이 존재하지 않을 수 있다. 또한 Google Drive의 웹훅 채널 관리(주기적 재등록 필요)나 장기 실행 작업 처리에도 부적합한 경우가 많다.

따라서 실용적인 아키텍처는 Drive API를 진정한 소스 인터페이스로 사용하고, 동기화 로직을 별도의 워커 프로세스로 분리하는 데서 출발한다. Google Drive는 changes.watch를 통해 변경 알림 웹훅을 제공하지만, 이 알림만으로는 '무엇이' 변경되었는지 알 수 없다. 실제 변경 내용을 확인하려면 알림을 받은 후 changes.list API를 호출하여 변경 목록과 새 pageToken을 얻어야 한다. 이 웹훅 채널은 최대 1주일의 수명을 가지므로, 주기적인 갱신(renwal) 로직이 반드시 필요하다.

동기화 워커를 구현할 수 있는 주요 아키텍처 옵션과 그 트레이드오프는 다음과 같다.

GitHub Actions 중심: 작은 웹훅 수신기(Receiver)가 Google Drive 알림을 받아 GitHub의 repository_dispatch 이벤트를 트리거한다. GitHub Actions 워크플로우가 Drive API를 직접 호출하여 콘텐츠를 가져오고, 저장소를 변경한 후 커밋과 푸시를 수행한다. 장점은 Git 작업이 가장 자연스럽고, GitHub의 생태계를 최대한 활용할 수 있다는 점이다. 단점은 웹훅 수신기라는 작은 서버 요소가 여전히 필요하다는 것이다.
Cloud Run / 서버리스 워커: Google Drive 웹훅을 직접 수신하는 독립적인 서버리스 함수가 모든 동기화 단계(Drive API 호출, Git 작업)를 수행한다. 장점은 클라우드 네이티브하고 애플리케이션 서버와 완전히 분리된다는 점이다. 단점은 인프라 구성이 약간 추가되며, Git 클론/작업 환경을 함수 내에 구성해야 한다.
로컬 머신 워커: Google Drive Desktop이 설치된 개인 머신(예: 개발자의 Mac)에서 웹훅을 수신하거나 폴링(polling)하여 기존의 로컬 파일 시스템 기반 동기화 스크립트를 재사용한다. 장점은 구현이 빠르고 기존 스크립트를 최대한 활용할 수 있다. 단점은 해당 머신이 항상 실행 중이어야 하며, 퍼블릭 웹훅 수신을 위해 추가적인 터널링(ngrok 등)이 필요할 수 있다.

아키텍처 선택 시 고려해야 할 일반화 가능한 원칙은 '관심사의 분리' 와 '도구의 적절한 사용' 이다. 콘텐츠 편집(Google Drive), 버전 관리 및 배포 트리거(Git), 실제 빌드 및 호스팅(CI/CD)은 각각 다른 도구가 가장 잘하는 일이다. 이 아키텍처의 본질은 이 이기종 시스템들을 API와 웹훅으로 신뢰성 있게 연결하는 '접착(glue) 로직'을 설계하는 것이다. 이때 워커 계층은 변경 감지, API 호출, 상태 관리(pageToken 저장), 멱등성(idempotency) 보장(중복 알림 처리)과 같은 안정성 패턴을 반드시 포함해야 한다.

이러한 아키텍처를 Next.js 정적 사이트의 블로그 콘텐츠나 문서를 Google Drive에서 관리하는 구체적인 맥락에 적용한다면, blog 및 zt/literature 폴더의 변경만 필터링하고, Drive 파일 경로를 저장소 내의 src/app/docs/ 하위 경로로 매핑하는 규칙을 정의하게 된다. 또한 이미지와 같은 바이너리 에셋의 처리 방식과 삭제 이벤트의 반영 여부도 초기 설계에서 결정해야 할 사항이다.

Open questions

Google Drive 내의 바이너리 에셋(이미지)을 어떻게 효율적으로 동기화하고 참조할 것인가?
파일 삭제 이벤트를 Git 저장소에서도 삭제로 반영해야 하는가, 아니면 보관용으로 남겨둘 것인가?
여러 사용자가 동시에 Drive를 편집할 때 발생할 수 있는 동시성 문제를 어떻게 완화할 것인가?

Google Drive 기반 콘텐츠 동기화 아키텍처

관련 항목

Open questions