Github LFS 대역폭 초과로 인한 장애 극복하기

최근 팀 프로젝트를 진행하면서 GitHub 저장소의 Git LFS 대역폭 초과로 인해 심각한 문제가 발생했다.
이 문제는 개발 흐름을 중단시킬 만큼 치명적이었고, 자체 Git 서버(Gitea) 구축으로 문제를 해결했다..
이 글에서는 장애가 어떻게 발생했고, 어떤 대처를 했으며, 향후 어떻게 컨트롤할지를 기록해둔다.

문제 설명

한달이라는 짧은 기간의 프로젝트 진행 중 2주차…
즉, 절반을 지나가던 시점 새벽에 문제가 발생했다.

 

내가 작업한 브랜치를 병합한 뒤 Main 브랜치에 체크아웃하여 결과를 확인하고 후속 작업을 하기 위해 Main 브렌치를 Pull 받는 과정에서 LFS로 관리되는 애셋들이 올바르게 표시되지 않는 문제가 발생하면서 발견했다.

 

이를 뒤늦게 파악한 우리는 병합한 내용을 확인하기 위해 Main 브랜치를 체크아웃 시도하고 있었고 로컬 파일이 손상되는 문제를 겪게 되었다.

안타깝게도 최신 Main 브랜치의 데이터를 가지고 있는 팀원이 없어 프로젝트에 위기가 찾아오게 되었다.

문제 요약

1. Git LFS 대역폭이 초과되어 LFS 파일이 Pull 되지 않음
2. 브랜치에 체크아웃 시 LFS 파일이 포인터 형태로만 존재
3. 다른 브랜치로 전환할 때 작업 파일이 손상될 우려 발생
4. 전반적인 개발 흐름 마비

원인 파악

• GitHub Free 요금제는 월 10GiB의 Git LFS 대역폭 제한이 있으며, 이 한도를 초과할 경우 더 이상 LFS 파일을 받을 수 없게 된다.
• 게다가 최근 대역폭이 1GiB로 대폭 축소될 예정이라는 공지가 있었고, 이것이 장애의 직접적인 원인이 되었다.

해결책 탐색

가장 간단한 방법은 Github의 LFS 대역폭을 상향하는 것.

• 하지만 우리는 가난한 학생들이고, 게임 개발 중이기 때문에 많은 대역폭이 필요하게 됨을 직감했다.
• 중요한 BGM, SFX, VFX 및 애니메이션이 추가되지 않았고 머지 않아 매우 큰 파일들이 대량으로 추가될 것이라는 것을 어린아이도 쉽게 상상할 수 있었다.

대안) 새로운 Git Server를 구축한다.

• 장기적으로 외부 대역폭에 의존하지 않고 내부적으로 사용할 수 있는 자체 Git Server를 구축한다.
• 다행히 나에게는 개인 NAS가 있었고 여기에 자체 Git Server를 설치할 수 있겠다는 판단이 섰다.
• Git Server 후보로는 GitLab과 Gitea 가 떠올랐다.
• GitLab의 경우 CI/CD와 DevOps 기능을 다양하게 제공해준다.
• 하지만 구축이 상대적으로 복잡하고 가정집의 NAS 성능으로는 부담스러운 자원을 요구하고 있었다.
• 따라서 빠르고 간단히 구축할 수 있는 Gitea를 선택하게되었다.

문제 해결 과정

1. 자체 Git Server 구축 (Gitea)

장기적으로 요금 절약을 위해 Github 정책에 영향받지 않는 내부용 Git Server를 구축할 필요가 있었다.

그래서 NAS에 Gitea를 설치하고 Github 저장소를 이관하기로 결정했다.

• Gitea 장점
  • NAS에서도 동작 가능 (경량 서버)
  • GitHub와 유사한 UI 제공
  • Git 히스토리 및 파일 전부 이전 가능

2. Github LFS 대역폭 제한 임시 상향

• 온전한 데이터는 Github에만 존재하는 상태
• 마이그레이션을 위해서는 다운로드 대역폭이 필요하여 임시로 대역폭을 상향

3. Github -> Gitea 마이그레이션

• Github에 있는 히스토리와 파일을 모두 Gitea로 마이그레이션을 진행

4. Gitea -> Github Mirror Push 설정

