今週まで、うちのアプリがクラッシュしたことを知る手段は、誰かが教えてくれることだけでした。ほとんどの人は教えてくれません。アプリを開き直し、また落ちたら、もう開かなくなるだけです。API側は把握できていました（ERRORログはすべてチームのチャットチャンネルに流れます）。でも、スマートフォン上でのクラッシュは、私に見える場所には何の痕跡も残していませんでした。

実は、アプリにはすでに報告の仕組みがひとつありました。アプリが誰かの前にエラーメッセージを表示すると、そのメッセージをAPIの小さなエンドポイントに送り、サーバーがERRORでログに残すので、これもチャットチャンネルに届きます。きっかけは、削除が 成功していた のに行がリストに残り、もう一度タップすると「No Item matches the given query」と表示された件でした。サーバーはごく普通の404を2回記録しただけで、何も言いませんでした。この仕組みでカバーできるのは、アプリが捕まえて表示したエラーです。クラッシュは事情が違います。報告を送るはずのJavaScriptそのものが、たった今死んだのですから。

素直な解決策はSentryです。SentryのSDKはとても気に入っていて、React Nativeのクラッシュレポートが「解決済みの問題」になっているのはこのSDKのおかげです。ただ、ユーザーデータを預ける業者がまたひとつ増え、プライバシーポリシーの行がまたひとつ増え、うちの規模なら多くても1日数件のレポートのためにまた請求書が増えるのは避けたいところでした。そこでSDKはそのままに、サービスの方を置き換えました。アプリのDSNは自前のAPIを指していて、そこのDjangoアプリの小さな一部分が、送られてきたものを受け取り、グルーピングし、アラートを出し、保存します。

この記事では、その仕組みと、本物のネイティブクラッシュが実際に届くことをどう確かめたかを紹介します。

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が送ってくるもの：エンベロープ

#

Sentryの通信フォーマットはエンベロープです。JSONのヘッダー行が1行あり、その後に任意の数のアイテムが続きます。各アイテムは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、生のdeflateに対応し、展開は1MBで打ち切ります。クラッシュイベントは数KBなので、それより大きいものはクラッシュイベントではありません。
• 長さ指定のペイロードは改行を含むことがあります。 \n で分割すると、ネイティブSDKが送るイベントがすべて壊れます。length があるときは必ずそれに従う必要があります。

パーサーは短いものです。残すのは event アイテムだけで、セッション、トランザクション、添付ファイル、クライアントレポートは受け取ったうえで捨てます。

SDKが理解できる形で応答する

#

これは思っていたより大事でした。SDKはディスク上にキューを持ち、届いたか確信が持てないものはすべて再送します。なので、サーバーの応答次第で、SDKが送り続けるかどうかが決まります。

• 200：保存できたとき、 または意図的に捨てたとき 。セッションアイテムに4xxを返すと、SDKはそれを保持したまま永遠に再送します。
• 429と Retry-After ：スロットリングしたとき。エンドポイントにはIPごとの制限（1時間に120件）があります。クラッシュループに入ったスマートフォンは起動のたびに1件送ってくるからです。SDKは429を受けると、期待どおりに間隔を空けてくれます。
• 400：壊れたエンベロープ。ログはエラーではなく警告にしています。壊れたレポートが教えてくれるのは「どこかのクライアントがおかしい」ということで、次のまともなレポートが何がクラッシュしたかを教えてくれます。

SDKは最初の送信が届いたか確信が持てないと同じイベントを再送するので、event_id にはユニーク制約を付けてあり、重複は何も言わずに無視されます。

ソースマップなしでのグルーピング

#

ここは、自作の受信側がSentryなら代わりにやってくれる判断を自分でしなければならない部分です。Sentryはスタックトレースでクラッシュをグルーピングします。でも、リリース版のHermesバンドルは難読化されているので、フレーム名は1文字になり、行や列の位置はビルドのたびに変わります。フレームでグルーピングすると、同じバグがリリースのたびに新しいissueになってしまいます。

ソースマップがない状態（最後に詳しく書きます）では、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) は同じissueになります。SDKが {{ default }} を含まない独自の fingerprint を送ってきたらそちらを優先するので、デフォルトのグルーピングが合わないときはクライアント側から強制できます。例外を持たないイベントはマスクしたログメッセージで、どちらもないイベントはアプリ内の一番上のフレームでグルーピングします。ネイティブのシグナルクラッシュではメッセージが Signal 6, Code 0 のようになるので、シグナル単位でまとまります。粗いですが、シンボリケーションができるまでは正直なやり方です。

チャンネルを埋め尽くさないアラート

#

フィンガープリントごとにissueが1つでき、各レポートはその下にイベントとして保存されます。issueがERRORでログを出す（チャットのアラートが待ち受けているのはこれです）のは、次の場合だけです。

• 新しい issue
• 解決済み のissueが 再発 したとき（issueは再オープンされます）
• 10回目、100回目、1,000回目、10,000回目 の発生

通常の繰り返しはカウンターを増やすだけです。 無視 にしたissueはカウントは続けますが、アラートは一切出しません。その上にチャットのハンドラー自体のレート制限があるので、ダメなリリースでクラッシュループが起きても、届くのは壁のような大量のメッセージではなく、数件で済みます。

保存量も同じように上限を設けています。各issueは 直近50件 のイベントだけを残し、新しいものが来るたびに古いものを削除します。これで最初のグラフが壊れました。50件のイベントでは、先週どれくらいの頻度で起きていたかは分からないからです。そこで各issueに90日分の日ごとの件数も持たせ、カウンターを増やすのと同じトランザクションの中で更新するようにしました。グラフはこの件数から描き、イベントは読むためだけのものです。

自分で作るなら、小さな競合状態が二つ気にかける価値があります。まったく新しいクラッシュが同時に何台ものスマートフォンで起きると、二つのレポートが両方ともissueを作ろうとすることがあるので、フィンガープリントをユニークにして、負けた方が既存の行を読み直すようにします。また、90日の範囲は一番新しいレポートからではなく、サーバーの今日から数えます。時計がずれたスマートフォンは、来年の日付も含めてどんな日付のレポートでも送ってくる可能性があるからです。

ペイロードは128KBが上限です。超えたイベントはまずパンくずリストとデバッグ用のメタデータを削り、それでも大きければ例外、メッセージ、リリース、プラットフォームだけを残して、削ったことが分かる印を付けます。

データの除去

#

SDKは sendDefaultPii: false で動いているので、原理的にはIPアドレスもCookieもリクエストボディも送られません。それでもサーバーはこれに頼りません。保存する前に user からは id と username だけを残し、request は丸ごと捨てます。将来のSDKのバージョンや設定でこれらが送られ始めたときのためです。

実機でテストしたところ、除去すべきものがさらに二つ見つかりました。

• パンくずリストはクエリ文字列も含めたURL全体を記録します。 アプリの検索リクエストは検索語をクエリ文字列に載せて送るので、検索直後にクラッシュすると、その人が何を検索したかまで保存されていたことになります。今はサーバーがパンくずリストのURLをすべて ? で切っています。
• コンソールのパンくずリストには console.log に渡された生の引数が入っています。 アプリがたまたまログに出した任意のオブジェクトが入りうるということです。メッセージ本文は役に立つので残し、引数は捨てます。

どちらも実際のレポートを見て初めて気づいたもので、これが次の節の一番の動機です。

クライアント側

#

アプリでは、すべてが小さなモジュール1つを通ります。OTAアップデートのSDKをラップしているのと同じ理由で、OTAバンドルはネイティブモジュールが存在する前にビルドされたバイナリの上でも動くからです。RNSentry を持たないバイナリでトップレベルに import * as Sentry from "@sentry/react-native" と書くとimportの時点で例外が投げられ、画面が真っ白になります。なので、SDKは遅延して require し、それもネイティブモジュールが本当にあることを確認してからにしています。

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と環境（staging か production）を設定するので、どちらのビルドも同じエンドポイントに報告しつつ、区別できます。ログイン中のユーザーはアカウントIDで設定し、名前やメールアドレスは一切使いません。

エラーバウンダリには明示的な呼び出しが必要でした。Expo Routerのルートの ErrorBoundary はレンダリングエラーを捕まえて独自の画面を表示するので、そのエラーはSDKがフックしているグローバルハンドラーまで届きません。解決策は小さなラッパーで、useEffect の中で captureException を呼んでから、これまでどおりルーターのバウンダリを描画します。ルートのバウンダリにもルートごとのバウンダリにも同じものを使います。レンダリング中ではなくエフェクトの中で呼んでいるのは、再レンダリングのたびにではなく1回だけ報告するためです。ルートコンポーネントは Sentry.wrap でもラップしていて、それが例外を投げたら素のコンポーネントに戻ります。

Web向けには、全関数を無効にした .web.ts 版のモジュールを置いています。Metroがプラットフォーム別のファイルを選ぶので、SDKがWebのバンドルに入ることはありません。Webアプリには動かすべきネイティブモジュールがないからです。

ネイティブクラッシュが届くことを証明する

#

ユニットテストは手書きのエンベロープをPOSTするもので、証明できるのは、SDKが送ってくると 私が思っている ものをパーサーが処理できる、ということだけです。リリースから2日後、本番のクラッシュレポートはゼロでした。アップデートしたのはまだ3人だけだったので、ゼロでもおかしくはありません。でも「誰もクラッシュしていない」と「クラッシュが届いていない」は、サーバーから見るとまったく同じに見えます。本物を見たいと思いました。

そこで、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 を使ってスコープに設定し、ネイティブ層に同期させる必要があります。
• パンくずリストからアプリの動きが見えました。 コンソールの警告、ビューコントローラーのライフサイクル、HTTPの呼び出し。その中には分析SDK自身による収集用エンドポイントへのリクエストも含まれていて、アプリが他にどこと通信しているかを思い出させてくれます。そしてURLにはクエリ文字列が付いていて、これで先ほどの検索語の問題に気づきました。

レポートを読む

#

レポートはDjangoの管理画面で読みます。Sentryをゆるく真似たissueページで、上部に件数とResolve / Ignore / Reopenボタン、日ごとの棒グラフ、リリース・OS・端末・OTAバンドル別の内訳があり、その下でイベントを1件ずつ、例外、フレーム（アプリのフレームは強調し、ライブラリのフレームは折りたたみます）、パンくずリスト、端末のコンテキストと一緒に表示します。新しい依存関係は要りませんでした。

