이번 주 전까지 우리 앱이 크래시 났다는 걸 아는 방법은 누군가 알려 주는 것뿐이었습니다. 그런데 대부분은 알려 주지 않습니다. 앱을 다시 열고, 또 꺼지면 그냥 안 쓰게 되죠. API 쪽은 대비가 돼 있었습니다(ERROR 로그는 전부 팀 채팅 채널로 갑니다). 하지만 휴대폰에서 일어난 크래시는 제가 볼 수 있는 어디에도 흔적을 남기지 않았습니다.

사실 앱에 리포터가 하나 있긴 했습니다. 앱이 사용자에게 오류 메시지를 보여 주면 그 메시지를 API의 작은 엔드포인트로 보내고, 서버가 이를 ERROR로 기록하니 채팅 채널에도 올라옵니다. 삭제가 실제로는 성공했는데 목록에 행이 그대로 남아 있었고, 그걸 다시 탭하자 “No Item matches the given query"가 뜬 일이 있었습니다. 그때 만든 장치입니다. 서버는 평범한 404 두 개만 기록하고 아무 말도 하지 않았거든요. 이건 앱이 잡아서 보여 주는 오류만 다룹니다. 크래시는 다릅니다. 리포트를 보내야 할 JavaScript 자체가 방금 죽어 버린 거니까요.

뻔한 해법은 Sentry입니다. 저는 Sentry SDK를 꽤 좋아합니다. React Native에서 크래시 리포팅이 이미 해결된 문제처럼 느껴지는 건 이 SDK 덕분이죠. 다만 사용자 데이터를 쥐고 있는 업체가 하나 더 늘고, 개인정보 처리방침에 한 줄이 더 붙고, 우리 규모로는 하루에 많아야 몇 건인 일에 청구서가 또 하나 생기는 건 원하지 않았습니다. 그래서 SDK는 남기고 서비스만 바꿨습니다. 앱의 DSN은 우리 API를 가리키고, 그 Django 앱의 작은 한 부분이 SDK가 보내는 걸 받아서 묶고, 알리고, 보관합니다.

이 글은 그 구조와, 실제 네이티브 크래시가 정말 끝까지 도착하는지 확인한 과정에 대한 이야기입니다.

DSN 트릭

#

Sentry DSN은 https://<public-key>@<host>/<project-id> 형태입니다. SDK는 이를 https://<host>/api/<project-id>/envelope/로 가는 POST로 바꾸고, 키는 X-Sentry-Auth 헤더에 넣습니다. sentry.io에만 해당하는 부분은 하나도 없습니다. 그래서 앱에 박아 둔 DSN은 이렇습니다.

https://<CRASH_REPORT_KEY>@api.example.com/1

그리고 Django에는 SDK가 호출할 주소와 똑같은 라우트를 둡니다.

path("api/<int:project_id>/envelope/", crash_envelope, name="crash_envelope"),

키는 모든 바이너리에 들어 있으니 비밀이 아닙니다. 엔드포인트에 쓰레기가 몰리기 시작하면 바꿀 수 있게, 그리고 서버에 키가 설정되지 않았을 때 아무거나 다 받는 대신 전부 거절하게 하려고 있는 겁니다.

def crash_envelope(request, project_id):
    expected = settings.CRASH_REPORT_KEY
    if not expected:
        return Response({"detail": "Crash reporting is not configured"}, status=503)
    if not hmac.compare_digest(_key(request).encode(), expected.encode()):
        return Response({"detail": "Unknown key"}, status=401)
    ...

_key는 X-Sentry-Auth 헤더에서 sentry_key=를 읽고, 없으면 쿼리 스트링을 봅니다. 일부 SDK는 쿼리 스트링을 쓰기 때문입니다.

SDK가 보내는 것: envelope

#

Sentry의 전송 형식은 envelope입니다. JSON 헤더 한 줄 뒤에 아이템이 여러 개 이어지고, 각 아이템은 JSON 헤더 한 줄과 페이로드로 이루어집니다. 아이템 헤더에 length가 있으면 페이로드는 정확히 그 바이트 수만큼이고, 없으면 다음 줄바꿈까지입니다.

{"event_id":"9ec79c33...","dsn":"https://...@api.example.com/1"}
{"type":"event","length":4123}
{ ...the event JSON, 4123 bytes... }
{"type":"client_report"}
{"timestamp":1791400000.5,"discarded_events":[]}

여기서 두 가지에 걸려 넘어졌습니다.

• 네이티브 SDK는 본문을 gzip으로 압축하고, JavaScript SDK는 하지 않습니다. @sentry/react-native가 잡은 JS 오류는 평문으로 오지만, sentry-cocoa나 sentry-android가 보낸 네이티브 크래시는 Content-Encoding: gzip으로 옵니다. 디코더는 gzip, zlib로 감싼 deflate, raw deflate를 모두 처리하고, 압축 해제는 1MB에서 멈춥니다. 크래시 이벤트는 몇 KB 수준이라 그보다 크면 크래시 리포트가 아니니까요.
• 길이가 붙은 페이로드에는 줄바꿈이 들어 있을 수 있습니다. \n으로 쪼개면 네이티브 SDK가 보내는 이벤트를 전부 망가뜨립니다. length가 있으면 반드시 그걸 따라야 합니다.

파서는 짧습니다. event 아이템만 남기고, 세션·트랜잭션·첨부 파일·클라이언트 리포트는 받기만 하고 버립니다.

SDK가 알아듣는 방식으로 응답하기

#

생각보다 중요한 부분이었습니다. SDK는 디스크에 큐를 두고, 전달됐는지 확신이 없는 건 다시 보냅니다. 그러니 서버의 응답이 SDK가 계속 재시도할지를 결정합니다.

• 200: 저장했을 때, 또는 일부러 버렸을 때. 세션 아이템에 4xx로 답하면 SDK는 그걸 붙들고 영원히 재시도합니다.
• 429와 Retry-After: 스로틀에 걸렸을 때. 엔드포인트에는 IP당 스로틀(시간당 120건)이 있습니다. 크래시 루프에 빠진 폰은 실행할 때마다 리포트를 하나씩 보내기 때문이고, SDK는 429를 받으면 기대한 대로 물러납니다.
• 400: envelope가 깨졌을 때. 이건 에러가 아니라 경고로 기록합니다. 깨진 리포트는 클라이언트가 고장 났다는 뜻이고, 다음에 오는 정상 리포트가 무엇이 크래시 났는지 알려 줄 테니까요.

SDK는 첫 전송이 도착했는지 확신이 없으면 같은 이벤트를 다시 보내기도 합니다. 그래서 event_id에 unique 제약을 걸었고, 중복은 조용히 무시됩니다.

소스 맵 없이 묶기

#

직접 만든 수신기라면 Sentry가 대신 해 주던 선택을 직접 해야 하는 지점입니다. Sentry는 스택 트레이스로 크래시를 묶습니다. 하지만 릴리스용 Hermes 번들은 minify돼 있어서 프레임 이름은 한 글자이고, 줄·열 위치는 빌드할 때마다 바뀝니다. 프레임으로 묶으면 같은 버그가 릴리스마다 새 이슈로 열리죠.

소스 맵이 없는 상태에서(이건 마지막에 다시 얘기합니다) JavaScript 오류에서 가장 안정적인 건 타입과 메시지입니다. 그래서 핑거프린트는 예외 타입과 메시지로 만들고, 발생할 때마다 달라지는 부분은 가립니다.

