OTA 배포 가이드

00

Concept
구성 이해

OTA가 뭐고, 우리는 어떻게 구성했나

앱은 네이티브 껍데기(스토어에서 설치)와 그 안에서 도는 웹 번들(실제 화면·로직)로 나뉜다. OTA는 껍데기는 그대로 두고 웹 번들만 서버에서 내려받아 교체하는 방식이다. 우리는 Capgo 오픈소스 업데이터를 자체 서버(운영 Supabase)로 운영한다.

앱 쪽 업데이터: 앱 실행 시 새 번들이 있는지 서버에 물어보고, 있으면 받아둔다
번들 저장소: 운영 Supabase의 app-bundles 공개 버킷 — 번들 zip과 최신 버전 정보(latest.json)
갱신 판단 함수: app-update Edge Function — 이 기기에 줄 업데이트가 있는지 판단해서 응답
발행 스크립트: npm run ota:release 한 줄로 빌드 → 업로드 → 최신 정보 갱신까지 수행

반영 시점 — 발행하면 사용자가 앱을 껐다가 다시 켠 다음 실행부터 새 번들이 적용된다. 강제 즉시 반영이 아니라 자연스럽게 퍼지는 방식이다. 수신 대상은 1.0.8 이상 설치분.

01

Decide
OTA vs 네이티브

이 변경, OTA로 나가도 되나

변경된 파일을 보고 결정한다. 기준은 하나 — 네이티브 쪽을 건드렸으면 OTA로는 못 나간다.

변경 범위	배포 방식
웹 코드만 — `src/`, `public/`, 번역 파일, 환경값	OTA — 화면·텍스트·로직 수정 전부 여기 해당
`android/`, `ios/`, `capacitor.config.ts`, 네이티브 플러그인 설치	네이티브 빌드 — 버전 올리고 스토어 배포
둘 다 섞임	네이티브 빌드 — OTA는 새 네이티브 버전 기준으로 이후 재개

라이브러리 추가는 갈린다: 순수 자바스크립트 패키지는 OTA 가능, 네이티브 코드가 딸린 플러그인(카메라, 푸시 등)은 네이티브 빌드가 필요하다.

헷갈리기 쉬운 것 — 운영 웹사이트와 앱 OTA는 별개 채널이다. 웹 코드를 고쳤다면 "웹 배포(main 머지)"와 "앱 OTA" 둘 다 필요할 수 있다.

02

Release
발행

버전 정하고 발행하기

OTA 버전명은 현재 네이티브 버전 + 순번이다. 예를 들어 앱이 1.0.8이고 마지막 OTA가 1.0.8-2였다면 이번은 1.0.8-3.

최신 순번 확인 — 지금 서버에 올라간 마지막 버전을 조회한다

curl -s https://cbopkicwbznhqmxfhpog.supabase.co/storage/v1/object/public/app-bundles/latest.json

발행 — 빌드부터 업로드까지 한 명령으로 끝난다

# 예: 현재 1.0.8-2 → 이번 발행은 1.0.8-3
npm run ota:release -- 1.0.8-3

버전 일치 규칙 — 발행된 번들은 latest.json의 네이티브 버전과 정확히 같은 버전이 설치된 기기에만 전달된다. 개발용(-dev) 빌드는 서버가 차단한다. 네이티브 버전업 직후 첫 OTA를 올리기 전까지 새 설치분이 내장 번들로 도는 건 정상이다.

03

Verify
검증

발행 후 2가지 확인

최신 버전 정보 갱신 확인 — 위의 latest.json 조회를 다시 실행해 방금 올린 버전이 보이는지 확인
갱신 판단 함수 응답 확인 — 실제 앱이 묻는 방식 그대로 물어봐서 새 버전과 다운로드 주소를 돌려주는지 확인

# version_build = 현재 네이티브 버전명
curl -s -X POST https://cbopkicwbznhqmxfhpog.supabase.co/functions/v1/app-update \
-H "Content-Type: application/json" \
-d '{"platform":"android","version_build":"1.0.8","version_name":"builtin"}'

응답에 방금 발행한 버전과 번들 주소가 담겨 있으면 정상. 이후 실기기에서 앱을 껐다 켜고 두 번째 실행에 반영되는지 보면 확실하다.

04

Rollback
되돌리기

문제가 생기면 — 앞으로 롤백

잘못된 번들이 나갔다면 이전 상태의 코드를 새 순번으로 다시 발행한다. 예: 1.0.8-3이 문제라면 1.0.8-2 시점 코드를 1.0.8-4로 발행.

같은 버전명 재발행은 무시된다 — 앱은 이미 받은 버전명을 다시 받지 않는다. 되돌릴 때도 반드시 새 순번으로.

건드리면 전체 장애가 나는 두 곳 — 수정 전 반드시 팀에 공유할 것.

부팅 확인 신호 컴포넌트 제거 금지 — 앱이 "새 번들로 정상 부팅됐다"고 알리는 장치가 빠진 번들을 OTA로 내보내면, 전 기기가 매번 이전 번들로 롤백하는 무한 루프에 빠진다
갱신 판단 함수 재배포 시 인증 예외 옵션 필수 — 옵션을 빼먹고 배포하면 앱 요청이 전부 거부돼 OTA가 전면 중단된다

—

Checklist
발행 루틴

발행할 때마다 이 순서로

변경 diff에 네이티브 쪽 파일이 없다 (있으면 네이티브 빌드로 전환)
latest.json을 조회해 마지막 순번을 확인하고 +1로 버전을 정했다
npm run ota:release -- <버전> 발행이 에러 없이 끝났다
발행 후 latest.json에 새 버전이 반영됐다
갱신 판단 함수 응답에 새 버전과 번들 주소가 담겨 온다
웹 코드 변경이면 운영 웹 배포도 별도로 필요한지 확인했다

체크가 저장되지는 않아요!