作っている途中で一つ修正が出ました。ネイティブクラッシュでは「原因（culprit）」フレームが端末上のバイナリのパスになっていて、そこにインストールごとのUUIDが含まれるため、同じクラッシュが端末ごとに違って見えていました。今は 0x1000a1b2c (MyApp) のように、アドレスとバイナリ名だけを表示します。

プライバシーポリシーを、まるごと

#

クラッシュレポートは、ほぼ個人情報です。アカウントID、スマートフォンの機種、そしてアプリが死ぬ直前の1分間にその人が何をしていたか。なので、プライバシーポリシーに1段落必要でした。きちんと書くにはレポートに何が入っているかを正確に書く必要があったので、さっき見たばかりのペイロードから列挙しました。エラー、アプリのバージョンとOTAアップデート、機種、OSと言語、空きメモリと画面サイズ、直前の数十ステップ（開いた画面、 ? 以降を取り除いたWebアドレス、アプリ自身のログ）、そしてアカウントIDかランダムなインストールID。ポリシーには、レポートが自社のサーバーに届き、Sentryやその他のクラッシュレポート会社には送られないことも書いています。保存期間は表に専用の行を設けました。問題ごとに直近50件のレポートと、90日分の日ごとの件数です。

一つの段落をコードと突き合わせ始めると、残りを確認しないわけにはいきませんでした。既存のポリシーは耐えられませんでした。アカウント削除ページには、アカウントを閉じるとプッシュ通知のトークンとパスキーは即座に削除され、サーバーログは90日以内に消える、と書かれていました。どれも事実ではありませんでした。アカウントを閉じるとサインイン方法の紐付けが外れてプロフィールは匿名化されますが、プッシュ通知のトークンとパスキーは誰かが手で消すまで残りますし、ログのアーカイブにはまだ有効期限がありません。そこでポリシー全体を、コードが実際に何をしているかの棚卸しから書き直し、それらの行は今は「まだ自動では削除されません。メールでご連絡ください」となっています。安心感は減りますが、正確です。

リポジトリには今、そのためのルールがあります。ポリシーは私たちの意図ではなくコードが何をするかを書くこと、そして個人データを新たに収集・送信・保存する変更は、同じコミットでポリシーも更新すること。対象にはアプリ内の要約画面、アカウント削除ページ、そしてストアのコンソールにしか存在しないアプリストアのプライバシーフォームも含まれます。これを書き留めるきっかけになった変更が、クラッシュレポートでした。

足りないもの

#

シンボリケーション。 これが本当の穴で、sentry.ioがやっていて私がまだ置き換えていない唯一のものです。スタックはJavaScriptでは難読化され、ネイティブコードではシンボル化されていません。

• JavaScript： フレームはHermesバンドルの中を指しています。直すには、ストア向けビルドとOTAバンドルのすべてについて合成済みのHermesソースマップをリリースとバンドルをキーに保存しておき、ページを描画するときにJSのフレームに適用する必要があります。うちのクラッシュの大半はJavaScriptになるはずなので、次に取りかかるのはこれです。
• iOSのネイティブ： 命令アドレスにはビルドのdSYMが必要です。
• Android： 難読化（minification）を有効にするとJavaのフレームはR8で難読化され（mapping.txt が必要）、C++のフレームにはNDKのシンボルが必要です。

先ほど見つけた、もう少し小さな穴もあります。OTAタグは beforeSend でしか付けていないので、ネイティブクラッシュにはまだ付きません。実行中のバンドルが確定した時点でスコープに設定するのは数行ですが、まだ書いていません。

今のところ、issueから分かるのは、 何が クラッシュしたか、どのリリース、OTAバンドル、端末でか、そしてその直前に何をしていたかです。ソースの どこで かは分かりません。週に数回リリースする小さなアプリなら、これまでは型とメッセージとパンくずリストで十分に原因を見つけられています。

受信側、管理画面、テストを合わせてもコードは多くなく、すでに動いていたAPIの上に追加のコストはかかっていません。難しい部分はSDKがやってくれます。スマートフォン上でクラッシュを捕まえ、次の起動時にレポートを送り出すことです。

開示。 この移行と記事の執筆には Codemagic から報酬を受けています。Codemagic のレビューは事実関係の確認だけで、論調には及ばず、先方の要望で書き換えた箇所はありません。問題にぶつかって報告した箇所はそう書いていますし、あなたが読む時点で直っているものは、直ったものとして書いてあります。

2026年9月23日追記。 私が報告した問題には、Codemagic の開発者が順に対応してくれました。iOS のバージョン検出のバグ、二重に数えられたインストール、無音の初回セットアップ、うるさいデバッグコマンドを含めて大半はすでに修正済みで、ドキュメントにもコミット済みのネイティブプロジェクトの扱いとクラッシュ時のロールバックまでの予算が載りました。本文ではそれぞれ該当する箇所でそう書き添え、まだ残っているいくつかは元のままにしています。

2026年10月16日追記。 Patch に移ってから初めてのネイティブのアップグレード（Expo SDK 58）で、Patch の設定がまったく入っていない Android のリリースビルドができあがり、しかもどこもエラーを出しませんでした。何が起きたのかと、ファイル1つで済んだ修正は 初めてのネイティブアップグレード に書きました。

2月に、Expo のアップデートサーバーを自作した話 を書きました。あれは今も動いています。私が運営しているコミュニティアプリの maru は、それ以来すべての OTA 修正をあのサーバー経由で、両プラットフォームに、月1ドルほどで配信してきました。

それは同時に、部品を全部自分で抱えているということでもあります。データベースのテーブル、API エンドポイント、管理コマンド、パブリッシュスクリプト、共有シークレット、そして壊れたアップデートを一つずつ経験して覚えたハマりどころの数々。今回の計画を立てようと腰を据えたとき、スクリプトが書いた日からずっと、本番へパブリッシュするたびに “Sent 0 push notifications” と出力していたことに気づきました。このサーバーが一度も返したことのないフィールドを読んでいたのです。誰も気づいていませんでした。誰よりも私が。自前で運用するというのは、だいたいこういうことになります。

そこで Codemagic から、CodePush をオープンソースでセルフホストできる形にした Patch を試してみないかと声をかけられたとき、条件を一つ付けて引き受けました。デモではなく本物のアプリでやること。本物の署名、本物のリリース手順、手で編集した箇所のあるコミット済みのネイティブプロジェクト、その全部です。EAS Update から移行する人の多くが動かしているのは、まっさらなテンプレートではなく、そういうアプリでしょう。

その顛末を、粗い部分もそのままにして書きます。

Patch とは何か

#

Patch は、自分で動かすサーバーと、アプリに組み込む SDK でできています。サーバー側は API、バックグラウンドワーカー、Postgres、S3 互換のオブジェクトストレージ、Web ダッシュボードで、Docker Compose のスタックとして配布されています。クライアント側は @codemagic/react-native-patch という iOS と Android 向けの TurboModule で、Expo の config plugin が付いています。それに加えて、JavaScript をバンドルしてパブリッシュする CLI の cmpatch があります。

ソースを読んで、設計上の判断が2つ目に留まりました。

1つ目は、アプリが API に「アップデートはあるか」と一度も尋ねないことです。リリースがパブリッシュされるとワーカーが素の JSON マニフェストをオブジェクトストレージに書き、アプリはそれを取りに行くだけ。アップデートの確認はストレージか CDN に対する静的な GET が2回で、API が受け取るのはメトリクスだけです。私の旧エンドポイントは、アプリを起動するたびにリクエスト経路の上に乗っていました。こちらではそれが起こり得ません。

2つ目は、すべてのリリースが対象とするバイナリのバージョンを厳密に指定することと、CLI がネイティブプロジェクトのフィンガープリントを計算して、ネイティブコードが一致しないバイナリへ JavaScript をパブリッシュするのを拒むことです。私のサーバーにあったのは バージョン文字列1つと、たくさんの「大丈夫だろう」でした。

まずは手元のノートパソコンで

#

ドキュメントはローカルの評価用スタックから始めるように案内していて、実際そこから始めるのが正解です。

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

CLI のインストールは2秒でした。スタックのほうは初回に3分14秒かかり、大半はサーバーとダッシュボードのイメージをローカルでビルドしている時間です。非対話モードだとその間何も出力しないので、ハングしているようにしか見えません（その後修正され、今はステップごとに進捗を1行出します）。そのあと、healthy なコンテナが4つ、すべて localhost に束縛された状態で現れました。8080 にダッシュボード、3000 に API、Postgres、そして 9100 に MinIO です。私自身のスタックがすでに使っているポートは、きちんと避けてくれました。

このモードではサインインが無効になっていて、外部に公開するなという警告がすべてのページに出ます。

localhost:8080

スタックには Example Data というアプリがあらかじめ入っています。何かをパブリッシュする前に一度眺めておく価値があります。ダッシュボードが何のためにあるのかが分かるからです。次の2枚のスクリーンショットの数字はそのシードデータで、実際のユーザーではありません。

localhost:8080

localhost:8080

比較のために言うと、私のダッシュボードは、管理画面のアップデート一覧に「有効」のチェックボックスが付いただけのものでした。実際に何台の端末がアップデートを取り込んだのか、まったく分かりませんでした。

CLI のログインは PKCE と localhost へのコールバックを使ったまっとうなブラウザフローで、承認ページにはどのアカウントが要求しているかと、コードが1分ほどで失効することが書いてあります。

localhost:8080

本物のアプリに向ける

#

Patch はプラットフォームごとに1アプリを求め、それぞれに Staging と Production のデプロイメントが作られます。maru-ios はダッシュボードで、maru-android は cmpatch app create で作りました。主に両方を見ておきたかったからです。アプリを作ったあとに出るダイアログは、移行にあたってこの製品でいちばん役に立つ画面です。両方のデプロイメントキー、SDK が必要とする2つの URL、そしてデプロイメントキーは秘密情報ではないという注記が載っています。

localhost:8080