_MASKS = [
    (re.compile(r"0x[0-9a-fA-F]+"), "<addr>"),
    (re.compile(r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b"), "<uuid>"),
    (re.compile(r"\b[0-9a-fA-F]{16,}\b"), "<hex>"),
    (re.compile(r"\d+"), "<n>"),
]

Cannot read property 'title' of undefined (reading index 3)와 (reading index 17)은 같은 이슈가 됩니다. SDK가 {{ default }}가 들어 있지 않은 자체 fingerprint를 보내면 그게 우선이라, 기본 묶음이 틀렸을 때는 클라이언트에서 강제로 묶을 수 있습니다. 예외가 없는 이벤트는 가린 로그 메시지로, 둘 다 없으면 앱 코드의 맨 위 프레임으로 묶습니다. 네이티브 시그널 크래시는 메시지가 Signal 6, Code 0 같은 식이라 시그널별로 묶입니다. 거칠긴 하지만, 심볼리케이션이 생기기 전까지는 정직한 방식입니다.

채널을 도배하지 않는 알림

#

핑거프린트 하나가 이슈 하나가 되고, 리포트 하나하나는 그 아래 이벤트로 저장됩니다. 이슈는 정확히 다음 경우에만 ERROR로 기록합니다(채팅 알림이 듣는 게 이 레벨입니다).

• 새 이슈
• 해결됨으로 표시한 이슈가 다시 나타났을 때. 이때 이슈가 다시 열립니다.
• 10번째, 100번째, 1,000번째, 10,000번째 발생

평범한 반복은 카운터만 올립니다. 무시로 표시한 이슈는 계속 세기만 하고 알림은 보내지 않습니다. 여기에 채팅 핸들러 자체의 속도 제한까지 겹치니, 잘못된 릴리스로 크래시 루프가 돌아도 메시지 벽이 아니라 몇 줄로 끝납니다.

저장 공간도 같은 식으로 제한합니다. 이슈마다 최근 50개 이벤트만 남기고, 새 이벤트가 들어오면 오래된 건 지웁니다. 그런데 이것 때문에 첫 차트가 망가졌습니다. 이벤트 50개로는 지난주에 얼마나 자주 일어났는지 알 수 없으니까요. 그래서 이슈마다 90일치 일별 횟수를 따로 두고, 카운터를 올리는 것과 같은 트랜잭션 안에서 갱신합니다. 차트는 이 횟수로 그리고, 이벤트는 읽는 용도로만 씁니다.

이런 걸 직접 만든다면 작은 경쟁 상태 두 개는 챙겨 둘 만합니다. 완전히 새로운 크래시가 여러 폰에서 동시에 나면 두 리포트가 동시에 이슈를 만들려고 할 수 있으니, 핑거프린트에 unique 제약을 걸고 진 쪽이 기존 행을 다시 읽게 하세요. 그리고 90일 범위는 가장 최근 리포트가 아니라 서버 기준 오늘부터 재야 합니다. 시계가 잘못 맞춰진 폰은 리포트 날짜를 아무 날로나, 심지어 내년으로도 찍을 수 있거든요.

페이로드는 128KB로 제한합니다. 이보다 큰 이벤트는 breadcrumb과 디버그 메타데이터부터 버리고, 그래도 크면 예외, 메시지, 릴리스, 플랫폼만 남긴 뒤 잘렸다는 표시를 붙입니다.

개인정보 걷어 내기

#

SDK는 sendDefaultPii: false로 돌기 때문에, 원칙적으로는 IP 주소, 쿠키, 요청 본문이 오지 않습니다. 서버는 거기에 기대지 않습니다. 저장하기 전에 user에서는 id와 username만 남기고, request는 통째로 버립니다. 나중에 SDK 버전이나 설정이 바뀌어서 이런 걸 보내기 시작할 수도 있으니까요.

실제 기기로 테스트해 보니 걷어 내야 할 게 두 가지 더 나왔습니다.

• breadcrumb은 쿼리 스트링까지 포함한 전체 URL을 기록합니다. 앱의 검색 요청은 검색어를 쿼리 스트링에 담아 보내기 때문에, 검색 직후에 크래시가 나면 그 사람이 뭘 검색했는지가 저장됐을 겁니다. 이제 서버가 모든 breadcrumb URL을 ?에서 자릅니다.
• 콘솔 breadcrumb에는 console.log에 넘긴 인자가 그대로 들어 있습니다. 앱이 마침 로그로 찍은 객체라면 무엇이든 될 수 있죠. 메시지 텍스트는 쓸모가 있으니 남기고, 인자는 버립니다.

이 둘은 실제 리포트를 들여다보고 나서야 발견했습니다. 뒤에 나올 섹션이 필요한 가장 큰 이유가 이겁니다.

클라이언트 쪽

#

앱에서는 모든 게 작은 모듈 하나를 거칩니다. OTA 업데이트 SDK를 감싸 둔 것과 같은 이유입니다. OTA 번들은 네이티브 모듈이 생기기 전에 빌드된 바이너리에서도 돌아가거든요. RNSentry가 없는 바이너리에서 최상단에 import * as Sentry from "@sentry/react-native"를 쓰면 import 시점에 예외가 나고, 그러면 빈 화면입니다. 그래서 SDK는 지연 로딩하고, 그것도 네이티브 모듈이 실제로 있는지 확인한 다음에만 불러옵니다.

import { NativeModules, Platform, TurboModuleRegistry } from "react-native";
import Constants from "expo-constants";

const DSN = process.env.EXPO_PUBLIC_CRASH_DSN;

function nativeModulePresent(): boolean {
  try {
    return Boolean(TurboModuleRegistry.get("RNSentry") ?? NativeModules.RNSentry);
  } catch {
    return false;
  }
}

export function initCrashReporting(): boolean {
  if (!DSN || Platform.OS === "web" || !nativeModulePresent()) return false;
  const Sentry = require("@sentry/react-native");
  Sentry.init({
    dsn: DSN,
    release: Constants.expoConfig?.version ?? "unknown",
    sendDefaultPii: false,
    tracesSampleRate: 0,
    enableAutoSessionTracking: false,
    // ...turn off the other tracing options the same way
    maxBreadcrumbs: 50,
    beforeSend(event) { /* tag the OTA bundle */ return event; },
  });
  return true;
}

오류만 보냅니다. 서버가 트레이스, 세션, 프로파일, 리플레이를 저장하지 않으니 그중 아무것도 켜지 않았습니다. DSN이 없으면(개발 빌드, E2E 빌드) SDK는 아예 시작하지 않습니다. 빌드 프로필에서 DSN과 environment(staging 또는 production)를 지정하기 때문에, 두 종류의 빌드가 같은 엔드포인트로 보내면서도 서로 구분됩니다. 로그인한 사용자는 계정 ID로만 지정하고, 이름이나 이메일은 절대 넣지 않습니다.

에러 바운더리에는 명시적인 호출이 필요했습니다. Expo Router의 루트 ErrorBoundary는 렌더링 오류를 잡아서 자기 화면을 보여 주기 때문에, 그 오류는 SDK가 걸어 둔 전역 핸들러까지 가지 않습니다. 해결책은 작은 래퍼입니다. useEffect 안에서 captureException을 호출한 다음, 예전처럼 라우터의 바운더리를 렌더링하고, 루트와 라우트별 바운더리에 똑같이 씁니다. 렌더링 중이 아니라 effect 안에서 부르는 건, 다시 렌더링될 때마다가 아니라 한 번만 보고하게 하려는 겁니다. 루트 컴포넌트는 Sentry.wrap으로도 감싸는데, 이게 예외를 던지면 감싸지 않은 컴포넌트를 그대로 씁니다.

웹용으로는 모든 함수를 꺼 둔 .web.ts 버전의 모듈이 있습니다. Metro가 플랫폼별 파일을 고르기 때문에 SDK는 웹 번들에 아예 들어가지 않습니다. 웹 앱에는 돌릴 네이티브 모듈이 없으니까요.

네이티브 크래시가 정말 도착하는지 확인하기

#

단위 테스트는 손으로 쓴 envelope를 보냅니다. 파서가 SDK가 보낼 거라고 제가 생각하는 걸 처리한다는 것까지만 증명하죠. 출시 이틀 뒤, 프로덕션에 들어온 크래시 리포트는 0건이었습니다. 업데이트한 사람이 아직 세 명뿐이라 0건이어도 이상하지는 않았지만, 서버 입장에서는 “아무도 크래시가 안 났다"와 “크래시가 도착하지 않는다"가 똑같아 보입니다. 진짜 크래시를 하나 보고 싶었습니다.

그래서 DSN을 8000번 포트의 로컬 Django와 임시 키로 바꾼 Release 시뮬레이터 바이너리를 빌드했습니다.

EXPO_PUBLIC_CRASH_DSN=http://localcrashtestkey0000@localhost:8000/1 \
EXPO_PUBLIC_CRASH_ENVIRONMENT=local-verify \
xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Release \
  -destination 'platform=iOS Simulator,id=<udid>' -derivedDataPath /tmp/iosbuild

(Debug가 아니라 Release입니다. Debug 빌드는 dev launcher가 링크돼서 동작이 다르고, 사람들이 실제로 쓰는 건 Release니까요.) 그다음 설치하고, 실행하고, 몇 초 기다렸다가, 실제 결함이 하듯이 죽였습니다.

xcrun simctl install booted /tmp/iosbuild/Build/Products/Release-iphonesimulator/MyApp.app
xcrun simctl launch booted com.example.myapp      # prints the pid
kill -ABRT <pid>

시뮬레이터 앱은 평범한 macOS 프로세스라서, 시그널은 기기에서와 똑같이 SentryCrash의 핸들러에 도달합니다. 핸들러는 리포트를 디스크에 쓰기만 하고, 프로세스가 죽어 가는 동안에는 아무것도 보내지 않습니다. 다음 실행 때 SDK가 그걸 찾아서 보냅니다. 다시 실행하자 1초 뒤 시뮬레이터 네트워크 로그에 :8000로의 연결이 찍혔습니다.

그런데 Django 로그에는 아무것도 없어서 잠깐 헷갈렸습니다. 제가 설정해 둔 레벨에서는 개발 서버가 2xx가 아닌 응답만 기록하더군요. 데이터베이스에는 들어와 있었습니다.

SIGABRT: Signal 6, Code 0 | cocoa 1.4.0 iOS 27.1 iPhone19,4 handled=False
received 09:19:53, crashed 09:19:38
contexts: app, device, os, ota_updates, trace · 24 breadcrumbs

크래시부터 저장까지 15초였고, 대부분은 제가 앱을 다시 켜는 데 걸린 시간입니다. 그리고 실제 페이로드를 들여다보니 테스트로는 알 수 없던 것들이 보였습니다.

• 사용자 ID가 계정 ID가 아니었습니다. 테스트 빌드는 실제로 로그인한 상태가 아니라서, sentry-cocoa가 자체 설치별 ID로 대신 채웠습니다. 알아 둘 만한 점이고, 개인정보 안내에도 적어야 할 점입니다. 로그인했다면 리포트에는 계정 ID가, 아니라면 무작위 설치 ID가 담깁니다.
• 시간대가 없습니다. culture 컨텍스트가 있을 줄 알았는데 없었습니다. device 컨텍스트에는 locale, 메모리, 화면 크기, 저전력 모드, 커널 버전은 있지만 시간대는 없습니다.
• 네이티브 크래시는 beforeSend를 거치지 않습니다. JS 쪽 beforeSend가 실행 중인 OTA 번들로 ota 태그를 붙이는데, 네이티브 크래시는 다음 실행 때 네이티브 SDK가 조립하기 때문에 JS 훅을 전혀 지나지 않습니다. 네이티브 크래시에 태그를 붙이려면, 번들을 알게 된 시점에 setTag로 스코프에 태그를 걸어서 네이티브 레이어까지 동기화되게 해야 합니다.
• breadcrumb을 보면 앱이 뭘 하는지 보입니다. 콘솔 경고, 뷰 컨트롤러 생명주기, HTTP 호출이 있었는데, 그중에는 분석 SDK가 자기 수집 엔드포인트로 보내는 요청도 있었습니다. 앱이 그 밖에 어디와 통신하는지 다시 상기하게 되더군요. 그리고 URL에 쿼리 스트링이 붙어 있었고, 앞에서 말한 검색어 문제를 찾은 게 바로 여기서였습니다.

리포트 읽기

#

리포트는 Django 관리자에서 읽습니다. Sentry를 느슨하게 본뜬 이슈 페이지인데, 상단에 횟수와 Resolve / Ignore / Reopen 버튼, 일별 막대, 릴리스·OS·기기·OTA 번들별 비율이 있고, 그 아래로 이벤트를 하나씩 예외, 프레임(앱 프레임은 강조, 라이브러리 프레임은 접힘), breadcrumb, 기기 컨텍스트와 함께 보여 줍니다. 새 의존성은 필요 없었습니다.

만들다가 고친 게 하나 있습니다. 네이티브 크래시에서 “culprit” 프레임이 기기 안의 바이너리 경로로 나왔는데, 여기에 설치마다 다른 UUID가 들어 있어서 같은 크래시가 폰마다 다르게 보였습니다. 이제는 0x1000a1b2c (MyApp)처럼 주소와 바이너리 이름만 나옵니다.

개인정보 처리방침, 전부 다

#

크래시 리포트는 사실상 개인정보입니다. 계정 ID, 휴대폰 모델, 그리고 앱이 죽기 직전 1분 동안 그 사람이 한 일이 들어 있으니까요. 그래서 개인정보 처리방침에 한 단락이 필요했습니다. 제대로 쓰려면 리포트에 정확히 뭐가 담기는지 말해야 했고, 방금 들여다본 페이로드를 보면서 목록을 만들었습니다. 오류, 앱 버전과 OTA 업데이트, 휴대폰 모델, OS와 언어, 남은 메모리와 화면 크기, 직전 수십 단계(열어 본 화면, ? 뒤를 지운 웹 주소, 앱 자체의 로그 메시지), 그리고 계정 ID 또는 무작위 설치 ID입니다. 리포트는 우리 서버로 오고 Sentry나 다른 크래시 리포팅 회사로는 가지 않는다는 것도 처리방침에 적었습니다. 보관 기간은 표에 따로 한 줄을 뒀습니다. 문제별로 최근 50건의 리포트, 그리고 90일치 일별 횟수입니다.

한 단락을 코드와 대조하기 시작하니 나머지를 안 볼 수가 없었습니다. 기존 처리방침은 버티지 못했습니다. 계정 삭제 페이지에는 계정을 닫으면 푸시 알림 토큰과 패스키가 즉시 삭제되고, 서버 로그는 90일 안에 사라진다고 적혀 있었습니다. 셋 다 사실이 아니었습니다. 계정을 닫으면 로그인 수단의 연결이 끊기고 프로필이 익명화되지만, 푸시 토큰과 패스키는 누군가 손으로 지울 때까지 남아 있고, 로그 보관소에는 아직 만료 기간이 없습니다. 그래서 처리방침 전체를 코드가 실제로 하는 일의 목록을 바탕으로 다시 썼고, 그 줄들은 이제 “아직 자동으로 삭제되지 않음, 이메일로 요청해 주세요"라고 적혀 있습니다. 덜 안심되지만, 정확합니다.

이제 저장소에 이에 대한 규칙이 있습니다. 처리방침은 우리가 하려는 일이 아니라 코드가 하는 일을 설명하고, 개인정보를 새로운 곳에서 수집하거나 보내거나 보관하는 변경은 같은 커밋에서 처리방침도 고친다는 규칙입니다. 앱 안의 요약 화면, 계정 삭제 페이지, 그리고 스토어 콘솔에만 있는 앱 스토어 개인정보 양식까지 포함해서요. 이걸 글로 적어 두게 만든 변경이 크래시 리포팅이었습니다.

아직 없는 것

#

심볼리케이션. 이게 진짜 빈자리이고, sentry.io가 해 주는 일 중 제가 대체하지 못한 단 하나입니다. JavaScript 스택은 minify돼 있고, 네이티브 스택은 심볼리케이션이 안 돼 있습니다.

• JavaScript: 프레임이 Hermes 번들 안을 가리킵니다. 고치려면 모든 스토어 빌드와 모든 OTA 번들의 합성된 Hermes 소스 맵을 릴리스와 번들별로 보관해 두고, 페이지를 렌더링할 때 JS 프레임에 적용해야 합니다. 우리 크래시는 대부분 JavaScript일 테니 이게 다음 작업입니다.
• iOS 네이티브: 명령어 주소를 풀려면 해당 빌드의 dSYM이 필요합니다.
• Android: minify를 켜면 Java 프레임은 R8로 난독화되고(mapping.txt가 필요합니다), C++ 프레임은 NDK 심볼이 필요합니다.

위에서 발견한 더 작은 빈자리도 있습니다. 네이티브 크래시에는 아직 OTA 태그가 붙지 않습니다. beforeSend에서만 붙이고 있기 때문이죠. 실행 중인 번들이 확정되면 스코프에 태그를 거는 건 몇 줄이면 되는데, 아직 쓰지 않았습니다.

지금으로서는 이슈를 보면 무엇이 크래시 났는지, 어떤 릴리스와 OTA 번들과 기기에서였는지, 그 사람이 직전에 뭘 하고 있었는지는 알 수 있습니다. 소스의 어디에서인지는 알 수 없습니다. 일주일에 몇 번 배포하는 작은 앱에서는 지금까지 타입, 메시지, breadcrumb만으로도 원인을 찾기에 충분했습니다.

수신기와 관리자 페이지, 테스트를 합쳐도 코드는 많지 않고, 이미 돌아가던 API 위에 추가로 드는 비용은 없습니다. 어려운 일은 SDK가 합니다. 휴대폰에서 크래시를 잡고, 다음 실행 때 그 리포트를 밖으로 내보내는 일이죠.

밝혀둘 것. 이 마이그레이션과 글은 Codemagic의 의뢰로 비용을 받고 진행했습니다. Codemagic은 사실관계 확인을 위한 검토만 했을 뿐 어조에는 관여하지 않았고, 이 글의 어떤 부분도 그쪽 요청으로 바뀌지 않았습니다. 문제를 만나 보고한 곳은 그렇다고 적었고, 읽으실 시점에 고쳐져 있는 문제는 고쳐졌다고 적어두었습니다.

2026년 9월 23일 업데이트. Codemagic 개발자들이 제가 보고한 문제들을 하나씩 처리했습니다. iOS 버전 감지 버그, 두 번 집계되던 설치, 아무 말 없던 첫 실행, 시끄러운 debug 명령을 비롯해 대부분이 이제 고쳐졌고, 문서에도 커밋된 네이티브 프로젝트와 크래시 롤백 예산 이야기가 들어갔습니다. 본문에서 각 문제가 나오는 자리마다 표시해두었고, 아직 열려 있는 몇 가지는 그대로 두었습니다.

2026년 10월 16일 업데이트. Patch로 옮긴 뒤 첫 네이티브 업그레이드(Expo SDK 58)에서 Patch 설정이 하나도 들어가지 않은 Android 릴리스가 빌드됐는데, 어디서도 오류가 나지 않았습니다. 무슨 일이 있었는지, 그리고 파일 하나로 끝난 수정은 첫 네이티브 업그레이드에 적었습니다.

지난 2월에 Expo 업데이트 서버를 직접 만든 이야기를 썼습니다. 그 서버는 지금도 잘 돌아갑니다. 제가 운영하는 커뮤니티 앱 maru는 그 뒤로 모든 OTA 수정을 두 플랫폼 모두 이 서버를 통해 받았고, 비용은 월 1달러 정도였습니다.

동시에 그 모든 조각을 제가 떠안고 있다는 뜻이기도 합니다. 데이터베이스 테이블, API 엔드포인트, 관리 명령, 퍼블리시 스크립트, 공유 시크릿, 그리고 업데이트가 하나씩 깨질 때마다 배운 함정 목록까지요. 이번 작업을 계획하려고 앉았다가 알게 된 건데, 퍼블리시 스크립트는 처음 쓴 날부터 프로덕션 퍼블리시가 끝날 때마다 “Sent 0 push notifications"를 출력하고 있었습니다. 이 서버가 한 번도 돌려준 적 없는 필드를 읽고 있었던 거죠. 아무도 눈치채지 못했고, 저부터가 그랬습니다. 직접 만든 걸 운영한다는 게 대개 이렇게 흘러갑니다.

그래서 Codemagic에서 CodePush를 오픈소스로 다시 만든, 직접 호스팅할 수 있는 Patch를 써보지 않겠냐고 물었을 때, 조건 하나를 걸고 수락했습니다. 데모가 아니라 실제 앱으로 하겠다는 것. 실제 서명, 실제 릴리스 절차, 손으로 고친 부분이 들어 있는 커밋된 네이티브 프로젝트, 전부 다요. EAS Update에서 옮겨가는 사람 대부분은 새 템플릿이 아니라 그런 앱을 옮기니까요.

그 과정이 어땠는지, 거친 부분을 다듬지 않고 그대로 적었습니다.

Patch가 뭔가

#

Patch는 직접 운영하는 서버와 앱에 넣는 SDK로 이루어져 있습니다. 서버 쪽은 API, 백그라운드 워커, Postgres, S3 호환 오브젝트 스토리지, 웹 대시보드이고, Docker Compose 스택으로 제공됩니다. 클라이언트 쪽은 @codemagic/react-native-patch인데, iOS와 Android용 TurboModule에 Expo config plugin이 딸려 있고, 여기에 JavaScript를 번들링해서 퍼블리시하는 CLI cmpatch가 있습니다.

소스를 읽고 나니 설계 결정 두 가지가 눈에 들어왔습니다.

첫째, 앱은 업데이트가 있는지 API에 묻지 않습니다. 릴리스가 퍼블리시되면 워커가 오브젝트 스토리지에 평범한 JSON 매니페스트를 써두고, 앱은 그걸 가져오기만 합니다. 업데이트 확인은 스토리지나 CDN에 대한 정적 GET 두 번이고, API는 메트릭만 받습니다. 제 예전 엔드포인트는 앱이 실행될 때마다 요청 경로 위에 있었습니다. 이건 그럴 수가 없죠.

둘째, 모든 릴리스는 자기가 대상으로 하는 바이너리 버전을 정확히 명시하고, CLI는 네이티브 프로젝트의 핑거프린트를 계산해서 네이티브 코드가 일치하지 않는 바이너리에는 JavaScript 퍼블리시를 거부합니다. 제 서버에는 버전 문자열 하나와 많은 기대만 있었습니다.

먼저 노트북에서 돌려보기

#

문서는 로컬 평가용 스택부터 시작하라고 안내하는데, 시작점으로 맞습니다.

npm install -g @codemagic/patch-cli
cmpatch selfhost local-eval up

CLI 설치는 2초 만에 끝났습니다. 스택은 처음에 3분 14초가 걸렸는데 대부분 서버와 대시보드 이미지를 로컬에서 빌드하는 시간이었고, 비대화형 모드에서는 그동안 아무것도 출력하지 않아서 딱 멈춘 것처럼 보입니다. (지금은 고쳐져서 단계마다 진행 상황을 한 줄씩 출력합니다.) 그러고 나면 정상 컨테이너 네 개가 전부 localhost에 바인딩되어 나타납니다. 대시보드는 8080, API는 3000, Postgres, 그리고 MinIO는 9100. 제 스택이 이미 쓰고 있던 포트는 알아서 피해 갔습니다.

이 모드에서는 로그인이 꺼져 있고, 페이지마다 외부에 노출하지 말라는 경고가 붙습니다.

localhost:8080

스택에는 Example Data라는 앱이 시드로 들어 있는데, 뭔가 퍼블리시하기 전에 한번 볼 만합니다. 대시보드가 무엇을 위한 것인지 보여주거든요. 다음 두 스크린샷의 숫자는 실제 사용자가 아니라 그 시드 데이터입니다.

localhost:8080

localhost:8080

비교하자면 제 대시보드는 관리자 화면의 업데이트 목록에 “활성” 체크박스가 달린 게 전부였습니다. 실제로 몇 대의 폰이 업데이트를 받았는지는 전혀 몰랐고요.

CLI 로그인은 PKCE와 localhost 콜백을 쓰는 제대로 된 브라우저 플로우이고, 승인 페이지는 어느 계정이 요청하는지와 코드가 1분쯤 뒤에 만료된다는 걸 알려줍니다.

localhost:8080

실제 앱에 연결하기

#

Patch는 플랫폼마다 앱 하나를 원하고, 각 앱에는 Staging과 Production 배포(deployment)가 미리 만들어져 있습니다. 저는 maru-ios는 대시보드에서, maru-android는 cmpatch app create로 만들었습니다. 둘 다 써보고 싶어서요. 앱을 만들고 나서 뜨는 다이얼로그가 마이그레이션에는 이 제품에서 가장 유용한 화면입니다. 배포 키 두 개, SDK에 필요한 URL 두 개, 그리고 배포 키는 비밀이 아니라는 안내까지 한 화면에 있습니다.

localhost:8080

사소한 것 둘. cmpatch init은 이미 존재하는 앱에 프로젝트를 연결하는 명령이라, 마이그레이션 가이드가 어떻게 읽혔든 첫 번째 명령이 될 수 없었습니다. 이건 그 뒤에 고쳐져서, 이제 대화형 모드에서는 플랫폼마다 앱을 하나씩 직접 만들어줍니다. 그리고 다이얼로그는 API URL을 http://localhost:8080으로 알려주는데 문서와 CLI는 3000이라고 합니다. 각 포트가 둘 다 서빙하기 때문에 둘 다 동작하지만, 고개를 갸웃하게 되죠.

그다음 손대지 않은 앱에 cmpatch doctor를 돌렸더니 3초 만에 진짜 문제를 하나 찾아냈습니다. iOS 바이너리 버전을 2.0.0이라고 보고한 겁니다. 앱은 2.5.1입니다.

CLI는 ios/ 아래의 모든 Info.plist를 찾고, 경로에 “test"가 들어간 게 없으면 알파벳순으로 첫 번째를 고릅니다. maru에는 WidgetKit 익스텐션이 있는데, 그 폴더가 앱 본체 폴더보다 앞에 정렬되는 바람에 CLI가 익스텐션의 Info.plist를 집어 들었습니다. 그 plist가 2.0.0에 머물러 있던 건 제 버그지만, 결과는 고약합니다. 자동 감지는 모든 iOS 릴리스를 아무 폰도 돌리지 않는 버전에 겨냥하고, 에러는 하나도 나지 않습니다. 업데이트가 그냥 영영 도착하지 않는 거죠. 자체 호스팅 글에서 경고했던 바로 그 실패입니다. Android는 versionName을 제대로 읽었습니다. 우회책은 --target-binary-version이나 --plist-file을 넘기는 것이고, 제 퍼블리시 스크립트는 이제 app.config.js와 두 네이티브 프로젝트가 일치하는지 확인한 뒤 버전을 명시적으로 넘깁니다. 나중에는 같은 버그 때문에 doctor 자체의 매니페스트 검사가 멀쩡히 동작하는 배포에 대해 실패하기도 했습니다. 2.0.0 버전의 매니페스트를 찾으러 갔으니까요. 낡은 plist를 고치고 나서는 doctor가 24개 검사를 전부 통과했습니다.

Codemagic은 그 뒤 이 문제를 고쳤습니다. 이제 CLI는 익스텐션이 아니라 앱 타깃의 Info.plist에서 버전을 읽고, 앱일 수 있는 타깃이 둘 이상이면 cmpatch가 어느 쪽인지 물어봅니다.

JavaScript 쪽

#

expo-updates를 제거하고 SDK를 추가하는 건 두 줄짜리 변경입니다. 앱이 업데이트로 하던 일을 대체하는 데는 더 고민이 필요했습니다.

maru는 실행 시점과 포그라운드로 돌아올 때마다 업데이트를 확인하는데, 아무리 잦아도 15분에 한 번입니다. 업데이트가 있으면 내려받고 재시작할지 물어봅니다. 거절하면 다음 콜드 스타트 때 적용되고요. 설정 화면에는 지금 어떤 번들이 돌고 있는지 보여주는 수동 확인도 있고, 에러 리포터는 모든 리포트에 출처 업데이트를 태그로 붙입니다.

SDK 소스에서 처음 알게 된 건, 임포트 시점에 TurboModuleRegistry.getEnforcing으로 네이티브 모듈을 찾고 모듈이 없으면 예외를 던진다는 점입니다. maru는 웹 빌드도 내놓고 있어서, 최상위 임포트는 웹 앱을 통째로 죽이게 됩니다. 그래서 전부 SDK를 지연 로드하는 작은 모듈 하나를 거치게 하고, 아무것도 반환하지 않는 .web.ts 짝을 두었습니다. 덕분에 SDK가 웹 번들에서 완전히 빠지기도 하고요.

// ota.ts (ota.web.ts exports a patchSdk() that always returns null)
import { Platform } from "react-native";

type PatchSdk = typeof import("@codemagic/react-native-patch");
let sdk: PatchSdk | null | undefined;

export function patchSdk(): PatchSdk | null {
  if (sdk !== undefined) return sdk;
  if (Platform.OS === "web") return (sdk = null);
  try {
    sdk = require("@codemagic/react-native-patch") as PatchSdk;
  } catch {
    sdk = null;
  }
  return sdk;
}

자동 확인 자체는 대부분 sync()입니다. 예외를 던지지 않고 상태 값으로 resolve되죠.

const status = await patch.sync({
  installMode: "ON_NEXT_RESTART",
  mandatoryInstallMode: "ON_NEXT_RESUME",
});
if (status === "update-installed") offerRestart();

필수(mandatory) 릴리스에 대한 SDK 기본값은 IMMEDIATE인데, 사용자가 어디에 있든 JavaScript를 그 자리에서 다시 로드합니다. 저는 앱이 다음에 백그라운드에서 돌아올 때 적용되도록 바꿨습니다. 쓰다 만 글이 날아가는 건 웬만한 수정이 주는 이득보다 더 나쁜 버그니까요. 당시에는 InstallMode가 문서 예제가 암시하는 enum 객체가 아니라 문자열 유니온이었습니다. 지금은 상수 객체로 export되기 때문에 InstallMode.ON_NEXT_RESTART가 문서대로 동작합니다.

네이티브 쪽, ios/와 android/를 커밋해뒀다면

#

마이그레이션 가이드는 config plugin을 추가한 뒤 npx expo prebuild --clean을 돌리라고 합니다. 별도 체크아웃에서 돌려봤더니 번들된 이미지들, Android 네트워크 보안 설정, iOS 프라이버시 매니페스트, Podfile.lock을 지우고, build.gradle의 테스트 러너용 수정과 Info.plist 수백 줄을 되돌려놨습니다. --clean 없이도 Expo는 두 디렉터리를 어차피 비웠고요.

Patch 잘못은 아닙니다. maru는 managed Expo 앱으로 시작해서 네이티브 커스터마이징이 늘어난 경우라 ios/와 android/가 커밋되어 있고, EAS는 그걸 그대로 빌드합니다. 하지만 이런 앱은 흔한데, 가이드는 경고해주지 않았습니다. 지금은 해줍니다. Expo 마이그레이션 가이드가 두 갈래로 나뉘어서, 네이티브 프로젝트를 생성하는 경우에는 prebuild를, 커밋해둔 경우에는 손으로 적용할 변경 사항을 정확히 안내합니다.

플러그인이 실제로 바꾸는 건 손으로 해도 될 만큼 적었습니다. iOS에서는 AppDelegate.swift에 임포트 하나와 한 줄:

return CodemagicPatch.bundleURL() ?? Bundle.main.url(forResource: "main", withExtension: "jsbundle")

Android에서는 MainApplication.kt에 임포트 하나와 인자 하나(React Native 0.82 이상 형태이고, 그 전 버전은 대신 getJSBundleFile()을 오버라이드합니다):

ExpoReactHostFactory.getDefaultReactHost(
  jsBundleFilePath = CodemagicPatch.getJSBundleFile(applicationContext),
  // ...

여기에 플랫폼별 설정값 세 개와 기존 expo-updates 설정 제거까지. 두 프로젝트 합쳐 13줄 추가, 20줄 삭제였습니다.

플러그인은 그 설정값을 prebuild 시점에 리터럴로 써넣는데, 네이티브 프로젝트를 커밋해둔 상태에서는 모든 빌드에 배포 하나가 하드코딩된다는 뜻입니다. 저는 같은 프로젝트에서 프리뷰 빌드는 Staging으로, 스토어 빌드는 Production으로 가길 원했기 때문에, 값을 빌드 환경에서 가져오게 했습니다. Info.plist에서는 Xcode가 빌드 설정을 확장해줍니다.

<key>CodemagicPatchDeploymentKey</key>
<string>$(PATCH_IOS_DEPLOYMENT_KEY)</string>

그리고 android/app/build.gradle에서는:

def patchEnv = { name -> System.getenv(name) ?: (findProperty(name) ?: "") }
resValue "string", "CodemagicPatchDeploymentKey", patchEnv("PATCH_ANDROID_DEPLOYMENT_KEY")

키는 각 eas.json 빌드 프로파일에 EXPO_PUBLIC_ 값들 옆에 둡니다. 값이 비어 있으면 SDK는 조용히 아무것도 하지 않는데, 로컬 빌드라면 괜찮지만 스토어 빌드라면 재앙입니다. 그래서 app.config.js는 이제 preview나 production EAS 빌드에 키가 빠져 있거나 여전히 localhost를 가리키면 예외를 던집니다.

첫 업데이트

#

첫 릴리스로는 로그인 없이도 볼 수 있는 온보딩 헤드라인을 바꿔서 퍼블리시했습니다.

./scripts/publish-update.sh ios --notes "Onboarding headline over the air"

30초 걸렸고 대부분 Metro와 Hermes 시간이었습니다. 서버 워커는 업로드가 끝나고 0.6초 뒤에 매니페스트를 퍼블리시했습니다. 업데이트는 압축된 7.3 MB tarball이었는데, 예전 export가 만들던 11 MB Hermes 번들과 에셋에 비하면 작습니다.

여기서 제대로 해야 할 게 하나 있습니다. JavaScript 번들은 빌드될 때 EXPO_PUBLIC_ 값을 인라인하기 때문에, 업데이트는 그것이 올라갈 바이너리와 같은 값으로 빌드해야 합니다. 안 그러면 엉뚱한 백엔드에 말을 거는 JavaScript를 내보내게 되죠. 제 스크립트는 바이너리를 빌드한 것과 같은 eas.json 프로파일에서 값을 불러옵니다. 이제는 Patch의 CI 문서에도 이 내용이 적혀 있고, release-react가 EAS 프로파일을 직접 읽지 않는다는 점도 함께 나옵니다.

그런 다음 앱을 다시 실행했습니다. 기기 로그에는 업데이트 확인 전체가 오브젝트 스토리지로 가는 요청 두 개, meta.json과 2.5.1/manifest.json으로 찍혔습니다. SDK는 실행 3초 뒤에 Downloaded 이벤트를 기록하고 업데이트를 스테이징했고, 앱은 재시작을 제안했습니다.

버그는 제 것이었다

#

그리고 대시보드를 봤습니다. 시뮬레이터 한 대가 릴리스 v1을 설치했는데, 성공 설치 2건에 활성 사용자 2명으로 표시됐습니다.

localhost:8080

SDK는 상태와 아직 보내지 않은 메트릭 이벤트를 앱 컨테이너 안에 파일로 보관하기 때문에 추적이 쉬웠습니다. 타임스탬프는 같고 id는 다른 Success 이벤트가 두 개 있었습니다. 제 훅은 마운트 시 notifyAppReady()로 실행 중인 번들을 확인한 뒤 곧바로 sync()를 호출했는데, sync()는 내부에서 notifyAppReady()를 또 호출합니다. 두 호출이 겹치면서 각각 릴리스를 대기 중으로 보고, 각각 이벤트를 기록한 겁니다. 서버는 이벤트 id로 중복을 제거하지만 id가 달랐으니 둘 다 집계됐고, 그 중복은 영구적으로 남습니다.

제 쪽 수정은 실행마다 한 번의 공유 확인을 두고 나머지가 전부 그걸 await하게 하는 것이었습니다. SDK 쪽에서도 겹치는 호출을 막을 수 있을 텐데, 그렇게 제안했습니다. 지금은 실제로 막아줍니다. sync() 안의 호출까지 포함해 겹치는 notifyAppReady() 호출들이 확인 하나를 공유하기 때문에, 설치는 한 번만 기록됩니다. SDK 레퍼런스에도 이제 sync()가 준비 확인을 스스로 한다고 적혀 있어서, sync()를 쓰는 앱은 notifyAppReady()를 따로 호출할 필요가 없습니다.

기분 좋았던 건 수정을 배포하는 과정이었습니다. JavaScript만 바뀐 변경이라 릴리스 v2로 내보냈고, v1을 돌리는 기기에는 바이너리 diff를 보낼 수 있어서 v2는 7.3 MB 번들 대신 543 KB 패치로 내려갔습니다. 크기의 약 7%죠. 재시작 후: 다운로드 1, 설치 1, 성공 1, 활성 기기 1.

localhost:8080

일부러 망가뜨리기

#

롤백은 제가 가장 신경 쓴 기능입니다. 예전 구성에는 기기 쪽 롤백이 전혀 없었거든요. 나쁜 업데이트가 나가면 제가 알아채고 체크박스를 해제할 때까지 실행할 때마다 크래시가 났을 겁니다.

그래서 첫 렌더 전에 예외를 던지는 v3를 릴리스했습니다. 즉 notifyAppReady()를 절대 호출할 수 없는 번들이죠. 앱은 내려받고 재시작을 제안한 뒤 홈 화면으로 죽었습니다.

다음 실행에서도 v3가 다시 부팅되고 다시 크래시했는데, 이건 의외였습니다. 문서에는 notifyAppReady() 전에 크래시하는 번들은 롤백된다고 되어 있으니까요. 소스를 보니 설명이 됩니다. SDK는 크래시로 판정하기 전에 확인되지 않은 실행을 세 번까지 허용합니다. 확인되지 않은 실행 한 번은 JavaScript가 돌기도 전에 iOS가 멀쩡한 프로세스를 죽인 것일 수도 있으니까요. 네 번째 실행에서 v2로 돌아왔습니다.

그다음 기기가 스스로 실패를 crash_rollback으로 보고했고, 대시보드는 그걸 v3에 표시했습니다. 합리적인 설계지만 무슨 뜻인지는 분명히 해둘 필요가 있습니다. 나쁜 릴리스는 사용자마다 크래시 세 번을 겪은 뒤에야 회복된다는 것, 그리고 당시 문서에는 그 숫자가 없었다는 것. 지금은 문서에 나와 있고, 예산도 바꿀 수 있습니다. 네이티브에서는 CodemagicPatchMaxLaunchAttempts, Expo 플러그인에서는 maxLaunchAttempts로요. Staging 먼저, 그다음 Production 소규모 롤아웃을 해야 하는 이유입니다.

다른 모든 사용자에게 나쁜 릴리스를 멈추는 건 명령 하나이고, 1초도 안 걸렸습니다.

cmpatch release rollback --app maru-ios --deployment Staging

이력을 고쳐 쓰지는 않습니다. 이전 릴리스를 새 릴리스(v4, v2의 롤백으로 표시)로 다시 퍼블리시하기 때문에, 크래시한 릴리스는 실패 횟수와 함께 목록에 남습니다. 정직한 기록이죠. 대시보드에서도 다이얼로그로 같은 일을 할 수 있습니다.

localhost:8080

Android

#

Android에서는 두 가지가 놀라웠는데, 둘 다 Patch 탓은 아닙니다. SDK용으로 추가한 R8 keep 규칙이 app.config.js에 있었는데, 이건 prebuild를 통해서만 네이티브 프로젝트에 반영되기 때문에, 첫 릴리스 빌드는 본의 아니게 SDK가 keep 규칙 없이 R8을 견디는지 테스트한 셈이 됐습니다. 견딥니다. R8이 클래스 이름을 전부 바꿨는데도 업데이트 다운로드, 설치, 롤백이 문제없이 됐습니다. 그리고 막 콜드 부팅한 에뮬레이터는 Gradle이 아직 메모리를 쥐고 있어서 너무 느렸고, 첫 테스트는 SDK가 이미 시작한 다운로드를 끝내기 45초 전에 포기해버렸습니다.

릴리스 v1은 성공 1, 활성 기기 1로 적용됐고, 크래시하는 v2는 같은 세 번의 실행 예산을 쓴 뒤 롤백됐습니다.

해피 패스 너머

#

업데이트가 도착하고 롤백되는 게 핵심이지만, 팀은 나머지 기능 속에서 살아가니 하나씩 짚어봤습니다.

단계적 롤아웃은 결정론적인데, 이 점이 마음에 들었습니다. md5(deviceId + "-" + releaseLabel)의 앞 여덟 자리 16진수를 100으로 나눈 나머지가 롤아웃 퍼센트보다 작으면 포함되므로, 같은 폰은 한 릴리스에 대해 계속 포함되거나 계속 제외됩니다. 제 시뮬레이터가 다음 릴리스에서 91번 버킷에 있다는 걸 계산해두고 25%로 퍼블리시했더니, 시뮬레이터는 정확히 아무것도 받지 않았습니다. cmpatch release patch로 95%까지 올리는 데 1초도 안 걸렸고, 다음 실행에서 업데이트됐습니다.

그다음 릴리스는 409로 실패했습니다. “deployment has an active rollout below 100 percent”. 배포당 부분 롤아웃은 하나만 허용되니, 다른 걸 내보내기 전에 카나리를 끝내거나 비활성화하거나 롤백해야 합니다. 합리적이고 문서화도 되어 있지만, 머지마다 퍼블리시하는 파이프라인은 카나리 도중에 이 벽에 부딪힐 겁니다. 제가 보고한 뒤로는 CLI가 이 상황을 설명해줍니다. 활성 부분 롤아웃이 막고 있다면 기다려도 소용없다는 것과 롤아웃을 완료하거나 비활성화하는 방법을 알려주고, 다른 릴리스 작업이 아직 돌고 있다면 release inspect --wait로 기다리라고 합니다. 문서에도 릴리스 변경을 순서대로 하는 방법을 다룬 섹션이 생겼습니다.

필수 릴리스는 SDK의 mandatoryInstallMode를 씁니다. 제 설정은 다음 resume 때 적용이라, 앱은 업데이트를 내려받고 프롬프트를 띄웠고, 프롬프트를 무시한 채 앱을 백그라운드로 보냈다가 다시 가져오니 새 버전이 그냥 거기 있었습니다.

릴리스 비활성화는 단순히 제공을 멈추는 것 이상입니다. 최신 릴리스를 비활성화한 순간 매니페스트는 아직 활성 상태인 가장 새로운 릴리스를 가리켰고, 비활성화된 릴리스를 돌리던 기기에는 그쪽으로 돌아가는 패치가 제공됐습니다. 한 바이너리 버전의 릴리스를 전부 비활성화하면 매니페스트의 target이 null이 되고, SDK는 앱을 바이너리에 실려 나간 번들로 되돌립니다. 제 업데이트 훅은 처음엔 이 경우에 프롬프트를 띄우지 않았는데, 이제는 띄웁니다.

Staging에서 Production으로 승격(promote)하는 데는 1초도 안 걸렸고, 다시 빌드하는 대신 테스트한 패키지를 해시와 노트까지 그대로 재사용했습니다. 롤아웃 퍼센트도 받기 때문에 “Production의 10%로 승격"이 명령 하나입니다.

빌드와 퍼블리시를 별도 단계로 나눌 수도 있습니다. cmpatch bundle이 .cmpatch 아티팩트를 만들고, 대시보드의 “Bundle upload” 옵션은 업로드 전에 그걸 읽어서 플랫폼, 대상 버전, 핑거프린트, 서명 상태, 크기, 번들러를 보여줍니다. CI가 아티팩트를 빌드하고 퍼블리시 시점은 다른 사람이 정하는 구성에 맞습니다.

핑거프린트 가드를 제대로 맞닥뜨린 것도 여기서였습니다. 낡은 위젯 plist를 고친 뒤, 서버는 다음 릴리스를 409로 거부했습니다. 네이티브 프로젝트의 핑거프린트가 2.5.1에 대해 기록해둔 것과 더 이상 일치하지 않았기 때문입니다. Android에서는 app.config.js의 주석 하나를 고친 것만으로 충분했습니다. Expo가 앱 설정을 핑거프린트에 포함시키니까요. 대시보드는 같은 검사를 두 핑거프린트와 “Upload anyway” 버튼이 달린 경고로 보여줍니다. 두 경우 모두 설치된 바이너리의 네이티브 쪽은 아무것도 바뀌지 않았으니 무시하고 올리는 게 맞았습니다. 하지만 실제 운영에서 정직한 답은 거의 언제나 버전을 올리고 스토어 빌드를 하는 것이고, 제 퍼블리시 스크립트는 이제 이 상황이 생기면 정확히 그렇게 말해줍니다.

코드 서명은 RS256입니다. CLI가 패키지 해시를 RSA 개인 키로 서명하고, SDK는 바이너리에 컴파일된 공개 키로 검증합니다. 키는 base64 한 줄로 들어가서 제 빌드 설정 방식과 잘 맞았고, 두 플랫폼에서 모두 테스트했습니다. 앱에 키가 들어 있으면 서명되지 않은 릴리스는 다운로드 전에 거부됐습니다. 앱에 “require code signing"을 켜두면 서버는 서명되지 않은 퍼블리시를 거부하면서 해결 방법을 적고 가이드를 링크한 에러를 돌려줬습니다. 서명된 릴리스는 설치됐고, SDK는 서명이 검증됐다고 기록했습니다. 서명된 릴리스를 비활성화했을 때 서버가 되돌아간 이전의 서명되지 않은 릴리스도 거부했고요. 걸리는 점은, 업데이트로는 공개 키를 추가할 수 없기 때문에 처음 내보내는 바이너리에 공개 키가 들어 있어야 한다는 것입니다.

localhost:8080

팀과 CI도 갖춰져 있습니다. 멤버는 팀 전체에 적용되는 네 역할(owner, admin, developer, viewer) 중 하나를 받고, 초대는 그 사람이 처음 로그인할 때까지 대기합니다. 개인 액세스 토큰은 홈 디렉터리가 비어 있는 상태에서도 --token이나 환경 변수로 잘 동작했고, 토큰 목록에는 각 토큰이 마지막으로 쓰인 시점이 나옵니다. 같은 퍼블리시 스크립트를 Linux 러너에서 시크릿에 든 서명 키로 돌리는 수동 실행 CI 워크플로우도 써뒀는데, 호스팅된 서버가 필요해서 아직 돌려보지는 않았습니다.

그 당시라면 건너뛰었을 도구가 하나 있는데, cmpatch debug ios입니다. 시스템 로그를 “OTA"로 대소문자 구분 없이 필터링해서 스트리밍했는데, 이러면 “Rotation"에도 매칭돼서 20초짜리 앱 실행에 SpringBoard 메시지가 화면 한가득 나오고 앱에서 나온 건 하나도 없었습니다. 이건 고쳐져서, 이제는 SDK 마커가 붙은 줄만 보여줍니다. SDK 자체는 로그를 많이 남기지 않고 대부분 에러와 개발 빌드 경고 정도라, 스트림은 조용한 편이라고 생각하시면 됩니다. 혹시 보이는 getpwuid_r 경고는 Patch가 아니라 xcrun simctl에서 나오는 겁니다.

그래서 얼마나 어려운가

#

Codemagic이 제 의견을 물었으니, 최대한 담백하게 적겠습니다.

써보는 건 쉽습니다. 명령 두 개, 몇 분이면 실제 서버와 데모 데이터가 든 대시보드, 그리고 자기 앱에 연결할 수 있는 CLI가 생깁니다. 첫 한 시간 중 가장 좋은 부분이었습니다.

SDK 통합은 중간 정도의 작업이고, 어려움의 대부분은 Patch가 아니라 자기 프로젝트 안에 있습니다. 네이티브 폴더가 생성된 새 Expo 앱이라면 정말로 플러그인 하나에 expo-updates 호출을 바꾸는 몇 줄이 전부입니다. maru처럼 커밋된 네이티브 프로젝트, 위젯 익스텐션, 웹 빌드, R8, 빌드 프로파일이 있는 앱에서는 작업이 가장자리에 있었습니다. prebuild를 피하려고 네이티브 변경을 손으로 적용해야 했고, Staging과 Production 빌드가 다를 수 있도록 설정을 빌드 시점으로 옮겨야 했고, SDK를 웹에서 떼어놔야 했습니다. 업데이트의 JavaScript가 바이너리와 같은 환경으로 빌드되도록 하는 것도요. 이해하고 나면 어려운 건 없었습니다. 제가 작업할 때는 그 대부분이 문서에 없었는데, 커밋된 네이티브 프로젝트 경로와 번들 시점의 환경 문제는 이제 문서에 들어가 있습니다.

일상적인 사용은 좋습니다. 퍼블리시는 명령 하나에 30초 남짓. 롤아웃, 승격, 비활성화, 롤백은 CLI에서든 대시보드에서든 전부 1초 이내이고, 에러는 뭐가 잘못됐고 뭘 해야 하는지 말해줍니다. 서버의 가드(핑거프린트 검사, 한 번에 카나리 하나, 서명)는 엄격한데, 그 덕분에 제가 잘못된 일을 하는 걸 여러 번 막아줬습니다.

프로덕션에서 운영하는 건 더 큰 결심이 필요합니다. Postgres와 오브젝트 스토리지가 딸린 Docker Compose 스택을 직접 호스팅하고 백업하고 업그레이드해야 하고, 도메인 두 개와 OAuth 앱이 필요합니다. 이미 서버를 운영하는 팀에게는 조용한 오후 한나절이고요. 서버를 원치 않아서 EAS를 쓰는 팀에게는 이게 전환의 진짜 비용이고, SDK 작업보다 큽니다.

실제 시간으로 따지면 12:29에 CLI를 설치했고 13:34에 시뮬레이터에서 첫 업데이트가 적용됐는데, 그중 30분은 Patch와 무관한 이유로 멈춰 있던 Xcode 빌드였습니다. 이 글에 있는 모든 것은 두 플랫폼 모두 오후 중반까지 끝났습니다. 호스팅 서버는 빼고요.

시간을 가장 많이 잡아먹은 것들을 순서대로 꼽으면 이렇습니다. 커밋된 네이티브 프로젝트를 날려버린 expo prebuild --clean과 그 뒤 모든 걸 손으로 연결하는 방법을 알아내는 일. 아무도 돌리지 않는 버전으로 업데이트를 보낼 뻔한 iOS 버전 감지 버그. 두 번 집계된 설치. 이건 제 잘못이지만 sync()가 스스로 notifyAppReady()를 호출하는 이상 누구나 되풀이하기 쉬운 실수입니다. 그리고 테스트 도중에 저를 놀라게 한, 문서에 없는 크래시 3회 예산. 그다음은 맞긴 하지만 계획이 필요한 것들입니다. 무해한 네이티브 인접 편집에도 발동하는 핑거프린트 가드, 배포당 카나리 하나, 그리고 겹칠 수 없는 라이프사이클 작업(스크립트가 여러 일을 연달아 하는 순간 문제가 됩니다). 나머지는 사소했습니다. 아무 말 없는 첫 실행 설정, 시끄러운 debug 명령, 코드와 맞지 않던 문서 예제 몇 개.

이 모든 걸 상세 내용과 함께 Codemagic에 정리해서 보냈고, 9월 23일 기준으로 대부분이 고쳐졌습니다. 버전 감지, 겹치는 확인, prebuild 경고, 크래시 예산, 아무 말 없던 설정, debug 명령, InstallMode 예제, 그리고 릴리스 작업이나 카나리가 가로막을 때 나오는 에러까지요. 아직 남아 있는 건 더 작은 것들입니다. 다른 곳은 전부 :3000이라고 하는데 대시보드만 API를 :8080으로 보여주는 것, SDK가 웹과 Jest에서 임포트 시점에 예외를 던지는 것, 그리고 문서의 빈틈 몇 군데.

프로덕션으로 가기

#

위의 모든 것은 평가용 스택에서 돌렸습니다. 프로덕션은 같은 앱과 같은 스크립트를 실제 서버에 연결하는 것이고, 이게 maru의 계획입니다.

서버를 운영하는 공식 지원 방식은 Docker Compose 설치입니다. 80, 443 포트가 열린 Linux 머신, 도메인 두 개(API와 대시보드용 하나, 다운로드용 하나), 로그인용 GitHub OAuth 앱(이게 없으면 서버가 시작하지 않습니다)이 필요합니다. 나머지는 TLS까지 포함해 설치 스크립트가 처리합니다.

scripts/selfhost/install.sh \
  --api-domain updates.example.com \
  --storage-domain storage.updates.example.com \
  --email you@example.com \
  --github-oauth-client-id <id> --github-oauth-client-secret <secret>

데이터베이스와 스토리지 시크릿이 담긴 .env.selfhost를 써주는데, 이건 비밀번호 관리자에 넣어둬야 합니다.

다만 번들된 데이터베이스와 스토리지를 꼭 써야 하는 건 아니고, 그래서 제 스택 같은 구성에도 맞습니다. maru의 API는 이미 Fly.io에서 돌고 파일은 Tigris에 있는데, Patch는 둘 다에서 동작합니다. Compose 파일 아래를 보면 서버는 MODE=all(API와 릴리스 워커 함께)로 도는 컨테이너 하나이고, Postgres 데이터베이스, S3 호환 스토리지, 파일용 공개 HTTPS URL이 필요합니다. 즉 저장소의 Dockerfile로 빌드한 Fly 앱(아직 공개된 이미지가 없어서 fly deploy가 빌드합니다), Fly Postgres 데이터베이스, Tigris 버킷이면 됩니다.

MODE=all
DATABASE_URL=postgresql://…            # Fly Postgres
STORAGE_ADAPTER=s3
S3_ENDPOINT=https://fly.storage.tigris.dev
S3_REGION=auto
S3_BUCKET=myapp-patch
S3_FORCE_PATH_STYLE=true
PUBLIC_BASE_URL=https://myapp-patch.fly.storage.tigris.dev/codemagic-patch

주의할 점 둘. Compose 밖에서 운영하는 건 저장소에 참고 자료로 문서화되어 있을 뿐 이번 첫 오픈소스 릴리스에서 지원되는 경로는 아니라서, Fly에서는 업그레이드와 백업을 알아서 챙겨야 합니다. 저도 아직 그렇게 배포해보지는 않았습니다. 이건 보고가 아니라 계획입니다. 그리고 Fly의 0으로 스케일 다운 글을 읽으셨다면, 머신은 최소 한 대는 켜두세요. 매니페스트가 스토리지에서 바로 오기 때문에 폰이 업데이트 확인에서 API를 기다리는 일은 없지만, 그렇지 않으면 모든 메트릭 업로드와 모든 릴리스 작업이 콜드 부팅으로 시작하게 됩니다.

Tigris가 제가 가장 기대하는 부분입니다. maru의 파일이 이미 거기 있고, 앱이 실행될 때마다 때리는 URL 앞에 CDN을 세워주니까요. 이렇게 할 거라면 매니페스트 캐싱에 주의하세요. 기본 base-URL 전달 어댑터에서 Patch는 매니페스트를 no-cache로 서빙하는데, CDN을 퍼지할 수 없기 때문입니다. 매니페스트가 자체 TTL로 캐시되면 방금 롤백한 릴리스를 계속 내보내게 됩니다. 이 내용은 이제 설정 레퍼런스의 MANIFEST_CACHE_CONTROL 항목에 문서화되어 있고, 문서 사이트에서도 S3 호환 스토리지를 다룹니다.

호스팅된 서버에서는 앱을 다시 만들고, 새 키를 eas.json의 preview와 production 프로파일에 넣고(Staging 키와 Production 키), 퍼블리시용 토큰을 만듭니다.

cmpatch token create --name ci

코드 서명을 쓸 거라면 지금 정하세요. 프로덕션 키 쌍을 생성하고, 개인 키는 CI 시크릿으로 보관하고, 공개 키는 빌드 프로파일에 넣고, 두 앱 모두 “require code signing"을 켭니다. 첫 Patch 바이너리에는 새 버전 번호도 필요합니다. 스토어에 이미 올라간 바이너리는 expo-updates를 돌리고 있으니까요. 먼저 preview 프로파일로 TestFlight과 Play 내부 테스트용으로 빌드하고, 누군가에게 건네기 전에 키가 실제로 빌드된 Info.plist와 Android 리소스에 들어갔는지 확인하세요. 제 로컬 테스트가 검증하지 못한 유일한 고리가 이 부분입니다. 환경을 손으로 export했으니까요. 그다음 Staging에 퍼블리시하고, 테스터마다 다운로드 1, 성공 1을 확인하고, 그제야 스토어용으로 빌드합니다.

프로덕션 릴리스는 작게 시작해서 키워갑니다.

./scripts/publish-update.sh ios --production --rollout 10
cmpatch release patch --app maru-ios --deployment Production --label v1 --rollout-percentage 100

그동안 기존 서버는 계속 켜둡니다. 사람들이 아직 업데이트하지 않은 2.5.1 사본은 전부 여전히 그 서버를 확인하고, 그들을 위한 핫픽스도 여전히 예전 스크립트로 나갑니다. 로그에서 그 요청이 멈춘 게 보이면 기존 서버와 그 퍼블리시 스크립트, 시크릿까지 전부 지울 수 있습니다.

첫 네이티브 업그레이드

#

2026년 10월 16일 추가.

Patch는 10월 초부터 maru의 프로덕션 업데이트를 맡고 있습니다. 그 뒤 첫 네이티브 릴리스는 Expo SDK 58로의 이전이었습니다. React Native 0.88, 그리고 Android에서는 Gradle 플러그인의 새 메이저 버전입니다. 네이티브 변경은 OTA로 보낼 수 없으니 새 바이너리 2.6.0이 되고, 제 퍼블리시 스크립트는 그 바이너리가 나오기 전까지 2.6.0용 업데이트를 보내지 않습니다. 두 플랫폼 모두 첫 시도에 깔끔하게 빌드됐습니다.

위의 프로덕션 섹션에서, 빌드를 누군가에게 건네기 전에 키가 실제로 빌드된 Info.plist와 Android 리소스에 들어갔는지 확인하라고 했습니다. 이번에는 정말 확인했고, 이 섹션이 있는 이유가 바로 그 확인입니다. iOS 빌드에는 Patch 설정 네 개가 다 있었습니다. Android 빌드에는 하나도 없었습니다.

bundletool dump resources --bundle=build.aab --values | grep -A1 "string/Codemagic"

이 명령은 2.5.11 빌드에서는 키 네 개를 출력했고 2.6.0에서는 아무것도 출력하지 않았습니다. 환경 변수는 문제가 아니었습니다. Gradle의 generateReleaseResValues는 네 개를 다 씁니다. 지우는 건 그 뒤에 도는 릴리스 리소스 축소기(resource shrinker)인데, Android Gradle Plugin 9에서 훨씬 공격적으로 바뀌었습니다. 같은 앱의 리소스가 9,240개에서 7,116개로 줄었습니다. SDK는 설정을 getIdentifier로 이름을 써서 읽는데, 축소기는 이걸 볼 수 없으니 네 문자열을 쓰이지 않는 것으로 보고 지웠습니다. 없는 문자열은 빈 값으로 읽히고, 빈 값은 “업데이트 없음"이라는 뜻입니다. 실패하는 건 아무것도 없었을 겁니다. Android 2.6.0은 설치되고, 평소처럼 돌아가고, 업데이트는 한 번도 받지 못했을 것이고, 유일한 신호는 대시보드에 Android 2.6.0 기기가 하나도 없다는 것뿐이었을 겁니다.

수정은 축소기에게 네 문자열을 남기라고 알려주는 리소스 파일 하나입니다.

<!-- android/app/src/main/res/raw/codemagic_patch_keep.xml -->
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@string/CodemagicPatch*" />

이름을 keep.xml로 짓지는 마세요. React Native의 번들 태스크가 JavaScript 에셋용으로 이미 raw/keep.xml을 생성하고(이미지와 폰트가 살아남은 게 그 덕분입니다), 두 파일이 충돌합니다. 라이브러리의 keep 파일은 앱에 자동으로 병합되니 이 규칙이 있어야 할 더 나은 자리는 SDK 자체이고, 배포 키 없이 릴리스 빌드가 시작될 때 경고 하나만 나와도 조용히 지나가던 상황이 눈에 보이게 될 겁니다. 앞에서 나온 iOS 버전 감지 버그와 같은 종류의 실패입니다. 오류는 나지 않고, 업데이트가 그냥 도착하지 않습니다.

같은 확인에서 Patch와는 상관없는 두 번째 문제도 드러났는데, 이건 다른 이유로 알아둘 만합니다. Android 릴리스 빌드가 실행하자마자 크래시했는데, 그것도 두 번, Expo 자체 모듈 안의 서로 다른 두 가지 이유 때문이었습니다. 먼저 Expo의 위젯 모듈이 네이티브 클래스를 등록하지 못해서, JavaScript가 돌기도 전에 앱이 죽었습니다. 그걸 고치자 앱은 JavaScript를 시작하는 데까지는 갔다가 멈췄는데, Expo의 새 모듈 시스템으로 옮겨간 모듈 세 개가 등록되지 않았기 때문입니다. 둘 다 Patch의 크래시 롤백으로는 도움이 안 됩니다. 롤백할 업데이트가 없으니까요. 크래시 롤백은 나쁜 업데이트로부터 지켜주는 것이지, 나쁜 바이너리로부터 지켜주는 게 아닙니다. Patch가 있든 없든, 네이티브 업그레이드는 스토어에 올리기 전에 실제 기기나 에뮬레이터에 설치해서 열어봐야 합니다.

같은 테스트에서 작은 것이 하나 더 나왔습니다. sync()는 실패하면 "error"를 반환하고, 앱이 개발 모드로 돌고 있지 않으면 이유는 알려주지 않습니다. 그래서 릴리스 빌드는 뭔가 잘못됐다는 것밖에 로그로 남길 수 없습니다. 이제 제 훅은 sync가 실패하면 checkForUpdate()를 한 번 호출해서 거기서 던지는 오류를 로그로 남기는데, 덕분에 문제가 서버가 아니라 로컬 시뮬레이터 빌드의 Patch URL이 비어 있던 것(unsupported URL)이라는 걸 알게 됐습니다. 마지막 오류를 릴리스 빌드에서도 읽을 수 있다면 도움이 될 겁니다.

이제 제 네이티브 릴리스 체크리스트에는 전에 없던 세 줄이 있습니다. 빌드된 .ipa와 .aab에서 Patch 설정을 덤프해볼 것, 배포 키를 빌드 프로파일과 비교할 것, 그리고 제출하기 전에 debug 빌드가 아니라 릴리스 빌드 자체를 실행해볼 것.

Expo 청구서를 받고 있는 분에게

#

서버를 만드는 게 너무 큰 일처럼 보여서 EAS Update에 돈을 내고 있다면, Patch는 실질적인 답입니다. 서버를 운영하긴 하지만, 그건 Compose 스택과 설치 스크립트이지 여러분이 유지보수할 코드가 아닙니다. 제가 만든 것과 비교하면 단계적 롤아웃, 릴리스별 설치·실패 숫자, 바이너리 패치, 핑거프린트 가드, 코드 서명, 기기에서의 크래시 롤백, 롤백 버튼이 따라옵니다. 저는 그중 하나도 만들지 않았습니다.

비용은 이렇습니다. SDK가 앱에 들어 있어야 하니 누구든 Patch 업데이트를 받기 전에 새 바이너리가 필요하고, 계속 업그레이드하고 백업해야 할 서버가 생기고, 릴리스가 충분히 나쁘면 기본값 기준으로 사용자마다 크래시 세 번을 겪고, 네이티브 프로젝트가 커밋되어 있다면 손이 좀 갑니다. 아직 어리기도 합니다. 이번은 0.3.0 버전이었고, 버전 감지 버그, 시끄러운 debug 명령, 문서의 빈틈 몇 군데를 만났고, SDK가 막아줄 수 있었을 버그를 제가 직접 하나 만들었습니다. 버전 감지와 debug 명령은 그 뒤 고쳐졌고, 문서의 빈틈도 대부분 메워졌고, SDK는 이제 제가 한 실수를 막아줍니다. 그중 어떤 것도 마이그레이션을 멈추지는 못했고, 전부 CLI에서, 대시보드에서, 혹은 기기 안 SDK 파일에서 눈에 보였습니다. 제 예전 구성에 대해서는 할 수 없는 말이죠.

제가 만드는 마켓플레이스 앱은 React Native Web으로 만든 싱글 페이지 앱입니다. 모든 리스팅 페이지는 자바스크립트가 실행되기 전까지 스크립트 태그 하나와 빈 div일 뿐입니다. 사람에게는 아무 문제가 없지만 검색에는 치명적입니다. 구글은 그 JS를 실행할 때도 있지만, Bing은 하지 않고, 리스팅이 거의 다 한국어인 사이트에 가장 중요한 네이버 크롤러는 확실히 하지 않습니다.

이 글은 그 페이지들을 보이게 만든 과정과, 그다음에 제가 예상하지 못한 방식으로 그걸 되돌려버린 캐싱 규칙에 대한 이야기입니다.

클로킹이 아닌 다이내믹 렌더링

#

해결책은 오래됐고 구글도 인정하는 방식입니다. 크롤러를 감지해서, SPA가 그렸을 바로 그 콘텐츠를 담은 서버 렌더링 HTML을 내주는 것. 다른 콘텐츠가 아니라, 같은 콘텐츠를 더 일찍.

그래서 /listings/view?id=... 같은 리스팅 URL은 분기합니다. 브라우저는 SPA 셸을 받습니다. 크롤러는 진짜 문서를 받습니다. 제목, 리스팅의 핵심 정보, alt 텍스트가 붙은 사진별 이미지, 본문 발췌, 그리고 이 페이지가 고아가 되지 않도록 관련 리스팅 몇 개로 가는 링크까지.

마지막 항목이 생각보다 훨씬 중요했습니다. 내부 링크가 생기기 전에는 리스팅 페이지 약 1,000개를 가리키는 것이 아무것도 없었고, 서치 콘솔에서 크롤이 하루 7~11회로 가라앉는 게 보였습니다. 페이지를 찾지 못하는 크롤러는 그 페이지가 얼마나 좋은지 신경 쓰지 않습니다.

함정: 벤더 이름은 그 회사 봇의 이름이 아니다

#

크롤러 감지는 user-agent 매칭이고, 바로 여기서 발목을 잡혔습니다.

한국 플랫폼들은 회사 이름과 전혀 닮지 않은 이름으로 크롤링합니다. 네이버의 크롤러는 Yeti. 다음은 Daumoa. 카카오의 링크 스크래퍼는 kakaotalk-scrap. 셋 중 어느 것도 벤더 이름이 아닙니다.

한편 같은 벤더들이 인앱 브라우저를 탑재한 앱을 내놓고, 그 브라우저는 진짜 브라우저 UA 뒤에 앱 이름을 붙여 보냅니다. 카카오톡 인앱 브라우저는 KAKAOTALK/10.5.1이라고 말합니다. 카카오의 스크래퍼는 kakaotalk-scrap/1.0이라고 말하고요.

kakao로 매칭하면 둘 다 걸립니다. 제가 정확히 그렇게 했고, 그래서 링크를 연 카카오톡·네이버앱·다음앱 사용자 전원이 크롤러 페이지를 받았습니다. 자바스크립트도, 내비게이션도, 로그인도 없는 페이지를요. 문서로서는 훌륭하고, 사람에게는 완전히 쓸모없는.

해결책은 순서 규칙이고, 규칙으로 적어둘 만합니다.

import re

# 인앱 브라우저는 평범한 브라우저 UA 뒤에 앱 이름을 붙인다.
INAPP_BROWSER_RE = re.compile(r"kakaotalk/|naver\(inapp|daumapps", re.I)

# 벤더가 아니라 봇 이름으로 매칭한다. 네이버는 Yeti, 다음은 Daumoa,
# 카카오의 링크 미리보기 스크래퍼는 kakaotalk-scrap.
CRAWLER_RE = re.compile(r"googlebot|bingbot|yeti/|daumoa|kakaotalk-scrap", re.I)


def is_crawler(user_agent: str) -> bool:
    # 인앱 브라우저는 절대 크롤러가 아니다. 그래서 이 검사가 먼저 온다.
    if not user_agent or INAPP_BROWSER_RE.search(user_agent):
        return False
    return bool(CRAWLER_RE.search(user_agent))

인앱 브라우저를 먼저 검사하고, 그쪽이 이깁니다. 그리고 모든 크롤러 토큰은 벤더가 아니라 봇을 지목해야 합니다.

그다음 앞단에 Cloudflare를 놓았다

#

오리진은 시드니에 있는 공유 CPU 머신 한 대이고, 초당 20~30 요청을 감당합니다. Googlebot이 걸어야 할 URL은 약 995개입니다. 그 전부가 시드니까지 도달하고 있었습니다. 모든 URL에서 cf-cache-status가 DYNAMIC이었기 때문입니다. Cloudflare는 규칙이 시키지 않으면 HTML을 캐싱하지 않습니다. 존의 약 16%만 캐싱되고 있었고, 정작 중요한 부분은 하나도 포함되지 않았습니다.

그래서 크롤러 페이지에 캐시 규칙을 걸었습니다. 간단한 일이죠. 리스팅 URL의 본문이 하나가 아니라는 점만 빼면. 본문은 셋입니다.

• HTML을 요청하는 크롤러는 서버 렌더링 페이지를 받습니다.
• 사람은 SPA 셸을 받습니다.
• Accept: text/markdown을 보내는 에이전트는 데이터베이스에서 만든 마크다운을 받습니다. 빈 HTML 셸을 변환해봐야 빈 문서가 나올 뿐이니까요.

오리진은 Vary: Accept를 보내고, user-agent에 대한 Vary는 어차피 가망이 없습니다. 그리고 제가 몰랐던 게 여기 있습니다.

Cloudflare는 HTML에서 Vary를 무시합니다. 세 본문이 하나의 캐시 키를 공유합니다.

먼저 도착한 본문이 그 URL을 차지하고, 해당 엣지 위치의 이후 모든 방문자에게 오리진의 s-maxage가 허용하는 한 시간 동안, 거기에 stale-while-revalidate 하루를 더해 그대로 나갑니다.

프로덕션에서 양방향으로 다 목격했습니다.

• 네이버앱 사용자가 크롤러 페이지로 리스팅 URL을 워밍했고, 그다음 평범한 아이폰 사파리가 HIT으로 그 페이지를 받았습니다. 자바스크립트 없는 문서를 들여다보는 사람이 된 거죠.
• 사람이 SPA 셸로 URL을 워밍했고, Googlebot이 빈 셸을 받았습니다. SEO 작업 전체가 막으려던 바로 그 실패가, 이제 더 빠르게 엣지에서 제공된 겁니다.

좁혀서 고치는 규칙

#

Cloudflare가 HTML에서 Vary를 존중하게 만들 수는 없습니다. 대신 할 수 있는 건, 세 본문 중 하나만 캐시에 들어갈 자격을 갖게 만드는 것입니다.

(starts_with(http.request.uri.path, "/listings/")
 and not any(http.request.headers["accept"][*] contains "text/markdown")
 and (lower(http.user_agent) contains "googlebot" or ...)
 and not (lower(http.user_agent) contains "kakaotalk/" or ...))

크롤러 UA만 매칭하고, 마크다운 요청은 제외합니다. 이제 사람의 요청은 어떤 규칙에도 매칭되지 않으므로 예전처럼 DYNAMIC을 읽고 오리진으로 갑니다. 캐시를 읽고 쓰는 건 크롤러 요청뿐이고, 거기 들어갈 수 있는 본문은 크롤러용 하나뿐입니다.

엣지 TTL은 respect_origin입니다. 수명은 대시보드에 박히는 대신 페이지를 렌더링하는 코드가 계속 소유합니다.

놓치기 쉬운 운영 디테일 하나. 규칙을 좁힌다고 이미 캐시에 있는 것이 사라지지는 않습니다. 퍼지해야 합니다. 안 그러면 방금 생성을 멈춘 그 오염된 항목을 계속 내주게 됩니다.

두 목록, 그리고 그 오류가 대칭이 아닌 이유

#

이 규칙에는 크롤러 UA 목록이 필요하고, Django에는 이미 하나 있습니다. 같은 지식이 두 시스템에 두 벌 있는 건 대개 냄새나는 일이지만, 여기서 흥미로운 건 둘이 어긋났을 때 벌어지는 일입니다. 대칭이 아니거든요.

• Cloudflare의 봇 목록은 Django 쪽의 부분집합으로 유지되어야 합니다. Cloudflare는 봇이라 여기지만 Django는 아니라고 보는 토큰이 있으면, 크롤러 전용 키 아래에 SPA 셸이 캐싱되고 그게 진짜 크롤러에게 나갑니다.
• 인앱 브라우저 제외 목록은 Django 쪽의 상위집합이어야 합니다. 너무 많이 제외해봐야 캐시 히트를 잃을 뿐입니다.

어느 쪽이든 안전한 방향으로 틀리면 캐싱을 조금 잃습니다. 첫 번째를 반대 방향으로 틀리면 다시 Googlebot에게 빈 페이지를 내주게 됩니다. 참고로 이 비대칭 때문에 목록이 정규식 대신 contains를 씁니다. matches는 Business 플랜이 필요하고, 알려진 안전한 방향으로 대충이어도 되는 목록에는 contains로 충분합니다.

페이지 대신 빌드를 실패시키는 불변식

#

크롤러 페이지에는 7일간 유효한 presigned 이미지 URL이 들어갑니다. 페이지 자체는 엣지에서 한 시간, 거기에 stale-while-revalidate 하루가 붙습니다.

이 두 숫자는 서로 관련이 있고, 캐시 수명이 이미지 수명을 넘어서는 순간 엣지는 모든 사진이 403인 페이지를 내주기 시작합니다. 이걸 알려주는 알림은 없습니다. HTML 자체는 멀쩡하니까요.

그래서 그 숫자들을 정의하는 코드는 관계가 깨지면 임포트 자체를 거부합니다.

CRAWLER_IMAGE_TTL = 7 * 24 * 3600  # presigned 이미지 URL
EDGE_S_MAXAGE = 3600
EDGE_STALE_WHILE_REVALIDATE = 24 * 3600

# 엣지 캐시가 이미지 URL보다 오래 살 수 있으면 임포트 시점에 실패시킨다.
if EDGE_S_MAXAGE + EDGE_STALE_WHILE_REVALIDATE >= CRAWLER_IMAGE_TTL:
    raise RuntimeError("edge cache lifetime must stay below the image URL lifetime")

서로 다른 파일에 있는 두 상수 사이의 제약은 코드 리뷰에서는 보이지 않고, 프로세스 시작 시점에는 명백합니다. 프로세스가 시작하는 곳에 두세요.

Cloudflare가 한 일 중 되돌려야 했던 두 가지

#

Vary: Origin이 번들을 캐시 밖으로 밀어냈습니다. django-cors-headers는 자기가 건드리는 모든 응답에 Vary: Origin을 찍고, Cloudflare는 Accept-Encoding 외의 헤더로 Vary가 걸린 응답은 캐싱하지 않습니다. 그래서 크리티컬 패스에서 가장 큰 1.6MB 자바스크립트 번들이 통째로 엣지에서 조용히 제외되고 있었습니다. 해결책은 미들웨어를 목록 맨 앞에 두어 나가는 길에 마지막으로 실행되게 하고, 정적 자산 경로의 Vary를 다시 쓰는 것입니다.

엣지 압축이 오리진 압축보다 나빴습니다. Cloudflare가 즉석에서 Brotli를 하게 두면 2,041,742바이트가 나왔고, 오리진의 gzip은 1,658,115바이트였습니다. 생각하지 않아도 되는 대가로 23% 더 큰 셈입니다. 온더플라이 압축은 압축률이 아니라 CPU를 최적화합니다. 오리진에서 미리 압축한 자산이 이깁니다.

크롤링을 기다리지 않고 검색엔진에 알리기

#

프로토콜 두 개, 그리고 둘을 합쳐도 커버리지는 실망스럽습니다.

IndexNow는 핑 하나를 받고 Bing, Yandex, Seznam을 커버합니다. 구글과 네이버는 참여하지 않습니다. 리스팅이 저장될 때마다 백그라운드에서 짧은 타임아웃으로 핑을 보내고, 판매완료·마감된 리스팅은 건너뜁니다. 네트워크 실패는 경고를 남길 뿐 그걸 촉발한 저장을 절대 실패시키지 않습니다. 부가적인 베스트 에포트 작업에 허용할 수 있는 동작은 이것뿐이죠.

구글의 Indexing API는 정확히 두 가지 스키마 타입만 받고, 그중 하나가 제게 있는 JobPosting입니다. 살아 있는 공고는 URL_UPDATED, 마감된 공고는 URL_DELETED를 보냅니다. 그 삭제 신호가 정직한 이유는 마감된 리스팅이 noindex도 함께 내보내기 때문이고, 코드에 그렇게 적어두었습니다. 나중에 noindex를 걷어내는 사람이 무엇을 같이 망가뜨리는지 알 수 있도록.

거기서 시간을 두 번 썼습니다. 할당량은 하루 200 URL인데, 리스팅을 일괄 임포트하면 한 번에 수백 번이 호출됩니다. 그래서 임포트된 리스팅은 건너뜁니다. 안 그러면 임포트 한 번이 하루치 예산을 전부 씁니다. 그리고 엔드포인트는 콜론이 들어간 urlNotifications:publish입니다. 슬래시를 쓰면 구글은 평범한 HTML 404를 반환하는데, 그건 API가 비활성화된 것과 똑같아 보입니다.

구조화 데이터가 가르쳐준 것

#

규칙 셋, 각각 서치 콘솔에게 혼나면서 배웠습니다.

1. 파싱할 수 없는 건 빼세요. 급여는 자유 텍스트로 들어옵니다. 예전에는 원문 문자열을 baseSalary.value로 내보냈는데, 그건 유효하지 않고 모든 공고에 단위 누락 플래그가 붙었습니다. 지금은 파싱 안 되는 급여는 그냥 없습니다.
2. 스키마를 만족시키려고 필드를 지어내지 마세요. 구인 공고에 상세 주소가 있는 경우는 드뭅니다. PostalAddress에 그럴듯한 걸 넣고 싶어지죠. 구인 공고에 지어낸 주소는 불완전한 주소보다 나쁩니다. 그래서 지역과 국가만 들어갑니다.
3. 만료일은 선택이 아닙니다. 구글은 validThrough가 없는 JobPosting을 버립니다. 그래서 하나를 유도하되, 오래된 공고가 어제 만료됐다고 주장하지 않도록 하한을 둡니다.

그리고 사이트맵에 대한 네 번째. 전부에 changefreq: daily를 주장하지 마세요. 리스팅 천 개를 매일 다시 크롤링해달라는 요청은 과부하 상태의 호스트로 읽히고, 구글은 사이트 전체의 크롤 속도를 낮추는 것으로 응답합니다. 실제로 얼마나 최근에 바뀌었는지에서 유도하세요.

사이트맵에는 품질 하한선도 있습니다. 제목과 본문을 합쳐 40자. 서치 콘솔이 약 1,000개 리스팅을 “크롤링됨 – 현재 색인이 생성되지 않음"으로 보고했었고, 어떤 중고 페이지의 고유 콘텐츠 전부가 한 단어짜리 제목과 전화번호 하나였습니다. 40자는 일부러 낮게 잡았습니다. 484개 리스팅 중 471개가 한국어이고 한국어는 글자당 담는 정보가 많으니까요. 영어에 맞춘 기준이었다면 마켓플레이스의 절반이 날아갔을 겁니다. 얇은 리스팅도 인덱스 페이지를 통해 크롤 가능한 상태로 남고, 누군가 수정하면 자동으로 사이트맵에 다시 들어옵니다.

여기서 가져갈 것

#

• 한 URL에서 서로 다른 본문을 내주는 일은, 무엇보다 먼저 캐시 키 문제입니다. CDN이 무엇을 키로 삼는지 알아내고, 바로 그 콘텐츠 타입에서 증명하기 전까지는 Vary를 무시한다고 가정하세요.
• 두 시스템이 하나의 목록에 합의해야 한다면, 어느 방향의 오류가 안전한지 알아내서 양쪽 사본 옆에 적어두세요. “이건 어긋날 수 있고, 허용되는 어긋남은 이 방향뿐이다"가 어긋나지 않는 척하는 것보다 낫습니다.
• 봇은 벤더 이름이 아니라 봇 이름으로 매칭하세요. 특히 영어권 밖에서는, 그 벤더가 사용자 손에 들린 브라우저도 만들고 있습니다.
• 멀리 떨어진 상수 사이의 불변식은 시끄럽게 실패하는 곳에 두세요. 임포트 시점은 공짜이고 아무도 건너뛸 수 없습니다.

저는 현재 1인 개발자로 두 개의 프로덕트를 운영하고 있습니다. 하나는 현장에서 견적을 내는 기술자들을 위한 현장 견적 앱이고, 다른 하나는 게시글 등록과 실시간 메시징을 갖춘 마켓플레이스 겸 커뮤니티 앱입니다.

프로덕트도 다르고 사용자도 다르지만, 기술 스택은 거의 동일합니다. 그리고 둘 다 Fly.io에서 가장 저렴한 티어인 shared-cpu-1x 머신에서만 돌아갑니다. 이 제약은 의도적인 것입니다. 피크 부하에 맞춰 서버를 크게 잡는 대신, 작은 머신 한 대에서 뽑아낼 수 있는 성능을 최대한 끌어올리고, 정확히 어디서 무너지는지 측정한 다음, 그 측정된 한계를 기준으로 Fly의 오토스케일러가 머신을 추가하고 제거하도록 맡깁니다. 이 글에서는 이를 가능하게 하는 최적화들, 임계값의 근거가 된 부하 테스트 수치, 그리고 Fly.io에서 스케일 업/다운이 실제로 어떻게 동작하는지 다룹니다.

철학: 머신 한 대를 측정하고, 그다음 곱하기

#

두 앱 모두 스케일링 전략은 같은 세 단계입니다.

1. 작은 머신 한 대를 합리적인 수준에서 최대한 빠르게 만든다.
2. 무너질 때까지 부하 테스트를 하고, 지연 시간이 급격히 나빠지는 동시성 지점을 기록한다.
3. 그 지점 직전에 두 번째 머신이 시작되도록 Fly 오토스케일러를 설정하고, 트래픽이 줄면 유휴 머신을 정지시킨다.

그러면 용량은 머신 수에 거의 선형으로 비례해서 늘어나고, 기본 비용은 앱당 작은 VM 한 대입니다. 아래의 모든 내용은 이 세 단계 중 하나를 위한 것입니다.

작은 머신 한 대를 빠르게 만들기

#

Granian: API는 WSGI, WebSocket은 uvloop ASGI

#

두 백엔드 모두 Django 6 + Django REST Framework입니다. API는 Rust 기반 서버인 Granian이 서빙하지만, ASGI가 아니라 블로킹 스레드 풀을 쓰는 WSGI로 돌립니다.

granian --interface wsgi myapp.wsgi:application \
    --workers 1 --blocking-threads 16 \
    --workers-max-rss 1400 \
    --workers-kill-timeout 15 --respawn-failed-workers

처음에는 --interface asgi --loop uvloop로 시작했는데, 잘못된 선택이었습니다. 이 앱들의 모든 HTTP 뷰는 동기(sync)이고, Django의 ASGI 핸들러는 동기 뷰를 thread_sensitive로, 즉 워커당 한 번에 하나씩 실행합니다. 그래서 ASGI는 워커당 동시 요청을 사실상 하나로 묶어놓으면서도, asyncio/uvloop/Channels 스택 전체를 그냥 메모리에 올려두기만 했습니다. --blocking-threads를 쓰는 WSGI는 같은 동기 뷰를 진짜 스레드 풀에서 돌립니다. 워커 1개 × 스레드 16개 = I/O 바운드 요청(DB 읽기, S3 프리사인) 16개 동시 처리를, 비동기 스택보다 낮은 상주 메모리로 해냅니다.

왜 워커 하나일까요? VM이 코어 하나짜리 shared-cpu-1x이기 때문입니다. 두 번째 워커는 코어 하나에서 파이썬을 병렬로 돌릴 수 없지만(GIL + 코어 1개), 상주하는 Django 프로세스 하나를 통째로 더 잡아먹습니다. Granian이 바로 이 점을 경고합니다. 워커 하나에 스레드 16개가 I/O 바운드 작업에서 1 vCPU 머신의 현실적인 한계치입니다. --workers-max-rss 1400은 워커가 메모리 상한을 넘기면 재생성하므로, 폭주하는 PDF나 이미지 작업이 머신을 OOM으로 끌고 가는 대신 재활용됩니다.

WebSocket은 자체 Granian 프로세스로 빠졌습니다. uvloop와 --ws를 쓰는 ASGI 앱이고, 장수명 커넥션을 위해 워커 하나로 돌립니다. 동기 API에는 ASGI 경로가 전혀 필요 없습니다. 뷰가 소켓으로 푸시하려 할 때는 Redis를 통해 async_to_sync(channel_layer.group_send)를 호출하므로, 메시지는 여전히 WebSocket 프로세스로 건너갑니다. 서버 두 개가 각자 진짜 잘하는 인터페이스를 돌리는 셈입니다. 로컬 Docker도 같은 WSGI 스레드 풀로 돌리기 때문에, 테스트할 때 제 노트북이 프로덕션 머신 한 대와 거의 같은 조건이 됩니다.

핫 패스에는 Rust

#

Python 핫 패스에 Rust 기반 대체재가 있으면 무조건 씁니다.

• orjson (drf-orjson-renderer 경유) — 모든 API 응답이 표준 라이브러리 JSON 인코더 대신 Rust로 직렬화됩니다.
• blurhash-rs — 업로드 시점에 이미지 플레이스홀더를 계산합니다.
• uuid-utils — Rust 기반 UUID 생성.
• psycopg 3 (binary) — C로 가속된 Postgres 드라이버.

이것들은 아키텍처를 바꾸지 않습니다. 두 번째 머신이 필요해지기 전까지 vCPU 하나가 해낼 수 있는 한계치를 끌어올릴 뿐입니다.

숨어 있는 지연 비용 없애기

#

두 코드베이스를 통틀어 가장 큰 성능 개선은 알고리즘이 아니라 커넥션 재사용이었습니다. Granian의 스레드 풀에서는 새 스레드마다 boto3 S3 클라이언트를 새로 만들고 있었고, 사진이나 PDF를 반환하는 모든 엔드포인트가 그 비용을 지불하고 있었습니다. 작은 커스텀 스토리지 클래스로 클라이언트를 프로세스 단위로 캐싱하도록 바꾸자:

새 스레드에서의 서명된 URL 생성이 ~150ms에서 ~1ms로 줄었습니다.

데이터베이스에도 같은 교훈이 적용됩니다. Fly의 Postgres는 PgBouncer 뒤에 있으므로 앱은 conn_max_age=0으로 두고 커넥션 재사용을 풀러에 맡기며, 오래된 SSL 커넥션에 워커가 매달리지 않도록 connect_timeout을 5초로 잡아 빠르게 실패시킵니다.

진짜 병목이 있는 곳에 캐싱하기

#

마켓플레이스를 부하 테스트하면서 새겨둘 만한 사실을 발견했습니다. 한계는 CPU가 아니라 Postgres 커넥션이었습니다. 둘러보기 트래픽은 압도적으로 익명이고 사용자 간에 동일한데, 부하가 걸리면 그 동일한 목록 쿼리들이 CPU는 놀고 있는 동안 커넥션 풀을 포화시킵니다.

해결책은 익명 목록 페이지를 위한 Redis 캐시입니다. 무효화는 네임스페이스별 버전 카운터로 처리합니다. 쓰기가 발생하면 카운터 하나만 올리면 되고(O(1), 키 관리 불필요), 해당 리소스의 캐시된 페이지 전체가 즉시 무효화됩니다. 짧은 TTL이 놓친 것들을 보완합니다. 둘러보기 페이지를 Redis에서 바로 서빙하면 진짜 병목이 제거되고, 작은 머신은 커넥션을 로그인 트래픽에 쓸 수 있게 됩니다.

브로커 없는 백그라운드 작업

#

두 앱 모두 Celery 대신 Django의 데이터베이스 기반 태스크 프레임워크인 django-tasks-db를 씁니다. 별도의 db_worker 프로세스가 데이터베이스를 폴링하며 이미지 처리, PDF 생성, 기계 번역, 리마인더 같은 작업을 처리합니다. 브로커도 없고, 크기를 정하고 모니터링해야 할 추가 서비스도 없으며, API 프로세스는 무거운 작업에 절대 블로킹되지 않습니다. 심지어 워커는 PgBouncer를 우회해 Postgres에 직접 연결하는데, 오래 걸리는 작업은 트랜잭션 풀링과 잘 맞지 않기 때문입니다.

메모리: jemalloc과 스왑 쿠션

#

이미지와 PDF 처리는 정상 상태 기준의 메모리 산정으로는 예측할 수 없는 스파이크를 만듭니다. 저렴한 완화책 두 가지: Docker 이미지에 jemalloc을 프리로드해 단편화를 줄이고, 모든 머신에 스왑을 둡니다(API 머신 2GB, WebSocket 머신 1GB). 스파이크가 나면 프로세스가 OOM으로 죽는 대신 디스크로 스왑됩니다. 스왑은 성능 기능이 아니라, 메모리 할당을 작게 유지할 수 있게 해주는 보험입니다.

Django 부하 테스트: 변곡점 찾기

#

임계값은 직접 측정한 값이어야 설득력이 있습니다. 프로젝트마다 자체 하네스가 있습니다.

• 견적 앱에는 동시성 레벨을 훑으며 RPS, p50/p95/p99, 에러율을 보고하는 작은 Python 스트레스 테스트 스크립트가 있습니다. 미리 생성해 둔 수백 건의 샘플 데이터를 상대로 돌리기 때문에 목록 엔드포인트가 현실적인 데이터 양에서 쿼리됩니다.
• 마켓플레이스는 Locust로 30초 단위 스텝을 밟아 50 → 500 사용자까지 올리며 포화 지점을 찾고, 실제 둘러보기 위주 트래픽에 맞춘 엔드포인트 가중치를 씁니다. 여기에 더 작은 별도 테스트 스위트가 p95 < 2초 임계값으로 프로덕션을 상대로 가상 사용자 5 → 50을 램프합니다.

견적 앱 스윕의 대표적인 수치입니다(Granian 워커 1개 × 블로킹 스레드 16개, 개발 머신의 Docker):

그리고 다른 모든 것을 결정하는 숫자는 shared-cpu-1x 머신 한 대에서 마켓플레이스를 부하 테스트한 결과에서 나옵니다. 기존 ASGI 빌드에서는 이게 단단한 벽이었습니다. 동기 뷰가 사실상 슬롯 3개 정도로 직렬화되는 바람에, p95가 동시 요청 ~5개까지 300ms 미만을 유지하다가 모든 게 thread_sensitive 락 뒤에 줄 서면서 ~8–10개를 지나면 붕괴했습니다. 이 변곡점을 바깥으로 밀어낸 것이 바로 API를 WSGI 스레드 풀로 옮긴 일입니다. 머신당 실질 동시 슬롯이 ~3개가 아니라 16개가 됐고, 이 새 천장이 오토스케일링 설정 전체의 근거입니다.

Fly.io에서 스케일링이 동작하는 방식

#

Fly의 모델은 단순합니다. 앱은 프록시 뒤에 있는 동일한 머신들의 집합이고, 프록시가 머신별 부하를 셉니다. 선언하는 것은 숫자 두 개입니다.

[http_service.concurrency]
  type = 'requests'
  soft_limit = 12   # 이를 넘으면 다른 머신을 시작
  hard_limit = 24   # 이를 넘으면 큐잉 대신 부하를 차단

auto_stop_machines = 'stop'
auto_start_machines = true
min_machines_running = 1

스케일 업: 한 머신의 진행 중(in-flight) 요청이 soft limit을 넘으면 프록시가 정지된 머신을 시작하고 새 트래픽을 그쪽으로 보냅니다. WSGI 스레드 풀 덕에 머신마다 실질 동시 슬롯이 16개이므로 soft limit은 풀의 약 75%인 12로 잡았습니다. 이렇게 하면 사용자가 수 초짜리 지연을 겪은 뒤가 아니라 스레드에 아직 여유가 있을 때 두 번째 머신이 시작됩니다. hard limit 24(풀의 1.5배)는 서킷 브레이커입니다. 짧은 버스트는 스레드에서 큐잉되고, 그 너머에서는 머신 하나가 녹아내리게 두는 대신 프록시가 부하를 차단합니다. (기존 ASGI 빌드는 실질 슬롯이 ~3개여서 8/20이었습니다. 풀을 넓힌 덕에 두 숫자 모두 올릴 수 있었습니다.)

스케일 다운: 트래픽이 줄면 Fly가 유휴 머신을 자동으로 정지시키고, min_machines_running = 1까지 내려갑니다. 정지된 머신은 컴퓨팅 비용이 들지 않고 루트 파일시스템 스토리지만 청구되므로, 각 앱의 기본 비용은 말 그대로 작은 VM 한 대이고 버스트 용량은 항상 대기 중입니다.

원래 저는 여기에 정지된 머신이 “1초도 안 되어 콜드 스타트한다"고 썼습니다. 틀렸고, 비싸게 틀렸습니다. 가정하는 대신 실제로 측정해보니 콜드 스타트는 25~33초가 걸렸고, 아직 부팅 중인 머신에 떨어진 요청은 그 시간을 고스란히 기다려야 합니다. 처음에는 헬스 체크가 전부 초록불인 와중에 CDN 대시보드에 찍힌 22퍼센트 실패율을 이 콜드 스타트 탓으로 돌렸습니다. 알고 보니 그 숫자는 CDN 자체의 Early Hints 프로브가 오리진에서 실패한 것이었고, 실제 클라이언트가 받은 504는 하나도 없었습니다. 그래도 콜드 스타트 자체는 진짜였습니다.

해결책은 위의 스케일링 숫자에 있지 않습니다. 그 숫자들은 멀쩡합니다. 머신이 올라오는 동안 무엇을 하느냐에 있고, Fly에게 머신을 정지 대신 서스펜드하도록 요청하는 데 있습니다. 그러면 깨어나는 일이 약 3초짜리 메모리 복원이 됩니다. 따로 정리해두었습니다. 0으로 스케일 다운, 그리고 재시작마다 30초짜리 장애에서 진단 과정과 무엇을 바꿔야 하는지를 다룹니다. auto_stop_machines를 쓰면서 Fly에서 뭔가를 돌리고 있다면, 이 문단을 믿기 전에 그 글을 먼저 읽으세요.

한 가지 미묘한 포인트: 동시성 타입이 connections가 아니라 requests입니다. 현대 클라이언트는 keep-alive 커넥션을 계속 열어 두기 때문에, 커넥션을 세면 실제 부하에서도 수치가 거의 움직이지 않아 오토스케일러가 트리거되지 않습니다. 진행 중 요청을 세야 실제 작업량이 추적됩니다.

WebSocket은 다른 축으로 스케일된다

#

마켓플레이스는 WebSocket 서버를 같은 Docker 이미지를 공유하는 두 번째 Fly 앱으로 분리합니다. API 앱은 WSGI로 워커 1개 × 블로킹 스레드 16개를 돌리며 요청을 셉니다(soft limit 12). WebSocket 앱은 512MB 머신에서 ASGI로 uvloop와 함께 워커 1개를 돌리며 커넥션을 셉니다.

[http_service.concurrency]
  type = 'connections'
  soft_limit = 1500
  hard_limit = 2000

오래 유지되는 소켓은 열어 두는 비용은 거의 없지만 슬롯을 몇 시간씩 차지하고, HTTP 요청은 슬롯을 밀리초 단위로 차지합니다. 같은 오토스케일링 신호로 둘 다 감당할 수는 없습니다. 분리하면 각 플릿이 자기 부하를 제대로 반영하는 지표로 스케일되고, 유휴 WebSocket 용량은 2GB가 아니라 512MB만 차지합니다. Channels 쪽에서는 Redis 레이어가 capacity: 1500과 60초 메시지 만료로 돌아가고, 30초마다 소켓 keepalive를 보냅니다. Fly의 Redis 프록시가 Channels가 의존하는 장수명 BRPOP 소켓을 유휴 상태로 간주해 끊어버리기 때문입니다.

컴퓨팅을 엣지와 클라이언트로 오프로드하기

#

가장 저렴한 서버 작업은 서버가 아예 하지 않는 작업입니다.

• 정적 파일과 미디어는 Fly의 S3 호환 오브젝트 스토리지에 두고, 비공개 미디어는 서명된 URL로 CDN을 통해 서빙합니다. 이미지 바이트는 Django 머신을 전혀 거치지 않습니다.
• AI 추론은 사용자의 폰에서 돌아갑니다. 두 앱 모두 작은 로컬 LLM(양자화된 4B 모델, 약 2.7GB)을 내장해 기기에서 직접 돌립니다. 서버 측 추론 비용은 0이고, 오프라인에서도 동작합니다.
• 오프라인 우선 모바일(기기의 SQLite와 재시도가 있는 동기화 큐) 덕분에 앱은 키 입력마다 수다스러운 요청으로 API를 두들기는 대신, 쓰기를 배치로 모으고 통신 음영 지역을 견딥니다.

나머지 스택, 간단히

#

인증은 호스팅형 ID 공급자와 WebAuthn 패스키를 쓰고, WebSocket 커넥션은 업그레이드 완료 전에 인증합니다. 프로덕션은 Postgres, 개발은 SQLite. 관리자 화면과 감사 이력에는 기성 Django 패키지 몇 개를 씁니다. 모바일은 Expo 위의 React Native와 TypeScript에 Expo Router와 Tailwind를 쓰고, OTA 업데이트는 자체 호스팅 Expo Updates 서버에서 내보내며, 인앱 구독은 구독 관리 서비스에 맡깁니다. 품질 게이트는 백엔드에 pytest와 mypy, 클라이언트에 단위 테스트와 E2E 테스트입니다.

가져가서 쓸 만한 것

#

이식 가능한 아이디어는 특정 라이브러리가 아니라 루프 자체입니다. 저렴한 머신 한 대를 진짜로 빠르게 만들고(Rust 핫 패스, 커넥션 재사용, 진짜 병목 앞의 캐시, CDN과 클라이언트로 오프로드), 정확히 어느 동시성에서 무너지는지 찾을 때까지 부하 테스트를 하고, 오토스케일러의 soft limit을 그 변곡점에 놓고, 유휴 머신은 정지시키고, 최소 플릿은 1로 유지합니다. 프로덕션 앱 두 개, 실시간 기능, AI 어시스턴트 — 그런데 평상시 청구서는 플랫폼에서 가장 저렴한 VM 두어 대 값입니다.

지금 만들고 있는 견적 앱에는 절대 양보할 수 없는 요구사항이 하나 있습니다. 신호가 없어도 동작해야 한다는 것. 견적은 현장에 나가서 그 자리에서 작성하는데, 현장이라는 게 신축 건물이거나 지하라서 전파가 잡힌다는 보장이 없거든요. 이 제약 덕분에 많은 React 프로젝트가 얼버무리고 넘어가는 질문, “어떤 상태를 어디에 둘 것인가"를 정면으로 마주하게 됐습니다.

흔한 실패 패턴은 스토어 하나에 전부 밀어 넣는 겁니다. API 캐싱, 사용자 설정, 폼 상태, 인증 토큰까지 같은 Redux 덩어리 안에 뒤엉켜 있죠. 하지만 이것들은 성격도 수명도 다른 상태이고, 각자에게 맞는 도구가 따로 있습니다. Zustand, React Query, AsyncStorage는 각각 딱 하나의 문제를 제대로 풀어줍니다. 경계선만 잘 그으면 아키텍처는 거의 알아서 정리됩니다.

상태는 세 종류다

#

라이브러리 얘기를 하기 전에, 지금 관리하려는 게 뭔지부터 분명히 해두는 게 좋습니다.

클라이언트 상태는 앱 런타임에만 존재하는 데이터입니다. UI 토글, 선택된 탭, 폼 입력, 모달 열림 여부. 상위에 소유자가 없고, 프로세스가 끝나면 같이 사라집니다.

서버 상태는 사정이 다릅니다. 소유자는 서버이고, 앱이 들고 있는 건 로컬 복사본일 뿐이죠. 사용자 프로필, 상품 목록, 알림, 피드. 내 복사본은 낡아가고, 다시 가져와야 하고, 지금 이 순간 다른 클라이언트는 다른 버전을 보고 있을지도 모릅니다.

영속 상태는 재시작을 버텨야 하는 데이터입니다. 인증 토큰, 온보딩 완료 플래그, 캐시된 설정, 오프라인 데이터. 기기 자체에 저장됩니다.

대부분의 앱에는 셋 다 있습니다. 그리고 대부분의 사고는 셋을 도구 하나로 처리하려다 생깁니다.

Zustand: 클라이언트 상태 담당

#

Zustand는 격식 차릴 게 없는 작은 상태 라이브러리입니다. Provider도, 보일러플레이트도, 몇 겹씩 쌓인 Context 래퍼도 없습니다. 스토어 만들고 컴포넌트에서 쓰면 끝. 배울 게 사실상 그게 전부입니다.

여러 컴포넌트가 같은 UI 상태를 공유할 때(사이드바 열림/닫힘, 활성 필터, 선택된 항목), API에서 오지 않는 앱 레벨 상태가 있을 때(테마, 언어, 시작 시 읽는 기능 플래그), 장바구니 계산이나 멀티 스텝 위저드처럼 진짜 클라이언트 로직이 있을 때가 Zustand의 자리입니다. 동기적이고 예측 가능하게 업데이트돼야 하는 것들이죠.

기본 스토어는 이렇게 생겼습니다.

import { create } from 'zustand'

interface AppState {
  theme: 'light' | 'dark'
  sidebarOpen: boolean
  selectedFilters: string[]
  setTheme: (theme: 'light' | 'dark') => void
  toggleSidebar: () => void
  setFilters: (filters: string[]) => void
}

const useAppStore = create<AppState>((set) => ({
  theme: 'light',
  sidebarOpen: false,
  selectedFilters: [],
  setTheme: (theme) => set({ theme }),
  toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
  setFilters: (filters) => set({ selectedFilters: filters }),
}))

컴포넌트에서는 이렇게 씁니다.

function Sidebar() {
  const { sidebarOpen, toggleSidebar } = useAppStore()

  if (!sidebarOpen) return null

  return (
    <div className="sidebar">
      <button onClick={toggleSidebar}>Close</button>
      {/* sidebar content */}
    </div>
  )
}

Zustand에 넣지 않는 것

#

우선 API 응답입니다. API를 호출할 때마다 Zustand 스토어에 쓰고, 컴포넌트는 쿼리 대신 스토어를 읽는 프로젝트를 본 적이 있습니다. 그 끝은 캐시 무효화, 로딩 상태, 에러 처리, 리페치, 페이지네이션을 전부 손으로 다시 구현하는 것이었죠. 전부 React Query가 공짜로 해주는 일들입니다.

또 하나는 재시작 후에도 남아야 하는 데이터입니다. Zustand 상태는 메모리에 있어서 앱을 닫으면 사라집니다. persist 미들웨어로 AsyncStorage에 다리를 놓을 수는 있지만(뒤에서 다룹니다), 그건 의식적으로 내리는 결정이어야지 습관이어서는 안 됩니다.

React Query: 서버 상태 담당

#

React Query(요즘은 TanStack Query죠)는 원격 데이터의 라이프사이클 전체를 관리합니다. 페칭, 캐싱, 동기화, 업데이트, 가비지 컬렉션까지. 발상의 전환 포인트는 서버 데이터를 “내가 소유한 상태"가 아니라 “신선하게 유지해야 할 캐시"로 취급한다는 점입니다. 소유자는 서버고, 나는 복사본을 맡아둔 것뿐입니다.

API에서 오는 데이터라면 저는 전부 여기에 둡니다. 같은 엔드포인트를 여러 컴포넌트가 쓰는 데이터(요청은 자동으로 중복 제거됩니다), 페이지네이션과 무한 스크롤, 앱에 돌아왔을 때 백그라운드에서 다시 가져와야 하는 데이터, UI를 먼저 바꾸고 서버가 거부하면 되돌리는 낙관적 업데이트까지 전부요.

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'

function useUser(userId: string) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetch(`/api/users/${userId}`).then(res => res.json()),
    staleTime: 5 * 60 * 1000, // 5분 동안 fresh로 간주
  })
}