• Gitea에 커밋등의 이벤트가 발생하면 Github로 Mirror Push를 통해 백업한다.
• Github의 LFS는 1GiB용량 제한과 다운로드 대역폭 제한이 있다.
• 하지만, 업로드 시에는 다운로드 대역폭을 소모하지 않는다.

리스크 대응

Gitea 서버를 구축한 뒤 예상되는 리스크

• NAS 또는 라우터 장애
• 정전 등의 전원 문제
• 유지 보수 중 장애 대응 프로세스 미비
• 기술적 문제로 데이터 유실
• 외부 공격으로 인한 장애 혹은 보안 문제

리스크 대비 운영 내용

• Github로 수시로 데이터를 백업한다.
• Webhooks를 이용해 Gitea의 이벤트 발생시 알림 메세지를 발송한다.
• NAS의 DSM 관리페이지는 내부 IP에서만 접속할 수 있도록 처리.
• SSL -> VPN 프록시를 통해서 접속하도록 방화벽 설정
• NAS에서 내 네트워크에 접근하는 것은 차단해서 분리 조치
• Gitea이 예기치않게 종료될 경우 자동 재시작 설정

아쉽게도 UPS 등의 대응은 금전적인 이슈로 어렵다고 판단해 집에 정전이 발생하지 않기를 기도하고 있다.

리모트 정책 변경

기존 -> 현재 순으로 기재한다.

• 메인 리모트 : Github -> Gitea
• 서브 리모트 : 없음 -> Github
• LFS 정책 : Github에서 Pull/Push -> Gitea에서 Pull/Push
• 미러링 방식 : 수동 푸시 -> Gitea > GitHub 자동 푸시

Jira 연동 대신 백링크 방식으로 대체

우리는 프로젝트 초기부터 Jira를 메인 이슈 트래커로 사용해왔고, 업무 흐름상 Jira의 워크플로우와 대시보드, 스프린트 관리에 많이 의존하고 있었다.

하지만 Gitea는 Jira와 공식적인 연동을 지원하지 않기 때문에, 다음과 같은 방식으로 제한적으로 연계하여 사용하고 있다

• 커밋 메시지나 PR 제목에 Jira 이슈 키 (JIRA-123)를 명시
• Jira 이슈 화면에서 백링크(backlink) 형태로 커밋 내역이 자동 표시됨
• 예를 들어 커밋 메시지에 "Fix JIRA-101: 로그인 오류 수정"을 적으면, Jira의 JIRA-101 이슈에 해당 커밋이 자동으로 링크됨

이를 통해 개발 내역은 Jira 이슈에 자연스럽게 연결되며, Jira의 이슈에 커밋 내역이 링크된다.

✅ 즉, Gitea는 Git 저장소 역할만, Jira는 이슈 관리 역할만 수행하도록 분리된 구조로 운영 중이다.
아쉽게도 PR은 Jira의 이슈 화면에 연결되지는 않는다.

마무리하며

이번 장애는 단순히 GitHub LFS 용량을 초과했다는 문제로 끝나는 게 아니라, 내가 사용하는 도구에 얼마나 의존하고 있었는지를 돌아보게 만든 사건이었다.

 

기존에는 GitHub라는 안정적인 플랫폼을 사용하고 있었지만, 막상 문제가 생기니 우리가 직접 해결할 수 있는 부분이 많지 않다는 걸 느꼈다.

 

그래서 이번에 Gitea로 옮기게 된 건 단순한 대안이라기보단, 앞으로 비슷한 상황이 생겼을 때 대응할 수 있는 기반을 마련한 선택이었다.

물론 개인 NAS에서 Git 서버를 운영한다는 건 새로운 부담이기도 하다.

 

백업, 보안, 장애 대응 등 신경 써야 할 게 더 많아졌지만, 그만큼 더 유연하고, 필요한 만큼 확장 가능한 구조를 갖추게 됐다.

Jira처럼 꼭 필요한 툴은 그대로 쓰고, Gitea는 순수하게 Git 저장소로만 활용하는 지금의 구조도 꽤 만족스럽다.

 

아직 완벽하진 않지만, 최소한 다음에 또 문제가 생기더라도 내가 직접 대응할 수 있다는 자신감은 생긴 것 같다.