小さなことが2つ。cmpatch init はすでに存在するアプリにプロジェクトを紐付けるコマンドだったので、移行ガイドがどう匂わせていようと、最初のコマンドにはなりませんでした。これはその後修正され、今は対話モードならプラットフォームごとにアプリを1つずつ自分で作ってくれます。それから、ダイアログは API の URL を http://localhost:8080 と示すのに、ドキュメントと CLI は 3000 と言います。どちらのポートも両方を配信しているのでどちらでも動きますが、首をかしげることにはなるでしょう。

次に、手を付けていないアプリに対して cmpatch doctor を走らせたところ、3秒で本物の問題を見つけてきました。iOS のバイナリバージョンを 2.0.0 と報告したのです。アプリは 2.5.1 です。

CLI は ios/ 以下のすべての Info.plist を探し、パスに “test” を含むものがなければ、アルファベット順で最初のものを取ります。maru には WidgetKit の extension があり、そのフォルダがアプリ本体のフォルダより前に並ぶので、CLI は extension の 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 は今、extension ではなくアプリターゲットの Info.plist からバージョンを読みますし、アプリの候補になるターゲットが複数あれば、どれがそうなのかを cmpatch が尋ねてきます。

JavaScript 側

#

expo-updates を外して SDK を足すのは2行の変更です。アプリがアップデートに対してやっていたことを置き換えるほうは、もう少し考える必要がありました。

maru は起動時と、フォアグラウンドに戻るたびにアップデートを確認します。ただし最短でも15分おきです。見つかればダウンロードして再起動を提案し、断られれば次のコールドスタートで適用します。設定画面には、動作中のバンドルを表示する手動チェックもあり、エラーレポーターはすべてのレポートに、それが来たアップデートのタグを付けます。

SDK のソースから最初に学んだのは、インポート時に TurboModuleRegistry.getEnforcing でネイティブモジュールを探しに行き、モジュールがなければ例外を投げるということです。maru は Web ビルドも出荷しているので、トップレベルでインポートすると Web アプリが落ちます。そこで、SDK を遅延ロードする小さなモジュールを1つ用意し、すべてそこを通すようにしました。何も返さない .web.ts の双子を置いてあるので、SDK は Web バンドルから完全に外れます。

// 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() です。決して例外を投げず、ステータスに解決します。

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

SDK の必須リリースのデフォルトは IMMEDIATE で、ユーザーがどこにいようと JavaScript をリロードします。私はアプリが次にバックグラウンドから戻ってきたときに適用するよう変えました。書きかけの投稿が消えるのは、たいていの修正の効き目より重いバグだからです。それから当時は、InstallMode がドキュメントの例から想像する enum オブジェクトではなく、文字列の union 型でした。今は定数オブジェクトとしてエクスポートされているので、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 の移行ガイドには道が2つ用意されていて、生成されたネイティブプロジェクトなら prebuild、コミット済みのプロジェクトなら手で当てる変更をそのまま示してくれます。

plugin が実際に変える内容は、蓋を開けてみれば手作業で済む程度でした。iOS では AppDelegate.swift に import が1つと1行。

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

Android では MainApplication.kt に import が1つと引数が1つ（これは React Native 0.82 以降の形で、それより古いバージョンでは代わりに getJSBundleFile() をオーバーライドします）。

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

加えてプラットフォームごとに設定値が3つと、古い expo-updates の設定の削除。両プロジェクト合わせて13行の追加と20行の削除です。

plugin はこれらの設定値を prebuild 時にリテラルとして書き込みます。コミット済みのネイティブプロジェクトでは、ビルドごとにデプロイメントが1つハードコードされることになります。私は同じプロジェクトから、プレビュービルドは 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 で、以前のエクスポートが生成していた 11 MB の Hermes バンドルとアセットに比べて小さくなっています。

ここで間違えてはいけないことが1つ。JavaScript バンドルはビルド時に EXPO_PUBLIC_ の値をインライン展開するので、アップデートは着地先のバイナリと同じ値でビルドしなければなりません。さもないと、間違ったバックエンドに話しかける JavaScript を出荷することになります。私のスクリプトは、バイナリをビルドしたのと同じ eas.json のプロファイルから値を読み込みます。Patch の CI ドキュメントにも今はこの点が明記されていて、release-react 自体は EAS のプロファイルを読まないことも書かれています。

それからアプリを再起動しました。端末のログでは、アップデートの確認全体がオブジェクトストレージへの2リクエスト、meta.json と 2.5.1/manifest.json として現れました。SDK は起動の3秒後に Downloaded イベントを書き、アップデートをステージングし、アプリが再起動を提案しました。

バグは私のものだった

#

そこでダッシュボードを見ました。シミュレーター1台がリリース v1 をインストールしたのに、成功2件、アクティブユーザー2人と表示されています。

localhost:8080

SDK は状態と未送信のメトリクスイベントをアプリのコンテナ内にファイルとして持っているので、追跡は簡単でした。タイムスタンプが同一で id が異なる Success イベントが2つありました。私のフックはマウント時に notifyAppReady() で動作中のバンドルを確定させ、その直後に sync() を呼んでいて、sync() は自分でも notifyAppReady() を呼びます。2つの呼び出しが重なり、どちらもリリースを pending と見なし、どちらもイベントを記録した。サーバーはイベント id で重複排除しますが、id が違うので両方数えられ、その重複は永久に残ります。

私の側の修正は、起動ごとに確認処理を1つだけ共有し、ほかはすべてそれを待つようにすることでした。SDK 自身が重なった呼び出しを防ぐこともできるはずで、そう提案しました。今はそうなっています。sync() の内部のものも含め、重なった notifyAppReady() の呼び出しは1つの確認処理を共有するので、インストールは1回だけ記録されます。SDK のリファレンスにも、sync() は自分で準備完了を確定させるので、sync() を使うアプリが別に notifyAppReady() を呼ぶ必要はない、と書かれるようになりました。

気持ちよかったのは、この修正の出荷です。JavaScript だけの変更なのでリリース v2 として出せて、v1 の端末にはバイナリ差分を送れるので、v2 は 7.3 MB のバンドルではなく 543 KB のパッチ、サイズにして約7% でダウンロードされました。再起動後: ダウンロード1件、インストール1件、成功1件、アクティブ端末1台。

localhost:8080

わざと壊す

#

ロールバックは私がいちばん気にしていた機能です。以前の構成には端末側のロールバックがまったくありませんでした。悪いアップデートを出せば、私が気づいてチェックボックスを外すまで、起動のたびにクラッシュし続けたはずです。

そこで、最初の描画の前に例外を投げる v3 をリリースしました。つまり notifyAppReady() を決して呼べないリリースです。アプリはそれをダウンロードし、再起動を提案し、ホーム画面へ落ちました。

次の起動では再び v3 が立ち上がり、再びクラッシュしました。これには驚きました。ドキュメントには、notifyAppReady() の前にクラッシュしたバンドルはロールバックされると書いてあるからです。ソースが説明してくれました。SDK は未確認の起動を3回まで許してから、クラッシュだと判断します。未確認の起動1回は、JavaScript が動く前に iOS が健全なプロセスを殺しただけかもしれないからです。4回目の起動で v2 に戻ってきました。

そして端末は自分から失敗を crash_rollback として報告し、ダッシュボードは v3 に対してそれを表示しました。理にかなった設計ですが、それが何を意味するかははっきり言っておく価値があります。悪いリリースは、ユーザー一人あたり3回のクラッシュ起動を代償にしてから回復するのであって、当時のドキュメントにはその回数が書かれていませんでした。今は書かれていますし、この予算は設定で変えられます。ネイティブなら CodemagicPatchMaxLaunchAttempts、Expo の plugin なら maxLaunchAttempts です。だからこそ、まず Staging、次に小さな Production ロールアウトなのです。

ほかの全員に対して悪いリリースを止めるのはコマンド1つで、1秒かかりませんでした。

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

履歴を書き換えることはしません。前のリリースを新しいリリース（v4、v2 のロールバックとしてマーク）としてもう一度パブリッシュするので、クラッシュしたリリースは失敗数とともに一覧に残ります。これが正直な記録です。ダッシュボードからも、ダイアログで同じことができます。

localhost:8080

Android

#

Android には驚きが2つあり、どちらも Patch のせいではありません。SDK 向けに足した R8 の keep ルールは app.config.js に置いてあって、これは prebuild を通してしかネイティブプロジェクトに届きません。つまり最初のリリースビルドは、keep ルールなしで SDK が R8 を生き延びるかどうかを、意図せず試すことになりました。生き延びます。R8 はクラスをすべてリネームしましたが、アップデートのダウンロード、インストール、ロールバックは問題なく動きました。もう1つはエミュレーターで、コールドブートしたばかりで Gradle がまだメモリを握っていたせいで極端に遅く、最初のテストは、SDK がすでに始めていたダウンロードを終える45秒前に諦めてしまいました。

リリース v1 は適用され、成功1件、アクティブ端末1台。クラッシュする v2 は、同じ3回の起動予算のあとにロールバックされました。

ハッピーパスの先

#

アップデートが届いてロールバックされることが核ではありますが、チームが日々使うのはそれ以外の機能なので、一つずつ試していきました。

段階的ロールアウトは決定論的で、これは気に入りました。md5(deviceId + "-" + releaseLabel) の先頭8桁の16進数を 100 で割った余りがロールアウトのパーセンテージ未満なら対象になるので、同じ端末は同じリリースに対してずっと対象か対象外のままです。私のシミュレーターは次のリリースでバケット 91 に入ると計算できたので、25% でパブリッシュしたところ、シミュレーターには正しく何も来ませんでした。cmpatch release patch で 95% に上げると（1秒かかりません）、次の起動で更新されました。

すると次のリリースが 409 で失敗しました。“deployment has an active rollout below 100 percent”。デプロイメントごとに部分ロールアウトは1つしか許されないので、ほかの何かを出す前にカナリアを完了するか、無効化するか、ロールバックする必要があります。妥当ですし、ドキュメントにも書いてありますが、マージのたびにパブリッシュするパイプラインは、カナリアの途中でここにぶつかります。報告してからは、CLI がここで事情を説明してくれるようになりました。アクティブな部分ロールアウトが邪魔をしているなら、待っても解決しないことと、ロールアウトを完了または無効化する方法を教えてくれますし、別のリリースジョブがまだ動いているなら、release inspect --wait で待つように言ってくれます。ドキュメントにも、リリースの変更を順番に行うためのセクションができました。