function useUpdateUser() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (data: { id: string; name: string }) =>
      fetch(`/api/users/${data.id}`, {
        method: 'PATCH',
        body: JSON.stringify(data),
      }),
    onSuccess: (_, variables) => {
      queryClient.invalidateQueries({ queryKey: ['user', variables.id] })
    },
  })
}

컴포넌트에서는:

function UserProfile({ userId }: { userId: string }) {
  const { data: user, isLoading, error } = useUser(userId)
  const updateUser = useUpdateUser()

  if (isLoading) return <Spinner />
  if (error) return <ErrorMessage error={error} />

  return (
    <div>
      <h1>{user.name}</h1>
      <button
        onClick={() => updateUser.mutate({ id: userId, name: 'New Name' })}
        disabled={updateUser.isPending}
      >
        Update Name
      </button>
    </div>
  )
}

안 짜도 되는 코드들

#

서버 데이터를 여기 두라고 제가 고집하는 이유는, 공짜로 딸려오는 장치가 그만큼 많아서입니다. 컴포넌트 다섯 개가 같은 사용자를 요청해도 네트워크 요청은 한 번입니다. 창이 포커스를 되찾거나 네트워크가 재연결되면 알아서 리페치합니다. 오래된 캐시는 알아서 가비지 컬렉션되고요. 모든 쿼리가 isLoading, isError, data 같은 값을 넘겨주니 로딩·에러 UI를 매번 새로 만들 필요가 없습니다. 실패한 요청은 지수 백오프로 재시도되고, 롤백까지 포함된 낙관적 업데이트도 내장 패턴으로 제공됩니다. 직접 만들면 하루가 통째로 날아가는 것들이죠.

