3만 개 사이트에 1초 미만 콘텐츠 업데이트를 제공하는 GitBook의 비결

Vercel 위의 GitBook

• 단일 Vercel 배포로 운영되는 3만 개의 문서 사이트

• 엣지에서 처리되는 월 1억 2천만 페이지뷰

• 하루 4만 건의 캐시 무효화 처리, 건당 300ms 이내 완료

• 전체 트래픽의 41%가 AI 크롤러 및 자동화 시스템에서 발생

GitBook은 Vercel 위에서 3만 개의 문서 사이트를 운영하며, 매월 1억 2천만 페이지뷰를 처리하고 있다. n8n, Nvidia, Zoom 같은 기업들이 이 플랫폼을 믿고 자사 문서의 속도와 최신성을 맡기고 있다. 현대 엔지니어링 팀과 코딩 에이전트에게 문서는 실제 프로덕션 코드만큼이나 중요한 자산이며, GitBook은 그 기대의 중심에 서 있다.

GitBook의 퍼블리싱 방식은 팀이 소프트웨어를 배포하는 흐름과 닮아 있다. 변경 사항을 제안하고, 검토한 뒤, 머지하는 방식이다. 그런데 각자의 업데이트 주기를 가진 3만 개 사이트를 동시에 운영하면서 콘텐츠를 빠르고 최신 상태로 유지하는 것은 결코 단순한 문제가 아니었다. Vercel로 이전하기 전, 사이트 편집자가 머지 버튼을 누르고 배포된 사이트를 확인하러 가면 여전히 이전 버전의 콘텐츠가 보이는 일이 반복됐다. GitBook의 엔지니어링 총괄 Steven Hall은 이렇게 말한다. "한 고객사가 대규모 기능 출시를 준비했는데, 런칭 당일에 문서가 제품보다 뒤처져 있었습니다. 그 순간, 문서도 프로덕션 코드만큼 중요하다는 사실을 뼈저리게 깨달았죠."

멀티테넌트 환경에서 머지와 동시에 라이브 반영하기

GitBook의 퍼블리싱 콘텐츠 프런트엔드는 Next.js 기반의 오픈소스 프로젝트다. Vercel의 use cache 지시어가 공개되자, 팀은 속도 문제를 해결할 실마리를 찾았다. 전체 페이지 응답이 아닌 개별 데이터 패칭 함수 단위로 캐시를 적용하는 방식이었다. 이를 통해 비용이 큰 API 호출은 요청 간에 중복 제거되고, 캐시 동작 방식도 외부 설정 파일 속에 묻히는 대신 코드 안에서 직접 확인할 수 있게 됐다.

더 까다로운 문제는 캐시 무효화였다. 멀티테넌트 시스템에서 캐시를 전체 삭제하는 방식은 비용도 크고 낭비도 심하다. 한 팀이 오탈자 하나를 수정했다고 해서 나머지 2만 9,999개 사이트까지 재검증이 일어나서는 안 된다. GitBook에는 이미 콘텐츠가 오래됐음을 알리는 신뢰할 수 있는 신호가 있었다. GitBook 앱, GitHub, GitLab 어느 경로로든 발생하는 머지 이벤트가 바로 그것이다. 팀은 이 이벤트를 트리거로 삼아 태그 기반 무효화 방식을 구축했다. 캐시된 데이터는 콘텐츠 단위로 태그가 붙고, 머지가 발생하면 해당 태그에 연결된 데이터만 재검증된다. 나머지는 캐시 상태를 그대로 유지한다.

이제 변경 사항이 머지되면, 300밀리초 이내에 업데이트된 콘텐츠가 전 세계에 반영된다. GitBook은 하루에 이런 무효화 작업을 4만 건씩 처리한다. Hall은 말한다. "자체 캐싱을 직접 구축하는 것 외에 다른 방법은 사실 고려하지도 않았습니다."

트래픽의 41%가 사람이 아닐 때 달라지는 것들

2025년 GitBook 문서로 유입되는 AI 트래픽은 전년 대비 5배 급증했고, 현재 전체 페이지뷰의 41%를 차지한다. LLM과 자동화 시스템들이 GitBook을 내부 툴링, SDK, AI 애플리케이션의 신뢰할 수 있는 정보 원천으로 삼아 프로그래밍 방식으로 문서를 크롤링하고 있다.

이는 인프라 계산 방식 자체를 바꿔놓는다. 사람이라면 하나의 문서 사이트에서 몇 개 페이지만 둘러보고 끝내지만, AI 크롤러는 단 한 번의 세션에서 수백 개 사이트의 모든 페이지를 훑으며 사람이라면 절대 방문하지 않을 콜드 캐시 경로까지 건드린다. 이것이 3만 개 사이트 전체로 확산되면, 캐싱 구조가 감당해야 하는 것은 단순히 더 많은 트래픽이 아니라 근본적으로 예측하기 어려운 트래픽이다. 변경 후에는 콘텐츠가 즉시 일관되게 반영돼야 하고, 트래픽이 늘어도 인프라 비용은 예측 가능한 수준을 유지해야 한다.

Hall은 AI를 특별히 의식하고 이 캐싱 아키텍처를 선택한 것은 아니었지만, 결과적으로 딱 맞는 토대가 됐다고 말한다. "AI가 읽든 사람이 읽든, 문서는 빨라야 합니다. 목표는 캐시 히트율 100%에 가깝게 가져가는 것입니다. 캐시 히트는 빠른 문서를 의미하고, 빠른 문서는 GitBook의 핵심 기능이니까요."

다음 3만 개 사이트를 향해

캐싱 인프라는 아직 완성된 것이 아니다. 읽는 대상에 따라 콘텐츠를 다르게 제공하는 어댑티브 문서 같은 기능은 멀티테넌트 캐싱을 한층 복잡하게 만든다. AI 트래픽이 계속 늘어날수록 3만 개 사이트를 통해 흐르는 요청 규모도 함께 커질 것이다.

"어디를 봐도 트래픽이 오르고 있습니다. 엔지니어들이 더 많이 배포할수록 문서 변경도 늘어납니다. LLM은 매일 더 많은 페이지를 크롤링합니다. 규모가 커져도 지연 시간과 예측 가능성에 대한 높은 기준을 유지하는 것이 우리의 최우선 목표입니다." Hall의 말이다.

GitBook은 3만 개 이상의 팀이 제품 및 개발자 문서를 대규모로 생성·배포·관리하는 데 활용하는 AI 네이티브 문서 플랫폼이다. GitBook의 퍼블리싱 콘텐츠 프런트엔드는 오픈소스로 공개되어 있다.