必須リリースは SDK の mandatoryInstallMode を使います。私は次のレジューム時に適用する設定にしていたので、アプリはアップデートをダウンロードしてプロンプトを表示し、プロンプトを無視してアプリをバックグラウンドに送ってから戻すと、新しいバージョンがただそこにありました。

リリースの無効化は、提供をやめる以上のことをします。最新のリリースを無効化した瞬間、マニフェストはまだ有効な中でいちばん新しいリリースを指すようになり、無効化したリリースにいる端末には、そこへ戻るパッチが提供されました。あるバイナリバージョンのリリースをすべて無効化すると、マニフェストのターゲットは null になり、SDK はアプリを出荷時のバンドルに戻します。私のアップデート用フックは最初このケースでプロンプトを出していなかったので、今は出すようにしてあります。

Staging から Production への昇格は1秒かからず、テストしたのとまったく同じパッケージを、同じハッシュとノートのまま再利用しました。ビルドし直すのではありません。ロールアウトのパーセンテージも受け付けるので、「Production の 10% に昇格」がコマンド1つで済みます。

ビルドとパブリッシュを別々の手順に分けることもできます。cmpatch bundle が .cmpatch のアーティファクトを生成し、ダッシュボードの「Bundle upload」はアップロード前にそれを読み取ります。プラットフォーム、対象バージョン、フィンガープリント、署名の状態、サイズ、バンドラー。CI がアーティファクトをビルドし、いつパブリッシュするかは別の誰かが決める、という体制に向いています。

フィンガープリントのガードに本格的にぶつかったのもここです。古いウィジェットの plist を直したあと、サーバーは次のリリースを 409 で拒否しました。ネイティブプロジェクトのフィンガープリントが、2.5.1 に対して記録されていたものと一致しなくなったからです。Android では app.config.js のコメントを編集しただけで十分でした。Expo はアプリ設定をフィンガープリントに含めるからです。ダッシュボードは同じチェックを、両方のフィンガープリントと「Upload anyway」ボタンの付いた警告として表示します。どちらの場合もインストール済みのバイナリのネイティブ部分は何も変わっていないので、上書きが正解でした。ただ実運用では、正直な答えはほぼ必ずバージョンを上げてストア向けにビルドすることで、私のパブリッシュスクリプトはこれが起きたとき、今はまさにそう伝えます。

コード署名は RS256 です。CLI が RSA の秘密鍵でパッケージのハッシュに署名し、SDK がバイナリにコンパイルされた公開鍵でそれを検証します。鍵は base64 の1行として渡すので、私のビルド設定方式にそのまま収まり、両プラットフォームでテストしました。鍵をアプリに入れた状態では、署名なしのリリースはダウンロード前に拒否されました。アプリで「require code signing」を有効にすると、サーバーは署名なしのパブリッシュを、対処法を示しガイドへリンクするエラーで拒否しました。署名済みのリリースはインストールされ、SDK は署名を検証済みとして記録しました。署名済みのものを無効化したときにサーバーがフォールバックした、古い署名なしのリリースも拒否しています。注意点は、公開鍵が最初に出荷するバイナリに入っていなければならないことです。アップデートで後から足すことはできません。

localhost:8080

チームと CI もカバーされています。メンバーにはチーム全体で共通の4つのロール（owner、admin、developer、viewer）のいずれかが付き、招待は相手が最初にサインインするまで保留されます。パーソナルアクセストークンは空のホームディレクトリでも動き、--token でも環境変数でも渡せて、トークン一覧には最後に使われた日時が出ます。Linux ランナーで同じパブリッシュスクリプトを、シークレットから取り出した署名鍵で走らせる手動実行の CI ワークフローも書きましたが、ホスト済みのサーバーが要るので、まだ実行していません。

当時なら使わずにおいたツールが1つ、cmpatch debug ios です。システムログを “OTA” で大文字小文字を区別せずにフィルタしてストリームしていたので “Rotation” にもマッチしてしまい、20秒のアプリ起動で SpringBoard のメッセージが画面いっぱいに流れ、アプリからは何も出ませんでした。これは修正済みで、今は SDK のマーカーが付いた行だけを表示します。もっとも SDK はもともとあまりログを出さず、出るのはほとんどエラーと開発ビルドでの警告なので、静かなストリームだと思っておいてください。getpwuid_r の警告が出ることがありますが、これは Patch ではなく xcrun simctl から来ています。

実際のところ、どれくらい大変か

#

Codemagic から意見を求められたので、できるだけ率直に書きます。

試すのは簡単です。コマンド2つと数分で、本物のサーバー、デモデータ入りのダッシュボード、自分のアプリに向けられる CLI が手に入ります。最初の1時間でいちばん良かった部分だと思います。

SDK の組み込みはそこそこの作業で、難しさの大半は Patch ではなく自分のプロジェクトの側にあります。ネイティブフォルダを生成させたまっさらな Expo アプリなら、本当に plugin と、expo-updates の呼び出しを置き換える数行だけです。maru のように、コミット済みのネイティブプロジェクト、ウィジェット extension、Web ビルド、R8、ビルドプロファイルを抱えたアプリでは、作業は端のほうにありました。prebuild を避けるためにネイティブの変更を手で当て、Staging と Production のビルドが別物になるように設定をビルド時に決め、SDK を Web から遠ざける必要がありました。アップデートの JavaScript がバイナリと同じ環境でビルドされることも保証しなければなりません。理解してしまえばどれも難しくはありませんでした。私が作業した時点ではその大半がドキュメントにありませんでしたが、コミット済みのネイティブプロジェクトの手順とバンドル時の環境については、今は載っています。

日常の使い勝手は良いです。パブリッシュはコマンド1つと30秒ほど。ロールアウト、昇格、無効化、ロールバックは CLI からでもダッシュボードからでもすべて1秒未満で、エラーは何が悪くて何をすべきかを伝えてくれます。サーバーのガード（フィンガープリントのチェック、一度に1つのカナリア、署名）は厳格で、私が間違ったことをするのを何度も止めてくれました。

本番で運用するのは、より大きなコミットメントです。Postgres とオブジェクトストレージ付きの Docker Compose スタックで、ホスティング、バックアップ、アップグレードは自分でやらなければならず、ドメイン2つと OAuth アプリが必要です。すでにサーバーを運用しているチームなら静かな午後1回分。サーバーを持ちたくないからこそ EAS にいるチームにとっては、SDK の作業よりもここが乗り換えの本当のコストです。

実時間で言うと、12:29 に CLI をインストールし、13:34 にはシミュレーターで最初のアップデートが適用されていました。そのうち30分は、Patch と無関係な理由で止まった Xcode のビルドです。この記事にあることは両プラットフォームとも、ホスト済みのサーバーを除けば午後の半ばまでに終わっていました。

いちばん時間を取られたものを順に挙げると、expo prebuild --clean がコミット済みのネイティブプロジェクトを消してしまい、そのあと全部を手で配線する方法を考えたこと。iOS のバージョン検出のバグで、これは誰も動かしていないバージョンにアップデートを送るところでした。二重に数えられたインストールで、これは自分のせいですが、sync() が自分で notifyAppReady() を呼ぶ以上、誰でも簡単に再現してしまいます。そしてドキュメントにない3回の起動というクラッシュ予算で、テストの途中で驚かされました。その次に来るのが、正しいけれど計画が要るもの。無害なネイティブ周辺の編集のあとに発火するフィンガープリントのガード、デプロイメントごとに一度に1つのカナリア、重ねて実行できないライフサイクルジョブ。最後のはスクリプトが続けていくつか処理をした途端に効いてきます。残りは小さなものでした。無音の初回セットアップ、うるさいデバッグコマンド、当時コードと合っていなかったドキュメントの例がいくつか。

これらはすべて詳細とともに Codemagic に書いて渡し、9月23日の時点でその大半が直っていました。バージョン検出、重なった確認処理、prebuild についての警告、クラッシュ予算、無音のセットアップ、デバッグコマンド、InstallMode の例、そしてリリースジョブやカナリアが邪魔をしているときのエラーです。まだ残っているのは小さなものです。ほかがすべて :3000 と言うなかでダッシュボードだけが API を :8080 と表示すること、Web と Jest で SDK が import 時に例外を投げること、それにドキュメントの穴がいくつか。

本番へ

#

ここまでの内容はすべて評価用スタックに対して動かしたものです。本番は同じアプリと同じスクリプトを本物のサーバーに向けるだけで、これが maru の計画です。

サーバーを動かすサポート対象の方法は Docker Compose でのインストールです。ポート 80 と 443 が開いた Linux マシン、ドメイン2つ（API とダッシュボード用、ダウンロード用）、そしてサインイン用の GitHub OAuth アプリ。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 とリリースワーカーを一緒に）で動くコンテナ1つで、必要なのは 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

注意点が2つ。Compose の外で動かす方法はリポジトリに参考資料として書かれているだけで、この最初のオープンソースリリースではサポート対象の経路ではないので、Fly 上でのアップグレードとバックアップは自己責任です。私もまだその形ではデプロイしていません。これは計画であって、報告ではありません。それから、Fly のゼロスケール の記事を読んだ方は、マシンを最低1台は動かしておいてください。マニフェストはストレージから直接来るので、端末がアップデートの確認で API を待つことはありませんが、そうしないとメトリクスのアップロードとリリースジョブがすべてコールドブートから始まることになります。

Tigris はいちばん楽しみにしている部分です。maru のファイルがすでにある場所ですし、アプリの起動のたびに叩かれる URL の前に CDN を置いてくれます。これをやるならマニフェストのキャッシュには気をつけてください。素の base-URL 配信アダプターでは、Patch は CDN をパージできないためマニフェストを no-cache で配信します。マニフェストが独自の 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 のリソースに入ったかを確認してください。環境変数を手でエクスポートしていたので、ここだけはローカルのテストで検証できていない繋ぎ目です。それから Staging にパブリッシュし、テスター1人につきダウンロード1件と成功1件を確認して、そこで初めてストア向けにビルドします。