어울리지 않는 곳

#

클라이언트 전용 상태입니다. 서버를 거치지 않는 데이터에 React Query를 쓰면 절차만 늘어납니다. 모달 열림 상태에 캐시 무효화나 리페치 간격이 필요할 리 없으니까요.

장기 영속 레이어도 아닙니다. 캐시는 메모리에 있으니 재시작하면 텅 비고, 전부 다시 가져옵니다. 캐시를 영속화할 수는 있고 React Native에서는 그래야 하지만(아래 오프라인 섹션에서 다룹니다), 원본은 언제나 서버입니다.

AsyncStorage: 재시작을 버티는 것들 담당

#

AsyncStorage는 React Native의 키-값 저장소입니다. 웹에서의 대응물은 localStorage(동기)나 IndexedDB(비동기, 더 강력함)이고요. 어느 쪽이든 개념은 같습니다. 기기에 기록해서 프로세스보다 오래 사는 데이터라는 것.

플랫폼마다 속은 다르다

#

@react-native-async-storage/async-storage를 쓰면 API는 하나지만, 그 아래 백엔드는 플랫폼마다 꽤 다릅니다.

Android에서는 RKStorage를 통한 SQLite입니다. 앱 내부 저장소 디렉터리의 데이터베이스에 저장되고, 빠르고 안정적이며 샌드박스 처리돼 있어 다른 앱이 건드릴 수 없습니다. 다만 아래 표에 있는 기본 용량 제한은 염두에 두세요.