Production のリリースは小さく始めて広げます。

./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日追記。

10月初めから、maru の本番のアップデートは Patch が運んでいます。それ以降で初めてのネイティブリリースが Expo SDK 58 への移行でした。React Native 0.88、そして Android では Gradle プラグインの新しいメジャーバージョンです。ネイティブの変更は OTA では届けられないので新しいバイナリ 2.6.0 になり、私のパブリッシュスクリプトはそのバイナリが存在するまで 2.6.0 向けのアップデートを送ろうとしません。ビルドは両プラットフォームとも一発で通りました。

上の本番のセクションでは、誰かにビルドを渡す前に、キーが実際にビルド済みの Info.plist と Android のリソースに入ったかを確認するよう書きました。今回はちゃんと確認しましたし、このセクションがあるのはその確認のおかげです。iOS のビルドには Patch の設定が4つともありました。Android のビルドには1つもありませんでした。

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

このコマンドは 2.5.11 のビルドではキーを4つ出力し、2.6.0 では何も出しませんでした。環境変数のせいではありません。Gradle の generateReleaseResValues は4つとも書き出しています。消しているのはその後に走るリリースのリソースシュリンカーで、Android Gradle Plugin 9 ではずっと攻撃的になりました。同じアプリでリソースが 9,240 個から 7,116 個に減っています。SDK は設定を getIdentifier で名前から読みますが、シュリンカーにはそれが見えないので、4つの文字列を未使用とみなして消しました。存在しない文字列は空として読まれ、空は「アップデートなし」を意味します。何も失敗しなかったはずです。Android の 2.6.0 はインストールされ、普通に動き、アップデートを一度も受け取らず、唯一の兆候はダッシュボードに Android 2.6.0 の端末が1台もないことだけだったでしょう。

修正は、シュリンカーに4つの文字列を残すよう伝えるリソースファイル1つです。

<!-- 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 を生成していて（画像やフォントが生き残ったのはそのためです）、2つがぶつかります。ライブラリの keep ファイルはアプリに自動でマージされるので、このルールの置き場所としては SDK 自体のほうがふさわしく、デプロイメントキーなしでリリースビルドが起動したときに警告が1つ出るだけでも、黙って起きていたことが目に見えるようになります。前に出てきた iOS のバージョン検出のバグと同じ種類の失敗です。何もエラーにならず、アップデートがただ届かない。

同じ確認で、Patch とは関係のない2つ目の問題も見つかりました。こちらは別の理由で知っておく価値があります。Android のリリースビルドは起動直後にクラッシュしました。それも2回、Expo 自身のモジュールの中にある別々の2つの原因によってです。まず、Expo のウィジェット用モジュールがネイティブクラスの登録に失敗し、JavaScript が動く前にアプリが落ちていました。それを直すと、アプリは JavaScript の起動までは進んだものの、そこで止まりました。Expo の新しいモジュールシステムに移った3つのモジュールが登録されていなかったからです。どちらにも Patch のクラッシュロールバックは役に立ちません。ロールバックすべきアップデートがないからです。守ってくれるのは悪いアップデートからであって、悪いバイナリからではありません。Patch があってもなくても、ネイティブのアップグレードはストアに出す前に実機かエミュレーターにインストールして開いてみる必要があります。

同じテストから、もう1つ小さなことが出てきました。sync() は失敗すると "error" を返し、アプリが開発モードで動いていない限り理由は教えてくれません。なのでリリースビルドでは、何かがうまくいかなかったことしかログに残せません。今は私のフックが、sync が失敗したあとに一度だけ checkForUpdate() を呼んで、そこで投げられたものをログに出します。そうして初めて、サーバーが壊れていたのではなく、ローカルのシミュレータービルドの Patch の URL が空だった（unsupported URL）とわかりました。最後のエラーがリリースビルドでも読めれば助かります。

ネイティブリリースのチェックリストには、以前はなかった3行が加わりました。ビルド済みの .ipa と .aab から Patch の設定をダンプすること、デプロイメントキーをビルドプロファイルと突き合わせること、そして提出前にデバッグビルドではなくリリースビルドそのものを起動すること。

Expo の請求書を抱えている人に伝えたいこと

#

サーバーを作るのが大変そうに見えたから EAS Update にお金を払っているのなら、Patch は本物の答えです。サーバーは動かしますが、それは Compose スタックとインストーラーであって、自分でメンテナンスするコードではありません。私が作ったものと比べると、段階的ロールアウト、リリースごとのインストール数と失敗数、バイナリパッチ、フィンガープリントのガード、コード署名、端末側でのクラッシュロールバック、ロールバックボタンが手に入ります。私はどれも作っていませんでした。

代償は、SDK をアプリに入れる必要があるので、誰かに Patch のアップデートが届く前に新しいバイナリが要ること。アップグレードとバックアップを続けるサーバー。リリースが十分ひどければ、デフォルトでユーザー一人あたり3回のクラッシュ起動。ネイティブプロジェクトをコミットしているなら、いくらかの手作業。それに、まだ若い。今回のバージョンは 0.3.0 で、バージョン検出のバグ、うるさいデバッグコマンド、ドキュメントの穴をいくつか踏み、SDK が防げたはずのバグを自分でも作りました。バージョン検出とデバッグコマンドはその後修正され、ドキュメントの穴も大半が埋まり、私がやった間違いも今は SDK が防いでくれます。どれも移行を止めるものではなく、すべてが CLI、ダッシュボード、あるいは端末上の SDK 自身のファイルで見えていました。これは以前の構成には言えなかったことです。

私が作っているマーケットプレイスアプリは、React Native Web で作ったシングルページアプリです。すべての出品ページは、JavaScript が動くまでは script タグ1つと空の div でしかありません。人間には問題なくても、検索には致命的です。Google は JS を実行することもありますが、Bing は実行しませんし、出品のほとんどが韓国語のサイトにとって最も重要な Naver のクローラーは、間違いなく実行しません。

これは、そのページを見えるようにした話と、そのあと私の予想しなかった形でそれを台無しにしたキャッシュルールの話です。

クローキングではないダイナミックレンダリング

#

対処法は古く、Google も認めています。クローラーを判定し、SPA が描いたはずのものと同じ内容を含むサーバーレンダリング HTML を返す。別の内容ではなく、同じ内容を、より早く。

そこで /listings/view?id=... のような出品 URL は分岐します。ブラウザには SPA のシェル。クローラーには本物のドキュメント。見出し、出品の主要な情報、alt 付きの写真ごとの画像、本文の抜粋、そしてこのページが孤立しないよう関連する出品いくつかへのリンク。

最後の項目が思っていたより効きました。内部リンクができる前は、約1,000件の出品ページに何もリンクしておらず、Search Console でクロールが1日7〜11リクエストまで沈んでいくのが見えました。ページを見つけられないクローラーは、その中身がどれだけ良いかを気にしません。

罠: ベンダー名はそのボットの名前ではない

#

クローラー判定は user-agent のマッチで、ここでハマりました。

韓国のプラットフォームは、会社名とまったく似ていない名前でクロールします。Naver のクローラーは Yeti。Daum は Daumoa。Kakao のリンクスクレイパーは kakaotalk-scrap。3つとも、ベンダー名ではありません。

一方で同じベンダーが、埋め込みブラウザを持つアプリを出しています。そのブラウザは本物のブラウザ UA の末尾にアプリ名を足して送ります。KakaoTalk のアプリ内ブラウザは KAKAOTALK/10.5.1。Kakao のスクレイパーは kakaotalk-scrap/1.0。

kakao でマッチすれば両方に当たります。私はまさにそれをやり、その結果リンクを開いた KakaoTalk・Naver アプリ・Daum アプリのユーザー全員がクローラー向けページを受け取りました。JavaScript もナビゲーションもログインもないページを。ドキュメントとしては良くできていて、人間にはまったく使えないものを。

修正は順序のルールで、ルールとして書き出す価値があります。

import re

# アプリ内ブラウザは、普通のブラウザ UA の後ろにアプリ名を付ける。
INAPP_BROWSER_RE = re.compile(r"kakaotalk/|naver\(inapp|daumapps", re.I)

# ベンダー名ではなくボット名で照合する。Naver は Yeti、Daum は Daumoa、
# Kakao のリンクプレビュー用スクレイパーは 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 マシン1台で、毎秒20〜30リクエストを支えます。Googlebot が巡回する URL は約995本。その全部がシドニーまで到達していました。すべての URL で cf-cache-status が DYNAMIC だったからです。Cloudflare はルールが指示しない限り HTML をキャッシュしません。 ゾーンの約16%だけがキャッシュされ、肝心の部分は1つも入っていませんでした。

そこでクローラー向けページにキャッシュルールを。単純な話です。出品 URL の本文が1つではない、という点を除けば。本文は3つあります。

• HTML を求めるクローラーには、サーバーレンダリングされたページ。
• 人間には、SPA のシェル。
• Accept: text/markdown を送るエージェントには、データベースから組み立てた Markdown。空の HTML シェルを変換しても空のドキュメントにしかならないからです。

オリジンは Vary: Accept を送り、user-agent に対する Vary はどのみち望み薄です。そしてここに、私が知らなかったことがあります。

Cloudflare は HTML では Vary を無視します。 3つの本文が1つのキャッシュキーを共有します。

先に到着した本文がその URL を取り、同じエッジロケーションのその後の訪問者全員に対して、オリジンの s-maxage が許す1時間、さらに stale-while-revalidate の1日ぶん、それが出続けます。

本番で両方向とも観測できました。

• Naver アプリのユーザーがクローラー向けページで出品 URL を温め、そのあと素の iPhone Safari が HIT でそのページを受け取りました。JavaScript のないドキュメントを眺める人間の出来上がりです。
• 人間が SPA シェルで URL を温め、Googlebot が空のシェルを受け取りました。SEO の取り組み全体が防ごうとしていたまさにその失敗が、今度はより速く、エッジから提供されたわけです。

絞ることで直すルール

#

Cloudflare に HTML で Vary を尊重させることはできません。できるのは、3つの本文のうち1つだけがキャッシュに入る資格を持つようにすることです。

(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 だけにマッチさせ、Markdown リクエストは除外します。これで人間のリクエストはどのルールにもマッチせず、以前どおり DYNAMIC を読んでオリジンへ行きます。キャッシュを読み書きするのはクローラーのリクエストだけで、そこに入りうる本文はクローラー向けの1つだけです。

エッジ TTL は respect_origin。寿命はダッシュボードに固定されるのではなく、ページをレンダリングするコードが持ち続けます。

見落としやすい運用上の細部を1つ。ルールを絞っても、すでにキャッシュにあるものは消えません。 パージが必要です。さもないと、たった今生成を止めたばかりの汚染されたエントリを配り続けることになります。

2つのリストと、その誤りが対称でない理由

#

このルールにはクローラー UA のリストが必要で、Django にはすでに1つあります。同じ知識が2つのシステムに2部あるのは普通なら臭いますが、ここで面白いのは、両者がずれたときに何が起きるかです。対称ではないのです。

• Cloudflare 側のボットリストは、Django 側の部分集合であり続ける必要があります。 Cloudflare がボットだと思い Django はそう思わないトークンがあると、クローラー専用のキーの下に SPA シェルがキャッシュされ、それが本物のクローラーに出ていきます。
• アプリ内ブラウザの除外リストは、Django 側の上位集合である必要があります。 除外しすぎても、失うのはキャッシュヒットだけです。

どちらも安全な方向に間違えれば、キャッシュが少し減るだけ。1つ目を逆方向に間違えれば、また Googlebot に空のページを返すことになります。ちなみにこの非対称性こそ、リストが正規表現ではなく contains を使う理由でもあります。matches は Business プランが必要で、既知の安全な方向に大雑把でよいリストには contains で十分だからです。

ページではなくビルドを落とす不変条件

#

クローラー向けページには、7日間有効な署名付き画像 URL が埋め込まれています。ページ自体はエッジで1時間、加えて stale-while-revalidate の1日。

この2つの数字は関係していて、キャッシュ寿命が画像の寿命を超えた瞬間、エッジは全写真が403になるページを配り始めます。それを知らせるアラートはありません。HTML 自体は正常なのですから。

そこで、この数値を定義するコードは、関係が壊れていればインポート自体を拒否します。

CRAWLER_IMAGE_TTL = 7 * 24 * 3600  # 署名付き画像 URL
EDGE_S_MAXAGE = 3600
EDGE_STALE_WHILE_REVALIDATE = 24 * 3600

# エッジキャッシュが画像 URL より長生きしうるなら import 時に失敗させる。
if EDGE_S_MAXAGE + EDGE_STALE_WHILE_REVALIDATE >= CRAWLER_IMAGE_TTL:
    raise RuntimeError("edge cache lifetime must stay below the image URL lifetime")

別々のファイルにある2つの定数のあいだの制約は、コードレビューでは見えず、プロセス起動時には明白です。プロセスが起動する場所に置きましょう。

Cloudflare がやったことのうち、取り消す必要があった2つ

#

Vary: Origin がバンドルをキャッシュから締め出していました。 django-cors-headers は触れたすべてのレスポンスに Vary: Origin を刻み、Cloudflare は Accept-Encoding を超えて vary するレスポンスをキャッシュしません。その結果、クリティカルパス上で最大の 1.6MB の JavaScript バンドルが、まるごと静かにエッジから除外されていました。対処はミドルウェアをリストの先頭に置き、出ていく側で最後に走らせて、静的アセットのパスの Vary を書き換えることです。

エッジでの圧縮はオリジンでの圧縮より悪かった。 Cloudflare にその場で Brotli をやらせると 2,041,742 バイト、オリジン自身の gzip は 1,658,115 バイトでした。何も考えなくていい代わりに23%大きい。オンザフライ圧縮は圧縮率ではなく CPU を最適化します。オリジンからの事前圧縮済みアセットが勝ちます。

クロールを待たずに検索エンジンへ知らせる

#

プロトコルは2つ、そして2つ合わせてもカバー範囲は残念なものです。

IndexNow は ping を1つ受け取り、Bing、Yandex、Seznam をカバーします。Google と Naver は参加していません。出品が保存されるたびにバックグラウンドで短いタイムアウト付きの ping を送り、売却済み・終了済みの出品はスキップします。ネットワーク障害は警告を残すだけで、それを引き起こした保存を決して失敗させません。ベストエフォートのサイドチャネルに許される唯一の振る舞いです。

Google の Indexing API はちょうど2つのスキーマ型しか受け付けず、その1つが私の持っている JobPosting です。生きている求人は URL_UPDATED、終了したものは URL_DELETED。その削除通知が誠実でいられるのは、終了した出品が noindex も出しているからで、コードにそう書いてあります。あとで noindex を外す人が、ほかに何を壊すのかを知れるように。

ここでは2つのことに時間を取られました。クォータは1日200 URL で、出品を一括インポートすると一度に数百回呼ばれます。だからインポートされた出品はスキップします。さもないと1回のインポートで1日分の予算を使い切ります。そしてエンドポイントはコロン入りの urlNotifications:publish です。スラッシュを使うと Google はただの HTML 404 を返し、それは API が無効になっているのと見分けがつきません。

構造化データが教えてくれたこと

#

3つのルール、どれも Search Console に叱られて覚えました。

1. パースできないものは出さない。 給与は自由テキストで届きます。以前は生の文字列を baseSalary.value として出していて、それは無効で、すべての求人に単位欠落のフラグが立ちました。今はパースできない給与は単に存在しません。
2. スキーマを満たすためにフィールドをでっち上げない。 求人広告に番地が載ることは稀です。PostalAddress にもっともらしいものを入れたくなります。求人広告のでっち上げの住所は、不完全な住所より悪い。だから地域と国だけを入れます。
3. 有効期限は任意ではない。 Google は validThrough のない JobPosting を落とします。だから1つ導出し、古い出品が昨日期限切れになったと主張しないよう下限を置きます。

そしてサイトマップについて4つ目。すべてに changefreq: daily を主張しない。 1,000件の出品を毎日再クロールしてくれという要求は、過負荷のホストとして読まれ、Google はサイト全体のクロールレートを下げることで応じます。実際にどれだけ最近変わったかから導出しましょう。

サイトマップには品質の下限もあります。タイトルと本文を合わせて40文字。Search Console が約1,000件を「クロール済み – インデックス未登録」と報告していて、ある中古品ページの固有コンテンツは、一語のタイトルと電話番号だけでした。40文字は意図的に低くしてあります。484件の出品のうち471件が韓国語で、韓国語は1文字あたりの情報量が多いからです。英語に合わせた閾値なら、マーケットプレイスの半分が落ちていたでしょう。薄い出品もインデックスページ経由でクロール可能なまま残り、誰かが編集すれば自動的にサイトマップへ戻ります。

ここから持ち帰るもの

#

• 1つの URL で異なる本文を返すことは、何よりもまずキャッシュキーの問題です。 使っている CDN が何をキーにしているかを突き止め、そのコンテンツタイプで実証するまでは Vary を無視すると想定してください。
• 2つのシステムが1つのリストで一致しなければならないなら、どちら向きの誤りが安全かを見極め、それを両方の写しの隣に書いてください。「ずれてよい、ただし許されるずれ方はこれだけ」のほうが、ずれない前提より優れています。
• ボットはベンダー名ではなくボット名でマッチさせること。 特に英語圏の外では、そのベンダーがユーザーの手元のブラウザも作っています。
• 離れた定数のあいだの不変条件は、大きな音で失敗する場所に置くこと。 インポート時はタダで、誰もスキップできません。

私は現在、個人開発者として2つのプロダクトを運用しています。ひとつは現場で見積もりを出す職人向けの現場見積もりアプリ、もうひとつは出品とリアルタイムメッセージングを備えたマーケットプレイス兼コミュニティアプリです。

プロダクトもユーザーも全く違いますが、技術スタックはほぼ同一です。そしてどちらも、Fly.ioの最安ティアであるshared-cpu-1xマシンだけで動いています。この制約は意図的なものです。ピーク負荷に合わせてサーバーを大きくするのではなく、小さなマシン1台から絞り出せる性能を最大化し、どこで崩壊するかを正確に測定し、その実測された限界を軸にFlyのオートスケーラーにマシンの追加と削除を任せます。この記事では、それを可能にしている最適化、閾値の根拠となった負荷テストの数値、そしてFly.ioでスケールアップ/ダウンが実際にどう動くのかを紹介します。

哲学：1台を測定し、それを掛け算する

#

両アプリともスケーリング戦略は同じ3ステップです。

1. 小さなマシン1台を、合理的な範囲で可能な限り速くする。
2. 壊れるまで負荷テストを行い、レイテンシが崩壊する同時実行数を記録する。
3. その直前で2台目のマシンが起動するようFlyのオートスケーラーを設定し、トラフィックが減ったらアイドルマシンを停止させる。

こうすればキャパシティはマシン数にほぼ線形に比例し、ベースラインコストはアプリごとに小さなVM 1台です。以下の内容はすべて、この3ステップのいずれかのためにあります。

小さなマシン1台を速くする

#

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で—ワーカーあたり一度に1つずつ—実行します。つまりASGIは、ワーカーあたりの同時リクエストを実質1つに絞りながら、asyncio/uvloop/Channelsのスタック一式をただメモリに載せていただけでした。--blocking-threadsを使うWSGIは、同じ同期ビューを本物のスレッドプールで走らせます。ワーカー1つ × スレッド16 = I/Oバウンドなリクエスト（DB読み取り、S3のプリサイン）16件を同時に、非同期スタックより低い常駐メモリでさばきます。

なぜワーカーが1つなのか？VMがshared-cpu-1x—1コアだからです。2つ目のワーカーは1コアではPythonを並列に走らせられない（GIL + 1コア）くせに、常駐するDjangoプロセスをまるごと1つ余分に食います。Granianはまさにこの点を警告します。ワーカー1つにスレッド16が、I/Oバウンドな処理における1 vCPUマシンの正直な上限です。--workers-max-rss 1400はワーカーがメモリ上限を超えると再生成するので、暴走したPDFや画像処理がマシンをOOMへ引きずっていく代わりにリサイクルされます。

WebSocketは自前のGranianプロセスに切り出しました。uvloopと--wsを使うASGIアプリで、長寿命コネクションのためにワーカー1つで動かします。同期APIにはASGIの経路はまったく不要です。ビューがソケットへプッシュしたいときはRedis経由でasync_to_sync(channel_layer.group_send)を呼ぶので、メッセージは変わらずWebSocketプロセスへ渡ります。2つのサーバーが、それぞれ本当に得意なインターフェースを走らせているわけです。ローカルのDockerも同じWSGIスレッドプールで動かしているため、テスト時は私のラップトップがプロダクションマシン1台の近似になります。

ホットパスにはRust

#

PythonのホットパスにRustベースの代替があれば、必ず採用します。

• orjson（drf-orjson-renderer経由）— すべてのAPIレスポンスが標準ライブラリのJSONエンコーダーではなくRustでシリアライズされます。
• blurhash-rs — 画像プレースホルダーをアップロード時に計算。
• uuid-utils — RustによるUUID生成。
• psycopg 3 (binary) — Cで高速化されたPostgresドライバー。

これらはアーキテクチャを変えません。2台目のマシンが必要になる前に、1 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の処理は、定常状態ベースの見積もりでは予測できないメモリスパイクを起こします。安上がりな緩和策が2つ。Dockerイメージにjemallocをプリロードして断片化を抑えること、そして全マシンにスワップを持たせることです（APIマシンに2GB、WebSocketマシンに1GB）。スパイクが来てもプロセスがOOMで殺される代わりにディスクへスワップされます。スワップは性能のための機能ではなく、メモリ割り当てを小さく保つための保険です。

Djangoの負荷テスト：膝（knee）を見つける

#

閾値の根拠として通用するのは、実測した値だけです。プロジェクトごとに専用のハーネスがあります。

• 見積もりアプリには、同時実行数を掃引してRPS、p50/p95/p99、エラー率を報告する小さなPythonのストレステストスクリプトがあります。生成した数百件のサンプルデータに対して実行するので、リスト系エンドポイントは現実的なデータ量でクエリされます。
• マーケットプレイスはLocustで30秒刻みのステップ負荷により50 → 500ユーザーまでランプして飽和点を探し、実際の閲覧中心トラフィックに合わせたエンドポイント重み付けを使っています。さらに別建ての小さなテストスイートが、仮想ユーザー5 → 50をp95 < 2秒の閾値付きでプロダクションに対してランプします。

見積もりアプリのスイープの代表的な数値です（Granianワーカー1 × ブロッキングスレッド16、開発マシン上のDocker）：

そして他のすべてを決める数字が、shared-cpu-1xマシン1台でマーケットプレイスを負荷テストした結果から出てきます。旧来のASGIビルドでは、これが固い壁でした。同期ビューが実質3スロットほどに直列化されるため、p95は同時リクエスト約5までは300ms未満を保ち、すべてがthread_sensitiveのロックの後ろに並ぶことで約8〜10を超えると崩壊していました。この膝を外側へ押し出したのが、APIをWSGIスレッドプールへ移したことです—マシンあたりの実質同時スロットが約3ではなく16になり、この新しい天井がオートスケーリング設定全体の根拠です。

Fly.ioでのスケーリングの仕組み

#

Flyのモデルはシンプルです。アプリはプロキシの背後にある同一マシンの集合で、プロキシがマシンごとの負荷を数えます。宣言するのは2つの数字だけです。

[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は12—プールの約75%で、ユーザーが数秒のレイテンシを体験した後ではなく、スレッドにまだ余裕があるうちに2台目が起動します。hard limitの24（プールの1.5倍）はサーキットブレーカーです。短いバーストはスレッド上でキューイングされ、それを超えたら、1台のマシンが溶け落ちるのを許すのではなく、プロキシが負荷を遮断します。（旧来のASGIビルドは実質スロットが約3で8/20でした。プールを広げたことで両方の数字を引き上げられたのです。）

スケールダウン： トラフィックが減ると、Flyはアイドルマシンを自動的に停止し、min_machines_running = 1まで縮小します。停止中のマシンはコンピューティング費用がかからず rootfs のストレージ分だけなので、各アプリのベースラインコストは文字通り小さなVM 1台で、バースト用のキャパシティは常に待機しています。

私はここに、停止中のマシンは「1秒未満でコールドスタートする」と書いていました。それは間違いで、しかも高くつく間違いでした。想定ではなく実際に計測したところ、コールドスタートには25〜33秒かかっていて、まだ起動中のマシンに振られたリクエストはその時間をまるごと待たされます。当初は、ヘルスチェックがずっと緑のままCDNのダッシュボードに出ていた22パーセントの失敗率を、このコールドスタートのせいだと考えていました。ところがその数字は、CDN自身のEarly Hintsのプローブがオリジンで失敗していたもので、実際のクライアントが受け取った504はひとつもありませんでした。それでも、コールドスタートそのものは本物でした。

対処は上のスケーリングの数値にはありません。あの数値は問題ないのです。マシンが立ち上がる途中で何をしているか、そして Fly にマシンを停止ではなくサスペンドさせるかどうかにあります。そうすれば復帰は約3秒のメモリ復元になります。別記事にまとめました。ゼロスケールと、再起動のたびに起きる30秒の障害で、診断の過程と変更すべき点を扱っています。auto_stop_machines を使って Fly で何かを動かしているなら、この段落を信じる前にそちらを読んでください。

ひとつ微妙なポイント：同時実行のタイプがconnectionsではなくrequestsであることです。現代のクライアントはkeep-aliveコネクションを開きっぱなしにするため、コネクションを数えても実負荷でほとんど変動せず、オートスケーラーが発火しません。処理中リクエストを数えることで、実際の仕事量が追跡できます。

WebSocketは別の軸でスケールする

#

マーケットプレイスはWebSocketサーバーを、同じDockerイメージを共有する2つ目の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）を組み込み、端末上で動かしています。サーバー側の推論コストはゼロで、オフラインでも動作します。
• オフラインファーストのモバイル（端末上のSQLiteと、リトライ付きの同期キュー）のおかげで、アプリはキー入力のたびに細かなリクエストでAPIを叩くのではなく、書き込みをまとめて送り、電波の届かない場所でも動き続けます。

残りのスタックを手短に

#

認証はホスティング型のIDプロバイダーとWebAuthnパスキーで、WebSocketコネクションはアップグレード完了前に認証します。プロダクションはPostgres、開発はSQLite。管理画面と監査履歴には既製のDjangoパッケージをいくつか使っています。モバイルはExpo上のReact NativeとTypeScriptにExpo RouterとTailwindを組み合わせ、OTAアップデートはセルフホストのExpo Updatesサーバーから配信し、アプリ内課金はサブスクリプション管理サービスに任せています。品質ゲートはバックエンドがpytestとmypy、クライアントがユニットテストとE2Eテストです。

持ち帰ってほしいもの

#

移植できるアイデアは特定のライブラリではなく、ループそのものです。安いマシン1台を本当に速くする（Rustのホットパス、コネクション再利用、本当のボトルネックの前のキャッシュ、CDNとクライアントへのオフロード）。どの同時実行数で壊れるかを特定できるまで負荷テストする。オートスケーラーのsoft limitをその膝に置き、アイドルマシンは停止させ、最小フリートは1に保つ。プロダクションアプリ2つ、リアルタイム機能、AIアシスタント — それでも定常時の請求額は、プラットフォームで最安のVM数台分です。

いま開発している見積もりアプリには、絶対に譲れない要件がひとつあります。電波がなくても動くこと。見積もりは現場を訪ねてその場で作るのですが、現場は新築の建物だったり地下だったりで、電波はあてになりません。この制約のおかげで、多くのReactプロジェクトが曖昧なままにしている「どの種類のステートをどこに置くか」という問題に、正面から向き合わざるを得ませんでした。

よくある失敗は、すべてをひとつのストアに突っ込むことです。APIキャッシュもユーザー設定もフォームの状態も認証トークンも、全部同じReduxストアの中。でもこれらは性質もライフサイクルも違うステートで、それぞれに合った道具があります。Zustand、React Query、AsyncStorageはそれぞれちょうどひとつの問題をうまく解決してくれるので、境界線さえ引けば、アーキテクチャはだいたい勝手に片付きます。

ステートは3種類ある

#

ライブラリの話をする前に、自分が何を管理しているのかをはっきりさせておきましょう。

クライアントステートは、アプリのランタイムにしか存在しないデータです。UIのトグル、選択中のタブ、フォーム入力、モーダルの開閉。上流に所有者はおらず、プロセスが終われば消えます。

サーバーステートは事情が違います。所有者はサーバーで、アプリが持っているのはローカルコピーにすぎません。ユーザープロフィール、商品一覧、通知、フィード。手元のコピーは古くなりますし、再取得が必要ですし、今この瞬間に別のクライアントが別のバージョンを見ているかもしれません。

永続ステートは、再起動をまたいで残す必要があるデータです。認証トークン、オンボーディング完了フラグ、キャッシュした設定、オフライン用データ。デバイスそのものに保存されます。

たいていのアプリには3つとも存在します。そして、たいていの混乱は、3つをひとつの道具で扱おうとするところから始まります。

Zustand：クライアントステート担当

#

Zustandは余計な儀式のない小さなステートライブラリです。プロバイダーなし、ボイラープレートなし、何重にもネストしたコンテキストラッパーもなし。ストアを作ってコンポーネントで使う、覚えることはほぼそれだけです。

出番になるのは、複数のコンポーネントが同じUIステートを必要とするとき（サイドバーの開閉、アクティブなフィルター、選択中のアイテム）、APIから来ないアプリレベルのステートがあるとき（テーマ、言語、起動時に読み込むフィーチャーフラグ）、あるいはカートの計算やマルチステップのウィザードのような、本物のクライアントサイドロジックがあるときです。同期的で予測どおりに更新したいものは、だいたいここに入ります。

基本のストアはこんな形です。

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分間はフレッシュとみなす
  })
}

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>
  )
}