iOS에서는 작은 값은 NSUserDefaults, 큰 값은 직렬화된 파일에 들어갑니다. 역시 앱 컨테이너 안에 샌드박스 처리됩니다. Apple이 NSUserDefaults에 하드 리미트를 두진 않지만, 값 하나를 몇백 KB 이하로 유지하는 게 상식선입니다. 그보다 크다면 애초에 WatermelonDB나 Realm 같은 제대로 된 데이터베이스를 검토하는 게 맞습니다.

웹(React Native Web / Expo Web)에서는 localStorage로 폴백되는데, 브라우저에 따라 5~10MB 정도가 한계입니다. 웹 전용 React 앱이라면 localStorage를 직접 쓰거나, 데이터가 커지면 idb-keyval 같은 래퍼로 IndexedDB를 쓰면 됩니다.

내가 넣어두는 것들

#

인증 토큰과 세션 데이터, 계속 유지돼야 할 사용자 설정(언어, 테마, 알림 설정), 온보딩 완료 플래그, 오프라인용 캐시 데이터. 요컨대 “재시작을 버텨야 하는 작은 키-값"이 이 카테고리의 전부입니다.

API는 저장소가 가질 수 있는 가장 단순한 모양입니다.

import AsyncStorage from '@react-native-async-storage/async-storage'