書かずに済むもの

#

サーバーデータはここに置くべきだと私が言い張る理由は、タダでついてくる仕組みの多さです。5つのコンポーネントが同じユーザーを要求しても、ネットワークリクエストは1回だけ。ウィンドウがフォーカスを取り戻したり回線が復活したりすれば再取得してくれます。古いキャッシュは勝手にガベージコレクションされます。どのクエリも isLoading、isError、data などを返してくれるので、ローディングやエラーのUIをいちいち手作りしなくて済みます。失敗したリクエストは指数バックオフでリトライされ、ロールバック付きの楽観的更新も組み込みパターンとして用意されています。自前で作れば丸一日仕事です。

向いていないもの

#

クライアントだけのステートには不向きです。サーバーを経由しないデータにReact Queryを使っても、儀式が増えるだけ。モーダルの開閉にキャッシュ無効化や再取得間隔は要りません。

永続化レイヤーでもありません。キャッシュはメモリ上にあるので、再起動すれば空になって再取得が走ります。キャッシュの永続化はできますし、React Nativeではやるべきです（後半のオフラインの節で扱います）。それでも、正となるデータは常にサーバー側にあります。

AsyncStorage：再起動を生き延びるもの担当

#

AsyncStorageはReact Nativeのキーバリューストレージです。Webでの相当品は localStorage（同期）か IndexedDB（非同期で高機能）。考え方はどちらも同じで、デバイスに書き込むことでプロセスより長生きするデータ、ということです。

プラットフォームごとの中身

#

@react-native-async-storage/async-storage を使っていればAPIはひとつですが、中身はプラットフォームごとにかなり違います。

Androidでは RKStorage 経由のSQLiteで、アプリの内部ストレージディレクトリ内のデータベースに保存されます。高速で信頼でき、サンドボックス化されているので他のアプリからは触れません。ただし、下の表にあるデフォルトのサイズ上限には注意してください。

iOSでは、小さな値は NSUserDefaults、大きな値はシリアライズされたファイルに入ります。こちらもアプリのコンテナ内にサンドボックス化されています。Appleは NSUserDefaults にハードリミットを設けていませんが、個々の値は数百KB以下に抑えるのが常識的な線です。それを超えるようなら、そもそもWatermelonDBやRealmのような本物のデータベースを検討すべきでしょう。

Web（React Native WebやExpo Web）では localStorage にフォールバックします。上限はブラウザ次第で5〜10MB程度。Web専用の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()

Webでの相当品

#

Web専用の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の領分です。

セキュアストレージでもありません。root化・脱獄されたデバイスではAsyncStorageの中身は読めてしまいます。機密トークンは expo-secure-store か react-native-keychain に入れてください。

3つの組み合わせ方

#

実際のアプリでは3つを同時に使います。私がよく使うパターンをいくつか。

認証フロー

#

// 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の永続化ミドルウェアがギャップを埋める
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（Webなら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件落とすということです。

うれしいことに、この3つのライブラリだけで、重量級フレームワークに頼らず、かなりしっかりしたオフライン構成が組めます。

ステップ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',
    },
  },
})

3つのモードはこうなっています。

ほとんどのモバイルアプリでは 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()
})

アプリを1時間バックグラウンドに置いてから戻ってくれば 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>You're offline. Changes will sync when you reconnect.</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}>Sending...</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)  │        │            │
     └────────────┘        └────────────┘

本物の同期エンジンが必要になるとき

#

ここまでの構成は、サーバーのデータが正でオフラインは一時的なもの、という前提で成り立っています。競合解決込みの本当のオフラインファースト（2台のデバイスが同じドキュメントをオフラインで編集するノートアプリのような世界）が必要なら、このスタックでは足りず、専用の同期エンジンの出番です。WatermelonDBはReact Native向けに作られていて、SQLiteの上で動き、競合解決のための同期プロトコルを備えています。RealmはAtlas Device Syncと組み合わせれば、MongoDB Atlas経由の自動競合解決付きの完全なオフラインファーストデータベースになります。PowerSyncは既存のPostgresバックエンドと連携できるSQLiteベースの同期レイヤー。完全に自分で制御したければ、Expo SQLiteに自作の同期ロジックという道もあります。

Zustand + React Query + AsyncStorageで、モバイルアプリの8割くらいはカバーできます。残りの2割、つまり共同編集やマルチデバイス同期のようなオフライン中心のワークフローには、専用の同期データベースが必要です。

どこに置くか迷ったら

#

私は迷ったとき、この順番で自問しています。

よくあるパターン

#

プラットフォーム別のセットアップ

#

React Native (Android + iOS)

#

3つまとめて入れます。

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

Web専用のReact

#

AsyncStorageは飛ばして、localStorage か IndexedDB を直接使ってください。

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

Zustandのpersistミドルウェアは、Webではデフォルトで localStorage を使ってくれます。

persist(storeConfig, {
  name: 'my-store',
  // localStorage is the default on web  - no extra config needed
})

何度も見てきた失敗

#

APIデータをZustandに入れる。アクションの中に setUsers(apiResponse.users) があったら、一度手を止めてください。それはReact Queryの仕事で、その先に待っているのはキャッシュ無効化の下手な再発明です。

React Queryをクライアントステートに使う。queryFn がネットワークリクエストをしていないなら、道具を間違えています。

AsyncStorageをデータベース扱いする。1万件の配列をキーバリューストアにシリアライズし始めたら、素直にSQLiteなり本物のデータベースなりを使いましょう。

トークンを平文で置く。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の稼働状況や次の料金改定に振り回されずに済むのも、地味に大きいところです。

全体の構成

#

構成要素は4つです。アップデートのマニフェストを返しメタデータを保存する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
└─────────────────┘

実装

#

2つのモデル

#

すべての土台になるのが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)

ポイントは3つあります。アップデートがないときは204を返し、アプリは組み込みのバンドルをそのまま使い続けます。マニフェスト内のアセットURLは署名付き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

エクスポート前にプロダクションの環境変数を読み込み、プラットフォームは片方でも両方でも指定でき、次に説明するプロダクション同期まで面倒を見てくれます。

プロダクションへの同期

#

プロダクションの認証情報を手元のマシンに置きたくなかったので、本番へのデプロイは2段階にしました。まずローカルでパブリッシュし（アセットは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,
    )

ダウンロードには署名付き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ハッシュで検証されるので、改ざんされたアセットは単に失敗するだけです。署名付き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など）でなければなりません。ここを間違えると、クライアントがアセットを正しくキャッシュ・取得できなくなり、最初の1回だけ成功したあとアップデートが黙って壊れます。この問題を報告してくれた読者のRaphael Mutschlerさんに感謝します。原因を突き止めるまで、彼の環境ではアップデートがちょうど1回だけ動いていたそうです。

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がこの3つも、それ以上もやってくれます。移行の記事を参照してください。)

段階的ロールアウト

#

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のモデルが2つとビューがいくつか、パブリッシュ用スクリプトがひとつ、インフラ費用が月1ドル。始める前に想像していたよりずっと小さく収まり、以来両プラットフォームで淡々と動き続けています。

ここに載せたコードはそのプロダクションアプリのコードを例として簡略化したものなので、作るものに合わせて手を入れてください。読者のRaphael Mutschlerさんがスタンドアロンの実装をexpo-ota-serverとして公開してくれているので、すぐ動くものから始めたい方はそちらもどうぞ。

サーバーを自分で書きたくないなら

#

この記事を書いたあと、Djangoなしで同じ領域をカバーするものが2つ登場しました。1つ目は、上で触れたRaphaelさんのexpo-ota-server。2つ目はCodemagic Patchです。オープンソースで、Docker Composeのインストールで自分のマシン上で動き、Expo UpdatesプロトコルではなくCodePushを話すので、expo-updatesをそのSDKに、eas updateをcmpatch release-reactに置き換えることになります。S3互換ストレージを使えるので、この記事に出てくるようなTigrisのバケットもそのまま使えます。

「この先やりたいこと」に挙げて結局作らなかったものが、最初から揃っています。ステージングとプロダクションのデプロイメント、パーセンテージ指定のロールアウト、リリースごとのダウンロード数とインストール数、必須アップデート、バイナリパッチ、コード署名、そして新しいバンドルがアプリの準備完了を報告する前にクラッシュしたときの端末側でのロールバック。引き換えになるのは、SDKをアプリに入れる必要があるため誰かにPatchのアップデートが届く前に新しいネイティブバイナリが要ることと、管理コマンドの代わりに運用するサーバーが要ることです。

私は自分のアプリの1つを、コミット済みのネイティブプロジェクトと本物のリリースパイプラインごと、この記事の構成から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機能は、たいてい同じ作りです。ユーザーがメッセージを入力し、アプリがクラウドのモデル提供元へ送信し、応答が返ってきて、請求額が積み上がっていく。

施工業者が業務に使うアプリでこれをやると、困ったことになります。顧客の氏名・住所・電話番号が第三者に渡り、案件の詳細や見積もり、メモが外部のサーバーに置かれる。GDPRやデータレジデンシーといった、できれば関わりたくない論点も増えます。しかもAPI料金はユーザー数に比例して膨らんでいきます。

それなら、モデルをユーザーの端末で動かせばいい。というわけで、そうしました。

いま実現できるようになった理由

#

1年前なら手を出さなかったと思いますが、ほぼ同時期に3つの変化がありました。まず、量子化モデルが小さくなったこと。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に落ち着くまでに、4つの小型モデルを試しました。

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>タグでのチェーン・オブ・ソートにも対応しています。

Q4_K_Mは、llama.cppの「k-quant」と呼ばれる量子化形式のひとつです。重みはブロック単位で4ビットの値として保存され、ブロックごとに専用のスケールを持ちます。さらにM（medium）の構成では、影響を受けやすい一部のテンソルを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を追加して、development buildで動かします：

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

npx expo install llama.rn
npx expo run:ios

本番ビルド向けには、llama.rnが大きなモデル用に推奨している2つのiOSエンタイトルメント（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なら2〜3分、LTEだと5〜8分といったところです。ダウンロードが済んだら、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（これはプロンプト処理の時間です）、以降は1トークンあたり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さんが2人見つかりました。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を見失うことなく続きを再開できます。

セッションの保存

#

チャットセッションはアプリのバックエンドにも保存しています。真似する価値があるのは、アシスタントのメッセージを2通り持たせておくことです。表示用に整えたものと、<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();
}, []);