// 값 저장
await AsyncStorage.setItem('auth_token', token)

// 값 읽기
const token = await AsyncStorage.getItem('auth_token')

// 객체 저장 (직렬화 필요)
await AsyncStorage.setItem('user_preferences', JSON.stringify({
  theme: 'dark',
  language: 'en',
  notifications: true,
}))

// 객체 읽기
const prefs = JSON.parse(await AsyncStorage.getItem('user_preferences') ?? '{}')

// 값 삭제
await AsyncStorage.removeItem('auth_token')

// 전부 삭제 (주의해서 사용)
await AsyncStorage.clear()

웹에서는

#

웹 전용 React 앱에는 AsyncStorage가 아예 필요 없습니다. 단순한 키-값이면 localStorage로 충분합니다.

// 동기 - 메인 스레드를 블로킹하지만 작은 데이터에는 괜찮다
localStorage.setItem('theme', 'dark')
const theme = localStorage.getItem('theme')

// 구조화된 데이터용
localStorage.setItem('user', JSON.stringify({ name: 'Jared', role: 'admin' }))
const user = JSON.parse(localStorage.getItem('user') ?? '{}')

데이터셋이 커지면 IndexedDB를 씁니다.

import { get, set, del } from 'idb-keyval'

await set('large-dataset', hugeArray)
const data = await get('large-dataset')
await del('large-dataset')

어울리지 않는 곳

#

키-값 저장소지 데이터베이스가 아닙니다. 관계형 데이터, 수천 건짜리 배열, 인덱싱이나 쿼리가 필요한 것들은 SQLite(expo-sqlite), WatermelonDB, Realm의 영역입니다.

보안 저장소도 아닙니다. 루팅되거나 탈옥된 기기에서는 AsyncStorage 내용이 그대로 읽힙니다. 민감한 토큰은 expo-secure-store나 react-native-keychain에 두세요.

셋을 엮는 방법

#

실제 앱에서는 셋을 동시에 씁니다. 제가 자주 쓰는 패턴 몇 가지입니다.

인증 흐름

#

// 1. AsyncStorage: 인증 토큰 영속화
import AsyncStorage from '@react-native-async-storage/async-storage'

async function saveToken(token: string) {
  await AsyncStorage.setItem('auth_token', token)
}

async function getToken(): Promise<string | null> {
  return AsyncStorage.getItem('auth_token')
}

// 2. Zustand: 메모리에서 인증 상태 추적
import { create } from 'zustand'

interface AuthState {
  isAuthenticated: boolean
  token: string | null
  setAuth: (token: string) => void
  clearAuth: () => void
}

const useAuthStore = create<AuthState>((set) => ({
  isAuthenticated: false,
  token: null,
  setAuth: (token) => set({ isAuthenticated: true, token }),
  clearAuth: () => set({ isAuthenticated: false, token: null }),
}))

// 3. React Query: 토큰을 사용해 사용자 프로필 가져오기
function useCurrentUser() {
  const token = useAuthStore((s) => s.token)

  return useQuery({
    queryKey: ['currentUser'],
    queryFn: () =>
      fetch('/api/me', {
        headers: { Authorization: `Bearer ${token}` },
      }).then(res => res.json()),
    enabled: !!token, // 토큰이 있을 때만 패치
  })
}

시작할 때는 이렇게요.

// 앱 초기화
async function initializeApp() {
  const token = await getToken() // AsyncStorage에서 읽기
  if (token) {
    useAuthStore.getState().setAuth(token) // 빠른 접근을 위해 Zustand에 넣기
    // React Query가 자동으로 사용자 프로필을 가져온다
  }
}

AsyncStorage가 토큰을 재시작 너머까지 지켜주고, Zustand가 어디서든 싸게 읽을 수 있게 해주고, React Query는 토큰이 생기는 순간 프로필을 가져옵니다. 각자 잘하는 일 하나씩만 하는 거죠.

재시작해도 남는 테마 설정

#

import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'
import AsyncStorage from '@react-native-async-storage/async-storage'

// Zustand의 persist 미들웨어가 간극을 메워준다
const useThemeStore = create(
  persist(
    (set) => ({
      theme: 'light' as 'light' | 'dark',
      toggleTheme: () =>
        set((state) => ({
          theme: state.theme === 'light' ? 'dark' : 'light',
        })),
    }),
    {
      name: 'theme-storage',
      storage: createJSONStorage(() => AsyncStorage), // React Native
      // storage: createJSONStorage(() => localStorage), // Web
    }
  )
)

런타임 상태는 Zustand가 관리하고, persist 미들웨어가 뒤에서 AsyncStorage(웹이라면 localStorage)와 동기화합니다. 컴포넌트는 영속 레이어가 있는지도 모르고, 알 필요도 없습니다.

오프라인 우선 읽기

#

import { useQuery } from '@tanstack/react-query'
import AsyncStorage from '@react-native-async-storage/async-storage'

function useProducts() {
  return useQuery({
    queryKey: ['products'],
    queryFn: async () => {
      try {
        const res = await fetch('/api/products')
        const data = await res.json()

        // 오프라인 사용을 위해 AsyncStorage에 캐시
        await AsyncStorage.setItem('cached_products', JSON.stringify(data))

        return data
      } catch (error) {
        // 네트워크 실패 - 캐시 데이터 시도
        const cached = await AsyncStorage.getItem('cached_products')
        if (cached) return JSON.parse(cached)
        throw error
      }
    },
    staleTime: 10 * 60 * 1000,
  })
}

페칭과 인메모리 캐싱은 React Query, 네트워크가 없을 때의 폴백은 AsyncStorage. 그런 분담입니다.

오프라인 모드, 단계별로

#

여기가 제 진짜 관심사입니다. 사용자가 지하철, 엘리베이터, 비행기에서 앱을 연다는 일반론도 맞지만, 제 경우는 더 절박합니다. 견적은 현장에서 쓰는 건데, 현장에 신호가 있으리란 보장이 없거든요. 지하에서 스피너만 돌고 있다는 건 견적 한 건을 놓친다는 뜻입니다.

다행히 이 세 라이브러리만으로도, 무거운 프레임워크 없이 꽤 견고한 오프라인 구성을 만들 수 있습니다.

1단계: 오프라인인지 알기

#

먼저 기기가 네트워크 상태를 앱에 알려주고, 앱은 그 답을 어딘가에 담아둬야 합니다. 이벤트는 @react-native-community/netinfo가 쏴주니, 작은 Zustand 스토어에 담아 어디서든 읽을 수 있게 합니다.

import { create } from 'zustand'
import NetInfo from '@react-native-community/netinfo'

interface NetworkState {
  isOnline: boolean
  setOnline: (online: boolean) => void
}

const useNetworkStore = create<NetworkState>((set) => ({
  isOnline: true,
  setOnline: (online) => set({ isOnline: online }),
}))

// 앱 시작 시 한 번만 구독
NetInfo.addEventListener((state) => {
  useNetworkStore.getState().setOnline(state.isConnected ?? false)
})

이제 어떤 컴포넌트든 useNetworkStore((s) => s.isOnline)을 확인해서 오프라인 배너를 띄우거나, 전송 버튼을 비활성화하거나, “다시 연결되면 동기화됩니다"라고 안내할 수 있습니다.

2단계: React Query에 오프라인 알려주기

#

React Query에는 오프라인일 때 쿼리와 뮤테이션이 어떻게 움직일지 정하는 networkMode가 내장돼 있습니다.

import { QueryClient } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      networkMode: 'offlineFirst',
      // 캐시 데이터를 즉시 반환하고, 온라인일 때 백그라운드에서 리패치
      staleTime: 5 * 60 * 1000,
      gcTime: 24 * 60 * 60 * 1000, // 캐시를 24시간 유지
      retry: (failureCount, error) => {
        // 오프라인이면 재시도하지 않음 - 어차피 또 실패할 뿐
        if (!useNetworkStore.getState().isOnline) return false
        return failureCount < 3
      },
    },
    mutations: {
      networkMode: 'offlineFirst',
    },
  },
})

세 가지 모드는 이렇습니다.

대부분의 모바일 앱에는 offlineFirst가 정답입니다. 캐시 데이터는 즉시 보이고, 새 데이터는 네트워크가 허락할 때 도착합니다.

3단계: 쿼리 캐시 영속화

#

기본 상태에서는 캐시가 메모리에만 있어서, 재시작하면 온 화면이 스피너가 됩니다. 오프라인 모드라면 캐시를 AsyncStorage에 영속화해야 합니다.

import { QueryClient } from '@tanstack/react-query'
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
import AsyncStorage from '@react-native-async-storage/async-storage'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 24 * 60 * 60 * 1000, // 24시간 - maxAge 이상이어야 함
    },
  },
})

const asyncStoragePersister = createAsyncStoragePersister({
  storage: AsyncStorage,
  key: 'react-query-cache',
})

// App 컴포넌트에서
function App() {
  return (
    <PersistQueryClientProvider
      client={queryClient}
      persistOptions={{
        persister: asyncStoragePersister,
        maxAge: 24 * 60 * 60 * 1000, // 24시간보다 오래된 데이터는 복원하지 않음
        dehydrateOptions: {
          shouldDehydrateQuery: (query) => {
            // 성공한 쿼리만 영속화
            return query.state.status === 'success'
          },
        },
      }}
    >
      <YourApp />
    </PersistQueryClientProvider>
  )
}

이제 신호가 없는 곳에서 앱을 열어도 빈 화면 대신 마지막으로 받아온 데이터가 바로 보이고, 네트워크가 돌아오면 React Query가 조용히 뒤에서 리페치합니다.

4단계: 오프라인 중의 쓰기를 큐에 쌓기

#

읽기는 쉬운 절반입니다. 재미있어지는 건 쓰기 쪽인데, 신호가 없는 곳에서 댓글을 달거나 주문을 넣거나 프로필을 고치면, 그 변경을 큐에 쌓아뒀다가 나중에 재실행해야 하죠.

React Query의 답은 useMutation과 onMutate의 낙관적 업데이트입니다.

import { useMutation, useQueryClient } from '@tanstack/react-query'
import AsyncStorage from '@react-native-async-storage/async-storage'

interface Comment {
  id: string
  text: string
  postId: string
  createdAt: string
  pending?: boolean
}

function useAddComment(postId: string) {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: async (text: string) => {
      const res = await fetch(`/api/posts/${postId}/comments`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ text }),
      })
      return res.json()
    },

    // 낙관적 업데이트 - 댓글을 즉시 표시
    onMutate: async (text) => {
      await queryClient.cancelQueries({ queryKey: ['comments', postId] })

      const previous = queryClient.getQueryData<Comment[]>(['comments', postId])

      const optimisticComment: Comment = {
        id: `temp-${Date.now()}`,
        text,
        postId,
        createdAt: new Date().toISOString(),
        pending: true, // UI에서 "전송 중..." 표시
      }

      queryClient.setQueryData<Comment[]>(
        ['comments', postId],
        (old) => [...(old ?? []), optimisticComment]
      )

      return { previous }
    },

    // 실패 시 롤백
    onError: (err, text, context) => {
      if (context?.previous) {
        queryClient.setQueryData(['comments', postId], context.previous)
      }
    },

    // 서버에서 실제 데이터를 가져오기 위해 리패치
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['comments', postId] })
    },
  })
}

뮤테이션에 networkMode: 'offlineFirst'가 설정돼 있으면, 네트워크가 돌아올 때까지 mutationFn이 일시 정지됩니다. 낙관적 업데이트 덕에 댓글은 화면에 바로 뜨고, 실제 API 호출은 재연결 시점에 나갑니다.

순서대로 재실행해야 하는 보류 변경이 수십 건씩 쌓이는, 더 본격적인 큐가 필요하다면 뮤테이션 큐 자체도 영속화할 수 있습니다.

import { MutationCache } from '@tanstack/react-query'

// 보류 중인 뮤테이션을 AsyncStorage에 저장
const mutationCache = new MutationCache({
  onError: async (error, variables, context, mutation) => {
    // 디버깅을 위해 실패한 뮤테이션 기록
    const pending = JSON.parse(
      await AsyncStorage.getItem('pending_mutations') ?? '[]'
    )
    pending.push({
      key: mutation.options.mutationKey,
      variables,
      timestamp: Date.now(),
    })
    await AsyncStorage.setItem('pending_mutations', JSON.stringify(pending))
  },
})

5단계: 네트워크가 돌아오면 맞춰주기

#

재연결 처리의 대부분은 React Query가 알아서 합니다. 멈춰 있던 뮤테이션은 재개되고, 낡은 쿼리는 리페치됩니다. 우리가 할 일은 React Query의 매니저들을 React Native 이벤트에 연결해주는 것뿐입니다.

import NetInfo from '@react-native-community/netinfo'
import { onlineManager, focusManager } from '@tanstack/react-query'
import { AppState } from 'react-native'

// React Query에 네트워크 상태 변경을 알려주기
onlineManager.setEventListener((setOnline) => {
  return NetInfo.addEventListener((state) => {
    setOnline(!!state.isConnected)
  })
})

// 앱이 포그라운드로 돌아올 때 리패치
focusManager.setEventListener((setFocused) => {
  const subscription = AppState.addEventListener('change', (status) => {
    setFocused(status === 'active')
  })
  return () => subscription.remove()
})

앱을 한 시간쯤 백그라운드에 뒀다가 돌아오면 focusManager가 리페치를 돌려 최신 데이터를 보여주고, 터널을 빠져나와 신호가 잡히면 onlineManager가 멈춰 있던 것들을 다시 굴립니다.

6단계: UI로 알려주기

#

뭘 하든, 네트워크 에러를 조용히 삼키는 것만은 하지 마세요. 지금 오프라인이라는 것, 어떤 변경이 보류 중인지 사용자에게 보여줘야 합니다.

import { useNetworkStore } from './stores/network'

function OfflineBanner() {
  const isOnline = useNetworkStore((s) => s.isOnline)

  if (isOnline) return null

  return (
    <View style={styles.banner}>
      <Text>오프라인 상태입니다. 다시 연결되면 변경사항이 동기화됩니다.</Text>
    </View>
  )
}

function CommentItem({ comment }: { comment: Comment }) {
  return (
    <View style={[styles.comment, comment.pending && styles.pending]}>
      <Text>{comment.text}</Text>
      {comment.pending && (
        <Text style={styles.pendingLabel}>전송 중...</Text>
      )}
    </View>
  )
}

전체 그림

#

┌─────────────────────────────────────────────────┐
│                   Components                     │
│  useQuery() for reads    useMutation() for writes│
└──────────┬──────────────────────┬────────────────┘
           │                      │
     ┌─────▼──────┐        ┌─────▼──────┐
     │ React Query │        │ React Query │
     │   Cache     │        │  Mutation   │
     │ (in-memory) │        │   Queue     │
     └─────┬──────┘        └─────┬──────┘
           │                      │
     ┌─────▼──────────────────────▼──────┐
     │     AsyncStorage Persister         │
     │  (survives app restart)            │
     └─────┬──────────────────────┬──────┘
           │                      │
     ┌─────▼──────┐        ┌─────▼──────┐
     │   Zustand   │        │   Network  │
     │ (isOnline,  │◄───────│   NetInfo  │
     │  UI state)  │        │            │
     └────────────┘        └────────────┘

진짜 동기화 엔진이 필요해지는 순간

#

지금까지의 구성은 서버가 원본이고 오프라인은 일시적이라는 전제 위에 서 있습니다. 충돌 해결까지 포함된 진짜 오프라인 우선(두 기기가 같은 문서를 오프라인에서 고치는 메모 앱 같은 세계)이 필요하다면, 이 스택으로는 부족하고 전용 동기화 엔진이 필요합니다. WatermelonDB는 React Native용으로 만들어져 SQLite 위에서 돌고, 충돌 해결용 동기화 프로토콜을 갖췄습니다. Realm은 Atlas Device Sync와 묶으면 MongoDB Atlas를 통한 자동 충돌 해결이 되는 완전한 오프라인 우선 데이터베이스가 되고요. PowerSync는 기존 Postgres 백엔드와 붙는 SQLite 기반 동기화 레이어입니다. 완전한 제어가 필요하면 Expo SQLite에 직접 만든 동기화 로직이라는 길도 있습니다.

Zustand + React Query + AsyncStorage로 모바일 앱의 80% 정도는 커버됩니다. 나머지 20%, 그러니까 협업 편집이나 멀티 디바이스 동기화 같은 오프라인 중심 워크플로우에는 전용 동기화 데이터베이스가 필요합니다.

어디에 둘지 헷갈릴 때

#

저는 애매하면 이 질문들을 순서대로 던져봅니다.

자주 나오는 패턴

#

플랫폼별 설치

#

React Native (Android + iOS)

#

셋 다 한 번에 설치합니다.

npm install zustand @tanstack/react-query @react-native-async-storage/async-storage

민감한 데이터용 보안 저장소도 추가하고요.

npx expo install expo-secure-store
# or
npm install react-native-keychain

Expo

#

AsyncStorage는 Expo에서 그대로 동작합니다. 네이티브 링킹도 필요 없습니다.

npx expo install @react-native-async-storage/async-storage

웹 전용 React

#

AsyncStorage는 건너뛰고 localStorage나 IndexedDB를 직접 쓰면 됩니다.

npm install zustand @tanstack/react-query
# Optional for IndexedDB
npm install idb-keyval

Zustand의 persist 미들웨어는 웹에서 기본으로 localStorage를 씁니다.

persist(storeConfig, {
  name: 'my-store',
  // 웹에서 localStorage가 기본값 - 추가 설정 필요 없음
})

자꾸 보게 되는 실수들

#

API 데이터를 Zustand에 넣는 것. 액션 안에 setUsers(apiResponse.users)가 있다면 일단 손을 멈추세요. 그건 React Query의 일이고, 그 길 끝에는 어설픈 캐시 무효화 재발명이 기다리고 있습니다.

클라이언트 상태에 React Query를 쓰는 것. queryFn이 네트워크 요청을 안 한다면 도구를 잘못 골랐습니다.

AsyncStorage를 데이터베이스처럼 쓰는 것. 10,000건짜리 배열을 키-값 저장소에 직렬화하고 있다면, 그냥 데이터베이스를 쓰는 게 맞습니다.

토큰을 평문으로 두는 것. AsyncStorage는 보안 저장소가 아닙니다. 인증 토큰, API 키, 자격 증명은 expo-secure-store나 플랫폼 키체인으로 보내세요.

영속화를 손으로 만드는 것. 마운트 때 AsyncStorage를 읽고 상태가 바뀔 때마다 쓰는 코드를 짜고 있다면, Zustand의 persist 미들웨어가 하이드레이션과 직렬화까지 이미 다 해줍니다. 코드는 줄고 버그도 줄어들죠.

서버 데이터는 React Query로. 클라이언트 상태는 Zustand에. 재시작을 버텨야 하는 건 AsyncStorage에, 민감한 건 보안 저장소에.

제가 겪어본 최악의 아키텍처들은 하나같이 거대한 스토어 하나로 모든 게 흘러들었습니다. 좋은 아키텍처에는 서버 상태, 클라이언트 상태, 영속화할 것 사이에 또렷한 선이 있었고요. 그 선을 일찍 그어두면 그다음 일이 전부 쉬워집니다.

2026년 9월 13일 업데이트. 이 글이 올라간 뒤 Codemagic이 CodePush 계열의 오픈소스 자체 호스팅 OTA 서버 Patch를 공개했습니다. 서버를 직접 만들고 싶지는 않아서 여기까지 오셨다면 이제 현실적인 선택지가 하나 생긴 셈입니다. 저도 그 뒤 아래 구성에서 Patch로 앱 하나를 옮기고 그 과정을 글로 정리했고, 마치며 아래에 짧은 메모를 덧붙였습니다. 밝혀둘 것: 그 마이그레이션과 글은 Codemagic의 의뢰로 비용을 받고 진행했고, 이 글에 언급을 넣어달라는 요청도 있었습니다. 본문의 코드는 이후 짧은 예제로 줄였습니다.

제가 만들고 있는 견적 앱은 버그 수정을 OTA(Over-the-Air)로 배포합니다. JavaScript 변경 사항이 App Store 심사를 거치지 않고 바로 사용자 폰에 도착하죠. Expo의 호스팅 서비스인 EAS Update를 쓰면 이걸 알아서 해주지만, 저는 Django REST Framework와 Tigris S3로 서버를 직접 만들었습니다. 그 뒤로 iOS와 Android 업데이트는 전부 이 서버가 처리하고 있습니다.

Expo OTA 업데이트는 이렇게 동작합니다. 앱에 들어 있는 expo-updates 라이브러리가 플랫폼과 런타임 버전을 헤더에 담아 업데이트 서버에 매니페스트를 요청합니다. 서버는 호환되는 최신 업데이트와 그 JavaScript 번들·에셋의 URL을 돌려주고, 앱은 그것들을 내려받아 다음 실행 때 새 번들로 뜹니다. EAS Update는 이 프로토콜을 구현한 Expo의 호스팅 서버일 뿐이라, 같은 프로토콜을 말하는 서버라면 무엇이든 그 자리를 대신할 수 있습니다. 제가 만든 게 바로 그런 서버입니다.

이 글에서는 모델 설계부터 매니페스트 엔드포인트, 퍼블리시 파이프라인, 그리고 직접 운영해 봐야 알게 되는 함정까지 전체 과정을 정리했습니다.

굳이 직접 호스팅하는 이유

#

제 경우엔 비용이 가장 컸습니다. EAS Update 요금은 사용량에 따라 올라가서, 사용자가 늘고 업데이트가 잦아지면 부담이 됩니다. 반면 Tigris 같은 S3 호환 스토리지는 거의 공짜에 가깝죠. 다른 이유가 더 중요한 경우도 있을 겁니다. 애플리케이션 에셋을 전부 자체 인프라 안에 둬야 하는 업계도 있고, 서버를 직접 운영하면 업데이트 흐름 전체를 손에 쥐게 되니 특정 사용자 그룹에만 배포하거나 번들 A/B 테스트를 하는 것도 자유롭습니다. 업데이트 파이프라인이 Expo의 가용성이나 다음 요금 개편에 좌우되지 않는다는 점도 은근히 큽니다.

전체 구조

#

구성 요소는 넷입니다. 업데이트 매니페스트를 내려주고 메타데이터를 저장하는 Django 백엔드, 번들과 에셋 실물을 보관하는 Tigris, 내보내기·업로드·등록을 한 번에 처리하는 퍼블리시 스크립트, 그리고 Expo 서버 대신 제 서버를 바라보도록 설정한 모바일 앱입니다.

┌─────────────────┐
│   Mobile App    │
│  (expo-updates) │
└────────┬────────┘
         │ 1. Request manifest
         │    (with headers: platform, runtime-version)
         ↓
┌─────────────────┐
│  Django Server  │
│  /api/expo-     │◄─── 2. Query DB for latest update
│   updates/      │
│   manifest/     │
└────────┬────────┘
         │ 3. Generate presigned URLs
         │
         ↓
┌─────────────────┐
│   Tigris S3     │
│  (Asset Files)  │◄─── 4. App downloads bundles directly
└─────────────────┘

구현

#

모델 두 개

#

모든 것의 바탕은 ExpoUpdate와 ExpoUpdateAsset입니다. 전자는 업데이트별 메타데이터를 담습니다.

class ExpoUpdate(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    runtime_version = models.CharField(max_length=50, db_index=True)
    platform = models.CharField(
        max_length=10,
        choices=[("ios", "iOS"), ("android", "Android")],
        db_index=True
    )
    is_active = models.BooleanField(default=True, db_index=True)
    manifest_data = models.JSONField()
    description = models.TextField(blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        indexes = [
            models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
        ]

설계할 때 의도한 부분이 몇 가지 있습니다. runtime_version은 app.json의 runtimeVersion에 대응하는데, 클라이언트는 자기 런타임 버전과 일치하는 업데이트만 내려받기 때문에 이 필드가 핵심 역할을 합니다. iOS와 Android는 번들 자체가 다르니 레코드를 분리했고, is_active는 롤백 장치입니다. 문제 있는 업데이트를 비활성화하면 클라이언트는 이전 것으로 돌아갑니다. manifest_data에는 Expo Updates v1 프로토콜 매니페스트 전체를 JSON으로 넣어두기 때문에, 서빙할 때는 꺼내기만 하면 됩니다.

ExpoUpdateAsset은 개별 파일을 추적합니다.

class ExpoUpdateAsset(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    update = models.ForeignKey(ExpoUpdate, on_delete=models.CASCADE, related_name="assets")
    hash = models.CharField(max_length=255, db_index=True)
    key = models.CharField(max_length=255)
    content_type = models.CharField(max_length=100)
    file_extension = models.CharField(max_length=10)
    file_path = models.CharField(max_length=500)
    file_size = models.IntegerField(default=0)

에셋은 SHA-256 해시로 참조하므로 불변이고 캐시하기도 좋습니다. 같은 에셋을 여러 업데이트에서 공유할 수도 있고요.

매니페스트 엔드포인트

#

앱과 서버가 실제로 대화하는 곳이 /api/expo-updates/manifest/입니다. Expo Updates v1 프로토콜을 구현합니다.

@action(detail=False, methods=["get"], url_path="manifest")
def manifest(self, request):
    # Extract required headers
    protocol_version = request.META.get("HTTP_EXPO_PROTOCOL_VERSION")
    platform = request.META.get("HTTP_EXPO_PLATFORM")
    runtime_version = request.META.get("HTTP_EXPO_RUNTIME_VERSION")

    # Validate protocol version
    if protocol_version != "1":
        return Response(
            {"error": f"Unsupported protocol version: {protocol_version}"},
            status=400
        )

    # Find latest active update for this runtime + platform
    update = ExpoUpdate.objects.filter(
        runtime_version=runtime_version,
        platform=platform,
        is_active=True,
    ).order_by("-created_at").first()

    # No update available - client uses embedded bundle
    if not update:
        response = Response(status=204)
        response["expo-protocol-version"] = "1"
        return response

    # Generate presigned URLs for all assets
    manifest_data = build_manifest(update)  # fills in presigned asset URLs

    return Response(manifest_data, status=200)

여기서 중요한 게 셋 있습니다. 업데이트가 없으면 204를 반환하고, 앱은 내장 번들을 그대로 씁니다. 매니페스트의 에셋 URL은 presigned URL이라 Django를 거치지 않고 Tigris CDN에서 바로 내려받습니다. 그리고 응답의 expo-protocol-version 헤더는 생략하면 안 됩니다. 클라이언트가 실제로 확인하거든요.

업데이트 퍼블리시

#

퍼블리시는 Django 관리 명령과 이를 감싼 셸 스크립트로 합니다. 관리 명령은 expo export 출력을 읽고, 에셋마다 SHA-256 해시를 계산하고, 번들과 에셋을 Tigris에 병렬로 올리고, 데이터베이스 레코드를 만들고, 필요하면 프로덕션 동기화용 임포트 JSON까지 버킷에 올립니다. 핵심만 추리면 이렇습니다.

from concurrent.futures import ThreadPoolExecutor

from django.db import transaction


def publish(platform, runtime_version, manifest, files):
    # Upload the bundle and assets in parallel (keys are content hashes)
    with ThreadPoolExecutor(max_workers=10) as executor:
        list(executor.map(upload_asset, files))

    # Swap the active update in one transaction
    with transaction.atomic():
        ExpoUpdate.objects.filter(
            runtime_version=runtime_version,
            platform=platform,
            is_active=True,
        ).update(is_active=False)

        return ExpoUpdate.objects.create(
            runtime_version=runtime_version,
            platform=platform,
            manifest_data=manifest,
        )

평소에 실제로 치는 명령은 래퍼 스크립트 쪽입니다.

# Publish to local environment
./publish.sh ios

# Publish to production
./publish.sh ios --production

# Dry run to validate
./publish.sh --dry-run

내보내기 전에 프로덕션 환경 변수를 불러오고, 플랫폼은 하나만 또는 둘 다 지정할 수 있으며, 다음에 설명할 프로덕션 동기화까지 알아서 해줍니다.

프로덕션 동기화

#

프로덕션 인증 정보를 제 노트북에 두고 싶지 않아서, 프로덕션 배포는 두 단계로 나눴습니다. 먼저 로컬에서 퍼블리시하고(에셋은 Tigris로, 메타데이터 JSON 스냅샷도 함께), 그다음 S3 경로를 담아 프로덕션 API를 호출하면 서버가 직접 메타데이터를 가져옵니다.

@action(detail=False, methods=["post"], url_path="import-update")
def import_update(self, request):
    # Authenticate via Bearer token
    token = request.META.get("HTTP_AUTHORIZATION", "").removeprefix("Bearer ")
    if not hmac.compare_digest(token, settings.IMPORT_TOKEN):
        return Response({"error": "Invalid token"}, status=401)

    # Download the import JSON from the bucket
    s3_key = request.data.get("s3_key")
    obj = s3_client.get_object(Bucket=bucket_name, Key=s3_key)
    data = json.loads(obj["Body"].read())

    # Import into the production database
    with transaction.atomic():
        update, _ = ExpoUpdate.objects.update_or_create(id=data["id"], defaults={...})
        for asset_data in data["assets"]:
            ExpoUpdateAsset.objects.update_or_create(...)

    # Clean up the import JSON
    s3_client.delete_object(Bucket=bucket_name, Key=s3_key)
    return Response({"update_id": str(update.id)})

앱이 내 서버를 바라보게 하기

#

app.json에서 업데이트 URL과 런타임 버전을 설정합니다.

{
  "expo": {
    "runtimeVersion": "1.0.0",
    "updates": {
      "url": "https://api.example.com/api/expo-updates/manifest/"
    }
  }
}

runtimeVersion은 앱과 서버 간에 엄격하게 맞춰야 합니다. 네이티브 코드를 바꾸거나 Expo SDK를 올렸다면 런타임 버전을 올리고 그 버전용 업데이트를 새로 퍼블리시하세요.

Tigris 스토리지

#

Tigris는 S3 호환 오브젝트 스토리지인데, AWS S3보다 훨씬 저렴하고 글로벌 엣지 캐싱이 기본으로 포함됩니다. 사용자가 수 메가바이트짜리 번들을 내려받는 상황에서는 이게 꽤 중요하죠. Django 쪽 설정은 이렇습니다.

# settings.py
BUCKET_NAME = os.getenv("BUCKET_NAME")
AWS_ENDPOINT_URL_S3 = os.getenv("AWS_ENDPOINT_URL_S3")
AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")
AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")
AWS_REGION = os.getenv("AWS_REGION", "auto")

클라이언트 생성은 평범한 boto3입니다.

import boto3

def create_s3_client(endpoint_url, region, access_key, secret_key):
    return boto3.client(
        "s3",
        endpoint_url=endpoint_url,
        region_name=region,
        aws_access_key_id=access_key,
        aws_secret_access_key=secret_key,
    )

다운로드는 presigned URL을 거치므로 앱이 CDN에서 바로 받아옵니다.

presigned_url = s3_client.generate_presigned_url(
    "get_object",
    Params={"Bucket": bucket_name, "Key": asset.file_path},
    ExpiresIn=3600,  # 1 hour
)

보안

#

매니페스트 엔드포인트는 일부러 인증을 걸지 않았습니다. 로그인하기 전의 앱에도 업데이트는 필요하니까요. 임포트 엔드포인트는 이야기가 다릅니다. 프로덕션 데이터베이스에 쓸 수 있는 만큼 공유 시크릿으로 보호하고, 타이밍 공격을 막기 위해 상수 시간 비교를 씁니다.

IMPORT_TOKEN = os.getenv("IMPORT_TOKEN")

# Constant-time comparison prevents timing attacks
if not hmac.compare_digest(token, IMPORT_TOKEN):
    return Response({"error": "Invalid token"}, status=401)

에셋 무결성은 이 설계에서 공짜로 따라옵니다. 모든 것이 SHA-256 해시로 검증되니 변조된 에셋은 그냥 실패할 뿐입니다. presigned URL도 1시간이면 만료돼서 번들이 계속 직링크로 노출될 일이 없습니다.

속도

#

(runtime_version, platform, is_active, -created_at) 복합 인덱스 덕분에 업데이트가 아무리 쌓여도 매니페스트 쿼리는 빠르게 유지됩니다.

class Meta:
    indexes = [
        models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
    ]

퍼블리시 스크립트는 에셋을 병렬로 업로드합니다.

with ThreadPoolExecutor(max_workers=10) as executor:
    futures = {executor.submit(upload_asset, asset): asset for asset in assets}
    for future in as_completed(futures):
        # Track progress

에셋 50개 정도의 일반적인 업데이트 기준으로, 퍼블리시 시간이 2분 남짓에서 15초로 줄었습니다. 배포 쪽은 할 일이 없습니다. Tigris가 알아서 사용자 가까운 엣지에 캐싱해 줍니다.

평소 워크플로우

#

개발 중

#

# 1. Make code changes in the app
git commit -am "Fix bug"

# 2. Publish OTA update to local environment
./publish.sh ios

# 3. Test on device
# App automatically downloads and applies update

프로덕션 배포

#

# 1. Publish to production
./publish.sh ios --production

# 2. Monitor
# Check Django admin for update records
# Verify assets in Tigris dashboard

롤백

#

# Mark problematic update as inactive in Django admin
# or via management shell:
python manage.py shell

>>> from updates.models import ExpoUpdate
>>> bad_update = ExpoUpdate.objects.get(id="uuid-here")
>>> bad_update.is_active = False
>>> bad_update.save()

# Clients will now receive the previous active update

비용

#

이 앱의 활성 사용자는 500명 정도입니다. Tigris에서는 과거 업데이트 약 200MB 저장에 월 $0.02쯤, 업데이트 다운로드로 나가는 월 약 50GB 이그레스에 $1.00쯤 나옵니다. Django 쪽은 원래 API가 돌아가던 서버에 얹혀 있어서 추가 비용이 없고요. 다 합쳐 월 1달러 수준입니다. 비슷한 사용량이면 EAS Update는 연간 $300~500 정도 나올 테니, 본전은 사실상 바로 뽑았습니다.

모니터링과 디버깅

#

특별한 건 없습니다. ViewSet이 매니페스트 요청을 전부 로그로 남깁니다.

logger.info(f"Manifest request: platform={platform}, runtime={runtime_version}")

사실상의 대시보드는 Django admin입니다. 모델만 등록해 두면 조회와 필터링이 다 됩니다.

@admin.register(ExpoUpdate)
class ExpoUpdateAdmin(admin.ModelAdmin):
    list_display = ["platform", "runtime_version", "is_active", "created_at"]
    list_filter = ["platform", "is_active", "runtime_version"]
    search_fields = ["description"]

클라이언트 쪽에서는 expo-updates가 지금 무엇을 보고 있는지 알려줍니다.

import * as Updates from 'expo-updates';

Updates.checkForUpdateAsync().then(update => {
  console.log('Update available:', update.isAvailable);
  console.log('Manifest:', update.manifest);
});

함정들

#

런타임 버전 불일치

#

가장 흔한 실패가 가장 조용하게 일어납니다. 클라이언트는 자기 런타임 버전과 일치하는 업데이트만 내려받습니다. 설치된 앱이 런타임 1.0.0인데 1.0.1용으로 퍼블리시하면, 아무것도 도착하지 않고 에러도 없습니다. 런타임 버전은 빌드와 맞춰 두고, 올리는 건 네이티브 코드가 바뀔 때만으로 제한하세요.

createdAt 타임스탬프

#

expo-updates 클라이언트는 매니페스트의 createdAt을 내장 번들의 commitTime과 비교해서, createdAt이 더 새로운 업데이트만 적용합니다. ViewSet에서는 데이터베이스 타임스탬프로 덮어씁니다.

manifest_data["createdAt"] = update.created_at.strftime("%Y-%m-%dT%H:%M:%S.%fZ")

로컬 개발에서 OTA를 퍼블리시한 뒤에 바이너리를 빌드했다면, 타임스탬프가 더 새로워지도록 OTA를 다시 퍼블리시하세요.

매니페스트 에셋 key 값

#

매니페스트의 에셋별 key 필드는 expo-updates가 캐싱에 쓰는 값인데, 랜덤 UUID나 아무 문자열이 아니라 결정론적 해시(파일명의 MD5 같은)여야 합니다. 이걸 틀리면 클라이언트가 에셋을 제대로 캐시하거나 가져오지 못해서, 첫 로드만 성공하고 그 뒤로는 업데이트가 조용히 깨집니다. 이 문제를 알려준 독자 Raphael Mutschler에게 감사드립니다. 원인을 찾기 전까지 그의 환경에서는 업데이트가 정확히 한 번만 동작했다고 하네요.

expoClient의 앱 설정

#

Linking, Constants처럼 런타임에 앱 설정을 읽는 기능을 쓰고 있다면, 매니페스트의 extra.expoClient 필드에 앱 설정을 넣어야 합니다. 없으면 처음엔 멀쩡히 실행되다가, 앱을 껐다 다시 열 때 크래시하거나 아예 열리지 않을 수 있습니다. expo-updates가 내장 매니페스트를 OTA 매니페스트로 교체하는데, expoClient가 빠져 있으면 해당 API들이 의존하는 설정에 접근할 길이 없어지기 때문입니다. 이것도 Raphael Mutschler가 잡아준 문제입니다.

에셋 정리

#

오래된 업데이트는 Tigris에 계속 쌓입니다. 지금은 수동으로 정리하고 있습니다.

# Delete updates older than 30 days
from datetime import timedelta
from django.utils import timezone

cutoff = timezone.now() - timedelta(days=30)
old_updates = ExpoUpdate.objects.filter(created_at__lt=cutoff, is_active=False)

for update in old_updates:
    # Delete assets from S3
    for asset in update.assets.all():
        s3_client.delete_object(Bucket=bucket_name, Key=asset.file_path)
    # Delete DB records
    update.delete()

당연히 예약 작업으로 돌려야 할 일인데, 아직 손을 못 댔습니다.

다음에 붙이고 싶은 것들

#

(2026년 9월: 지금은 Patch가 이 세 가지를 비롯해 더 많은 걸 해줍니다. 마이그레이션 후기를 참고하세요.)

점진적 롤아웃

#

rollout_percentage 필드를 추가하면 일부 사용자에게 먼저 내보낼 수 있습니다.

rollout_percentage = models.IntegerField(default=100)

# In the manifest view:
if update.rollout_percentage < 100:
    # Hash user ID and check if they're in rollout group
    user_hash = int(hashlib.sha256(user_id.encode()).hexdigest(), 16)
    if (user_hash % 100) >= update.rollout_percentage:
        return Response(status=204)  # No update

스테이징 업데이트 분리

#

environment 필드를 두면 스테이징 빌드와 프로덕션이 서로 다른 업데이트를 받게 할 수 있습니다.

environment = models.CharField(max_length=20, default="production")

# Client sends environment in custom header
environment = request.META.get("HTTP_X_UPDATE_ENVIRONMENT", "production")
update = ExpoUpdate.objects.filter(environment=environment, ...).first()

다운로드 집계

#

작은 모델 하나면 “이 업데이트, 실제로 받은 사람이 있긴 한가?“라는 질문에 제대로 답할 수 있게 됩니다.

class ExpoUpdateDownload(models.Model):
    update = models.ForeignKey(ExpoUpdate, on_delete=models.CASCADE)
    user_id = models.CharField(max_length=255, null=True)
    platform = models.CharField(max_length=10)
    downloaded_at = models.DateTimeField(auto_now_add=True)

마치며

#

시스템 전체가 Django 모델 두 개와 뷰 몇 개, 퍼블리시 스크립트 하나, 그리고 인프라 비용 월 1달러입니다. 시작하기 전에 예상했던 것보다 작게 끝났고, 그 뒤로 두 플랫폼에서 조용히 제 몫을 하고 있습니다.

위 코드는 그 프로덕션 앱의 코드를 예제로 단순화한 것이니, 만드시는 것에 맞게 고쳐 쓰면 됩니다. 독자 Raphael Mutschler가 독립형 구현을 expo-ota-server로 공개해 두었으니, 바로 돌아가는 코드에서 시작하고 싶다면 그쪽도 좋습니다.

서버를 직접 쓰고 싶지 않다면

#

이 글을 쓴 뒤로 Django 없이 같은 자리를 채워주는 것이 둘 생겼습니다. 하나는 위에서 언급한 Raphael의 expo-ota-server입니다. 다른 하나는 Codemagic Patch입니다. 오픈소스이고, Docker Compose 설치로 자기 서버에서 돌아가며, Expo Updates 프로토콜 대신 CodePush 방식을 쓰기 때문에 expo-updates를 Patch SDK로, eas update를 cmpatch release-react로 바꾸게 됩니다. S3 호환 스토리지를 쓸 수 있어서 이 글에 나온 것 같은 Tigris 버킷도 그대로 씁니다.

“다음에 붙이고 싶은 것들"에 적어두고 결국 만들지 않은 것들이 기본으로 들어 있습니다. 스테이징과 프로덕션 배포, 퍼센트 롤아웃, 릴리스별 다운로드·설치 집계, 필수 업데이트, 바이너리 패치, 코드 서명, 그리고 새 번들이 앱 준비 완료를 보고하기 전에 크래시하면 기기에서 롤백하는 기능까지요. 대신 SDK가 앱에 들어 있어야 하니 누구든 Patch 업데이트를 받기 전에 새 네이티브 바이너리가 필요하고, 관리 명령 대신 운영할 서버가 생깁니다.

제 앱 하나를, 커밋된 네이티브 프로젝트와 실제 릴리스 파이프라인째로, 이 글의 구성에서 Patch로 옮겼습니다. 그 후기에 뭐가 됐고 뭐가 안 됐는지, 실제로 얼마나 어려운지를 적었습니다. 그 작업은 Codemagic이 후원했고, 사실관계 검토는 있었지만 편집 방향에 대한 검토는 없었습니다.

전체 사양은 Expo Updates Protocol Specification을 참고하세요.

이 글에서는 llama.rn(llama.cpp의 React Native 바인딩)과 Qwen 1.7B로 이걸 어떻게 만들었는지 정리했습니다. 이 크기의 모델치고는 기대 이상으로 일을 잘합니다.

요약하면 이렇습니다. llama.rn을 설치하고, 앱을 처음 열 때 4비트 GGUF 모델(1 GB 정도)을 내려받고, initLlama로 로드한 뒤 응답을 스트리밍으로 받으면 됩니다. iPhone 14 Pro에서 네트워크 없이 초당 15토큰 정도 나옵니다. 이 글의 나머지는 그걸 쓸모 있게 만들기까지의 과정입니다. 모델 고르기, 함수 호출을 안정적으로 끌어내기, 메모리 관리하기.

📝 업데이트: 지금은 처음의 Qwen3-1.7B 대신 Qwen3.5-2B-GGUF를 쓰고 있습니다. 또 /no_think 메시지 꼼수를 버리고 chat_template_kwargs 파라미터로 씽킹 모드를 제대로 끄는 방식으로 바꿨습니다:

chat_response = client.chat.completions.create(
    model="Qwen/Qwen3.5-27B",
    messages=messages,
    max_tokens=32768,
    temperature=0.7,
    top_p=0.8,
    presence_penalty=1.5,
    extra_body={
        "top_k": 20,
        "chat_template_kwargs": {"enable_thinking": False},
    },
)

프롬프트에 꼼수를 심는 것보다 훨씬 깔끔하게 제어됩니다.

클라우드 AI를 쓰기 싫었던 이유

#

모바일 앱의 AI 기능은 대개 공식이 같습니다. 사용자가 메시지를 입력하면, 앱이 클라우드 모델 업체로 보내고, 응답이 돌아오고, 청구서가 쌓입니다.

시공 업체가 업무용으로 쓰는 앱에서 이 공식을 따르면 곤란한 점이 한둘이 아닙니다. 고객의 이름, 주소, 전화번호가 제3자에게 넘어가고, 프로젝트 내용과 견적, 메모가 남의 서버에 쌓입니다. GDPR이니 데이터 레지던시니 하는, 엮이고 싶지 않은 문제도 따라오고요. 게다가 API 비용은 사용자가 늘수록 커집니다.

대안은 모델을 사용자 휴대폰에서 직접 돌리는 것이고, 그래서 그렇게 했습니다.

이제야 가능해진 이유

#

1년 전이었으면 시도하지 않았을 텐데, 비슷한 시기에 세 가지가 바뀌었습니다. 우선 양자화 모델이 작아졌습니다. Q4_K_M 양자화를 거친 Qwen 1.7B는 1.1 GB로 웬만한 게임보다 작고, 한 번 받으면 앱 저장소에 그대로 있습니다. 다음으로 모바일 GPU가 빨라졌습니다. llama.cpp는 iOS에서는 Metal, 최근 Qualcomm GPU를 단 Android에서는 OpenCL을 쓰는데, iPhone 14 Pro 기준 초당 15토큰 정도 나옵니다. 실시간 스트리밍에는 충분하죠. 마지막으로 소형 모델 자체가 쓸 만해졌습니다. Qwen 1.7B는 구조화된 지시를 따르고, JSON을 파싱하고, 여러 단계의 추론도 이어갑니다. 비즈니스 로직에 필요한 게 딱 이 정도입니다. 시를 쓰라는 게 아니니까요.

모델 고르기

#

Qwen3-1.7B로 정착하기 전에 소형 모델 네 개를 테스트했습니다.

TinyLlama 1.1B(637 MB)는 제일 빨랐지만 고객 ID를 지어내거나 필수 필드를 빼먹는 등 구조화된 출력이 도무지 안정되지 않았습니다. Phi-3-mini(1.8 GB)는 추론은 괜찮은데 말이 너무 많아요. 20단어면 될 답이 200단어짜리 작문으로 돌아옵니다. Gemma-2B(1.2 GB)는 분류에는 빠르고 정확했지만 함수 호출이 약해서, 제 도구 시스템에 필요한 <action> 태그를 안정적으로 내놓지 못했습니다. Qwen3-1.7B(1.1 GB)가 딱 적당했습니다. 구조화된 출력이 믿을 만하고, 지시를 정확히 따르고, <think> 태그로 사고 연쇄(chain-of-thought)까지 지원합니다.

Q4_K_M은 llama.cpp의 “k-quant” 양자화 포맷 중 하나입니다. 가중치를 블록 단위로 묶어 4비트 값으로 저장하되 블록마다 자체 스케일을 두고, M 조합에서는 민감한 텐서 몇 개를 6비트로 남겨 둡니다. 그래서 파일은 16비트 가중치보다 70% 정도 작아지고, 품질 손실은 크지 않습니다.

llama.rn 설정

#

llama.rn은 llama.cpp를 React Native용으로 감싼 라이브러리인데, 설치 자체는 쉬운 축에 듭니다:

npm install llama.rn
cd ios && pod install

Expo라면, llama.rn은 네이티브 모듈이라 Expo Go에서는 돌아가지 않습니다. config plugin을 추가하고 개발 빌드를 쓰세요:

// app.config.js
export default {
  expo: {
    plugins: ["llama.rn"],
  },
};

npx expo install llama.rn
npx expo run:ios

프로덕션 빌드에서는 이 플러그인이 llama.rn이 큰 모델용으로 권장하는 iOS entitlement 두 개(Extended Virtual Addressing과 Increased Memory Limit)도 함께 넣어 줍니다.

모델 본체는 첫 사용 시에 내려받습니다:

const MODEL_URL = "https://huggingface.co/unsloth/Qwen3-1.7B-GGUF/resolve/main/Qwen3-1.7B-Q4_K_M.gguf";
const MODEL_PATH = FileSystem.documentDirectory + "llama-models/Qwen3-1.7B-Q4_K_M.gguf";

const downloadModel = async () => {
  const downloadResumable = FileSystem.createDownloadResumable(
    MODEL_URL,
    MODEL_PATH,
    {},
    (progress) => {
      const pct = progress.totalBytesWritten / progress.totalBytesExpectedToWrite;
      setDownloadProgress(pct);
    }
  );

  await downloadResumable.downloadAsync();
};

WiFi에서는 23분, LTE에서는 58분쯤 걸립니다. 다 받았으면 GPU 가속을 켜고 로드합니다:

const ctx = await initLlama({
  model: MODEL_PATH,
  n_ctx: 8192,      // 8K context window
  n_gpu_layers: 99, // Use GPU for all layers
});

n_gpu_layers: 99는 빼먹지 마세요. 연산을 CPU 대신 Metal이나 OpenCL로 넘기는 것만으로 5배쯤 빨라집니다.

스트리밍 추론

#

10초 동안 스피너만 쳐다보고 싶은 사람은 없으니, 응답은 토큰 단위로 스트리밍합니다:

let fullResponse = "";

await llamaContext.completion(
  {
    messages: [
      { role: "system", content: systemPrompt },
      { role: "user", content: "Create a job for John Smith" }
    ],
    n_predict: 512,
    temperature: 0.7,
    top_p: 0.8,
  },
  (data) => {
    // Called for each token
    fullResponse += data.token;
    setStreamingText(fullResponse);
  }
);

요즘 폰이라면 첫 토큰까지 200ms 정도(프롬프트 처리 시간입니다), 이후로는 토큰당 50~80ms입니다. 네트워크를 거치는 API와 비교하면 체감상 즉각적이죠.

소형 모델도 해낼 수 있는 함수 호출

#

대형 클라우드 모델이 쓰는 함수 호출 방식은 JSON 스키마에 기대는데, 소형 모델은 여기서 넘어집니다. JSON이 깨지고, 필수 필드가 빠지고요. 그래서 더 단순한 XML 기반 프로토콜을 씁니다:

const systemPrompt = `You are an AI assistant. When you need to take an action, output:
<action>{"type":"search_customers","query":"Smith"}</action>

Available actions:
- search_customers: {"type":"search_customers","query":"John"}
- create_job: {"type":"create_job","customer_id":5,"alias":"Living Room"}
- update_job: {"type":"update_job","job_id":"J-0042","status":"quoting"}

Rules:
1. ONE action tag per response, at the very end
2. When searching/creating → end with <action>
3. When just chatting → no action tag
`;

XML 태그를 고른 이유는 사실 소박합니다. <action>과 </action>은 시작과 끝이 헷갈릴 여지가 없고, 파싱은 정규식 하나면 끝나고, 프롬프트 안의 예시가 그대로 포맷 문서 역할을 하고, 모델이 태그 앞뒤에 잡소리를 붙여도 잘 동작합니다.

파싱 코드는 보이는 그대로 단순합니다:

function parseAction(text: string): Action | null {
  const match = text.match(/<action>([\s\S]*?)<\/action>/);
  if (!match) return null;

  try {
    return JSON.parse(match[1].trim());
  } catch {
    return null;
  }
}

action이 나오면 실행하고, 결과를 대화에 다시 넣어줍니다:

const action = parseAction(modelResponse);
if (action) {
  const result = await executeAction(action);

  // Inject result as a system message
  conversationHistory.push({
    role: "user",
    content: `[TOOL_RESULT] ${result.message}\n\n→ NEXT: Tell the user what happened.`
  });

  // Continue generation
  await generateNextResponse();
}

이것만으로 다단계 워크플로우가 제대로 돌아갑니다:

사용자: “Create a job for Smith”

1. 모델: <action>{"type":"search_customers","query":"Smith"}</action>
2. 시스템: [TOOL_RESULT] Found: Jane Smith (id:42), Bob Smith (id:89)
3. 모델: “Smith가 두 명 있네요. Jane과 Bob 중 누구인가요?”
4. 사용자: “Jane”
5. 모델: <action>{"type":"create_job","customer_id":42}</action>
6. 시스템: [TOOL_RESULT] Job J-0073 created
7. 모델: “완료했습니다! Jane Smith의 작업 J-0073을 생성했습니다.”

<think> 태그로 사고 연쇄 끌어내기

#

소형 모델은 추론을 소리 내서 하게 만들면 눈에 띄게 안정됩니다. Qwen에는 씽킹 모드가 기본으로 들어 있습니다:

const systemPrompt = `Before each response, wrap your reasoning in <think> tags:

<think>
INTENT: what does the user want?
HAVE: what data do I already have?
NEED: what's still missing?
DECISION: call tool | ask user | just respond
</think>

Then output your actual response.`;

모델 내부에서는 이런 식으로 굴러갑니다:

<think>
INTENT: create a job
HAVE: customer query "Smith"
NEED: exact customer_id
DECISION: search first
</think>
<action>{"type":"search_customers","query":"Smith"}</action>

<think> 태그는 UI에 내보내기 전에 걷어내지만, 개발 중에는 디버깅용으로 그대로 보이게 둡니다. 효과가 정말 큽니다. 모델이 액션을 확정하기 전에 스스로 논리를 정리하거든요.

긴 대화를 8K 안에 담기

#

8K 컨텍스트 윈도우는 도구 결과가 쌓이기 시작하면 생각보다 빨리 찹니다. 제 경우 30턴쯤에서 한계에 부딪혔습니다.

해결책은 대화 압축입니다. 모델에게 스스로를 요약하게 시킵니다:

const compactPrompt = `Summarize this conversation in under 200 words.
Include: user's goal, customers/jobs created (with IDs), and any unfinished tasks.

${conversationHistory.map(m => `${m.role}: ${m.content}`).join('\n\n')}`;

const summary = await chat([{ role: "user", content: compactPrompt }]);

// Replace history with summary
conversationHistory = [
  { role: "user", content: `[CONTEXT SUMMARY]\n${summary}\n[END SUMMARY]` }
];

메시지 50개짜리 대화가 150토큰 정도로 줄어들고, 모델은 만들어 둔 작업이나 고객 ID를 잊지 않고 이어갑니다.

세션 저장

#

채팅 세션은 앱 백엔드에도 저장합니다. 따라 해 볼 만한 건 어시스턴트 메시지를 두 벌로 저장하는 겁니다. 화면에 보여 줄 정리된 버전 하나, <think>와 <action> 태그를 그대로 남긴 원본 하나죠. 이렇게 해 두면 채팅 히스토리는 UI에서 깔끔하게 재생되고, 세션을 다시 열 때는 액션까지 포함한 전체 컨텍스트가 복원됩니다. 사용자는 여느 채팅 앱처럼 히스토리 드롭다운에서 대화를 오갈 수 있습니다.

프로덕션 벤치마크

#

iPhone 14 Pro (A16 Bionic, 6GB RAM):

• 모델 로드: 약 3초
• 첫 번째 토큰: 180-220ms
• 스트리밍: 14-16 tokens/초
• 메모리: 약 1.8 GB

Samsung Galaxy S23 (Snapdragon 8 Gen 2, 8GB RAM):

• 모델 로드: 약 4초
• 첫 번째 토큰: 250-300ms
• 스트리밍: 10-12 tokens/초
• 메모리: 약 2.1 GB

iPhone 11 (A13, 4GB RAM):

• 모델 로드: 약 6초
• 첫 번째 토큰: 400-500ms
• 스트리밍: 6-8 tokens/초
• 메모리: 약 2.2 GB (저메모리에서 간헐적 크래시)

제 기준으로는 쾌적하게 쓰려면 RAM 6GB 이상. 4GB에서도 돌긴 하지만 앱이 백그라운드로 갈 때 모델을 내려야 할 겁니다.

메모리 관리

#

메모리를 움켜쥐고 있는 앱은 iOS가 가차 없이 죽이기 때문에, 포그라운드를 벗어나면 모델을 해제합니다:

useEffect(() => {
  const subscription = AppState.addEventListener("change", (nextAppState) => {
    if (nextAppState === "background") {
      llamaContext?.release(); // Free ~2 GB
    } else if (nextAppState === "active") {
      loadModel(); // Reload when foregrounded
    }
  });

  return () => subscription.remove();
}, []);