この記事はその逆の順番の話です。サービスは作ったマシンの上で動き続け、Cloudflare Tunnel がそこに公開の HTTPS ホスト名を与えます。ノート PC の上でインターネットに向けて待ち受けているものは何もありません。ポートフォワーディングも、ルーターの設定も、むき出しの IP アドレスもなし。マシンのほうから Cloudflare に接続し、Cloudflare はその接続を通してリクエストを送り返してきます。トンネルは無料で、TLS 証明書、DDoS 対策、キャッシュは、おそらく既に持っている Cloudflare のゾーンに付いてきます。

例は実際のものです。私のプロダクトのひとつ は Fly.io で動いていて、そのモバイルアプリはバックエンドから JavaScript の OTA(無線)更新を受け取ります(セルフホストの Expo Updates)。本番はそのままにして、開発ビルド用にその更新サーバーの二つ目のコピーを自分の Mac で動かしたかったのです。以下の出力は、うまくいかなかった部分も含めて、その日の午後のものです。

Cloudflare Tunnel とは実際のところ何なのか

#

普通のサーバーは接続を待ちます。インターネットからノート PC に届くようにするには、ルーターでポートを開け、それをノート PC に転送し、ISP がパブリックな IPv4 アドレスをくれることを祈るしかありません(多くの地域では、私のところも含めて、くれません)。そうなると、そのポートで待ち受けているものはすべて、インターネット中のスキャナーから一日中届くことになります。

トンネルはこれを逆にします。cloudflared はアプリの隣で動き、Cloudflare のエッジへ外向きの接続を開きます。近くの二つのデータセンターへ四本です。ゾーンの DNS レコードがホスト名をトンネルに向けます。そのホスト名へのリクエストが届くと、Cloudflare が TLS を終端し、リクエストをその接続のどれか一本に流します。あとは cloudflared が、設定で指定したローカルのサービスに渡します。

セキュリティの面で大事なのは、ルーターに受信ルールがひとつもなく、IP アドレスが DNS に一度も出てこないことです。自宅の回線をスキャンしても何も見つかりません。そこで待ち受けているものが何もないからです。

設定方法、最初から最後まで

#

必要なのは Cloudflare に載せたドメイン(無料プランで十分)と、インストール済みの cloudflared(Mac なら brew install cloudflared)です。

1. 一度だけログインする。 ブラウザが開くのでゾーンを選ぶと、このマシンがそのゾーンにトンネルと DNS レコードを作れるようにする証明書が保存されます。

cloudflared tunnel login

2. トンネルを作る。 このプロジェクト用のものはすべて専用のフォルダに置いています。認証情報ファイルはトンネルの身元そのもので、それを持っている人なら誰でもあなたのホスト名のトラフィックを配信できてしまうからです。

mkdir -p ~/.cloudflared/myapp && cd ~/.cloudflared/myapp
cloudflared tunnel create --credentials-file ./creds.json myapp-local
chmod 600 creds.json

Tunnel credentials written to ./creds.json. Keep this file secret. To revoke these credentials, delete the tunnel.
Created tunnel myapp-local with id 1ade030c-…

3. ホスト名をトンネルに向ける。 ホスト名ごとにコマンドを一回実行すると、<tunnel-id>.cfargotunnel.com へのプロキシ済み CNAME が作られます。

cloudflared tunnel route dns myapp-local ota.example.com
cloudflared tunnel route dns myapp-local checkin-local.example.com

4. ingress ルールを書く。 セキュリティにとって肝心な部分なので、下で節をひとつ設けます。

5. 動かす。 私のアプリは既に Docker Compose で動いているので、cloudflared は同じネットワーク上のコンテナがひとつ増えるだけです。アプリにはサービス名で届くので、アプリ側はホストにポートを公開する必要すらありません。

# compose.tunnel.yml, used alongside the project's docker-compose.yml
services:
  cloudflared:
    image: cloudflare/cloudflared:2026.10.7
    command: tunnel --config /etc/cloudflared/config.yml run
    volumes:
      - ${HOME}/.cloudflared/myapp:/etc/cloudflared:ro
    restart: unless-stopped
    depends_on: [api, edge]

docker compose -f docker-compose.yml -f ~/.cloudflared/myapp/compose.tunnel.yml up -d cloudflared

INF Registered tunnel connection connIndex=0 … location=icn06 protocol=quic
INF Registered tunnel connection connIndex=1 … location=icn07 protocol=quic
INF Registered tunnel connection connIndex=2 … location=icn07 protocol=quic
INF Registered tunnel connection connIndex=3 … location=icn06 protocol=quic

ソウルへの接続が四本。これでノート PC は、外から見てインターネット上にいます。restart: unless-stopped のおかげで、再起動しても Docker が立ち上がればすぐに戻ってきます。

サーバーではなくパスを公開する

#

ここは私が危うくやりかけた間違いで、おそらく一番よくある間違いです。手軽な設定は一行で済みます。hostname → http://localhost:8000。これで公開されるのは開発サーバー丸ごとです。

開発サーバーはそんな使い方を想定して作られていません。私のものは DEBUG=True で動いていて、エラーが起きれば完全なトレースバックと設定が表示されます。認証も切ってあり(AUTH_MODE=disabled)、どんな Bearer トークンでもテストユーザーとしてログインできます。localhost ならまさにそれで正しく、公開ホスト名の上では大惨事です。あなたのところにも似たようなものがあるはずです。デフォルトパスワードのままの管理画面、データ投入用のエンドポイント、デバッグツールバー、あるいは呼ぶのが自分だけだからと呼び出し元を信用している API。

だからトンネルの設定は許可リストにします。cloudflared は各リクエストを ingress ルールと上から順に、ホスト名とパスの正規表現で照合します。最初に一致したものが勝ち、最後のルールが残りすべてを受け止めます。

tunnel: myapp-local
credentials-file: /etc/cloudflared/creds.json

ingress:
  # OTA: the two read-only endpoints the phone calls, and the files they link.
  - hostname: ota.example.com
    path: ^/api/expo-updates/(manifest|status)/$
    service: http://api:8000
  - hostname: ota.example.com
    path: ^/media/
    service: http://api:8000
  # Device check-ins, authenticated by each device's own key.
  - hostname: checkin-local.example.com
    path: ^/c/$
    service: http://edge:8081
  # Everything else, including /admin/ and the publish endpoint: 404 at the edge.
  - service: http_status:404

公開用のエンドポイントは同じサーバーの同じ接頭辞の下(/api/expo-updates/import-update/)にありますが、リストには入っていません。管理画面も、API の残りの部分も同じです。そうしたリクエストは Cloudflare から先へは出ていきません。

自分の正規表現を信じる必要はありません。URL がどのルールに一致するかは cloudflared が教えてくれます。

cloudflared tunnel --config config.yml ingress rule https://ota.example.com/admin/

https://ota.example.com/api/expo-updates/manifest/        service: http://api:8000
https://ota.example.com/api/expo-updates/import-update/   service: http_status:404
https://ota.example.com/admin/                            service: http_status:404
https://ota.example.com/media/expo-updates/x.js           service: http://api:8000
https://checkin-local.example.com/c/                      service: http://edge:8081
https://checkin-local.example.com/health                  service: http_status:404

このチェックはスクリプトにして、設定を変えるたびに走らせるのがおすすめです。数秒で終わりますし、意図より広く一致する正規表現は、他人に指摘されて初めて気づく類の間違いです。

経験則をあと二つ。

• 公開するものは自分で認証すること。 OTA のエンドポイントが配るのは公開の読み取り専用データです。デバイスのチェックインはデバイスごとの鍵で署名されています。どちらも安全をネットワークに頼っていません。ログインのないページを誰かに見せたいなら、ログインを作るのではなく、そのホスト名の前に Cloudflare Access を置きましょう(50 ユーザーまで無料)。
• トンネルを開発ワークフローの裏で常時動かさないこと。 意図したホスト名のために意図して動かし、終わったら止めます。docker compose stop cloudflared のコマンド一発で、すべてがインターネットから消えます。

ホスト名を飲み込んだリダイレクト

#

トンネルがつながり、ルールも確かめたところで、外から試してみました。

https://ota.example.com/api/expo-updates/status/?…   301
https://ota.example.com/api/expo-updates/manifest/   301
https://ota.example.com/admin/                       301
https://checkin-local.example.com/c/                 301

どのパスも同じ 301 を返しました。トンネルなら 404 を返すはずのものまでです。つまりリクエストは cloudflared に届いていません。Location ヘッダーは https://www.example.com/ で、server: cloudflare ヘッダーで決まりでした。Cloudflare が自分で応答していたのです。

原因は自分でした。何か月も前に、でっち上げのサブドメインを歩き回るスキャナー向けのシンクホールとして、ゾーンレベルのリダイレクトルール「その他のサブドメイン → www」を追加していました。リダイレクトルールは Cloudflare のリクエスト処理の中で、リクエストがオリジンに送られる前に動きます。そしてトンネルはただのオリジンです。同じルールが私のプレビュー環境も捕まえて、Workers に届く前に止めていました。対処も前回と同じで、ルールの式に例外をもうひとつ足すだけです。

… and not http.host in {"ota.example.com" "checkin-local.example.com"}

トンネルのホスト名が、アプリではなく Cloudflare のリダイレクトやエラーページを返してくるなら、トンネルをデバッグする前に、そのゾーンの Rules → Redirect Rules、Page Rules、WAF のカスタムルールを確認してください。cloudflared は転送したリクエストをすべてログに残すので、ログが空ならリクエストはそこまで来ていません。

できないこと

#

• 公開インターネットからの UDP。 トンネルの公開ホスト名が運ぶのは HTTP(S)(と WebSocket、gRPC)です。私のプロダクトのデバイスは普段 UDP 上の CoAP でチェックインしますが、それはトンネルを通れません。ローカルのコピーにつながるデバイスは HTTPS のチェックインにフォールバックし、そのたびに数秒余計にかかります。アイデアがゲームサーバーや VoIP なら、トンネルは向いていません。
• 稼働率。 ノート PC です。蓋を閉じればサイトは落ち、Cloudflare が 530 のエラーページを出します。デモや十人規模のベータ、ステージング用のコピーならそれで構いません。誰かが頼りにしているものには向きません。
• ビルドに焼き込まれるもの。 モバイルアプリの更新 URL はネイティブの設定なので、トンネルの URL で作ったビルドだけがそれを使います。ストア版のビルドは本番と話し続けるので、だからこそこの構成は安心して試せました。

コスト: Cloudflare Tunnel は無料?

#

無料プランの Cloudflare ゾーン、トンネル、その証明書、DNS レコード、合わせて 0 ドル。マシンはもともと動いていました。本当のコストは、今やあなたが稼働率の担当チームになる、ということだけです。

その代わりに省けるのは、「自分のマシンでは動く」と「お金を払ってホストする価値がある」の間の段階です。テスターやデザイナー、最初のお客さんに、その日の午後のうちにリンクを送れます。誰も興味を示さなければ、失ったものは何もありません。興味を示してくれたら、本物のホストへの移行は変更ひとつで済みます。CNAME を別の場所に向けるだけです。

最初に出会ったのは9月でした。ヘルスチェックはすべて正常なのにCloudflareのダッシュボードではリクエストの22%が失敗していたときで、私はEarly Hintsをオフにして次へ進みました。11月に同じゾーンを見ると、Early Hintsがまたオンになっていて、1日で504が2,600件たまっていました。今回は、その正体を正確に知りたかったし、もう一度オフにするのが正解なのか、きちんと働かせるのが正解なのかも知りたかったのです。このゾーンはFly.ioのオリジン1台の前段にあり、そのオリジンがDjango API、Expo製のWebアプリ、Hugoで作ったマーケティングサイトを配信しています。

短い答え

#

• この504を書いているのは訪問者ではなく、CloudflareのEarly Hintsキャッシュです。CloudflareのログではClientRequestSource = earlyHintsCacheになっています。
• ここでの504はキャッシュミスを意味します。そのURLに保存されたヒントがなかったということです。ヒットは2xxとして記録されます。
• これらはオリジンに一切届きません。OriginResponseStatusは0です。
• Early HintsはLink HTTPレスポンスヘッダーで動きます。HTML内の<link rel="preload">タグでは動きません。
• ヘッダーを送れば、プリロードするものがあるページでは、このミスがヒットに変わり、本物の103 Early Hintsレスポンスが返るようになります。

先に知っておくと役立つことが、あと3つあります。ヒントにするのはレンダリングに必須のCSS、スクリプト、フォントだけにして、フォントにはcrossoriginを残してください。確認はcurl -sv --http2で、200の前に103が見えるはずです。そして、ほかに何を決めるにせよearlyHintsCacheはアラートから外しておき、今後もヘッダーを送らないなら、ログのノイズで代償を払うよりEarly Hintsをオフにしてください。

偽のCloudflare 504と本物の504の見分け方

#

LogpushやInstant Logsを使っているなら、まず2つのフィールドを見てください。ClientRequestSourceは、実際の訪問者のリクエストならeyeball、Early Hintsの参照ならearlyHintsCacheです。OriginResponseStatusが0なら、オリジンには接続すらしていません。

GraphQL Analytics APIでは、同じ区別がrequestSourceディメンションとして取れます。5xxの急増を信じる前に、私は今このクエリを実行するようにしています。

query ($zone: String!, $since: Time!) {
  viewer {
    zones(filter: { zoneTag: $zone }) {
      httpRequestsAdaptiveGroups(
        limit: 20
        filter: { datetime_geq: $since, edgeResponseStatus: 504 }
        orderBy: [count_DESC]
      ) {
        count
        dimensions { requestSource userAgent clientRequestPath }
      }
    }
  }
}

User-Agentでまとめても同じ話になります。9月、Early Hintsの参照はbastion early hintsとnginx-ssl early hintsとして記録されていました。11月はfl2 early hintsとnginx-ssl early hintsでした（FL2はCloudflareのプロキシの新しい世代です）。24時間で、このゾーンの504の2,631件すべてがこれらのUser-Agentから来ていました。ブラウザ、アプリ、curl、検索クローラーからのものは1件もありませんでした。

訪問者が実際に見た本物の504は、ほぼ必ずCloudflareの外側、つまりあなたの側から来ています。アプリケーションの前段にあるプロキシやロードバランサーが待ちきれずに諦めたのです。nginxかもしれないし、クラウドのロードバランサーかもしれないし、スリープ中のマシンが起きるのを待つプラットフォームのプロキシかもしれません。Cloudflare自身のタイムアウトは別のコードを使います。522はオリジンに接続できなかったこと、524は接続はできたが125秒以内（Enterprise未満のプランのデフォルト）に応答がなかったことを意味します。

504のせいでCloudflareのタイムアウトを延ばす方法を探してこの記事に来たのなら：504の背後にあるタイムアウトは、ほぼ確実にCloudflareのものではありません。nginxのproxy_read_timeout、ロードバランサーのアイドルタイムアウト、あるいはプラットフォームがマシンを起こすのにかかる時間を確認してください。役に立つ手がかりがひとつあります。125秒よりかなり短い、30秒や60秒といったきりのいい数字でリクエストが失敗するなら、それはCloudflareではなく、あなたのプロキシの上限です。（Cloudflareの125秒の上限を最大6,000秒まで延ばせるのはEnterpriseプランだけで、Cloudflare自身もそれを応急処置と位置づけています。）

この504の正体

#

Early Hintsが有効なゾーンでは、HTMLページか拡張子のないURLへのリクエストごとに(APIの多いゾーンでは、API呼び出しのほとんどがこれに当たります)、内部の参照がひとつ追加されます。Cloudflareが、送るべきヒントがあるか自分のキャッシュを確認しているのです。この参照はClientRequestSource = earlyHintsCacheとして独立した行に記録されます。エンドユーザーのリクエストではなく、オリジンに送られることもありません。

その行のステータスは、エラーではなくキャッシュ参照の結果です。

• 2xxはヒットです。CloudflareにそのURL用のLinkヘッダーが保存されていて、それを103としてブラウザに送ったということです。私のゾーンでは、ヒットは200と204の両方で現れます。
• 504はミスです。何も保存されていなかったので、先に送るものがなかったということです。

オリジンがEarly Hintsの使うヘッダーを一度も送らなければ、すべての参照がミスになり、すべてのリクエストが504の行を1行ずつ残します。私が何も変える前の3時間で、このゾーンは173件のEarly Hints参照を記録し、173件すべてがミスでした。機能がオンになってから、一度もヒントを送っていなかったのです。

9月の記事についての訂正もひとつ。私はこれを「Flyのオリジンから応答を得られない」プローブだと説明していました。それは正確ではありません。この参照はそもそもオリジンに行きません。504はタイムアウトではなく、キャッシュミスを記録したものです。

CloudflareはこのことをEarly Hintsのドキュメントで簡潔に説明しています。ClientRequestSource: earlyHintsCache として記録されたEarly Hintsの参照は「expected and benign」(想定内で無害)であり、200はキャッシュヒット、504はミスです。Log Explorerでは ClientRequestSource != "earlyHintsCache" で除外できます。Cache Analyticsはもともとこれらを除外していますが、私を怖がらせたHTTPトラフィックのグラフは除外していません。

偽の504のせいでサーバーを増強してしまった

#

この区別が大事な理由がここにあります。この記事に取りかかる前日の11月3日、Cloudflareには約13,300件の訪問者リクエストに対して3,292件の504が記録されていました。見かけ上のエラー率は25%です。APIはFly.ioのshared-cpu-1xマシンで動いていて、これはバーストクレジット方式です。保証されるCPUの取り分は小さく、速く動くにはクレジットを消費します。8月の負荷テストでは、持続的な負荷がかかると毎秒およそ20〜30リクエストまでスロットリングされることが分かっていました。「ピーク時にリクエストの4分の1がタイムアウトしている」のは、まさにそのスロットリングに見えました。そこでAPIをshared-cpu-2xに移しました。

ところが、その504はすべてEarly Hintsのキャッシュミスでした。requestSourceで分け、オリジン自身のログも見直すと、こうなっていました。

• 10月28日から11月4日までのCloudflareの5xxは、1日1件ほどの525を除いてすべてearlyHintsCacheのルックアップでした（調べた525はセキュリティスキャナーからのものでした）。
• 10月24日から11月4日までのオリジンのアクセスログには5xxが1件もなく、10秒を超えたリクエストは1件だけでした。
• Flyのメトリクスでは、最も多いときでも毎秒7リクエスト程度で、マシンが使ったCPUは1コアの5分の1以下でした。スロットリングの上限には一度も近づいていません。

大きいマシンは何も直していませんでした。何も壊れていなかったからです。APIはshared-cpu-1xに戻しました。

request sourceで分けていない5xxチャートをもとに、キャパシティを判断しないでください。オリジン自身のログとも突き合わせてください。Cloudflareはリクエストの4分の1が失敗したと言っているのにサーバーのログにエラーがないなら、サーバーに手を入れる前に、Cloudflareが何を数えているのかを確かめましょう。

2026年11月5日更新：このセクションの最初の版では、その週にAPIがshared-cpu-1xで本当にダウンしたと書いていました。実際にはダウンしていませんでした。上の数字は、確認したときに分かったことです。

HTTP 103はエラーなのか？

#

違います。1xx台のステータスコードは情報レスポンス、つまりサーバーが本当のレスポンスの前に送れる中間レスポンスです。RFC 8297で定義された103 Early HintsはLinkヘッダーを運び、サーバーがまだページを組み立てている間に、ブラウザが重要なCSS、JavaScript、フォントの取得を始めたり、別のオリジンへの接続を開いたりできるようにします。最終的な200は同じリクエストの中で後から届きます。

対応状況はまちまちですが、安全です。Chromium系ブラウザ（Chrome 103以降、Edge）と最新のFirefoxは、preloadとpreconnectの両方のヒントを処理します。Safari(17以降)はpreconnectだけを使います。ブラウザが103を処理するのはHTTP/2とHTTP/3の場合だけです。理解しないブラウザはいつも通り200を待つだけなので、103はほとんどの訪問者にとっては先回りになり、それ以外の訪問者には何の影響もありません。

私の設定が空だった理由：Linkヘッダーと<link rel=preload>の違い

#

ここに一番時間を使いました。すでに動いていて当然に見えたからです。

Early Hintsがキャッシュするのはただひとつ、rel=preloadかrel=preconnectの関係を持つ**Link HTTPレスポンスヘッダー**です。Cloudflareは通常のレスポンス（HTMLまたは拡張子なしURLの200、301、302）からこのヘッダーを読み取って保存し、次の訪問者には完全なレスポンスの準備ができる前に103として再送します。

私のページにはすでにプリロードがありました。ただし、HTMLの<head>内のタグとしてです。

<link rel="preload" href="/_expo/static/css/global-7d77bd.css" as="style">
<link rel="preload" href="/_expo/static/js/web/entry-fd7fa4.js" as="script">
<link rel="preload" href="/fonts/manrope-latin.woff2" as="font" type="font/woff2" crossorigin>

これらのタグにも意味はあります。ブラウザはこれを見て動きます。ただし、ブラウザがこのタグを目にするのはHTMLを受け取ってパースを始めた後で、それこそEarly Hintsが先回りしようとしている瞬間です。Expoのエクスポートも、私が使っているHugoのテーマも、このタグは自動で書いてくれますが、ヘッダーはどちらも設定しません。機能はオンで、プリロードも宣言されていたのに、両者は一度も出会っていなかったのです。

解決策：すでに持っているデータでヘッダーを送る

#

いちばんきれいな解決策は、バンドルのハッシュが変わるたびに古くなる重要アセットのリストを手で管理することではありません。各ページは、何をプリロードしたいかをすでにタグで宣言しています。だから、ページを配信するときにそれをLinkヘッダーに写せばいいのです。標準ライブラリのhtml.parserは引用符ありの属性もなしの属性も(Hugoのminifierは引用符を外します)扱ってくれるので、正規表現で間違える余地はありません。

from html.parser import HTMLParser


class PreloadLinks(HTMLParser):
    def __init__(self):
        super().__init__()
        self.hints = []

    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        if tag != "link" or "preload" not in (a.get("rel") or "").split() or not a.get("href"):
            return
        hint = f"<{a['href']}>; rel=preload"
        if a.get("as"):
            hint += f"; as={a['as']}"
        if a.get("as") == "font" or "crossorigin" in a:
            hint += "; crossorigin"
        self.hints.append(hint)


def link_header(html: str, limit: int = 12) -> str | None:
    parser = PreloadLinks()
    parser.feed(html)
    return ", ".join(list(dict.fromkeys(parser.hints))[:limit]) or None

そして、DjangoのHTMLレスポンスに付けます。

response = HttpResponse(html, content_type="text/html")
if (link := link_header(html)) and "Link" not in response:
    response["Link"] = link

ひとつだけ、私がはまった細部を。フォントにはcrossoriginを残してください。これがないフォントのプリロードは別のリクエストとして扱われ、フォントが2回ダウンロードされて、ページは速くなるどころか遅くなります。

103を自分で書く必要はありません。ASGIやGranian、uvicornに中間レスポンスのコードを足すこともありません。Cloudflareがあなたのヘッダーから103を作ります。あなたの仕事はヘッダーを送ることだけです。

ほかのスタックでは

#

ルールはどこでも同じです。HTMLレスポンスにLinkヘッダーを付け、残りはCloudflareに任せます。

• nginxでは、HTMLを配信するlocationに：

  location = / {
      add_header Link "</css/app.css>; rel=preload; as=style" always;
      add_header Link "</fonts/inter.woff2>; rel=preload; as=font; crossorigin" always;
  }

• LaravelとViteの組み合わせには、このためのミドルウェアAddLinkHeadersForPreloadedAssetsがすでにあり、ViteのプリロードをLinkヘッダーに変換してくれます。これに対して報告されている2つの問題は、上で書いた落とし穴と同じです。modulepreloadのヒントがcrossoriginなしで送られ、ブラウザがそれを捨ててスクリプトを2回ダウンロードしうること、そして大きなページではヘッダーがApacheの約8KBのヘッダー上限を超えたことです。お使いのバージョンで両方を確認してください。

• それ以外：Linkヘッダー1つにカンマ区切りで書くか、Linkヘッダーを複数送ります。どちらでも動きます。

みんながやりすぎるのは、何をヒントにするかです。レンダリングに必須のCSS、エントリースクリプト、ファーストビューで使うフォント1〜2個だけをヒントにして、すべてのチャンクを入れないでください。リストが長いと、ブラウザは今必要なものより先に、まだ必要ないものを取りに行ってしまいます。私は12個を上限にしていますが、それもExpoのエクスポートがプリロードのリストをすでに絞ってくれているからです。

Cloudflareの後ろにいない場合や、CDNがEarly Hintsに対応していない場合でも、Linkヘッダーは少しだけ役に立ちます。ボディをパースする前、レスポンスヘッダーが届いた時点でブラウザがそれらの取得を始められるからです。ただし、サーバーかCDNが送らない限り103は返りません。

動いているか確認する方法

#

curlなら103を直接見られます。HTTP/2でリクエストし、ステータス行とLinkヘッダーだけを残します。

$ curl -sv --http2 -o /dev/null https://example.com/register 2>&1 | grep -E '^< (HTTP|link)'
< HTTP/2 103
< link: </_expo/static/css/reset-f5d396.css>; as=style; rel=preload, …
< HTTP/2 200
< link: </_expo/static/css/reset-f5d396.css>; rel=preload; as=style, …

先に103が届き、その後に200が来ます。Cloudflareはヒント内の属性の順番を並べ替えますが、問題ありません。すべてのリクエストが103を受け取るとは思わないでください。私の場合、最初の3回のうち2回でした。変更後の最初のアクセスはヘッダーを保存するだけで、最終レスポンスのヘッダーがすでに用意できている場合、Cloudflareは103を省略します。

そのうえで、上の分析クエリに戻り、requestSource: "earlyHintsCache"で絞り込んで、ステータスとパスでまとめてください。修正したページでは、ミスに代わってヒットが出てくるはずです。

何が変わり、何が残ったか

#

ヘッダーを本番に出して数分後、このゾーンは初めてEarly Hintsのヒットを記録し、curlではWebページに本物の103レスポンスが見えました。ヘッダーひとつで2つの問題が同時に片づきました。機能が動き始め、「504」の一部が消えたのです。

残った問題は、JSON APIにはプリロードするものがないことです。APIのエンドポイントはミスを出し続け、504の行を残し続けます。APIの比重が大きいゾーンでは、これが依然として大部分です。妥当な選択肢は3つあります。効果のあるページにヘッダーを送り、APIのパスがミスを記録し続けるのは受け入れる。機能は動き、チャートは静かになりますが、完全には静かになりません。ほかに何を決めるにせよ、earlyHintsCacheを5xxのアラートとダッシュボードから除外する。内部のキャッシュ参照で誰かが呼び出されるべきではありません。あるいは、今後もLinkヘッダーを送らないなら、Early Hintsをオフにする（ダッシュボードのSpeed → Settings → Content Optimization、またはAPIのゾーン設定early_hints）。HTMLがとても小さいシングルページアプリでは得るものが少ないかもしれず、オフにすればすべての参照が止まり、ノイズも一緒に消えます。

私はオンのままにしました。Webページは先回りできるようになり、APIのミスはアラートが関わるすべての場所から除外しました。9月に機能をオフにする代わりにやるべきだったのは、まさにこれでした。

ホスティング型のAPMも、本番のトレーシングも、わざわざ思い出して開くダッシュボードもありません。追加でお金がかかっているのはログアーカイブだけで、月2ドルほどです。以下が全リストと、やめたもの・信じなくなったものです。そのうちのひとつのせいで、私はユーザーが誰ひとり体験していない障害を何日も追いかけていました。

ここで言うモニタリングと、どれだけ小さな規模の話か

#

私がDevOpsモニタリングと言うときは、2つのことを指しています。誰かに言われる前に何かが壊れていると気づけること、そして当て推量なしに原因を突き止められることです。以下のツールはすべて、この2点で評価しています。

昨年、開発者が本当に使ってくれるモニタリングの作り方という記事を書きましたが、そのときはおもにチームを想定していました。小さなチームならクラウド事業者に組み込みのモニタリング、サービスが何百もあるならホスティング型のAPM、という具合です。今回はその同じ考え方の、いちばん小さい側の端です。2つのプロダクトはどちらもいまの技術スタックで書いたとおりFlyのshared-cpu-1xマシン上のDjangoで、開発者はどちらも私ひとりです。モニタリングがプロダクトで開発者がそのユーザーだとすれば、私のモニタリングのユーザーは1人だけということになります。9月にFlyのメトリクスからベースラインを取ったところ、マーケットプレイスのAPIのCPU使用率は平均1%でした。エンタープライズのスタックではありませんし、そう見せるつもりもありません。

メトリクス、ログ、トレースの3本柱のうち、私が持っているのは2本です。どちらのプロダクトにも分散トレーシングはありません。それぞれDjangoのコードベースひとつとデータベースひとつで、トレースがまたぐべきサービス境界がないからです。私が見ているトレースは、自分のワークステーションで動かしているリバースプロキシのものだけです。

一覧

#

「両アプリ」と書いていないものは、すべてマーケットプレイスの話です。見積もりアプリはもっと少なく、Flyのヘルスチェック・ログ・メトリクス、iOSのアプリ解析、そしてデータベースを毎日Parquetに書き出してDuckDBで問い合わせる仕組みくらいです。クラッシュレポートもアラートのチャンネルもなく、この記事でいちばん大きな穴はここです。(アップデートサービスの行について開示しておくと、このサービスを提供している会社は、同社のブログに書く記事に対して私に報酬を払っています。)

エラー：チャットに投稿するロギングハンドラー

#

9月までは、処理されなかった500も、失敗したプッシュ通知も、壊れたWebSocketフレームも、出てくる場所は flyctl logs だけでした。そしてあのストリームを自分から読みに行く人はいません。いまはロギングハンドラーが、API・WebSocketサーバー・バックグラウンドワーカーのどこで起きたものでも、ERROR以上のレコードをすべてチャットチャンネルに送ります。WARNINGはあえて通知しません。

ハンドラーはバックグラウンドのスレッドで送信するので、リクエストを遅くしません。ハンドラーの中では何もログに書かないので、再帰しません。そして同じエラーは10分に1回まで、1時間に最大30件までしか送らないので、障害が起きても千件のメッセージではなく1件として読めます。

このチャンネルには、エラーと突き合わせて読みたいものも流れてきます。デプロイは開始時、立ち上がったとき、失敗した箇所でコミットと実行者付きで投稿し、OTAアップデートやWebリリースも同じです。ひとつのアカウントに間違ったサインインコードが集中したときもERRORで記録するので、誰かが当てずっぽうに試していれば障害と同じ場所に現れます。

10月、どのログにも対応する行がないアラートがひとつ届きました。それ以来、アラートには短いランダムなid、ホスト名、プロセスの起動コマンドを付け、同じ行をそのプロセスのログにも書くようにしています。idがどこにも見つからなければ、そのアラートはそこにログを書かないプロセス、たとえばSSHのシェルから来たということです。チャンネルに届くものはすべて、私が一緒に作業しているコーディングエージェントが読めるフィードにも入ります。コードを触っているエージェントも、私と同じタイミングでエラーを目にするわけです。

ログ：FlyのシッパーでS3へ、DuckDBで検索

#

Fly自身のバッファが持っているのは数分ぶんの出力、だいたい直近100行ほどです。デプロイを見守るには十分ですが、昨日のことには役に立ちません。そこで3つめのFlyアプリでFlyのログシッパーを動かしています。組織のログストリームを購読するVectorで、変えたのはS3シンクひとつだけです。

[sinks.aws_s3]
  type = "aws_s3"
  bucket = "myapp-logs"
  compression = "gzip"
  key_prefix = "logs/{{fly.app.name}}/%F/"   # one folder per app per day
  batch.timeout_secs = 300                  # a quiet app still lands its lines

マーケットプレイスのアプリのログは1行残らず、gzipしたJSONとしてS3互換のバケットにたまります。シッパーは256MBのshared-cpu-1xマシン1台で、月2ドルほど、ストレージ代は小銭程度です。DuckDBはマクロひとつでファイルをその場で読み、1日分ならおよそ1秒で返ってきます。

CREATE MACRO logs(app, day := '*') AS TABLE
  SELECT * FROM read_json_auto('s3://myapp-logs/logs/' || app || '/' || day || '/*.log.gz',
                               union_by_name := true);

SELECT timestamp, message FROM logs('myapp-api', '2026-09-06') WHERE message LIKE '% 500 %';

ゼロスケールの記事でコールドスタートを測ったのも、このマクロでした。起動スクリプトがフェーズごとに名乗り、どの行にもマシンのidが付いているので、あとは GROUP BY だけです。

つまり、ひとつのストリームを読む人ごとに3段階に分けているわけです。アーカイブはINFO以上をすべて保持し(本番のアプリがINFOでログを出しているのはこのためです)、ライブ表示のスクリプトはWARNINGとERRORだけを見せ、チャットチャンネルはERRORを受け取ります。ただ、どれも呼び出し元はわかりません。アクセスログにはクライアントのIPもユーザーエージェントもないので、それはCloudflareで調べます。

メトリクス：Flyに標準で付いてくるPrometheus

#

Flyは組織ごとにマネージドのPrometheusを動かしてくれるので、自前のメトリクス基盤は持っていません。知りたいことがあるときにAPIを叩きます。マシンごとのメモリ、CPU、バーストクレジット(共有CPUでは fly_instance_cpu_balance が効いてきます)、アプリごとのレスポンス数や同時実行数などです。最初に知っておきたかったことが2つあります。fly tokens create で作ったトークンは Authorization: FlyV1 <token> として渡します。Bearer が使えるのは flyctl auth token の個人トークンだけで、読み取り専用トークンだと “something went wrong resolving organization” が返ってきます。そして保持期間はおよそ2週間です(Flyの説明では15日ほど)。

これが本領を発揮したのは9月でした。ログに “Could not open a database connection” が1日に何度も出ていて、どう見てもアプリのバグに見えました。マネージドPostgresのクラスタも同じPrometheusに入っていて、そのエラーが出た分にはいつも、プライマリのスクレイプ時間が80ミリ秒ほどから1〜10秒に跳ね上がっていました。レプリカは平常で、Postgresの起動時刻は動いていません。Postgresが再起動したのではなく、その下のホストが止まっていたのです。タイムスタンプを添えてFlyのサポートに送り、10月初めのメンテナンス再起動でプライマリが別のホストに移ってからは、毎日の停止はなくなりました。

クラッシュレポート：自前のAPIに向けたSentryのSDK

#

以前は、スマホでアプリが落ちても、私に見える場所のどこにも痕跡が残りませんでした。当然の答えはSentryで、私はその半分だけを取り入れました。アプリにはSentryのオープンソースSDKが入っていますが、DSNは私のDjango APIのエンドポイントを指しています。そのエンドポイントがSentryのenvelope形式を受け取り、クラッシュをまとめ、同じチャット用のハンドラーで通知します。トレーシング、セッション、リプレイはオフにしていて、受け取るのはエラーだけです。

sentry.ioに登録しなかったのは、1日に数件のレポートのために、ユーザーデータを預ける業者をひとつ、プライバシーポリシーの記述を1行、請求書を1枚増やしたくなかったからです。代わりに払っている代償はシンボリケーションで、これはまだ置き換えられていません。スタックはminifyされたJavaScriptか生のネイティブアドレスなので、イシューを見れば何がどのリリースと端末で落ちたのか、直前にユーザーが何をしていたのかはわかっても、ソースのどこなのかはわかりません。

ダッシュボードはメッセージ1本

#

どちらのアプリにもダッシュボードは作っていません。昨年の記事にダッシュボードの判定基準を書きました。誰にも自発的に開かれないダッシュボードは存在価値を証明できていない、というものです。勝手に届くメッセージなら開く必要がないので、私にとっていちばんダッシュボードに近いのは、毎朝チームのチャットに届く1本の投稿です。

最初は直近24時間の本番エラーです。チャットチャンネルではなくログアーカイブから読みます。アラートは件数を絞っているので、何かが何回起きたのかを教えてくれないからです。数字、id、アドレスを伏せてからまとめるので、同じ失敗が100件あっても件数付きの1行になり、メールアドレスがチャンネルに流れることもありません。

続いて失敗したヘルスチェック、前日の利用状況を1週間前の同じ曜日と比べたもの(日曜日が月曜日と同じになることはありません)、直近1週間の検索流入、返信待ちのチャット、タスクボード、そして支出です。読み込めなかったセクションはそう書かれ、投稿自体は届きます。

アプリ解析の数字をAPIで読んでいると、少し疑ってかかるようになります。8月にはアゼルバイジャンからAndroidの初回起動が121件あり、その後アンインストールが119件続きました。その月のAndroidの合計は、これを除いて読んでいます。

リリースには専用の画面があります。OTAアップデートを自前のサーバーから配っていたころ、リリースを見る手段は “is active” のチェックボックスが付いた管理画面の一覧だけで、何台がアップデートを受け取ったのかまったくわかりませんでした。いまのサービスのダッシュボードは、端末が実際にどのリリースを動かしているか、インストールがどうだったか、そして壊れたバンドルが落ちてSDKが前のものに戻したときにはそのクラッシュロールバックまで見せてくれます。ホスティング型のアップデートサービスへの移行については別の記事にまとめています。

やめたもの、信じなくなったもの

#

この中に有料のツールはひとつもありません。ほとんどはシグナルだと思っていたのに実はそうではなかったもので、あとひとつは置き場所を間違えていたジョブです。

ユーザーエージェントでまとめるまでの、Cloudflareの504率

#

9月、Cloudflareのダッシュボードには、1日のリクエストの22%が504で失敗しているように見える数字が出ていました。アプリが30秒ごとにポーリングするエンドポイントに集中していて、ヘルスチェックはすべて緑、アプリ自身のログではそのリクエストは速く返っていました。何日もかけました。マシンのコールドスタートに25〜33秒かかり、それが1日92回起きていることを突き止めて直し、ゼロスケールの記事にそれが原因だと書きました。

翌朝、同じ504をユーザーエージェントでまとめてみました。9月5日から9日までの7,344件は、すべてCloudflare自身のEarly Hintsのキャッシュ参照(ユーザーエージェントは bastion early hints と nginx-ssl early hints)でした。この参照はオリジンには一切届きません。その行の504はタイムアウトではなく、キャッシュミスを記録したものです。実際のリクエストのパスをなぞるので、いちばん忙しいエンドポイントに集まり、本当にユーザーが失敗しているように見えました。アプリ、ブラウザ、curl、検索エンジンのクローラーには1件もありません。オリジンが Link ヘッダーを送っていなかったので、Early Hintsは何の役にも立っておらず、いったんオフにしました。その後、ちゃんと動くようにしました。

コールドスタートの対応自体は無駄になりませんでした。デプロイもスリープからの復帰も速くなっています。ただ、直しているつもりだった障害は、一度もユーザーに届いていませんでした。

だからこそ、いちばん伝えたいルールはこれです。CDNのエラー率を信じる前に、ユーザーエージェントでまとめて、CDN自身の仕組みから出たものではないか確かめてください。Cloudflareの無料プランなら httpRequestsAdaptiveGroups へのGraphQLクエリで、1日ずつ見られます。次の騒ぎも同じクエリで片付きました。ポーリング用のエンドポイントのひとつが1日70〜260件から2,880件に跳ね上がったのですが、スクレイパーではありませんでした。テストのあとiOSシミュレーターでアプリを起動したままにしていた、私自身のMacでした。

緑のヘルスチェック

#

Flyは両アプリの /api/health/ を30秒ごとに確認し、その結果でどのマシンにトラフィックを送るかを決めます。その仕事は得意です。ただ、ヘルスチェックはすでに起動しているマシンに対して動くので、マシンが起動する前に起きることは見えません。コールドスタート、プロキシの前の待ち行列、ついに届かないリクエストなどです。いまはルーティング以外のことは期待していません。

デプロイにはかわりにプローブのスクリプトを使います。デプロイのあいだずっとオリジンを叩き、ひとつでも失敗すれば終了コード1で終わります。このスクリプトが素の flyctl deploy で7.3秒の空白を捉え、先に予備のマシンを起こすデプロイスクリプトに切り替えてからは、2,514件中の失敗はゼロでした。

ヘルスチェックは、それ自体が原因の障害も2回起こしています。7月には、Djangoの SECURE_SSL_REDIRECT がFlyの平文HTTPのプローブに301で応え、すべてのマシンがチェックに失敗して、全員に503が返りました。8月には、ヘルス用ビューの except Exception を絞り込んだせいで “connection already closed” のエラーが500として漏れ、ビューのリトライがまさにそのケースのためにあったのに、Flyがマシンを外してしまいました。いまのチェックは、このプロセスがリクエストを処理できるかだけを問い、データベースが止まっても両アプリがルーティングから外れることはありません。

朝のサマリーも、数え方で同じ教訓を学びました。マーケットプレイスはアイドルのマシンをサスペンドするので、リクエストで起こされたマシンは起動後数百ミリ秒で最初のチェックに失敗し、次のチェックで通ります。それを数えていたせいで毎朝が障害のように読めたので、1分以内に再び通った失敗は、いまはマシンの復帰とデプロイとして別に表示しています。

CIの定期実行ジョブ

#

朝のサマリーは、cronで動くCIのワークフローとして始まり、1日で引っ越しました。アプリ解析と検索のデータを読むようになると、必要な鍵がアナリティクスのプロジェクトのサービスアカウントキーになったからです。そのプロジェクトで何でもできる鍵なので、CIのシークレットには置きたくありませんでした。いまは私のMacのスケジューラーが20分ごとに動かし、オークランド時間の朝8時を過ぎていて、その日の投稿がまだのときだけ投稿します。8時に眠っていたMacは、目を覚ましたときに投稿するわけです。ワークフローは、アプリ解析と検索のセクションを抜いた手動用の予備として残しています。

もう一度始めるなら

#

最初の障害のあとではなく、最初のユーザーが来る前に3つを用意します。チームがすでに読んでいるチャットチャンネルへのエラー通知(件数制限付き)、SQLで問い合わせられるオブジェクトストレージのログアーカイブ、そしてプラットフォームがすでに集めているメトリクス。月に数ドルで済みます。クラッシュレポートは、アプリがスマホに載る週に入れます。そうしないと、スマホで起きたクラッシュは誰にも何も伝えないからです。朝のサマリーは、確認する場所が増えすぎて、結局どこも確認しなくなりそうになったころに足せば十分です。

トレーシングは、リクエストがまたぐ2つめのサービスができるまで、ホスティング型のAPMは、共有ダッシュボードとオンコールの当番表、そして他社の請求書を払う予算が必要なチームができるまで待ちます。昨年の記事で紹介したツールが元を取り始めるのはそこからです。それまでのいちばん役に立つ習慣はタダです。数字が怖く見えたら、何が壊れたかを決める前に、その数字を何が生み出したのかを確かめること。この記事に出てきた騒ぎのいくつかは、プロダクトではなくモニタリングそのものから生まれていました。

GitHub ActionsでDocker Composeを動かす方法を探してここに来たなら、先に結論を。私はそれを2年やって、やめました。いまのCIは同じPostgresとValkeyのイメージをservices:として宣言し、同じuv run …とnpm run …をランナー上で直接実行します。Composeは開発者が手元で動かすものに戻りました。以下はその理由と、実際のファイルです。

2024年にCI/CDのロジックはプラットフォーム固有のYAMLではなくDocker Composeにという記事を書きました。ビルドのロジックはComposeに置き、CIツールにはそれを呼ぶことだけをさせる、という内容です。2年たって、実際にリリースに使っているリポジトリを全部見直しました。ワークフローがあるのは4つで、コミッターはどれも私一人です。そして、そのワークフローのうちdocker composeを呼んでいるものは、もう一つもありません。原則は残り、やり方は残りませんでした。以下はその代わりに入ったものです。ファイルを削って例にしたもの、GitHubが記録したステップごとの所要時間、そしてCI/CDの図が期待するほどには自動化されていない部分も書いています。

動かしているパイプラインを一つの表に

#

教科書の言葉でいえば、二つのHugoサイトは継続的デプロイメントで、アプリ（私が作っているマーケットプレイス兼コミュニティアプリ）は継続的インテグレーションにコマンド一つのリリースを足した継続的デリバリーです。チェックは何かがおかしいと教えてくれるだけで、デプロイを止めはしません。これは意図してそうしています。OTAアップデートは対象のバイナリバージョンを使っているすべての端末に届くので、マージの副作用ではなく判断であるべきです。そしてAPIはデータベースのマイグレーションが走る場所です。残り二つのDjangoアプリには、ワークフローがそもそもありません。

CIの側：ワークフロー一つ、ジョブ二つ

#

アプリのCIは.github/workflows/checks.ymlというファイル一つです。10月11日までは、これすらありませんでした。以下はその形を削って例にしたものです。

# Lint, types and tests on every push and pull request to main.
# Nothing here deploys.
name: Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: checks-${{ github.ref }}
  cancel-in-progress: true

jobs:
  python:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_USER: myapp
          POSTGRES_PASSWORD: myapp
          POSTGRES_DB: myapp
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U myapp"
          --health-interval 5s --health-timeout 5s --health-retries 20
      valkey:
        image: valkey/valkey:8-alpine
        ports: ["6379:6379"]
    env:
      DEBUG: "True"
      DATABASE_URL: postgresql://myapp:myapp@localhost:5432/myapp
      REDIS_URL: redis://localhost:6379
      PYTHON_JIT: "0"   # match production
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10
        with:
          enable-cache: true
          prune-cache: true
      - run: uv sync --locked
      - run: uv run ruff check .
      - run: uv run mypy myapp/
      - run: uv run python manage.py test --parallel 4 --noinput

  app:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        working-directory: frontend
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: frontend/package-lock.json
      - run: npm ci
      # Expo writes this on `expo start` and it is gitignored,
      # so a fresh checkout doesn't have it.
      - run: printf '/// <reference types="expo/types" />\n' > expo-env.d.ts
      - run: npm run typecheck
      - run: npx jest --ci

二つのジョブは並行して走ります。これまでに成功した35回の実行で、アプリのジョブの中央値は約7分、Pythonのジョブは約12分半です。

services:ブロックが、Composeファイルの移った先です。これは次の節で書きます。環境変数はいくつかとフラグ一つだけです。ほかはすべて開発者がdocker compose upで得る開発用のデフォルトに落ちるので、テストにシークレットは一つも要りません。本当にそうか確かめるために、まさにその環境だけで、ほかに何もない状態でテストの一部を走らせました。

CIは手元のノートPCや本番イメージと同じインタープリタ、つまりuv自身がビルドしたPython 3.15.0で動きます。uv syncが.python-versionを読み、まさにそのビルドをダウンロードするからです。（実際のファイルではsetup-uvにpython-version-fileという入力も渡していますが、これは何もしていません。setup-uv v6にはそんな入力がなく、毎回の実行にそういう警告が付いています。この記事を書いていて初めて気づきました。）

インタープリタを揃えた甲斐は、ワークフローを入れて8日後に出ました。10月19日に3.15のJITコンパイラを有効にしたところ、有効にして最初の実行でテストが一つ落ちたのです。アプリが保存のたびに通るコードパスのごく普通のyield fromが、AttributeError: 'list' object has no attribute 'send'を投げていました。同じコミットをJITなしで走らせると通ります。私のMacはarm64で一度もこれに当たらず、ランナーは本番マシンと同じx86_64です。JITはCIでもDockerfileでも再び無効にしてあり、このバグが本番に届くことはありませんでした。これはpython/cpython#155823で、3.15.0のリリース後の10月13日に上流で修正されています。

実は最初の実行も落ちていて、こちらの理由はもっと地味です。Expoはexpo startのときにexpo-env.d.tsを書き出し、このファイルはgitignoreされています。なので私が使ってきた作業コピーにはどれもあり、まっさらなチェックアウトにはありませんでした。TypeScriptは、ローカルでは一度も出たことのないエラーを五つ出しました。そのファイルを書き出すステップが対処です。

concurrencyは、同じブランチに新しいpushが来ると前の実行を取り消します。これまでに取り消された12回は、すべてこれによるものです。コミット前のフック（pre-commit）がリンターを走らせ、PythonかTypeScriptがステージされていれば型チェッカーも走らせるので、ミスの大半はpushまで行きません。

Docker Composeファイルはどこへ行ったか

#

アプリのdocker-compose.ymlのうち、CIに関係する部分を例にしたものです。実物にはもっと多くのサービスと、ずっと多くの環境変数があります。

services:
  valkey:
    image: valkey/valkey:8-alpine
    ports:
      - "6379:6379"

  # Host port 55432, not 5432, so it can't collide with a local Postgres.
  postgres:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=myapp
      - POSTGRES_PASSWORD=myapp
      - POSTGRES_DB=myapp
    ports:
      - "55432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp -d myapp"]
      interval: 5s
      retries: 10

  api:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://myapp:myapp@postgres:5432/myapp
      - REDIS_URL=redis://valkey:6379
    depends_on:
      postgres:
        condition: service_healthy
      valkey:
        condition: service_started

volumes:
  postgres_data:

checks.ymlのservices:ブロックと並べると、同じイメージが二つです。Postgres 17（こちらはAlpine版、CIはDebian版）とvalkey/valkey:8-alpine。いまの関係はこうです。Composeファイルは開発者が動かすもの。CIは同じイメージをサービスコンテナとして宣言し、開発者が打つのと同じコマンド、uv run …とnpm run …をランナー上で直接実行します。

2024年の記事と比べると、いちばん大事にしていた部分は残りました。CIツールは薄く、チェックもデプロイも自分で実行できるコマンドです。残らなかったのは、CIからComposeを呼ぶやり方です。

アプリのCIはDockerイメージをまったくビルドしません。イメージはデプロイのときにFlyのビルダーが一度だけビルドし、CIはコードが大丈夫かどうかだけ答えればよく、ツールチェーンがキャッシュされていればそれは6秒のインストールで済みます。それにComposeファイルは作業コピーをバインドマウントし、データを投入しますが、それはテストの実行がすることではありません。CI用に別のComposeファイルが必要になっていたはずで、それは同じサービスの二つ目の定義を手で揃え続けるということです。

そして2024年の例には、当時気づかなかったバグがありました。docker compose buildはイメージをビルドするだけで、サービスのcommandは実行しません。なので、あのファイルのnpm testはCIで一度も走っておらず、ワークフローはテストが通ろうが落ちようが緑でした。

あの記事がいちばん心配していたリスク、つまりCIベンダーの乗り換えは、結局起きませんでした。実際に起きた移行は反対側でした。このブログとクライアントのサイトがホスティング先をCloudflare Pagesに移し、ブログのほうは45行のワークフローを一つ新しく書くだけで済みました。ビルドがもともとコマンド一つだったからです。それから、私が警告していた300行のワークフロー。一つあります。pyhtml2textのものです。wheelをLinux、macOS、Windowsのランナーで、それぞれ複数のアーキテクチャ向けにビルドしなければならないので長いのですが、だからこそプラットフォーム固有のYAMLが正しい道具になる唯一の仕事でもあります。

キャッシュ：まずステップの所要時間を読む

#

GitHubはすべてのステップの所要時間を記録していて、gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobsで取り出せます。以下は10月20日の、アプリで最新の成功した実行です。

依存関係のキャッシュは二つとも有効で、どちらも安い部分です。GitHubがこのリポジトリ用に保持しているuvのキャッシュは200KBほどで、setup-uvがダウンロードし直せば済むものを整理してしまうからです。npmのほうは400MB近くあります。時間がかかっているのはテストで、テストはすでに4並列で走っています。実行を速くしたいなら、キャッシュではなくテストスイートに手を入れます。

ブログは正反対です。Hugoが処理した画像はgitignoreされたresources/_genにあるので、新しいランナーのたびにカバー、本文の画像、プレースホルダーを全部エンコードし直していました。後で載せるワークフローはactions/cacheでこれを復元します。キーは画像そのもののハッシュで、合わなければいちばん新しい古いキャッシュで代用します。Hugoは足りない分しか処理しないからです。キャッシュ導入前の最後の8回では、ビルドのステップに33〜76秒かかっていました。導入後の26回は6〜20秒で、例外は94秒の一回だけ。しかも同じコミットでプレースホルダーと二つ目のカードサイズを追加したうえでの数字です。

アプリのイメージはFlyのビルダーでビルドされ、依存関係のファイルをコードより先にコピーし、uvのダウンロードキャッシュはBuildKitのキャッシュマウント（RUN --mount=type=cache,target=/root/.cache/uv）に置いています。ただ、もっと大きな改善はキャッシュではありませんでした。以前の.dockerignoreはブロックリストで、追加のgit worktreeを置いたフォルダーを漏らしていました。それぞれが自分の依存関係とビルド成果物を抱えています。そのせいで27万7千ファイル、7.7GBが、デプロイのたびにビルダーへ送られていました。許可リストに書き直したいま、ビルドコンテキストは40MBほどです。パターンの例はこうです。

# Exclude everything, then let back in only what the Dockerfile COPYs.
*

!pyproject.toml
!uv.lock
!manage.py
!myapp
!static

# Rules match the whole relative path and the last match wins,
# so these re-excludes apply inside the allowed directories too.
**/__pycache__/
**/*.pyc
**/.DS_Store
**/*.log

シークレットはできるだけ少ない場所に

#

シークレットは三か所にあります。GitHub Actionsのシークレットはワークフローがすることのためのもので、二つのHugoリポジトリにはそれぞれCLOUDFLARE_API_TOKENが一つあるだけです。Flyのシークレットはアプリの実行時設定で、flyctl secrets setで入れ、Actionsを経由することはありません。そしてノートPCのgitignoreされた.envに、デプロイスクリプトがCloudflareのキャッシュを消すときに使うトークンがあります。

PyPIにはシークレットがそもそも要りません。pyhtml2textはトラステッドパブリッシングを使っています。GitHubがワークフローに発行する短命のOIDCトークンをPyPIが受け付けるので、リリースのジョブはid-token: writeを求めるだけで、リポジトリのシークレットのページは空です。漏れるものも、ローテーションするものもありません。

トークンには必要な分だけを与えます。GitHubにあるアプリのFlyトークンは、マシンの一覧を取るだけの定期チェック用なので、fly tokens create readonlyで作っています。Pagesのデプロイが求めるのはcontents: readとdeployments: writeだけで、それ以上はありません。

入力は直接スクリプトに入れず、必ずenv:を通します。OTAのワークフローは自由記述のリリースノートを受け取ります。これをrun:の中に${{ inputs.notes }}と書くと、bashが読む前にテキストがスクリプトにそのまま貼り込まれるので、引用符とセミコロンを含むノートはコードになってしまいます。環境変数として渡せば、データのままです。パターンの例です。

      - name: Publish
        env:
          OTA_API_TOKEN: ${{ secrets.OTA_API_TOKEN }}
          INPUT_PLATFORM: ${{ inputs.platform }}
          INPUT_ROLLOUT: ${{ inputs.rollout }}
          INPUT_NOTES: ${{ inputs.notes }}
        run: |
          args=("$INPUT_PLATFORM")
          [ -n "$INPUT_ROLLOUT" ] && args+=(--rollout "$INPUT_ROLLOUT")
          [ -n "$INPUT_NOTES" ] && args+=(--notes "$INPUT_NOTES")
          ./scripts/publish-ota.sh "${args[@]}"

GitHubの外に置いたままのキーもあります。ある定期レポートには、アプリのサインイン基盤に対する管理者権限を持つキーが必要です。なのでそのレポートは定期ワークフローから、Mac上の定期ジョブに移しました。ワークフローは手動の予備として残してあり、そのキーが要るセクションを除いて投稿します。

デプロイ：pushごとに、スクリプトで、タグで

#

Hugoサイトはpushのたびにデプロイ

#

ブログのワークフローを例にしたものです。初回だけPagesのプロジェクトを作るステップは省いています。

name: Deploy to Cloudflare Pages

on:
  push:
  workflow_dispatch:

env:
  HUGO_VERSION: "0.165.0"
  PAGES_PROJECT: my-site

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v7
        with:
          submodules: true

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      # Processed images are gitignored; restore them so Hugo only
      # re-encodes what is new. An older cache still helps.
      - uses: actions/cache@v6
        with:
          path: resources/_gen
          key: hugo-resources-${{ hashFiles('content/**/*.jpg', 'content/**/*.png', 'assets/img/**') }}
          restore-keys: |
            hugo-resources-

      # A multilingual site has no root 404.html; without one, Pages
      # answers unknown paths with index.html and a 200.
      - name: Build
        run: |
          hugo --gc
          cp public/en/404.html public/404.html

      # ...

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy public --project-name=${{ env.PAGES_PROJECT }} --branch=${{ github.ref_name }}

--branch=${{ github.ref_name }}によってmainが本番になり、ほかのブランチはどれもプレビューURLを得ます。クライアントのサイトのワークフローはこれと同じ形で、ビルドの前にrm -rf publicが一行加わっています。あちらはpublic/がコミットされているので、そうしないと削除したページがアップロードに残り続けるからです。

Hugoのバージョンはここでだけ固定しています。10月にパッケージマネージャーのアップグレードでノートPCのHugoが0.168に上がりましたが、これはテーマが対応する最新版より一つ新しいものです。デプロイは0.165のままで、何も起きませんでした。

そして、ビルドそのものがテストです。9月14日、あるブランチのプレビューデプロイが3回続けて失敗しました。そのブランチの記事が、Hugoのrefでまだ下書きの記事を指していたのです。CIは本番と同じように下書きを除いてビルドするので、リンク先は存在せず、HugoはREF_NOT_FOUNDで止まりました。その間もmainは普通にデプロイされ続けていました。

アプリのAPIはスクリプトでデプロイ

#

デプロイスクリプトの中心部分を例にしたものです。

IMAGE_LABEL="deploy-$(git rev-parse --short HEAD)-$(date +%Y%m%d%H%M%S)"

# Build first, then wake a spare machine, then roll out exactly that image.
flyctl deploy --config fly.toml --build-only --push --image-label "$IMAGE_LABEL"
curl -fsS --retry 5 https://myapp.fly.dev/health > /dev/null
flyctl deploy --config fly.toml --image "registry.fly.io/myapp:$IMAGE_LABEL"

そしてfly.tomlの対応する部分です。

[deploy]
  # max_unavailable only counts machines that are running,
  # which is why the script wakes one first.
  strategy = "rolling"
  max_unavailable = 1

イメージは一度だけビルドし、コミットと時刻からなるラベルを付けてFlyのレジストリに送り、そのラベルでデプロイします。なので、ロールアウトされるのはビルドしたものそのものです。

ゼロダウンタイムを実現しているのは、先に予備のマシンを起こしておくことです。max_unavailable = 1が数えるのは動いているマシンだけですが、アプリは暇なときに動いているマシンを一台も置きません（サスペンドしたマシンは1秒ほどで復帰します）。そのため、起きていた一台が寝ているマシンと同じバッチで置き換えられ、後ろに温まったマシンが一台もない、ということが起きていました。9月28日にオリジンへプローブを送り続けて測ったところ、素のflyctl deployではタイムアウトが7回と7.3秒の空白があり、先にビルドしてロールアウト開始時にはマシンを一台起こしておくスクリプトのデプロイでは、2,514リクエストで失敗はゼロでした。

スクリプトの残りは、エラーの通知が届くチームのチャットチャンネルにデプロイの印を残します。エラーが固まって出たとき、直前に何が変わったかと照らし合わせられるようにです。それからCloudflareのキャッシュを消し、マシンを温めておきます。Webフロントエンドはイメージをまったく通りません。それはフロントエンドとバックエンドを別々にデプロイするに書きました。

マイグレーションはパイプラインのステップではありません。Flyのrelease_commandが私の環境では固まってしまったので、新しいイメージで最初に起動したマシンがロックを取ってマイグレーションし、ほかのマシンは待ちます。そのため、どのマイグレーションもまだ動いているコードと両立しなければなりません。カラムはあるデプロイで追加し、次のデプロイで使うのをやめ、三回目のデプロイで削除します。

このスクリプトに、私のノートPCでなければならない部分は特にありません。ただ、ノートPCにしかないファイルがいくつかあって、それが縛りになっています。Cloudflareの認証情報と、最後に何をデプロイしたかの記録で、まっさらなランナーにはこれがありません。コミットしていない変更もデプロイしてしまい、チャットでそう知らせますが、Webのリリース用スクリプトは汚れた作業ツリーを拒否します。

ブランチごとのプレビュー環境で私は、これを手でやるのは自分一人なら構わないが、二人目の開発者からはgitで何かが起きたから起きるようにしなければならない、と書きました。アプリの開発者はまだ一人です。あの記事のブランチ環境のワークフローは、作ったときのブランチにそのまま置いてあります。

OTAのワークフローは手動専用です。公開は判断であるべきですし、アップデートのサービスは部分ロールアウトが開いている間は新しいリリースを拒むので、pushトリガーではカナリアのたびに引っかかってしまいます。このワークフローは一度も実行されたことがありません。これまでのOTAアップデートはすべてノートPCから、ワークフローが呼ぶのと同じスクリプトで出しています。薄いワークフローにする理由は一言でこれです。リリースをどう始めても、同じスクリプトです。

pyhtml2textはタグでリリース

#

リリースのジョブです。パッケージ名は一般的なものにしてあります。

  release:
    runs-on: ubuntu-latest
    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
    needs: [linux, macos, windows, sdist]
    environment:
      name: pypi
      url: https://pypi.org/p/mypackage
    permissions:
      id-token: write       # trusted publishing and signing
      contents: write
      attestations: write
    steps:
      - uses: actions/download-artifact@v8
      - uses: actions/attest@v4
        with:
          subject-path: 'wheels-*/*'
      - uses: astral-sh/setup-uv@v10
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        with:
          prune-cache: true
      - name: Publish to PyPI
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        run: uv publish --trusted-publishing always 'wheels-*/*'

リリースのジョブはすべてのビルドジョブを待ち、実際に公開するのはタグのときだけです。手動実行はビルドとアテステーションまではしますが、何もアップロードしません。actions/attestはどのワークフローが各wheelをビルドしたかを記録し、uv publish --trusted-publishing alwaysはパスワードの代わりにOIDCトークンでアップロードします。パッケージそのものについては閉じられたプルリクエスト、フォーク、そしてPyPIパッケージに書きました。

定期ワークフローはベストエフォート

#

アプリには定期ワークフローが一つあります。Flyがベースラインより多くのマシンを起動していないかを見るチェックで、放っておけば請求書で初めて気づくことです。通知はわざと失敗することで行います。定期実行が失敗すると、GitHubが所有者にメールを送るからです。

設定はcron: '*/15 * * * *'、1日96回です。ところがこの2週間は1日3〜8回しか動いておらず、実行間隔の中央値は3時間40分ほどでした。GitHubのドキュメントが挙げる理由は負荷だけです。Actionsが混んでいると定期実行は遅れることがあり、混み具合によっては落とされることもある、と。持続的なスケールアウトを見るなら数時間で十分です。数分以内に鳴らなければならないものにとって、GitHubのcronは監視ではありません。

パイプラインに投げかけたい質問

#

これから作る人も、すでにあるものを見直している人も：

1. GitHub Actionsが丸一日止まったら、それでもリリースできますか？ できないなら、リリースのロジックがYAMLの中にあるということで、2024年の記事がまだ当てはまります。
2. CIは本番と同じインタープリタ、同じCPUアーキテクチャ、同じデータベースのメジャーバージョンで動いていますか？ 私のCIがコンパイラのバグを捕まえられたのは、ランナーと本番がどちらもx86_64で、ノートPCがそうではなかったからです。
3. まっさらなチェックアウトで通りますか？ 通らないとしたら、たいていは生成されてgitignoreされたファイルのせいです。
4. 実行時間は実際どこに使われていますか？ キャッシュを足す前に、ステップの所要時間を読んでください。
5. シークレットはそれぞれ何か所にありますか？ そして本当にGitHubに置く必要がありますか？

私の作業環境は、同じ場所にそろうことがほとんどない三台のマシンでできています。一台目は MacBook Air で、私の行くところにはどこへでもついてきます。二台目はオフィスにある devbox という名前のワークステーションで、ちゃんとした GPU を積んでいて、Ollama、ファインチューニング用のツール、専用のコンテナレジストリを持つ小さな Kubernetes クラスタ、そして長いジョブをこつこつ処理させたまま置いてきたエージェントが動いています。三台目はスマホです。私が作ったアプリが実際に使われるのはここで、一日の大半を wifi ではなくモバイルデータで過ごしています。

長いあいだ、この三台はまともに会話できていませんでした。ラップトップから devbox に届くのはオフィスの LAN にいるときだけ。スマホからラップトップの dev サーバーに届くのは両方が同じ wifi にいるときだけで、しかも 0.0.0.0 にバインドするのを忘れず、その朝 DHCP が Mac に割り当てたアドレスを打ち込んだ場合に限られました。ワークステーション上の面白いものはすべて、Ollama の API も、クラスタのダッシュボードも、トレースも、レジストリも、localhost かクラスタのネットワークにバインドしてありました。わざとです。どれもインターネットに置くべきものではないからです。

この記事は、Cloudflare WARP と二本の Cloudflare Tunnel でこれらをつなげた方法と、それで AI 機能やモバイルアプリの作り方がどう変わったか、そして何も言わずに壊れたいくつかのことについて書いたものです。

本当に欲しかったもの

#

要件として書き出すと短いです。

1. ラップトップはシンクライアントにする。GPU や大量の RAM、何時間もの実行時間が必要なものはすべて devbox で動かし、ラップトップからはオフィスでも自宅でもカフェでも同じ方法で届くようにする。
2. スマホからは、どこにいても、モバイルデータでも、dev サーバーとシェルに届くようにする。いちいちオンオフを覚えておかなければならない VPN は使わない。
3. システムの振る舞いを見るためのもの、つまりダッシュボード、トレース、docker info、モデル一覧は、私だけが見られて、ほかの誰にも見られないようにし、公開 URL は決して付けない。
4. インバウンドのポートは開けない。オフィスのルーターにも、自宅のルーターにも、どこにも。

四つ目で、昔ながらの答えであるポートフォワードとダイナミック DNS は候補から外れます。凝った手の多くも外れます。devbox もラップトップも自分では管理できない NAT の内側にいて、ラップトップにいたっては数時間ごとに違う NAT の内側にいるからです。

以前: SSH トンネルのリポジトリ

#

最初の版は自分用の小さなリポジトリで、今もこれが土台の層です。解決するのは、ラップトップ上で「SSH 越しに届くものにきれいな名前を付ける」という問題だけです。dnsmasq が *.test に 127.0.0.1 を返し、Caddy がホスト名でローカルのポートへ振り分けつつ tls internal でブラウザを満足させ、autossh の launch agent 群が SSH のフォワードを開いたまま保ち、切れたらつなぎ直します。ホスト名を見ればそれがどこにあるかが分かります。

つまり https://devbox-ollama.ssh.test/api/tags はワークステーション上のモデル一覧を返し、https://api.local.test は自分のマシン上で動いている、開発中のアプリの API です。

.ssh や .cloud のような新しいトップレベル名ではなく .test のサブドメインにしていて、.local も使いません。RFC 6761 はまさにこの用途のために .test を予約していて、.local は mDNS のものです。.local を乗っ取ると Mac で Bonjour の検出が動かなくなります。dnsmasq はもともと *.test 全体をワイルドカードで受けているので、ラベルがひとつ増えても何の負担もありません。127.0.0.1 を指す /etc/resolver/test ファイルがひとつあれば、その後 DNS の変更は一切不要です。

存在しない名前で HTTPS

#

これらの名前はすべて、ブラウザが信頼する証明書付きの HTTPS で配信しています。私のラップトップの中にしか存在しないホスト名でそれは無理そうに聞こえますが、Caddy は自前の内部認証局でこれをやってのけます。サイトに tls internal と書くと、Caddy は Let’s Encrypt に頼む代わりにローカルの CA からそのサイトの証明書を発行します。インストーラーが一度だけ実行する caddy trust が、その CA のルートを macOS のシステムキーチェーン(Chrome と Safari はここを読みます)と Firefox 独自のストアに入れます。それ以降は https://anything.test は証明書の警告なしに開き、素の http:// はそちらへリダイレクトされ、マシンの外には何も出ていきません。

見た目だけの話ではありません。今の Web プラットフォームは、素の HTTP では動かないものがたくさんあります。secure cookie、service worker、クリップボード API、SameSite=None が絡むものすべて。Web ビルドを素の http://localhost でテストすると、本番の HTTPS ドメインで出るバグが隠れてしまいます。https://app.local.test でテストすれば、それが自分のラップトップの上で表に出てきます。

サイトブロックはこうです。ポート以外はどのサービスでも同じです。

devbox-ollama.ssh.test, devbox-ollama.test {
	tls internal
	import cors
	reverse_proxy 127.0.0.1:11435 {
		import proxyhdr
		transport http {
			keepalive off
			dial_timeout 5s
		}
	}
}

面倒な部分は二つのスニペットが受け持っています。cors は * を返す代わりに呼び出し元の Origin をそのまま返します。認証情報が絡むと * は許されないからです。そして OPTIONS のプリフライトには自分で 204 を返すので、上流が相手をする必要はありません。proxyhdr は Host ヘッダーを接続先のアドレスに書き換えます。ルーターの管理画面や Chrome のリモートデバッグ用エンドポイントのような気難しいバックエンドは Host を検証するので、書き換えなければ devbox-ollama.ssh.test を聞いたこともない名前として弾いてしまいます。Ollama 自身のオリジンチェックはどのポートでもループバックなら通すので、Host を 127.0.0.1:11435 に書き換えれば通ります。

keepalive off は、私なら間違えていたはずの設定です。上流はどれも SSH のフォワードで、ネットワークが変わるたびに autossh が壊して作り直します。keep-alive がオンだと、Caddy はとっくに死んだトンネルへのプール済みコネクションを握り続け、リロードするまで訳の分からない 404 を返します。オフにすればリクエストごとに新しく接続し、ループバックならそのコストは測れないほど小さいです。

各サービスは昔のフラットな名前(devbox-ollama.test)でも応答するので、サフィックスの仕組みを入れる前のブックマークもそのまま使えます。

メニューバー

#

launchd が十数本のフォワードを開いたまま保っていると、私が繰り返し気にするのは「これ、生きてる?」ということでした。その答えは launchctl list、lsof、curl の三か所に散らばっていました。そこで小さなメニューバーのプラグインでひとつにまとめ、すべてのホスト名の横に色付きの丸を出すようにしました。

• 🟢 トンネル経由でサービスがリクエストに応答した
• 🟡 トンネルは開いているが、その先のサービスが黙っている
• 🔴 ローカルのポートで何も待ち受けていない、つまりトンネル自体が落ちている

役に立つのは黄色です。緑と赤だけのチェックでは「SSH のフォワードが死んだ」と「向こう側で Ollama が落ちた」を区別できず、この二つは直し方がまったく違います。プラグインはサービスの一覧を自分では持たず、ほかと同じプロキシと SSH の設定を読むので、そこにサービスを足せばメニューにも足されます。

最初の版は欲張りすぎでした。十秒ごとに更新し、サービスごとにいくつもプロセスを起こしていたので、一回の実行で七十個ほどになり、macOS はすぐにこのプラグインを「エネルギー消費の大きいアプリ」に並べました。実行ごとにスナップショットを一回だけ取り、更新を数分おきにしたところ、コア一つの 0.1% ほどに収まりました。バッテリーを食う状態表示では本末転倒なので、最初からコストを見積もっておく価値があります。

穴がひとつあって、それがいちばん肝心なところでした。devbox には公開された名前がありません。その SSH フォワードは 192.168.x のアドレスに接続していたので、ラップトップがオフィスの LAN にいるあいだしか動きませんでした。オフィスを離れるとメニューバーは赤くなって赤いままで、ラップトップを楽にするためにワークステーションへ移したものすべてに、まさにその隣に座っていないときに限って届かなかったのです。

正しい向きの二本のトンネル

#

解決策は三つの部分からなり、最初の二つが Cloudflare Tunnel です。

Cloudflare Tunnel とは、cloudflared が Cloudflare のエッジへのアウトバウンド接続を保ち続けるものです。Cloudflare はその接続を通してリクエストを送り返してくるので、何重の NAT の内側にあるマシンでも、ルーターで何かを待ち受けさせることなく到達できるようになります。ホテルの wifi に移ったラップトップにもついていき、CGNAT も乗り越えます。

私は二本、マシンごとに一本ずつ動かしていて、その理由は一言書いておく価値があります。手っ取り早いのは、ラップトップに一本だけトンネルを置いて、オフィス LAN 上の devbox の SSH ポートを指す ingress ルールをひとつ足すことでした。これなら devbox には何もインストールしなくて済みます。ただしラップトップを経由することになり、オフィスから出ていくのはそのラップトップです。解決するために作ったはずのまさにその状況で壊れていたでしょう。devbox は動かないので、devbox が自分でエッジへの接続を持ちます。

# config.yml on devbox (runs as a systemd service)
protocol: auto        # prefer QUIC, fall back to HTTP/2 over TCP 443
ha-connections: 4     # mains-powered, its job is to stay reachable

warp-routing:
  connectTimeout: 5s

ingress:
  - hostname: ssh-devbox.example.com
    service: tcp://127.0.0.1:22
  - service: http_status:404

ssh:// ではなく tcp:// にするのは、間違えやすいところです。ssh:// を選ぶと Cloudflare のブラウザ上で描画するターミナルになり、ストリームは Web ページ用に包まれます。そこに普通の ssh クライアントを通すと、バナーまでは届いて、鍵交換で死にます。tcp:// は cloudflared access ssh が期待する素のバイトの土管で、おまけに scp、rsync、SSH 越しの git、ポートフォワードも通ります。

この最後の点が、SSH の層の穴を塞ぎました。SSH の設定は今、接続ごとに経路を選びます。

Match originalhost devbox !exec "nc -z -G 1 <office-lan-ip> 22 >/dev/null 2>&1"
    ProxyCommand cloudflared access ssh --hostname ssh-devbox.example.com ...

オフィスの LAN にいれば確認が成功し、SSH は直接、1 ホップで接続します。それ以外の場所では確認が失敗し、SSH は Cloudflare を経由します。認証には Access のサービストークンを使うので、ブラウザでのログインが割り込むこともありません。Match host ではなく Match originalhost です。host は HostName が置き換えられた後にマッチするので、その時点で名前はもう IP になっていて、ブロックが発動しません。結果として、devbox-ollama.ssh.test はオフィスでも自宅でも電車の中でも動き、メニューバーの丸は緑のままです。

ラップトップのトンネルは逆向きです。Mac 上の dev サーバーに本物の公開 HTTPS ホスト名を与えます。開発中のアプリそれぞれについて、その API、WebSocket サーバー、Web ビルドです。どれも Cloudflare Access の背後にいます。これについては後で戻ってきます。ここが、この仕組みを無謀ではなく安全なものにしている部分だからです。

メニューバーも両方のトンネルを把握するようになりましたが、確認の問い合わせではそれができませんでした。インバウンドのトンネルには確認すべきローカルのポートがなく、二つのコネクタの片方はそもそもラップトップで動いていません。すぐ思いつくテスト、ssh-devbox.example.com に curl することは、コネクタがつながっていてもいなくても Cloudflare のエッジから応答が返るので、死んだトンネルでも緑と読んでしまいます。launchd もあてになりません。cloudflared はエッジへの接続をすべて失っていても「loaded, exit 0」のまま居座ります。そこでトンネルについては、それぞれに健全なコネクタがあるかを Cloudflare の API に尋ねます。ssh がたどり着くかどうかを決めるのはそれだからです。API に届かなければ、その部分は赤で描くのではなく丸ごと表示しません。メニューはひと目で読むものなので、そこでの誤報は一行欠けるよりも高くつきます。

三つ目の部分: WARP でネットワークにする

#

ホスト名付きのトンネルは、HTTPS を話すものと、cloudflared を動かせるマシンからの SSH には最高です。スマホにはそれができません。それにトンネルのホスト名は TCP のエンドポイントではありません。Cloudflare のエッジがそこで終端するのは HTTPS と WebSocket だけなので、ssh.example.com のポート 22 は閉じていて、Access をどういじっても開きません。

そこで WARP の出番です。Cloudflare One Agent(エンタープライズ向けの WARP クライアントです。組織に参加できないコンシューマー向けの「1.1.1.1」アプリではありません)を、ラップトップとスマホで私の Zero Trust 組織に登録しています。各トンネルがプライベートルートを広告し、WARP を動かしているデバイスはそのアドレスに素のソケットを開けば正しいマシンにたどり着けます。「このサービスに名前で届く」ではなく、「これらのマシンが私と同じネットワークにいる」になるわけです。

これらのアドレスは各マシンのループバックのエイリアスで、起動時に作られます。なので DHCP にも、どのルーターの内側にいるかにも左右されません。198.18.42.2 は、オフィスでも、自宅からでも、5G のスマホからでも devbox です。Mac の本当の LAN アドレスは移動するたびに変わりますが、こちらは決して変わりません。

スプリットトンネルは include モード にしていて、中身はこれらのルート(と、WARP 自身が必要とする Cloudflare の範囲)だけです。これがクライアントを常用できるものにしています。デフォルトは exclude モードで、WARP はプライベートな範囲のリスト以外のすべてを運ぶので、スマホが送るすべてのバイトが Cloudflare を回り道します。これにはバッテリーとレイテンシに実際のコストがあって、必要なときだけオンにするようになっていたはずで、それでは意味がありません。include モードなら、三台のマシン宛ての通信は WARP を通り、それ以外はいつもの経路で手つかずのまま出ていきます。だからクライアントはつけっぱなしです。ラップトップの warp-cli status は一日中 Connected と言っていて、私はそのことを考えもしません。

トランスポートは、UDP 2408 の WireGuard ではなく、UDP 443 上の HTTP/3 で HTTP/2 へのフォールバックを持つ MASQUE にしています。キャリアやゲストネットワークの中には 2408 を塞ぐところがありますが、443 を塞ぐところはまずありません。私の組織のポリシーでは MASQUE の耐量子鍵合意もオンになっています。探しに行ったわけではありませんが、断る理由もありません。

なぜ 198.18 なのか、なぜ IPv6 アドレスがあるのか

#

このアドレスは妙に見えますし、最初に選んだアドレスは、学ぶところのある形で間違っていました。

最初に試したのは 10.10.0.1 でした。誰でもまずそれに手を伸ばすからです。これはスプリットトンネルのどちらのモードでも失敗します。exclude モードでは、WARP のデフォルトのリストが RFC 1918 の範囲すべてと 100.64.0.0/10 を除外するので、クライアントはその宛先への通信をデバイスから出る前に捨ててしまいます。include モードでは、たまたま参加した本物の 10.x ネットワークとぶつかります。カフェもコワーキングスペースも、多くのオフィスも、まさにその範囲を使っています。198.18.0.0/15 は RFC 2544 のベンチマーク用の範囲です。予約済みで、公開インターネットでルーティングされることはなく、WARP の除外リストにも入っておらず、普通のネットワークでは使われていません。IPv6 のアドレスが ULA(fd00::/8)なのも同じ理由です。

そもそもなぜ IPv6 があるのか、のほうが面白い話です。v4 のアドレスが動くようになったあと、wifi につないだスマホから試して問題なかったので、完了にしました。5G では動きませんでした。Agent は connected と言っていて、トンネルは健全で、Access も問題なし。wifi でのテストがそのすべてを証明していました。問題は、今のモバイルネットワークはほとんどが IPv6 オンリーだということでした。スマホにはネイティブの IPv4 がまったくなく、v4 のリテラルにはキャリアの 464XLAT トランスレーター経由で届いていました。include リストに v4 のプレフィックスしかないと、このトランスレーターはトンネルの 外側 にいます。通信は公開インターネットに出ていき、そこでは 198.18.0.0/15 はルーティングされないので、音もなく捨てられていました。スマホにはエラーもなく、コネクタのログにも何もありません。

解決策は、スマホが IPv6 でネイティブに届く二つ目のアドレスをすべてのマシンに持たせ、それをルートと include リストの両方に足すことです。今では、モバイルデータのときにスマホの SSH クライアントが実際に使っているのは fd12:3456:789a:: のアドレスのほうです。

オフロード: 端末としてのラップトップ

#

この仕組み全体は、この部分のためにあります。

モデルとファインチューニング。 Ollama は devbox 上で動き、127.0.0.1:11434 にバインドしています。オフィス LAN のほかのマシンからも見えませんし、インターネットからなど言うまでもありません。ラップトップ上では https://devbox-ollama.ssh.test として、あるいはポートそのものを欲しがるツール向けには素のポートとして現れます。

OLLAMA_HOST=127.0.0.1:11435 ollama list

11434 ではなく 11435 なのはわざとです。11434 は Ollama 自身のデフォルトで、もしラップトップでもローカルの Ollama を動かすことがあれば、二つがポートを奪い合い、どちらが先に起動したかによって「ローカル」のはずのものから devbox の答えが黙って返ってくることになります。

実際の効果として、AI 機能を作っているとき、呼び出すモデルはどこにいてもラップトップではなくワークステーションの GPU で動きます。評価の実行、大量のドキュメントの埋め込み、ファインチューニング。これらは devbox で動き、ラップトップのファンは回らないままです。エージェントを試作しているときは、ワークステーション上のローカルモデルを指して、API の請求を気にせずツール呼び出しを何度でも繰り返し、ループが固まってからホスト型のモデルに切り替えられます。

長時間動くエージェント。 一時間かかるエージェントのセッションが、ラップトップの蓋が開いているかどうかに左右されるべきではありません。代わりに devbox で動かせば、ラップトップはそれを覗く窓にすぎません。蓋を閉じて、あとでどこからでも、あるいはスマホからでも ssh devbox すれば、まだそこにいます。トンネル以前はこれがオフィスでしか使えませんでした。まさに必要のない場所です。

ビルドとクラスタ。 devbox のクラスタは専用のレジストリを持っているので、イメージはラップトップからホテルの wifi でアップロードするのではなく、ワークステーション上で、それが動く場所のすぐ隣でビルドして push できます。クラスタのダッシュボード、ingress のダッシュボード、レジストリの UI は、どれもラップトップ上では *.ssh.test のホスト名です。

モバイルの開発ループ。 スマホはラップトップと同じプライベートネットワークにいて、ラップトップの dev サーバーには Access の背後の公開ホスト名もあります。なのでアプリのネイティブビルドを建物の外へ持ち出して、5G で、自分の机で動いている API と話させることができます。あるいは devbox 上のほうと話させることも、そちらに置いてきたのなら。実機で本物のモバイルネットワーク越しに回すフィードバックループは、以前は共有のステージングサーバーへのデプロイを意味していました。今はファイルを保存することを意味します。

ここにはひとつ、アプリのバグとしてデバッグし始める前に知っておく価値のある罠があります。Access は WebSocket のホスト名も守っていて、ネイティブの WebSocket クライアントはブラウザではありません。CF_Authorization の cookie を持っていないので、ネイティブビルドから WebSocket サーバーへの接続はエッジで 403 で拒否され、その 403 は自分のサーバーのエラーとは似ても似つきません。ブラウザのタブは、ログインしたときの cookie をすでに持っているので問題ありません。ブラウザ以外のもの(ネイティブアプリ、スクリプト、dev API を呼ぶエージェント)への答えは Access の サービストークン で、二つのヘッダーとして送ります。

CF-Access-Client-Id:     <client_id>
CF-Access-Client-Secret: <client_secret>

トークンはそれ自体では何の権限も与えません。Access がそれを受け入れるのは、ポリシーでそのトークンを指名しているアプリだけなので、届く範囲はちょうど dev ホスト名の一覧で、それより広くはありません。私はそのポリシーを allow ではなく non_identity の判定に分類しています。こうすると監査ログの中で、ログインした人ではなくベアラーシークレットとして見分けがつきます。

インターネットが決して見ない統計

#

欲しかったもののもう半分は、可視性でした。システムの振る舞いを教えてくれるものの大半は、正しく、公開されていません。devbox では次のものです。

• ingress プロキシのダッシュボードと、そのトレースが入ったトレーシング UI
• Kubernetes クラスタ用のダッシュボード
• コンテナレジストリの UI(読み取り専用)
• Ollama のモデル一覧と、今ロードされているもの
• docker info とコンテナの統計

どれにも公開ホスト名はなく、これからも付けることはありません。ループバックかクラスタのサービス IP にバインドされていて、届くのは SSH のフォワード経由で、そのフォワード自体がトンネルに乗っています。スマホの監視アプリは、WARP をまたいだ SSH で docker info --format '{{json .}}' を読むので、コンテナが動いているか、何かがメモリを食い尽くしていないかを、どこからでも確認できます。

このアプリのおかげで、書いておく価値のある小さなバグを見つけました。Mac のトンネル用 sshd が、デバッグしていたときのまま LogLevel DEBUG2 になっていました。-e を付けると sshd は stderr にログを出し、セッションにとってその stderr は SSH チャネルの stderr そのもの です。すべてのコマンドの出力に debug2: do_setup_env: set TMPDIR がくっついて返ってきて、二つのストリームをまとめるスマホのアプリは、正しい JSON の後ろにログの行が続いたものを受け取り、パースに失敗して、全体をエラーとして表示していました。LogLevel INFO で直りました。デバッグが終わったらログレベルは戻しましょう。

同じくらい意図的なのが、このネットワークに 載せない ものです。昔の autossh トンネルは、私が面倒を見るのを手伝っている、よそのネットワークのルーターにもいくつか届きます。それらには公開ホスト名も WARP のルートも与えません。インターネット上のルーター管理画面は、ログインの背後にあってもリスクですし、私が広げてよいネットワークでもありません。

Access は省略できない

#

Cloudflare Tunnel のホスト名は、DNS レコードができた瞬間に公開インターネット上に存在します。その前にファイアウォールはありません。それこそがポートを開けないことの要点です。守りは Cloudflare のエッジから来なければならず、それをするのが Access です。訪問者が誰であるかを証明するまで、リクエストを転送すること自体を拒否するので、認証されていないスキャナーがラップトップに届くことはありません。これは重要です。相手は dev サーバーだからです。設定が載ったデバッグモードのトレースバック、開きっぱなしの JavaScript バンドラー。これらのホスト名の背後にあるものは、どれもインターネットに面するように作られていません。

ポリシーは私自身のメールアドレスだけを許可し、ほかは何も許可しません。証明の手段は、メールでのワンタイム PIN とシングルサインオンの二つです。セッションは八時間です。現実的な脅威は、誰かが PIN を総当たりすることではなく、一日有効な cookie を持ったままカフェで開きっぱなしにしたラップトップだからです。

SSH は、お互いを知らない二つの仕組みによって二重に認証されます。Access は TCP のストリームが sshd に届いてよいかどうかを決め、sshd はそれでも私の鍵を要求します。どちらかを失っても、マシンは開きません。Mac のトンネル用 sshd は Cloudflare の SSH CA も信頼しているので、Access は SSO のセッションから発行した短命の証明書で私をログインさせられます。一方で authorized_keys もそれと並んで使えるままなので、Access の設定が壊れても自分のラップトップから締め出されることはありません。

いちばん気に入っているのは小さな部品です。公開は三つのことがそろったときに起きます。DNS レコード、動いているコネクタ、アクティブなゾーン。この三つは別々のタイミングで、私が制御できない順番で成り立ちます。ゾーンはネームサーバーを変えてからしばらくして勝手にアクティブになります。Mac がスリープしているあいだかもしれません。そこで launch agent は cloudflared を直接動かしません。代わりにプリフライトを動かし、トンネル自身の設定からホスト名を読み取り、Access の API にどれが保護されているかを尋ね、保護されていないものがひとつでもあれば起動を拒否します。

HOSTNAMES=$(grep -E '^\s*-\s*hostname:' "$CONFIG" | sed -E 's/.*hostname:\s*//' | sort -u)
PROTECTED=$(curl -fsS -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/apps?per_page=100" \
    | python3 -c 'import sys,json; print("\n".join(a.get("domain","") for a in json.load(sys.stdin)["result"]))') \
    || { echo "could not reach the Access API. refusing (fail closed)."; exit 1; }

for h in $HOSTNAMES; do
    grep -qxF "$h" <<<"$PROTECTED" || { echo "NOT starting: $h has no Access app"; exit 1; }
done
exec cloudflared tunnel --config "$CONFIG" run

launch agent には KeepAlive が付いているので、拒否されると 30 秒ごとに自分で再試行し、Access のアプリができればトンネルは勝手に上がります。フェイルクローズの代償は停止です。フェイルオープンの代償は露出です。どちらを説明するほうがましか、私は分かっています。

つまずいた四つのこと

#

ここまでに書いたことは、今はすべて動いています。そこにたどり着くまでに、四つのうち三つは同じパターンでした。壊れているものはどこにもエラーを出さず、自分に見える部分はすべて健全だと報告していました。

ルートと include リストは別々のリスト。 トンネルのルートは、Cloudflare があるアドレスを正しいコネクタまで運ぶ 気になる ようにするものです。WARP の include リストは、そもそもクライアントがそれを 送る ようにするものです。devbox にスマホから届かなかったのは、ルートは存在していたのに、include リストにはまだ Mac のアドレスしかなかったからです。スマホはパケットをローカルで捨て、コネクタは通信をひとつも見ず、ダッシュボードはすべて緑でした。新しいマシンを足すたびに、そのアドレスを両方に足す必要があります。

IPv6 オンリーのモバイルネットワークでの IPv4 リテラル。 上で書いたとおりです。wifi では動き、5G では失敗し、エラーはなし。WARP のルートが wifi では動いてモバイルデータでは動かず、Agent が connected と表示しているなら、原因はトンネルではなくルーティングです。

cloudflared の背後の macOS の sshd。 macOS は sshd を launchd のソケットアクティベーションで起動し、接続ごとに短命の sshd -i をひとつ立てます。cloudflared の背後だと、バナーはクライアントに届くのに、クライアントの識別文字列が戻る前にストリームが壊され、すべてのログインが kex_exchange_identification で死にます。両端から確認し、素の TCP リレーでも再現したので、Cloudflare は原因から外れました。解決策は、二つ目の独立した sshd -D を 127.0.0.1:2222 と WARP のループバックアドレスで、自分のユーザーとして動かすことです。トンネルのオリジンになるためだけに存在する sshd です。システム設定のリモートログインには手を付けていません。devbox は Linux で、普通の長生きする sshd が動いているので、この問題は一度も起きませんでした。

存在しなくなる設定フィールド。 古い例には、トンネルの設定に warp-routing: enabled: true と書いてあります。cloudflared 2026.8 はこのフィールドをはっきり拒否します。WARP ルーティングは、ブロックが存在し、ルートがトンネルを指していれば常にオンです。少なくともこれはエラーを出してくれたので、ほかの三つのあとでは、ほとんど親切に感じました。

何が変わったか

#

正直にまとめると、ハードウェアがどこにあるかで作業場所を選ぶのをやめました。ラップトップは良いキーボードと良い画面と長いバッテリーで、それ以上である必要はありません。ワークステーションは、私がどこにいても力仕事を引き受けます。スマホは、オフィスの wifi につながれたものではなく、本物のネットワーク上の本物のテスト端末です。そして、システムが何をしているかを見るための部分は、私にとってはクリックひとつの距離にあり、ほかの誰にとっても存在しません。

この規模なら Cloudflare の無料の Zero Trust プランに収まります。かかったのは時間と、書いておいてよかったと思っている README です。上に書いた失敗はどれも、二回目にはまた新鮮な謎になっていたはずだからです。

似たようなことを考えているなら、自分の環境にこう問いかけてみてください。

1. ラップトップで動いているもののうち、ラップトップがいつでも届く唯一のマシンだという理由だけでそこにあるものは何か?
2. スマホから dev サーバーに、オフィスの wifi だけでなくモバイルデータでも届くか? wifi ではなく 5G で試してください。
3. ダッシュボードのうち、外から見るのにそれが楽だったという理由で公開しているものはどれか? どれもプライベートルートに置き換える候補です。
4. 明日、あるトンネルのホスト名が Access のアプリなしで上がってきたら、何がそれを止めるか? 答えが「自分が覚えているはず」なら、プリフライトを書いてください。
5. プライベートアドレスは、訪れる先のネットワークが決して使わない範囲にあるか?

ひとつのアプリを作る小さなチームを思い浮かべてください。開発者は二人でも五人でも構いません。分野ごとの専門家ではなく、それぞれが自分のブランチで、データベースのマイグレーションから API を経てモバイルアプリの画面まで、機能をひとつ端から端まで受け持つ人たちです。チームの回し方としては良いやり方で、二人目の開発者が加わった瞬間から繰り返し起きる失敗がひとつあります。「今ステージング使ってる人いる?」というメッセージです。

そのメッセージの裏には、機能を作り終えてテスターやデザイナーに見せたいのに見せられない開発者がいます。ステージングには二人目の開発者のブランチが載っていて、dev には三人目のブランチが載っていて、そちらは二日前にログインを壊してから再デプロイされていません。数人、共有環境が二つ、そしてスケジュール調整を引き受けているチャットのスレッド。

これは人の問題ではありません。トポロジーの問題です。全員が環境を「自分のブランチが本物になる場所」として扱っているので、環境がマージのやるべき仕事をブランチひとつずつ順番に肩代わりし、残りの全員が列に並んでいるのです。

自分のスタックの本番の形は My Current Stack に書きました。Fly.io の最安マシン上の Django、コネクションプーラーの背後の Postgres、キャッシュと Channels レイヤー用の Redis、別立ての WebSocket アプリ、バックグラウンドワーカー、ファイル用の S3 互換バケット、ホスティング型の認証プロバイダー、前段の Cloudflare、そしてそれら全部と話すモバイルアプリです。この記事は、そのスタックを、どのブランチでも開発者が PR にラベルをひとつ付ければ数分のうちに HTTPS 付きの公開コピーを丸ごと手に入れられるものに変えた話です。他の誰かに頼むことも、誰かが用意してやることもありません。Postgres クラスタも Redis もバケットも、二つ目は用意しません。インフラは共有のままです。変わるのは、共有リソースのすべてが名前で切り分けられるようになることで、その名前はブランチから来ます。ここにチームの規模を前提にしたものはありません。開発者が二人でも二十人でも設計は同じで、増えるのはアプリの一覧だけ、それはスイーパーが面倒を見ます。作って、ブランチを三つ同時に動かして、予想していなかった二か所で壊して、片付けるまでを午後のうちに済ませました。以下の出力はその実行から取ったものです。

共有環境ひとつが開発者一人分より先に伸びない理由

#

共有 dev 環境には前提がひとつ焼き込まれています。全員が見たがる「現在のコードのバージョン」がひとつだという前提です。開発者が一人のとき、あるいはチームが変更の流れをひとつ歩調を合わせて進めているときは正しい。二人目の開発者が別のスケジュールで機能に着手した瞬間に正しくなくなり、端から端までのオーナーシップではそれがすべての機能で起きます。それ以降、環境が抱えるものはすべて取り合いになります。

• デプロイされたコード。 最後にデプロイした人が勝ちます。残りの人の作業は再デプロイするまで見えず、再デプロイすれば前の人のものが消えます。
• データベースのスキーマ。 各開発者が自分の機能のデータモデルを持つとき、いちばん強く噛みつく部分です。最初のブランチがカラムを足す。一時間後にデプロイされた二つ目のブランチはそれを知らず、ORM が insert で失敗し始める。あるいは両方のブランチが 0042_* マイグレーションを持っていて、共有データベースが誰のマイグレーション履歴とも一致しない状態になり、誰かがリセットして、三人目が午後いっぱいかけて用意したテストデータを消す。
• キャッシュ。 あるブランチのシリアライザ変更が、別のブランチのコードが読むのと同じ Redis キーの下にキャッシュされる。そこから出てくるバグ報告は不可解で、一件ごとに午前中がつぶれます。
• サードパーティ連携。 OAuth コールバックがひとつ、Webhook URL がひとつ、プッシュ証明書がひとつ。誰のブランチがデプロイされていようと、そのブランチがイベントを受け取ります。
• テスター。 デプロイされているものしかテストできないので、機能が準備できた順ではなく、環境がたまたま確保された順に一度にひとつずつテストします。

チームは予約システムで応じます。チャットのスレッド、ピン留めメッセージ、/claim staging ボット。それはロックです。作業を見せられる唯一の場所にかかったロックは、デリバリー速度にかかったロックです。開発者二人なら苛立つ程度です。三人なら良い週には耐えられます。四人目が加わるか、機能ひとつがデザイナーとの三日間のやり取りでステージングを握り続ければ、耐えられなくなります。

人が最初に手を伸ばす対処は三つ目の共有環境、「dev2」や「uat」です。数週間は稼げます。列が二車線になっただけです。

本当の対処は、dev もステージングもそもそも環境ではなかったと気づくことです。あれは 誰かのブランチの現在の状態に URL が付いたもの でした。それがそうなら、あるべき数は今チームが気にしているブランチの数で、あるべき寿命はブランチの寿命です。

モデル: ブランチが環境である

#

目標の状態はこうです。

この表の、誰が作り誰が壊すかをもう一度見てください。どれも git のイベントか時計です。git がコントロールプレーンです。存在すべき環境の集合は存在するブランチの集合からそのまま決まり、自動化の仕事は現実をそれに合わせておくことだけです。PR のラベルが作り、その後の push のたびに更新し、PR を閉じるかマージすると壊し、毎晩のジョブが前の三つの取りこぼしを片付けます。すべてのブランチが環境を得るわけでもありません。ラベルがゲートで、開発者のクリックひとつなので、バックアップの push やボットの依存関係更新は費用ゼロです。誰も環境を用意しません。チケットを受けた DevOps エンジニアでも、チャットで呼ぶボットでも、毎回プロンプトを打つ AI エージェントでもありません。十人目の開発者の最初のブランチも、一人目のブランチとまったく同じやり方で、PR にラベルが付いたという理由で環境を得ます。人に頼まなければならないなら、それはスケールしたのではなく、行列の場所が変わっただけです。

そしてこれを成り立たせる規則はひとつです。環境が触れるすべてのリソースは、ブランチにちなんで決定論的に名付ける。 開発者名でもチケット番号でもなく、誰かが開くまで存在しない PR 番号でもありません。ブランチです。開発者が実際に扱うのがブランチだから、そして名前が決定論的なら、同じブランチで ./scripts/env up を二度目に実行したとき、新しい環境を作る代わりに既に作った環境を見つけられるからです。

名前は人のためのスラッグと、一意性のための短いハッシュです。

branch=$(git rev-parse --abbrev-ref HEAD)              # feature/payments-retry
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20)
hash=$(printf '%s' "$branch" | sha256sum | cut -c1-6)
ENV="${slug%-}-${hash}"                                 # feature-payments-retr-3f9a1c

feature-payments-retr-3f9a1c が環境です。この文字列が Fly アプリ名、Postgres データベース名(ハイフンはアンダースコアに)、Redis のキー接頭辞、バケットのオブジェクト接頭辞、エラートラッカーの environment、そしてホスト名の左端のラベルになります。ブランチ名を知っている人なら誰でも計算できます。どこかを引く必要はありません。

その最後の一文が設計です。環境の台帳もコーディネーターもありません。env up、env down、ホスト名をルーティングする Cloudflare Worker、毎晩のスイーパーが、それぞれ独立にブランチから名前を計算し直し、構造的に一致します。特に Cloudflare は何も調整していません。Worker はホスト名から Fly アプリへの純粋関数で、環境が作られたことも消されたことも知りません。アプリがあればリクエストは届き、なければ Fly が自分のエラーで答えます。

ここから三つのことが出てきます。

第一に、「ステージング誰が使ってる」が問いでなくなります。feature-payments-retr-3f9a1c-dev.example.com があり、fix-login-redirect-8b21e0-dev.example.com があり、それぞれそのブランチにいる人のものです。

第二に、ステージングがゴミ捨て場ではなく本番の正直なリハーサルになります。本番に行くまさにそのイメージで、数分前に本番の形のスナップショットから複製したデータベースを相手に組まれます。そこで動けば、本番に残る変数は本番のデータだけです。

第三に、各開発者が共有リソースの root を持たずに力を得ます。ブランチ環境の爆発半径はそのブランチ環境です。四人目の新人が初日に自分のブランチに何をデプロイしようと、最悪の結果は自分のブランチが壊れることです。

fly.io/dashboard/my-org

物理的には共有、論理的には分離

#

「ブランチごとに環境」の魅力的な版は丸ごとコピーです。Postgres クラスタをひとつずつ、Redis をひとつずつ、バケットをひとつずつ。きれいですが、悪い取引です。Fly Postgres クラスタはマシンひとつにボリュームひとつにリストア一回で、Redis はもうひとつのマシン。環境ごとに数分待ち、遊んでいるデータベース十数個分を払うことになります。スイーパーが片付ける種類も一つではなく四つになります。

代わりに、各共有サービスはプレビュー組織全体で一度だけ、小さな本番くらいのサイズで用意し、すべての環境が $ENV をキーにその一切れを受け取ります。壁に貼っておきたい表です。

このうち二つには一言添えておきます。

Postgres: スキーマではなくデータベース。 クラスタひとつを切り分けるもうひとつの方法は、環境ごとにスキーマを持ち、接続ごとに search_path を設定することです。接続の options に -c search_path=... を押し込めば Django もやってくれますが、トランザクションモードのコネクションプーラーは指示しない限り起動時オプションを捨てますし、そうすると結局プール内のすべての接続がひとつの環境に属さなければなりません。「なぜ自分のクエリが違うテーブルに当たるのか」系のバグの温床で、環境ごとにデータベースならそもそも存在しない問題です。データベースは固い境界で、CREATE DATABASE ... TEMPLATE は数秒でひとつ作り、DROP DATABASE は何も残さず消します。ブランチ環境はプーラーを通さず 5433 番ポートで Postgres に直接つなぎます。本番のバックグラウンドワーカーと同じやり方です。プーラーは本番の同時実行数で元を取るもので、ブランチ環境がそれを見ることはありません。

シークレット: 共有ではなく生成。 dev 用シークレット一式を作って全環境にコピーすれば楽でしょう。やめましょう。env up スクリプトは環境ごとに新しい SECRET_KEY(セッション署名)、ENCRYPTION_KEY(保存時に暗号化するもの全部)、ENV_TOKEN(モバイルアプリが提示する bearer トークン、後述)を生成し、その Fly アプリのシークレットストアにだけ保存します。あるブランチのセッションクッキーは別のブランチでは無価値で、漏れたプレビュー用トークンが開くのはプレビューひとつだけで、開発者はわざわざ探さない限り値を見ることがありません。Fly だけでなく別のシークレットマネージャーにシークレットを置くなら、同じ規則が当てはまります。パスは myapp/preview/$ENV/ で、スイーパーが環境と一緒にそのパスを消します。環境をまたいで本当に共有されるシークレットは共有インフラ自体の認証情報(Postgres の管理者 URL、Redis の URL、バケットのキー)だけで、それらはどの環境でもなく CI に住んでいます。

Redis の行がいちばん疑いやすいので、試しました。ひとつの環境の中からキャッシュキーを入れ、もうひとつから読み、共有 Redis のすべてのキーを列挙します。

$ fly ssh console -a myapp-feature-profile-tagl-fa8832 -C "python manage.py shell -c \"from django.core.cache import cache; cache.set('who-am-i', 'tagline-branch', 600)\""
$ fly ssh console -a myapp-feature-profile-webs-dcb2e7 -C "python manage.py shell -c \"from django.core.cache import cache; print(cache.get('who-am-i'))\""
None

$ # every key in the shared Redis
  feature-profile-tagl-fa8832:1:who-am-i
  ...

同じ Redis、同じキー名で、もう一方の環境からは何も見えません。

この記事の残りは、あの八行に $ENV を刻印するスクリプトと、それを正直に保つ規則です。

./scripts/env up

#

開発者が自分のブランチから実行するスクリプトにすると、考え方の全体はこうなります。CI も同じスクリプトを実行します。勝手にずれていく CI 専用の経路はありません。ラップトップに必要なのは fly と git だけ。SQL は fly ssh 経由で Postgres アプリへ行き、環境の Redis キーとバケットのオブジェクトは消す前に環境自身のマシンが削除するので、ラップトップは gitignore された env ファイル以外に共有 Redis やバケットの認証情報を持ちません。要点になる行だけに絞ると、次のとおりです。

#!/usr/bin/env bash
# scripts/env up|down|name|url: one environment per branch on shared preview infrastructure
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; PG_APP=${PREVIEW_PG_APP:-myapp-preview-pg}; DOMAIN=${BASE_DOMAIN:-example.com}

branch=${BRANCH:-$(git rev-parse --abbrev-ref HEAD)}
[[ "$branch" == "main" ]] && { echo "main has staging, not a branch environment" >&2; exit 1; }
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20); slug=${slug%-}
ENV=${ENV_OVERRIDE:-${slug}-$(printf '%s' "$branch" | shasum -a 256 | cut -c1-6)}   # the sweeper passes the name
APP="myapp-${ENV}"; DB="env_${ENV//-/_}"; HOST="${ENV}-dev.${DOMAIN}"

pg() { fly ssh console -a "$PG_APP" -q -C "psql postgres://postgres:${PG_PASSWORD}@localhost:5433/postgres -At -c \"$1\""; }
exists() { fly apps list --org "$ORG" --json | grep -q "\"Name\": *\"$APP\""; }

up() {
  echo "== $branch -> $ENV"
  exists || fly apps create "$APP" --org "$ORG"                         # idempotent
  [[ "$(pg "SELECT 1 FROM pg_database WHERE datname='$DB'")" == "1" ]] || pg "CREATE DATABASE $DB TEMPLATE seed_template"

  have=$(fly secrets list -a "$APP" --json | grep -o '"Name": *"[^"]*"' | cut -d'"' -f4 || true)
  gen() { grep -qx "$1" <<<"$have" || echo "$1=$(openssl rand -hex 32)"; }   # generated once, never rotated by a later `up`
  { gen SECRET_KEY; gen ENCRYPTION_KEY; gen ENV_TOKEN
    echo "ENV_NAME=$ENV"; echo "ALLOWED_HOSTS=$HOST,$APP.fly.dev"
    echo "DATABASE_URL=postgres://postgres:${PG_PASSWORD}@${PG_APP}.flycast:5432/${DB}"
    # ... plus the shared Redis URL and bucket credentials
  } | fly secrets import -a "$APP" --stage

  fly deploy -a "$APP" --config fly.preview.toml --remote-only --ha=false \
    --build-arg GIT_SHA="$(git rev-parse --short HEAD)" --build-arg GIT_BRANCH="$branch"
  echo "https://$HOST"
}

down() {
  [[ "$APP" =~ ^myapp-[a-z0-9-]+-[0-9a-f]{6}$ ]] || { echo "refusing to destroy $APP" >&2; exit 1; }
  if exists; then
    fly machine start -a "$APP" >/dev/null 2>&1 || true                 # it may be suspended
    fly ssh console -a "$APP" -q -C "python manage.py teardown_env" || echo "warning: cleanup failed; the sweeper will catch it" >&2
    fly apps destroy "$APP" --yes
  fi
  pg "DROP DATABASE IF EXISTS $DB WITH (FORCE)" || true
}

case "${1:-}" in up) up ;; down) down ;; name) echo "$ENV" ;; url) echo "https://$HOST" ;; esac

デモでは push する代わりに自分のラップトップから走らせました。三つのブランチはリポジトリの履歴に残したくない使い捨てで、出力が流れるのを見ていたかったからです。チームで使うときは誰もこれを打ちません。後で出てくるラベルのワークフローがまさにこのスクリプトを走らせ、ここから先の出力は Actions のログに残るはずのものです。ツール自体を載せたブランチで最初に実行したときの出力です。

$ ./scripts/env up
== feature/branch-environments -> feature-branch-envir-c65cb4
New app created: myapp-feature-branch-envir-c65cb4
CREATE DATABASE
Secrets have been staged, but not set on VMs. Deploy or update machines in this app for the secrets to take effect.
==> Building image
image size: 139 MB
✔ Machine 1a2b3c4d5e6f78 [app] update finished: success
https://feature-branch-envir-c65cb4-dev.example.com

$ curl -s https://feature-branch-envir-c65cb4-dev.example.com/api/version/
{"environment": "feature-branch-envir-c65cb4", "branch": "feature/branch-environments", "commit": "a1b2c3d4", "region": "syd"}

コマンドから URL まで二分半ほどで、大半はイメージのビルドです。コミットをもうひとつ積んで同じブランチで二度目の up をすると、「New app created」も「CREATE DATABASE」も出ず、同じシークレット名をステージしつつ生成したものは作り直さず、リビルドしました。同じ URL、新しいコミット。

中の選択のいくつかは一文ずつ値します。

fly.preview.toml は fly.toml ではない。 本番は API、WebSocket サーバー、バックグラウンドワーカーを別々の Fly アプリとプロセスグループで動かし、それぞれが自分の指標でスケールするようにしていて、それがスタックの記事の主張のすべてです。ブランチ環境はスケールする必要がありません。マシンひとつであるべきです。だからプレビュー設定はプロセスがひとつです。コンテナのエントリーポイントにプレビュー用のモードを足し、マイグレーションを走らせてから WebSocket を有効にした ASGI サーバーをひとつ起動します。Channels はもともとひとつの ASGI アプリケーションの中で HTTP と WebSocket の両方をルーティングするので、プロセスひとつでアプリ全体を配信します。そのモードでは同期ビューが thread-sensitive で、だいたい一度にリクエストひとつずつ動きます。本番で自分が捨てたまさにその取引ですが、ここでは正確に正しい取引です。ブランチをテストする人は誰も気づかないからです。

# fly.preview.toml (the app name comes from `fly deploy -a`)
app = 'placeholder'
primary_region = 'syd'

[processes]
  app = "/app/entrypoint.sh preview"   # migrate, then one ASGI server for HTTP and WebSockets

[env]
  DJANGO_SETTINGS_MODULE = 'myapp.settings'
  DEBUG = 'False'

[http_service]
  internal_port = 8000
  force_https = true
  auto_stop_machines = 'suspend'
  auto_start_machines = true
  min_machines_running = 0
  [[http_service.checks]]
    path = '/healthz'
    [http_service.checks.headers]
      Host = '127.0.0.1'               # the app's own hostname isn't known to a static file

[[vm]]
  size = 'shared-cpu-1x'
  memory = '1gb'

auto_stop_machines = "suspend"、min_machines_running = 0。 昼食以降誰も開いていないブランチ環境の費用はゼロであるべきです。stop でなく suspend なら、30 秒のコールドスタートの代わりに 504 を追いかけて たどり着いた 3 秒ほどの再開が得られ、ここでは 30 秒でも許容できます。デモ環境三つのうち二つは、デプロイ完了の一分後には fly apps list で既に suspended でした。

fly.io/apps/myapp-feature-profile-tagl-fa8832

DEBUG = False、本番と同じ settings モジュール。 ブランチ環境は公開 URL です。テストに関わるすべての面(本物の HTTPS、本物のクッキー、同じヘルスチェック)で本番のように振る舞い、誰かを傷つけうるすべての面で本番と違うべきです。プレビュー用の設定ファイルを別に用意する代わりに、差分は env up が設定するシークレットが運びます。サンドボックスの決済キー、認証プロバイダーの管理者認証情報なし、そして以下のすべての接頭辞を有効にする ENV_NAME。

設定ひとつがすべてを切り分ける。 ENV_NAME は設定に新しく入った唯一のつまみで、四か所に適用されます。

ENV_NAME = os.getenv("ENV_NAME", "")
_prefix = f"{ENV_NAME}/" if ENV_NAME else ""

CACHES["default"]["KEY_PREFIX"] = ENV_NAME                           # every cache key
CHANNEL_LAYERS["default"]["CONFIG"]["prefix"] = f"{ENV_NAME}:asgi"  # Channels group and channel names
STORAGES["default"]["OPTIONS"]["location"] = f"{_prefix}media"      # uploads
STORAGES["staticfiles"]["OPTIONS"]["location"] = f"{_prefix}static"

channels の分を忘れると、二つのブランチの WebSocket サーバーがグループ名を共有し、ある環境で送ったメッセージが別の環境に現れます。一日を食う種類のバグです。

五か所目は、後から共有 Redis を読んで初めて見つけました。504 の記事の起動時ロック、つまりイメージごとにマシン一台がマイグレーションを走らせる間ほかが待つ仕組みは、イメージ参照をキーにしていました。同じコミットから組まれたブランチ環境二つは同じイメージを持ちます。二つ目は一つ目の「done」マーカーを見つけて、マイグレーションされていない自分のデータベースへの自分のマイグレーションを飛ばしていたでしょう。今は環境名がキーに含まれ、そのキーは接頭辞の下に住んでいます。共有インフラの設計が生み続ける種類の問題です。暗黙のうちに「デプロイごと」だったものはすべて明示的に環境ごとにしなければならず、何が暗黙だったかは見るまで分かりません。

データベースは空からマイグレーションするのではなく複製する。 次の節です。

データベース: 数秒で複製されるテンプレート

#

ブランチ環境のデータベースは三つのうちのどれかです。全員と共有。ここまで我々を連れてきたやり方です。空からマイグレーションしてフィクスチャでシード。決定論的ですが、フィクスチャが実物の形をしたデータに敵ったことはなく、いつも十八か月は古い。あるいは本番の形のスナップショットの複製。現実的な行数、フィクスチャが常に埋まっていると仮定していたカラムの現実的な null、空のテーブルでは一瞬で終わるが実物では四十分かかるマイグレーションが姿を現します。

三つ目を採り、二つ目は CI 専用のチェックとして残します。そして三つ目をブランチごとにやれるほど速くするのは、多くの人が存在を忘れている Postgres の機能です。

-- Nightly, on the preview cluster. Restore last night's prod backup into seed_raw,
-- run the anonymiser, then freeze it as a template nobody can connect to.
ALTER DATABASE seed_raw RENAME TO seed_template;
UPDATE pg_database SET datistemplate = true, datallowconn = false WHERE datname = 'seed_template';

-- Per branch, in the time it takes to copy the files:
CREATE DATABASE env_feature_payments_retr_3f9a1c TEMPLATE seed_template;

CREATE DATABASE ... TEMPLATE はクラスタ内のファイルレベルのコピーです。数ギガバイトなら pg_restore にかかる数分ではなく数秒です。複製中のテンプレートには開いた接続があってはならず、datallowconn = false がそれを強制します。夜間ジョブが生きているテンプレートの上にリストアするのではなく seed_raw に組んで最後にリネームするのもそのためです。

デモではテンプレートを本番ダンプからではなく手で作りました。fly proxy でプレビュークラスタにトンネルを掘り、manage.py migrate、それからリポジトリ自前のシードコマンドで、小さいながら現実的なデータ一式を入れました。十九メガバイト。ブランチが三つ上がるにつれてクラスタにその複製が三つ現れ、それぞれ 19 MB、それぞれ一秒未満でした。

$ fly ssh console -a myapp-preview-pg -C "psql ... -c '\l'"
             datname             | template | size
---------------------------------+----------+-------
 env_feature_branch_envir_c65cb4 | f        | 19 MB
 env_feature_profile_tagl_fa8832 | f        | 19 MB
 env_feature_profile_webs_dcb2e7 | f        | 19 MB
 seed_template                   | t        | 19 MB

プレビュークラスタは非マネージドの Fly Postgres ノードひとつ、1 GB ボリューム付きの shared-cpu-1x で、月に二ドルほどです。ブランチ環境はプライベートネットワークの .flycast 経由でつなぎます。公開されているものは何もありません。

匿名化は省略できません。本番データが -dev ホスト名で届く瞬間、それは本番データであってはなりません。名前、メール、電話番号、住所、自由記述、決済参照、トークン、すべてリネームの前に上書きします。匿名化が失敗したら前夜のテンプレートが残り、誰かにメッセージが飛びます。小さな仕事で、このアプローチ全体をプライバシー質問票に答える人が受け入れられるものにする、まさにその仕事です。

エントリーポイントがすべてのイメージの初回起動で migrate を走らせるので、ブランチ自身のマイグレーションがテンプレートの上に適用されます。「自分のマイグレーションは本番の形のデータで動くか」の最初の正直なテストで、誰かが URL を開く前に起きます。

ホスト名: ワイルドカードひとつ、Worker ひとつ、そしてドキュメントが教えてくれなかった二つのこと

#

すべての環境には公開の HTTPS ホスト名が必要で、「公開」が要点です。スマホを持ったテスター、別のネットワークのデザイナー、VPN を入れないプロダクトマネージャー。Fly はアプリごとに myapp-$ENV.fly.dev を無料でくれて、それだけでも動きます。ただ *.fly.dev ホスト名には問題が三つあります。送るには不格好で、前に Cloudflare がいないので本番にかけている保護がひとつも効かず、自分のドメインに置きたければ環境ごとに DNS レコードひとつと証明書ひとつを作ることになり、スイーパーの片付けものがひとつ増えます。

それを全部なくす版が、ワイルドカードひとつと Cloudflare Worker ひとつです。計画は *.dev.example.com でした。二つのことに止められ、どちらも同じ計画を立てる前に知っておく価値があります。

Universal SSL が覆うワイルドカードは一段だけ。 Cloudflare の無料証明書は example.com と *.example.com に発行されます。*.dev.example.com は覆いません。二段目のワイルドカードには月 10 ドルの Advanced Certificate Manager が要ります。feature-branch-envir-c65cb4.dev.example.com への最初のリクエストは、自分のものが何ひとつ動く前に SSL ハンドシェイク失敗で死にました。対処は環境を最初のラベルに置くことです。feature-branch-envir-c65cb4-dev.example.com。既にある証明書が覆い、既にあるプロキシ済みの *.example.com レコードが覆います。でっち上げのサブドメインを歩き回るスキャナー向けのシンクホールとして自分が置いたあのレコードです。だから環境に DNS は一切要りません。

Redirect Rules は Workers より先に走る。 ルートを置いたところ、すべての -dev ホスト名が Worker が動くことなく www のトップページへ 301 で答えました。シンクホールはゾーンレベルのリダイレクトルール「その他のサブドメインはすべて → www」で、Cloudflare のリダイレクトフェーズは Workers フェーズより前に実行されます。ルールに節がひとつ必要でした。and not ends_with(http.host, "-dev.example.com")。デプロイスクリプトが up で足し down で外します。誰かが手で編集したルールこそ忘れられるものだからです。

dash.cloudflare.com/…/example.com/rules/redirect-rules/…/edit

DNS 側は元からあったあのレコードです。

dash.cloudflare.com/…/example.com/dns/records

その二つを片付ければ、ルーティングは *-dev.example.com/* の Worker ひとつです。

// dev-router.js: <env>-dev.example.com -> myapp-<env>.fly.dev
const DEV_SUFFIX = "-dev.example.com";
const ENV_NAME = /^[a-z0-9-]+-[0-9a-f]{6}$/;   // slug-hash, as scripts/env names them

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (!url.hostname.endsWith(DEV_SUFFIX)) return new Response("not a dev hostname", { status: 404 });
    const env = url.hostname.slice(0, -DEV_SUFFIX.length);
    if (!ENV_NAME.test(env)) return new Response(`no such environment: ${env}`, { status: 404 });

    url.hostname = `myapp-${env}.fly.dev`;
    const upstream = new Request(url, request);
    upstream.headers.set("X-Forwarded-Host", request.headers.get("host") ?? "");

    const res = await fetch(upstream);
    const out = new Response(res.body, res);
    out.headers.set("X-Robots-Tag", "noindex, nofollow");   // a half-finished branch is not for search engines
    out.headers.set("X-Dev-Environment", env);
    return out;
  },
};

Cloudflare がワイルドカードで TLS を終端し、Worker がラベルから Fly ホスト名を計算し、マシンまでの区間は Fly 自身の *.fly.dev 証明書が覆います。WebSocket のアップグレードは fetch をそのまま通ります。そしてルートがゾーンにあるので、Cloudflare が本番にしてくれることはすべて使えます。WAF ルール、レート制限、ボット対策モード、そして Access。

dash.cloudflare.com/…/example.com/workers

ブランチ三つを同時に上げ、Worker ひとつ、各ホスト名が答えたもの。

すべての 200 には Worker が付けた X-Robots-Tag: noindex, nofollow と X-Dev-Environment: <env> が添えられていました。404 は Fly に尋ねる前に Worker 自身が返したものです。

Cloudflare Access は「公開」を「届くべき人に届く」に変える装置です。*-dev.example.com にアプリケーションひとつ、「@example.com のメールなら誰でも」というポリシーひとつで、ブラウザからの訪問者はログインページを一度見て二度と気にしなくなります。ラップトップのデザイナー、PM、テスターはそれで済みます。デモには入れませんでした。環境は一時間、noindex を付けてシードデータ以外何もない状態で上がっていました。

モバイルアプリは覆えません。ネイティブアプリは Access のログインリダイレクトを完了できないからです。道は二つ。Access はログインを迂回するサービストークン(CF-Access-Client-Id / CF-Access-Client-Secret のヘッダー対)をサポートしていて、モバイルアプリの dev メニューが dev ホスト名用の一対を持てます。あるいはもっと単純に、/api/ に Access の迂回を入れ、ログイン済みのユーザーか環境の ENV_TOKEN、つまり env up がまさにこの環境のために生成したあのトークンのどちらもないリクエストを Django が拒否するようにします。どちらでも、モバイル側はベース URL とトークンの二つのフィールドを持つ dev メニュー画面で、テスターが既にインストールしているアプリがそのブランチと話すようになります。新しいビルドは要りません。OTA(無線)更新チャネルはアプリがビルドされたときのものを指したままで、API のベース URL はビルド時ではなく実行時の設定であり、元々そうあるべきでした。

認証は意図的に共有する唯一の共有サービスです。identity は環境ごとのものではありません。テスターはどのブランチでも同じアカウントでログインしたい。承認済みドメインに example.com を入れた、認証プロバイダーの dev プロジェクトひとつがすべての -dev ホスト名を覆い、すべての環境がそれに対して ID トークンを検証します。各環境のデータベースのユーザーテーブルはテンプレートのユーザーのコピーなので、テスターのアカウントはテンプレートにあったすべての場所にあります。

GitHub Actions でプレビュー環境を自動化する: イベントが入り、環境が出る

#

上のすべてを手でやるのは、やるのが自分だけなら構いません。二人目の開発者がいる時点で、誰かが覚えていたからではなく git で何かが起きたから起きなければなりません。自動化の全体はワークフロー四つ、リポジトリ設定ひとつ、ルールセットひとつ、GitHub environment ひとつで、そのどれもが git イベントを、開発者が手で走らせるのと同じ scripts/env の呼び出しに対応させます。勝手にずれる CI 専用の経路はありません。

ラベル、push、delete のワークフロー

#

# .github/workflows/branch-env.yml
name: branch environment
on:
  pull_request:
    types: [labeled, unlabeled, synchronize, closed]
  delete:
  workflow_dispatch:
    inputs:
      branch: { description: branch to bring up without a PR, required: true }

concurrency:
  group: env-${{ github.head_ref || github.event.ref || inputs.branch }}
  cancel-in-progress: true

env:
  FLY_API_TOKEN: ${{ secrets.FLY_PREVIEW_TOKEN }}   # org-scoped deploy token; a separate preview org keeps it away from prod
  PG_PASSWORD: ${{ secrets.PREVIEW_PG_PASSWORD }}
  # ... the shared Redis URL and bucket credentials, the same way

jobs:
  up:
    # the gate: a PR carrying the `env` label, or someone asking for a branch by hand
    if: >-
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' && github.event.action != 'closed'
        && contains(github.event.pull_request.labels.*.name, 'env'))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { ref: "${{ github.head_ref || inputs.branch }}" }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - id: env
        env: { BRANCH: "${{ github.head_ref || inputs.branch }}" }
        run: scripts/env up && echo "url=$(scripts/env url)" >> "$GITHUB_OUTPUT"
      - if: github.event_name == 'pull_request'
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: env
          message: "Branch environment: ${{ steps.env.outputs.url }}"

  down:
    # label removed, labelled PR closed or merged, or the branch itself deleted
    if: >-
      (github.event_name == 'pull_request' &&
        ((github.event.action == 'closed' && contains(github.event.pull_request.labels.*.name, 'env')) ||
         (github.event.action == 'unlabeled' && github.event.label.name == 'env'))) ||
      (github.event_name == 'delete' && github.event.ref_type == 'branch')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: BRANCH="${{ github.head_ref || github.event.ref }}" scripts/env down

ゲートは env ラベルで、ここは自分がいちばん強く主張したい部分です。ゲートがないと、すべてのブランチがアプリひとつとデータベースの複製ひとつの費用を払います。ラップトップのバックアップ代わりに push したブランチ、明日 squash されるスパイク、ボットが午前三時に開いた依存関係の更新まで。だから push だけでは何も起きず、PR を開くだけでも何も起きません。PR に env を付けると環境が立ち上がり、ラベルが付いている間は push のたびに更新され、ラベルを外すか PR を閉じるかマージすると落ちます。オプトインは依然として GitHub のイベントであって人への依頼ではなく、誰かが見るかどうかを知っている唯一の人がするクリックひとつです。固定コメントがユーザーインターフェースです。PR にラベルを付けると、誰にでも送れる URL 付きのコメントが現れ、push のたびに積み上がるのではなくその場で更新されます。PR ができる前に立ち上げたいブランチは workflow_dispatch が、残りはラップトップからの ./scripts/env up が受け持ちます。

知っておく価値のあるゲートが他に二つあります。ブランチ名のフィルタ (branches: ['feature/**', 'fix/**']) は PR が要りませんが、すべての機能ブランチが費用を払います。「ドラフトでないすべての PR」はいちばん自動的で、チームが PR を遅く、準備できたときにだけ開くなら正しい選択です。自分がラベルを選んだのは、費用の判断を文脈を知っている人に置けることと、何も閉じずに取り消せることからです。気に入っている副作用がひとつ。フォークからの pull_request の実行にはシークレットが渡らないので、フォークは環境を立ち上げられません。

concurrency は見た目以上に重要です。ひとつのブランチへの立て続けの push は、先行のデプロイと競走させるのではなく取り消します。同じアプリへの fly deploy が二つ同時に走ると、片方が負ける結果になります。

PR があったものは、マージされたかどうかにかかわらず closed が片付けを受け持ちます。delete イベントは workflow_dispatch で立ち上げて結局 PR ができなかったブランチのための保険で、ブランチが実際に削除されたときにしか発火しません。それはリポジトリ設定 Automatically delete head branches で、既定ではオフです。オンにしておけば、Merge を押すことが PR を閉じてブランチを削除するので、どちらのイベント単独でも env down が走っていたはずです。マージボタンが片付けです。

gh api -X PATCH repos/org/myapp -f delete_branch_on_merge=true

FLY_PREVIEW_TOKEN がこのファイルで危険な行です。アプリを作り消せるので、$APP がブランチ環境以外の何かになった瞬間に本番を消せてしまいます。ガードは二つで、両方残します。トークンを別の Fly 組織に限定し、本番組織を文字どおり見えなくすること(デモでは新しい組織に課金情報を付ける手間を省くため本番組織を使い、二つ目のガードだけに頼りました)。そして down() が slug-hash パターンに合わないアプリ名をすべて拒否すること。

ブランチ環境が自分ではできないチェック

#

ブランチは自分のマイグレーションしか見ません。だから肝心のチェックは pull request で main をマージした状態に対して走り、main が要求する唯一のステータスチェックです。

# .github/workflows/migrations-check.yml
name: migrations
on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:18
        env: { POSTGRES_PASSWORD: ci, POSTGRES_DB: ci }
        ports: ['5432:5432']
        options: --health-cmd pg_isready --health-interval 5s --health-retries 10
    env:
      DATABASE_URL: postgres://postgres:ci@localhost:5432/ci
      SECRET_KEY: ci-only
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-python@v5
        with: { python-version: '3.14' }
      - run: pip install -r requirements.txt
      - name: Merge main into the branch (a conflict here fails the check too)
        run: |
          git config user.email ci@example.com && git config user.name ci
          git merge --no-edit origin/main
      - name: One leaf in the migration graph
        run: python manage.py makemigrations --check --dry-run
      - name: The full chain applies from nothing
        run: python manage.py migrate --noinput

三十秒。0042 / 0042 の衝突をリリース当日の驚きから二人目の開発者の PR の赤いチェックに変えるのがこれです。下のマイグレーションの節で実際に発火するところを示します。

main の規則

#

ブランチが一か月生きたり、誰かが main に直接 push したりすれば、このどれも持ちません。規則は保護というより、環境を小さく、マイグレーションを最新に保つためのものです。

• main は保護され、常にデプロイ可能。 現在の main に対して migrations チェックが緑の PR でだけマージします(strict なステータスチェックなので、先週緑だった PR は main が動けば再実行されます)。線形履歴、force-push 禁止、削除禁止。
• 機能ブランチは短い。 二週間開いているブランチは main より二週間遅れた環境と、他人のものと衝突する確率が二週間分高いマイグレーションを持ちます。一か月がかりの機能はフラグの裏で小分けに main へマージします。長生きするのはフラグであってブランチではありません。
• ブランチひとつ、環境ひとつ、データベースひとつ。 既に命名が強制しています。
• 本番に行くのはリリースタグだけ。 イメージはタグから一度組まれ、ステージングと本番はそのイメージを動かします。リビルドはしません。
• migrations/ に触れる PR は残りの二人のどちらかがレビューする。 後述。

ルールセットとしては、gh api -X POST repos/org/myapp/rulesets --input ruleset-main.json で一度だけ適用します。

{
  "name": "main", "target": "branch", "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    { "type": "required_linear_history" },
    { "type": "pull_request",
      "parameters": { "required_approving_review_count": 1, "dismiss_stale_reviews_on_push": true,
                      "required_review_thread_resolution": true } },
    { "type": "required_status_checks",
      "parameters": { "strict_required_status_checks_policy": true,
                      "required_status_checks": [ { "context": "check" } ] } }
  ]
}

正直なひっかかりがひとつ。このリポジトリは GitHub Free プランのプライベートリポジトリで、Free ではブランチ保護とルールセットはパブリックリポジトリでしか使えません。API は 403 Upgrade to GitHub Pro or make this repository public と答えます。delete_branch_on_merge 設定、environment、ワークフローは Free でもすべて動きます。だからプライベートな Free リポジトリの小さなチームにとって、上のルールセットは慣習です。migrations ワークフローは変わらず走り、変わらず赤くなりますが、マージボタンを灰色にするものはありません。月 4 ドルの判断で、自分なら二人目がマージできるようになった瞬間にそうします。

develop ブランチも release/* ブランチもありません。Git-flow は統合が高くつき、まとめてやらざるを得ないという前提で設計されました。ブランチ環境が統合を安くするので、まとめる必要が消えます。

ステージングはタグの環境で、本番は昇格

#

ステージングは仕組み全体を再利用します。main の v* タグがブランチ名 staging/v1.42.0 で scripts/env up を走らせ、命名がそれを staging-v1-42-0-<hash> に変えます。同じテンプレート複製のデータベース、同じ放置で suspend されるマシン、同じホスト名の体系。違うのはその後です。

# .github/workflows/release.yml (abridged)
on:
  push:
    tags: ['v*']
jobs:
  staging:
    steps:
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env up
      - run: echo "image=$(fly image show -a "myapp-$(BRANCH=staging/$GITHUB_REF_NAME scripts/env name)" --json | jq -r '…')" >> "$GITHUB_OUTPUT"
  production:
    needs: staging
    environment: production        # required reviewer on this environment = the promotion gate
    steps:
      - run: fly deploy --config fly.api.toml --image "${{ needs.staging.outputs.image }}"
      - run: fly deploy --config fly.ws.toml  --image "${{ needs.staging.outputs.image }}"
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env down

production ジョブは必須レビュアーのいる GitHub environment を待ちます。誰かがステージングを見て Approve を押すと、本番はステージングが動かした同じイメージを参照で受け取ります。リビルドではありません。最後のステップがステージングを消すのは、役目を終えたからです。誰も承認しなければリリース候補は却下されたということで、その「ブランチ」(staging/v1.42.0 は origin に存在したことがない)が生存チェックに落ちたときにスイーパーがステージングを片付けます。スイーパーが確認できる理由なしには何も存在できません。

毎晩のスイーパー

#

# .github/workflows/sweep-envs.yml
on:
  schedule:
    - cron: '0 14 * * *'     # 02:00 NZST
  workflow_dispatch:
jobs:
  sweep:
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: scripts/sweep-envs

fetch-depth: 0 なのは、スイーパーが Actions が既定でチェックアウトする一コミットではなく、すべてのリモートブランチとその最終コミット日時を必要とするからです。workflow_dispatch はインシデントの後に手で走らせられるようにするためです。

開発者が実際にすること

#

ブランチを push し、PR を開き、誰かに見てほしくなったら env ラベルを付ける。リストはそれだけです。三分以内に PR に URL が現れ、push のたびに更新され、PR がマージされるか閉じられれば消えます。チームメイトと衝突していれば、マイグレーションチェックが誰より先に教えてくれます。取り合うステージングがないので誰もステージングを取り合わず、片付けがマージそのものなので誰も何も片付けません。

そして、これを組んだ人がその後ブランチごとにやることは、何もありません。共有の Postgres、Redis、バケットは一度だけ用意し、シークレットは Actions に一度だけ入れ、そこから先に繰り返す作業といえば月曜にスイーパーのログを読むことくらいです。チケットの列も、呼ぶボットも、プロンプトを打つ相手もありません。

片付けを信用しない片付け

#

env down が通常の場合で、面白いのは誰が掃除するかです。Redis のキーとバケットのオブジェクトは共有サービスのもので、down を走らせるラップトップはどちらの認証情報も要りません。環境自身のマシンが既にそれを持ち、自分の接頭辞を既に知っているからです。だから down はマシンが suspend されていれば起こし、そこで小さな後片付け用のコマンドを走らせ、その後で初めてアプリを消しデータベースをドロップします。環境が自分で後片付けをします。

$ BRANCH=feature/profile-website ./scripts/env down
redis: deleted 0 keys under feature-profile-webs-dcb2e7:*
bucket: deleted 278 objects under feature-profile-webs-dcb2e7/
Destroyed app myapp-feature-profile-webs-dcb2e7
DROP DATABASE

$ curl -s -o /dev/null -w '%{http_code}\n' https://feature-profile-webs-dcb2e7-dev.example.com/api/version/
530

530 は調整についての要点をもう一度示しています。Worker は変わらずホスト名をルーティングし、Fly には何もなく、誰も Cloudflare に知らせる必要がありませんでした。

この後片付けのコマンドは ENV_NAME なしでは実行を拒否します。接頭辞が空なら共有バケットの全消去になってしまうからです。そのガードこそ、これがシェルスクリプトの三行ではなくアプリ内のコマンドとして存在する理由のすべてです。

それでも環境は漏れます。GitHub Actions の障害中にブランチが削除される。開発者が試作のためにラップトップから env up を走らせ、push はしないまま。fly apps destroy が一時的に失敗して || true が飲み込む。三か月後にアプリが四十個あり、誰かに何が起きたのかと問わせる請求書が来ます。

だから一つ目を信用しない二つ目の仕組みがあります。上の表の毎晩のスイーパーです。すべての myapp-* アプリを列挙し、それぞれがどのブランチのものか割り出し、ブランチが消えたか七日間 push のないものをすべて消します。一週間放置されたブランチに生きた URL は要らず、次の push が二分で作り直します。ハッシュは逆算できないので、スイーパーは生きているすべてのブランチの環境名を計算し、その集合にないアプリをすべて消してから、背後にアプリのない env_* データベースをドロップします。

#!/usr/bin/env bash
# scripts/sweep-envs: nightly
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; TTL_DAYS=${TTL_DAYS:-7}
cutoff=$(( $(date +%s) - TTL_DAYS*86400 ))

git fetch --prune --quiet origin
live=""
while IFS=$'\t' read -r ts branch; do
  [[ "$branch" == "main" ]] && continue
  (( ts >= cutoff )) || continue
  live+="$(BRANCH="$branch" scripts/env name)"$'\n'
done < <(git for-each-ref --format='%(committerdate:unix)%09%(refname:short)' refs/remotes/origin | sed 's#^\([0-9]*\)\torigin/#\1\t#')

apps=$(fly apps list --org "$ORG" --json | grep -o '"Name": *"myapp-[^"]*"' | cut -d'"' -f4)
for app in $apps; do
  env="${app#myapp-}"
  [[ "$env" =~ ^[a-z0-9-]+-[0-9a-f]{6}$ ]] || continue       # not a branch environment (e.g. myapp-preview-pg)
  grep -qx "$env" <<<"$live" && continue
  echo "sweeping $app: branch gone or idle > ${TTL_DAYS}d"
  ENV_OVERRIDE="$env" scripts/env down || true
done
# ...then any env_* database with no app: DROP DATABASE.

デモのブランチはどれも push されたことがなかったので (上のラップトップでの実行です)、スイーパーから見ればすべて消えたものでした。誰かがラップトップから立ち上げて結局 push しなかったスパイクが一週間後に置かれる状態が、まさにこれです。残りの二つを、tagline 環境が書き込んだ Redis キーも含めて解体しました。

$ ./scripts/sweep-envs
sweeping myapp-feature-branch-envir-c65cb4: branch gone or idle > 7d
redis: deleted 0 keys under feature-branch-envir-c65cb4:*
bucket: deleted 322 objects under feature-branch-envir-c65cb4/
Destroyed app myapp-feature-branch-envir-c65cb4
DROP DATABASE
sweeping myapp-feature-profile-tagl-fa8832: branch gone or idle > 7d
redis: deleted 3 keys under feature-profile-tagl-fa8832:*
bucket: deleted 278 objects under feature-profile-tagl-fa8832/
Destroyed app myapp-feature-profile-tagl-fa8832
DROP DATABASE

$ fly apps list --org myapp-preview | grep myapp-
 myapp-preview-pg │ myapp-preview │ deployed

(小さく噛まれたことがひとつ。macOS には連想配列のない bash 3 が付いてきます。スイーパーの最初の版はそれを使っていて、自分のラップトップで declare -A で死にました。上の版は改行区切りのリストを使い、どこでも動きます。)

費用は楽しい部分です。suspend されたマシンは rootfs 分だけで、月に数セント。データベースは既に払っているボリューム上の 19 MB。Redis は従量課金プランで、十万コマンドあたり 20 セント、ブランチテストの規模ではゼロに丸まります。バケットの接頭辞は保存した分だけ。共有 Postgres ノードが唯一の固定費で、月に二ドルほど。アクティブなブランチ二十本で常時稼働の shared-cpu-1x 一台分くらいで、スイーパーがそれを二百ではなく二十に保ちます。デモ全体、つまり一時間の環境三つと共有部品は、その間に飲んだコーヒーより安くつきました。

ブランチをまたぐマイグレーション、警告してくれる共有データベースなしで

#

各開発者が機能を端から端まで持つなら、すべてのブランチにマイグレーションが入っています。だからこの節が重要な節です。

共有環境の世界を離れるときに人が見落とすことがあります。全員がひとつの dev データベースにデプロイしていたとき、マイグレーションの衝突は即座に痛く表面化しましたが、ともかく表面化しました。マイグレーションがひとつ走り、次のデプロイが失敗し、誰かがその日の午後に直した。ブランチごとにデータベースがあると、各マイグレーションは自分の環境で完璧に動き、二つは二つ目が main にマージされたときに初めて出会います。不注意にやれば、衝突は安かった dev から安くないリリースへ移ります。

規則は四つ、すべて CI で強制できるので誰も覚えておく必要がありません。

1. main をマージした状態でマイグレーショングラフの葉が二つなら CI が失敗する。 makemigrations --check はモデルとマイグレーションの食い違いを捕まえますが、肝心の衝突は二つのブランチが両方とも 0042_* を足していることです。ブランチ単体ではなく、main にマージしたブランチに対して確認します。

git fetch origin main
git merge --no-commit --no-ff origin/main || { echo "merge conflict"; exit 1; }
python manage.py makemigrations --check --dry-run
python manage.py migrate --plan 2>&1 | grep -q "Conflicting migrations" && exit 1

これは自分でわざと起こしたものです。デモブランチ三つのうち二つ、feature/profile-tagline と feature/profile-website が、それぞれマイグレーションひとつでユーザープロフィールのモデルにフィールドをひとつ足し、各環境は上がる途中で自分のものを適用しました。新しいカラムはあるべき場所にだけありました。

env_feature_branch_envir_c65cb4      (no new column)
env_feature_profile_tagl_fa8832      tagline
env_feature_profile_webs_dcb2e7      website

両方とも 0042_* です。どちらのブランチも相手のものを見られないので、どちらの環境も問題があるとは教えてくれません。片方をもう片方にマージすると、チェックが教えてくれます。

$ git merge --no-commit --no-ff feature/profile-tagline
$ python manage.py makemigrations --check --dry-run
CommandError: Conflicting migrations detected; multiple leaf nodes in the migration graph:
  (0042_profile_tagline, 0042_profile_website in accounts).
To fix them run 'python manage.py makemigrations --merge'

$ python manage.py makemigrations --merge --noinput
Created new merge migration accounts/migrations/0043_merge_20260919_0324.py
    dependencies = [
        ('accounts', '0042_profile_tagline'),
        ('accounts', '0042_profile_website'),
    ]

二人目の作者が自分のブランチで、自分の環境で、誰の邪魔もせずにその --merge を走らせ、次の env up が自分の複製の上に 0043 を適用します。(この場合、git が先にテキストの競合も報告しました。両方のフィールドがモデルファイルの同じ行に足されていたからです。現実的で、テキストの競合が解消されるまでマイグレーションの衝突を隠すことは知っておく価値があります。)

2. マイグレーションは前のリリースのコードと後方互換である。 デプロイ中には新しいスキーマと古いコードが共存する窓があり、マシンがロールバックすればその逆もあります。カラムは nullable かデフォルト付きで足し、一度にリネームせず、現在のリリースがまだ読むものは決してドロップしない。足して、デプロイして、バックフィルして、コードを切り替えて、後のリリースでドロップする。expand and contract です。ここでより重要になる理由は、使い捨て環境がデプロイを頻繁にし、その窓の中にいる時間が増えるからです。タグごとのステージングがそれをリハーサルする場所です。

3. CI は空のデータベースにゼロからのマイグレーションもする。 テンプレートの複製は「自分のマイグレーションが現実的なデータに適用できるか」をテストします。空からの実行は「チェーン全体がまだ無から動くか」をテストし、前のデータマイグレーションが何かを埋めたと仮定していたマイグレーションを捕まえます。三十秒で、さもなければ次の新しいラップトップを待つ類のバグを捕まえます。

4. スキーマ変更には二つ目の目が付く。 小さなチームに CODEOWNERS ファイルは要りませんが、規則は要ります。migrations/ に触れる PR はマージ前にチームの誰かがレビューし、レビュアーの仕事は SQL を確認することではありません。自分かチームの他の誰かがこの二週間で同じテーブルに触れているかを知っていて、そう言うことです。開発者が十数人を超えるとその知識はひとりの頭に収まらなくなるので、そこで migrations/ への CODEOWNERS の記述が元を取ります。どんなツールもこれの代わりにはなりません。機械的なものはツールが全部捕まえてくれるので二分の仕事で、古い共有環境の世界で残す価値のある唯一の部分です。二人が衝突しかけていると気づく瞬間。

バージョニング、URL が何を動かしているか語るように

#

共有環境がひとつのとき、「ステージングに何が載ってる」はチャットで飛び交う質問でした。複数になれば環境の属性でなければならず、さもなければすべてのバグ報告が考古学から始まります。

• すべてのイメージがコミット SHA を持ち、アプリがそれを公開する。 fly deploy --build-arg GIT_SHA=... --build-arg GIT_BRANCH=... がイメージに環境変数として刻み、/api/version/ が環境名とリージョンと一緒に返します(上の出力参照)。「feature-profile-tagl-fa8832 で壊れてる」に対して誰もが最初にするのは、思っているコミットを動かしているかの確認です。最初のデモ環境はツールがコミットされる一コミット前の作業ツリーからデプロイされていて、エンドポイントがそう言いました。返ってきたのは期待した SHA ではなく、ひとつ前のコミットでした。
• ENVIRONMENT=$ENV がすべてのログ行とエラートラッカーの environment タグにある。 ブランチのエラーが本番のエラー追跡を汚さず、ワンクリックで絞り込めます。
• ブランチは SHA を、リリースはタグを持つ。 feature-payments-retr-3f9a1c にバージョン番号はありません。コミットがあります。ステージングと本番には v1.42.0 があります。
• モバイルアプリは URL ではなく最小 API バージョンを持つ。 dev メニューの URL フィールドがテスターが実機をブランチに向ける方法で、API スキーマバージョンを載せたバージョン確認用のエンドポイントが、アプリが理解できる相手と話しているかを知る方法です。

これで解決しないこと

#

一緒でなければ意味をなさない二つの機能は解決しません。ブランチ環境はブランチひとつを見せます。答えは両方をフラグの裏でマージして main を見ることで、main を追いかける常設環境ひとつ(main-dev.example.com、マージのたびに再デプロイ)でできます。自分が残す唯一の長生きする非本番環境で、誰もそこへデプロイはしません。次のリリースが何になるかを見るためのものです。

登録済みコールバックを求めつつワイルドカードを受け付けないプロバイダーは解決しません。私が使っている認証プロバイダーは親ドメインを受け付けるので、example.com がすべての -dev ブランチホスト名を覆います。一部の OAuth や決済プロバイダーはそうではなく、その場合は Worker が最後に確保した環境へルーティングする共有ホスト名をひとつ置きます。小さなものにかかった小さなロックで、すべてにかかったロックよりずっとましです。

マイグレーションの人間側は解決しません。ツールは機械的な衝突を捕まえます。同じ二週間に二人が同じ概念を両立しない形でモデリングするのは捕まえられず、それを直す唯一の方法は、どちらかが気づくマイグレーションレビューです。

あなたの環境で確かめてみること

#

共有の dev やステージングがあり、それを予約するチャットのスレッドがあるなら:

1. 完成したブランチが、作者以外の誰かに動いているところを見てもらえるまでどれだけ待ちますか? 一時間を超えるなら、そのロックの代金をデリバリー時間で払っていて、小さなチームならその大きな割合が待っています。
2. 共有データベースはどれくらいの頻度でリセットされ、そのとき誰が作業を失いますか?
3. 新しい開発者が初日に、誰にも何も頼まずに自分のブランチが動く公開 URL を手に入れられますか? 頼まなければならないものが何であれ、それが最初に自動化するものです。
4. 新しい環境は現実的なデータから始まりますか? 空から始まるなら、最初に捕まえ損ねるバグは、空のテーブルでは平気で実物のテーブルでは四十分かかるマイグレーションです。
5. 非本番のホスティングに、全員が忘れて一か月経ってもまだ存在するものがありますか? あるなら、何より先にスイーパーを書いてください。漏れは初日から始まります。

チャットのあの質問が消えるのは、人が尋ねるのをやめたからではなく、答えがいつも「使ってますよ、自分のを」だからです。

このブログへの検索流入はここ2年ほど横ばいで、動くことを期待するのはやめました。そこで代わりに、訪問者がどこから来ているのか、その中にAIアシスタントはいるのかを見に行きました。いることはいます。かろうじて、ですが。2026年9月16日までの12か月で、アクセス解析が数えたこのサイトのセッションは5,372。そのうちAIアシスタント経由は27で、内訳はchatgpt.comから12、gemini.google.comから9、Perplexityから6、claude.aiからは0でした。0.5%です。ただ、ChatGPTから来た人は良い訪問者でした。平均の滞在時間は5分。直接アクセスの27秒、Google経由の3分と比べると長い。すでに答えを読んだうえで、詳細を知りたくて来ているからです。

そこで、小さなブログがそういう回答の情報源に選ばれるにはどうすればいいのか、少し時間をかけて調べました。この記事はこのサイトでやったことと、それについてログが何を言っているかの話です。数字があるところは数字を出し、推測でしかないところはそう書きます。最初の草稿にあった3つの文は、実際に調べてみたら間違っていました。その訂正はそのまま残してあります。

ボットは2種類あって、引用してくれるのは片方だけ

#

まずはっきりさせておきたいのは、「AIボット」と呼ばれるものは仕事の違う2種類で、ユーザーエージェントも別、片方をブロックしてももう片方には何の影響もない、ということです。

学習用クローラーは、次のモデルを作るためにページを大量に持っていきます。OpenAIのはGPTBot、AnthropicのはClaudeBot、GoogleのはGoogle-Extendedというトークンで、AppleのはApplebot-Extendedで制御し、Common CrawlのCCBotは公開データセットの大半の元になっています。持っていかれたものは重みになって終わりで、こちらへのリンクは残りません。これらをブロックする理屈はあって、私も馬鹿げた話だとは思いません。

もう一方が検索取得用のボットです。誰かがChatGPTやClaudeやPerplexityに質問すると、アシスタントは検索を走らせ、その場で数ページを取得して読み、出典付きで答えを書きます。その取得はOAI-SearchBotとChatGPT-User、Claude-SearchBotとClaude-User、PerplexityBotとPerplexity-Userとして届きます。GoogleのAI Overviewsは普通のGooglebotを使うので、専用のスイッチはそもそも存在しません。訪問者を送り返してくれるのはこちらのボットです。引用されるのが目的なら最適化する相手はこちらで、GPTBotをブロックしてもChatGPTの検索結果には良くも悪くも何の影響もない、というのは知っておく価値があります。

このサイトのrobots.txtはHugoのデフォルトで、すべて許可です：

User-agent: *
Allow: /
Sitemap: https://jared.lynskey.co.nz/sitemap.xml

分けることも考えました。取得用のボットは通し、学習用は締め出す。でも、読まれることがそもそもの目的のブログでやる価値はないと判断しました。もしやるなら下のようになります。あえて載せるのは、Cloudflare が Googlebot に空のページを返していたと同じ教訓があるからです。一覧に書くのはボット名であって、会社名ではありません。「OpenAI」と書ける行は存在しないのです。

User-agent: GPTBot
User-agent: ClaudeBot
User-agent: Google-Extended
User-agent: Applebot-Extended
User-agent: CCBot
Disallow: /

User-agent: *
Allow: /

サイトがCloudflareの後ろにあるなら、確認しておくことが1つあります。2025年半ば以降、新しいゾーンはデフォルトでAIクローラーをブロックしますし、ボット設定には既存のゾーンにワンクリックで同じことをするトグルがあります。これは両方の種類をブロックします。このブログは先週Cloudflare Pagesに移したので、私の確認リストにも入っていました。「AIボット」というのが締め出すべきものに聞こえて有効にしたのなら、引用も一緒に切ってしまっています。その後Cloudflareは、管理しているrobots.txtにContent-Signalの行を書き込むようになりました。search、ai-input、ai-trainという別々のフラグを持つものです。誰も従う義務はありませんが、語彙としては正しいと思います。上と同じ区分を、壁ではなく希望として表現したものです。

実際にドアを叩いているのは誰か

#

Cloudflareへの移行には副作用がありました。初めて、すべてのリクエストをユーザーエージェント別に見られるようになったのです。2026年9月13日から16日までの4日間に来たものを、偽物を除いたうえで並べたのが下の表です。偽物についてはあとで書きます。

目を引くことが2つあります。学習用クローラーは、取得用ボットが数十ページを読むあいだに、すべてを2回読んでいます。そして取得用ボットは手当たり次第に取っているわけではありません。ChatGPT-UserもClaude-Userも、このサイトでいちばん具体的な記事であるアップデートサーバーの記事を取りに来ていて、コールドスタートの記事は日本語版が取得されています。

次に偽物の話です。GPTBotを名乗るリクエスト20件のうち18件は、OpenAIが公開しているIPレンジの外から来ていて、/.env、/.git/HEAD、/firebase-adminsdk.jsonを要求していました。「ChatGPT-User」を名乗る36件のうち15件も同じ類のものです。「PerplexityBot」のトラフィックは大半が/id_ed25519を欲しがっていました。ユーザーエージェントは誰でも送れるただの文字列で、脆弱性スキャナーはAIボットの名前なら素通しされることに気づいています。OpenAI、Anthropic、PerplexityはいずれもIPレンジを公開しています。ボットを特別扱いするなら、通すにせよ止めるにせよ、名前ではなくアドレスを確認すること。上の20、59、8は、正しいアドレスから来たリクエストの数です。

ページはブラウザなしで読めなければならない

#

取得用のボットは回答時にタイムアウト付きで取りに来て、ほとんどはJavaScriptを実行しません。バンドルが読み込まれるまで空のdivでしかないページは、彼らには読めないページです。Hugoは完成したHTMLを書き出すので、このブログはそれをただで手に入れていて、もっと凝ったものに移そうと思ったことが一度もない最大の理由がこれです。私が運営しているマーケットプレイスはその正反対で、React NativeのWebアプリです。あそこでクローラーに本物のドキュメントを渡すには動的レンダリングの分岐が必要で、そのあとキャッシュのバグがそれを静かに台無しにしました。上のCloudflareの記事がその話です。

速度も同じように効きます。そしてここでは、ログに間違いを正されました。Cloudflareの後ろにある静的サイトは、いちばん近いエッジから配信されるものだと思い込んでいました。そうではありませんでした。このブログはCloudflare Pagesにあって、HTMLはキャッシュされずに出ていき、ソウルからだとロサンゼルスから0.5秒ほどで返ってきます。数秒のタイムアウトを持つボットにはそれでも十分ですが、私が言い張っていたであろう数十ミリ秒ではありませんし、それが分かったのは測ったからです。6ページから答えを組み立てているアシスタントは、3秒かかるページを落とします。落としたとは教えてくれません。

段落をそのまま切り出せるように書く

#

こうしたシステムのページの使い方は、読者の読み方とは違います。ページをチャンクに分け、質問に対して各チャンクを採点し、点の高いものを引用します。800語かけて結論に向かっていく記事は、どのチャンクでも点が低い。各セクションが最初の文で主張を述べてから裏付ける記事は、質問に合ったセクションで点を取ります。

これは、どんな技術的なことよりも、ここでの書き方を変えました。フロントマターのdescriptionは今、読ませるためのフックではなく、記事が何を言っているかの要約です。アシスタントが見せるのはdescriptionだけ、ということがよくあるからです。セクションの見出しは、そのセクションの結論を書く。数字はグラフではなく、単位と一緒に文の中に入れる。日付は書き出す。1年後にページを読むモデルにとって「先週」は何の意味もないからです。そして、1本の記事は1つのことについて書く。

もう半分は、引用する価値のある何かを持っていることで、ここはデータが割れています。ログを見ると、回答時のボットが取得するのは具体的な記事です。コールドスタート、アップデートサーバー、iOSのデバッグ。Naverのクローラーの名前はYetiで、DaumのはDaumoa。私のホスティング先の再起動は504が出る30秒の窓。CloudflareのオンザフライのBrotli圧縮は、私のバンドルではgzipより悪い数字だった。こういう事実は書かれている場所が少ないので、それを必要とする質問はここに着地します。ところが、アシスタントからクリックして来る人の大半が着地するのは、2023年と2024年のマネジメントについての記事で、それぞれ1、2セッションずつ。具体的な記事は機械に読まれ、一般的な記事はクリックされる。これにきれいな説明は持っていませんし、でっち上げるよりは、そのまま報告するほうがいい。効くところがあるとすれば、それでもやはり、今週自分が突き止めた、検索しても見つからなかった具体的なことを書き残すことです。機械が実際に読んでいるのはそれだと、ログが示しているからです。

誰が書いたかを言い、同じことを言い続ける

#

ページを引用するかどうか決めているアシスタントがやっているのは、注意深い読者がやることと似ています。誰がいつ書いたのか、他に見つけたものすべてと矛盾しないか。このサイトでその仕組みを担っているのは、ほとんどテーマです。すべての記事に、著者、公開日、更新日を持つArticleの構造化データが付いていて、著者は同じ公開プロフィールへのリンクを持つPersonです。テンプレートの数行ですが、それが「あるページ」と「経歴のある名前の付いた人物によるページ」の違いです。

テーマがやってくれないのは一貫性です。aboutページ、llms.txt、各種の公開プロフィール、すべての記事の先頭にある1行は、同じ人物を同じ職歴で説明しています。何かが変わればすべて変える。そうしないと、忘れた1つが間違っているものになります。細かい話に聞こえますが、あるページではエンジニアリングマネージャーで別のページではフリーランス、というのはまさに、モデルが言葉を濁したり、別の人を選んだりする種類の矛盾です。

更新日も正直でなければなりません。内容が変わったときに変わり、それ以外では触りません。新しく見せるために日付を上げるのは、一度は効いて、そのあとドメイン全体が割り引かれる類のことです。

llms.txtとは何か、そして誰も読んでいないという事実

#

llms.txtは2024年9月に提案されたもので、サイトのルートに置くMarkdownファイルに、サイトの要約と厳選したリンクの一覧を書いて言語モデルに渡す、というものです。今年の2月に追加しました。私が誰かについての段落が1つ、そのあとマネジメント、インフラ、モバイル、コミュニティのセクションがあって、記事ごとに1行。タイトル、URL、そして記事の結論を述べた1文です。急いでいる人のために書いた目次のように読めます。

但し書きというのは、誰も読んでいない、ということです。手元にある4日分のログで/llms.txtへのリクエストは、自分のものだけでした。Common Crawlは2026年8月のクロールでこのサイトの76ページを取り込んでいますが、このファイルは一度もありません。主要なアシスタントで読むと表明しているところもない。つまり、ここの何かが引用される理由がこれだということはなく、その根拠で誰かに勧めるのはやめておきます。それでも残しているのには2つ理由があります。かかったのは1時間で、記事ごとに「この記事は実際に何を結論づけているか」を1文で書く作業のほうがファイルそのものより価値がありました。どの記事が何も結論づけていないかが分かったからです。それに、このサイトが何のためにあるかを機械に伝える唯一のページでもあり、必要にならなくても持っておきたい。手で書いていて忘れるので、その後ずれてきていて、それがHugoの出力フォーマットとしてフロントマターから生成すべきだという論拠になっています。やることリストには入っています。

フィード、サイトマップ、5つの言語

#

地味な配管も相変わらず効きます。サイトマップは、クローラーが新しい記事を公開当日に見つける手段です。RSSは、記事が変わったことを知る手段。どちらもHugoのデフォルトで、考えたことがありません。ClaudeBotは2日間でサイトマップを36回読んでいて、1,380ページをあれだけ速く見つけられたのはそのためです。

言語は、重要だと思っていなかった部分です。ここにあるものはすべて英語、日本語、韓国語、簡体字中国語、ベトナム語で、同じ記事だとクローラーに分かるようalternateリンクが付いています。クローラーはこれを5つのサイトとして扱います。ClaudeBotのクロールは5言語にほぼ均等に割れていて、Common Crawlが8月に取り込んだ73の記事ページのうち、英語版は4つだけでした。アシスタントは聞かれた言語で答え、その言語の情報源に寄るので、コールドスタートについての韓国語の質問は、英語ページをその場で翻訳したものではなく韓国語のページから答えられますし、ChatGPTが実際に取得したのは日本語のページでした。条件は、翻訳がその言語で書かれたもののように読めることです。今年の初めにネイティブスピーカーのチェックを入れてやった見直しは人間の読者のためでしたが、ベトナム語のページを珍しいものではなく情報源にしているのもそれです。

測れること

#

推測をやめてみたら、思っていたより多くのことが測れました。Cloudflareの無料プランでは、ユーザーエージェントとパス別のリクエストログが1クエリにつき1日分見られて、ボットの表はそこから来ています。リファラを見るには有料プランが要ります。リファラはアクセス解析ツールにあって、ダッシュボードを目を細めて眺めるのではなくレポートAPIで引き出したのが、冒頭の数字です。2つを合わせると全体の形が見えます。4日間で、取得用ボットはOpenAIとAnthropicのアドレスから90ページほどを取得しました。この1か月でChatGPTから来た人は2人。たくさん読まれ、ときどき引用され、めったにクリックされない。ページを使ったけれどクリックされなかった回答を見る方法は、相変わらず私の知るかぎりありません。いちばん役に立つ確認は今でも手作業です。記事が答えている質問をアシスタントに聞いて、誰のページを引用するか見る。

この中から1つだけ残すなら、書き方のルールです。robots.txtと構造化データとllms.txtは半日の作業で、終われば終わりです。各セクションが主張を最初に言うように書くこと、一般的なことではなく具体的なことを書くことは習慣で、ページに引用する価値があるかどうかを決めるのはその習慣です。2つ目は、主張する前に測ること。機械に信頼されるというのは、結局のところ人に信頼されるのとよく似ています。自分が誰かを言い、知っていることを言い、毎回同じように言う。

少し前まで、私が作っているマーケットプレイスアプリのWeb側への変更はすべてDjango APIの変更と同じ道を通って出ていました。Dockerイメージをビルドし、プッシュし、Fly.io上のマシン全台にローリングで展開する。Webフロントエンド（モバイルアプリのWebエクスポートと、静的サイトジェネレーターがビルドするマーケティングページ）はAPIと同じイメージにコピーされていたので、他に出しようがなかったのです。CSSの修正1つに7分ほどかかり、11台のマシンが再起動しました。8月のある日は、これを6回やりました。

この記事では、それを何に置き換えたかを順に追います。デプロイスクリプトがフロントエンドの2つのツリーをビルドし、バージョン付きプレフィックスでオブジェクトストレージにアップロードし、ポインタのオブジェクトを1つ書き換え、全マシンが新しいバージョンを配信するまで待ってから、CloudflareのキャッシュをAPI経由でパージします。反対側ではDjangoがリクエストごとにポインタを読み、そこに書かれたバージョンを配信します。APIはまったく再起動しません。

以前のやり方の何が問題だったか

#

いちばん大きなコストは再起動でした。11台がローリングするということはコールドブートが11回で、共有CPUではDjangoが立ち上がるのに13秒ほど、そのうち7秒はDjangoのimportだけに使われます。本物の訪問者にそのコストを払わせないよう、デプロイスクリプトの最後に全マシンを1回ずつ叩くウォームアップの工程を置いていましたが、そのせいでWebのリリースは毎回、いちばん遅いマシンを待って終わっていました。 そのコールドブートがFly.ioでどれだけ高くつくかは、ゼロスケールと、再起動のたびに起きる30秒の障害に書きました。要するに再起動のたびに訪問者が504を受け取りうる窓が開くので、何も再起動しないデプロイ経路はWebのリリースからその窓を丸ごとなくしてくれます。

2つ目の問題は、静的サイトの出力が分かれていたことです。HTMLはイメージに入るのに、RSSフィードと検索インデックスは直接バケットに行っていました。同じソースからビルドされてはいるものの同じ瞬間ではないので、食い違うことがありえて、食い違うまで誰も気づきません。

3つ目は習慣の話です。リリース1回に7分と再起動がかかると、小さなリリースをしなくなります。修正を3つ4つ溜めてからまとめて出すようになり、それこそが1行の変更が壊れた何かと一緒に出ていくパターンです。

バケットの中の配置

#

すべてS3互換バケットのweb/プレフィックス以下にあります。

web/current                              ← a text file containing one version string
web/a1b2c3d-20260914021500/manifest.json ← every file in this version
web/a1b2c3d-20260914021500/app/...       ← the app's web export
web/a1b2c3d-20260914021500/site/...      ← the static site's output
web/9f8e7d6-20260912093012/...           ← the previous version, still there

バージョンは短いgit SHAとUTCのタイムスタンプなので、どのコミットがいつ上がったかがそのまま読めます。リリースが本番になるとき変わるのはweb/currentだけです。

デプロイスクリプトがやること

#

全体は1本のスクリプトで、リポジトリのルートから実行します。順番に：

1. 汚れたツリーを拒否する。 最初にgit status --porcelainを実行し、何か出てきたら終了します。ディスクにあるものがそのままアップロードされるのですが、以前のマーケティングサイト用のデプロイスクリプトがその形でコミットしていない文言を出してしまったことがありました。分かってやる場合のために上書き用のフラグがありますが、使ったことはありません。その後git rev-parse --short HEADと現在時刻からバージョン文字列を作ります。

2. 2つのツリーをビルドする。 アプリは本番のAPIとWebSocketのURLを埋め込んでWebエクスポートを実行し、そのあとにBrotliの事前圧縮が続きます。事前圧縮は説明しておく価値があります。Cloudflareはオンザフライでもブロトリ圧縮してくれますが品質レベルが低く、このバンドルではgzipより悪い結果でした（1.66MBに対して2.04MB）。ビルド時に品質11で一度だけ圧縮すると1.28MBになるので、スクリプトは1KBを超えるJS・CSS・JSONファイルごとに.brの双子を隣に書き出します。マーケティングサイトは静的サイトジェネレーターをminify有効で実行します。

3. アップロードする。 2つのビルドディレクトリを走査し、全ファイルを16スレッドでweb/<version>/app/...とweb/<version>/site/...にアップロードします。各オブジェクトにはファイル名（先に.brを外したもの）から推定したContent-Typeが付き、Brotliの双子にはContent-Encoding: brも付きます。全ファイルが上がって初めて、相対パスのリスト2つを持つJSONであるmanifest.jsonを書きます。この順番が重要です。Django側はマニフェストのないバージョンを存在しないものとして扱うので、途中までしか上がっていないバージョンが現行になることはありえません。今は数百ファイルで、アップロードは6秒ほどです。

4. ポインタを書き換える。 put_object1回でweb/currentにバージョン文字列を書きます。これがリリースです。

5. マシンを待つ。 各APIマシンはポインタを5秒キャッシュするので、書き換え直後の一瞬は一部がまだ古いバージョンです。スクリプトはAPIのバージョン確認用エンドポイントを0.5秒ごとにポーリングし、新しいバージョンを返す連続回答を数えます。Flyは全マシンに負荷分散するので、一致する回答が16回連続（マシン数より多い）で出れば、全台がポインタを読み直したと判断できます。古い回答が1つでも来るとカウントはリセットされます。90秒で諦めて手で確認するよう促します。最初の本番の切り替えが30秒強かかったので、上限はそれより下げていません。

6. Cloudflareをパージする。 API呼び出し1回で、後述します。失敗したら警告を出して先へ進みます。

7. チームのチャットに投稿する。 ランタイムのエラー通知と同じWebhookに、バージョンと実行者を1行で送ります。エラーがまとまって出たとき、何が変わった直後かと照らし合わせられるようにです。ロールバックは琥珀色で投稿されます。

最初から最後までで1分強、そのほとんどはWebエクスポートです。

Django側

#

フロントエンドを配信していたのはもともとDjangoです。API以外のURLにはすべて、そのルートに対応するWebエクスポートのプリレンダー済みページを返し、マーケティング・プライバシーポリシー・サポートのページは静的サイトの出力から来ます。これらのビューは以前はディスク上のファイルを開いていました。今はバケットのことを知っている小さな層を1つ経由して読みます。

リクエストごとに解決するのは3つです。現在のバージョン（web/currentから読み、5秒キャッシュ）、そのバージョンのマニフェスト（そのバージョンが現在である間キャッシュ）、そしてファイル本体（ファイルの中身を持つ小さなインメモリのLRUなので、ページのHTMLとメインバンドルはメモリに残ります）。404が安く済むのはマニフェストのおかげです。パスが一覧になければ、バケットに聞かずに「ない」と答えます。クライアントがBrotliを受け付けるなら.brの双子ファイルを代わりに読んでエンコーディングヘッダを付けます。アセットはファイル名に内容のハッシュが付いているので、1年間のimmutableなキャッシュヘッダ付きで出ていきます。ルートとプリレンダー済みページの対応表のように、ファイル一覧から作るものもバージョンごとにキャッシュされるので、新しいデプロイが出ると最初のリクエストで作り直され、それより前には作られません。

それから、デプロイスクリプトがポーリングするエンドポイントがあります。

def web_version(request):
    # bundle: the layer that reads web/current and the manifest
    response = JsonResponse({"source": bundle.source(), "version": bundle.version()})
    response["Cache-Control"] = "no-store"
    return response

このエンドポイントは本番ではbucket:<version>を、イメージから配信しているときはfilesystemを返します。Flyのマシンはそれぞれ自分について答えるので、十数回叩けば全体が収束したか分かります。何かおかしいときに、どのマシンが何を本番だと思っているかを確かめる一番手っ取り早い方法でもあります。

CloudflareのキャッシュをAPIでパージする

#

サイトのHTMLはCloudflareのエッジで5分間キャッシュされます。パージしないと、デプロイはマシン上では動いているのに、ほとんどの訪問者は最大5分間古いページを受け取り続けることになり、これでは意味がありません。

パージはAPI呼び出し1回です。

urllib.request.Request(
    f"https://api.cloudflare.com/client/v4/zones/{zone}/purge_cache",
    data=json.dumps({"hosts": ["example.com", "www.example.com"]}).encode(),
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)

ページを全部列挙しなくて済むように、URLではなくホスト単位でパージしています。アセットはそもそもパージ不要です。ファイル名に内容のハッシュが付いているので、新しいビルドは新しいファイル名を指し、古いものは参照されなくなるだけです。更新が必要なのは、そのファイル名を参照しているHTMLだけです。

スクリプトがパージの 前に マシンを待つのは意図的です。先にパージすると、Cloudflareがまだ古いバージョンのマシンからキャッシュを埋め直してしまい、そのページがさらに5分間エッジに居座ることになります。

パージが失敗した場合、スクリプトは警告を出してそのまま完了します。キャッシュは5分以内に勝手に切れるので、最悪でもリリースが遅いだけで、壊れはしません。最後の工程でデプロイが中断されるよりはそのほうがいいと思っています。

本番にする前にビルドを確認する

#

書き換えなしのモードは、ステップ3までやって止まります。バージョンはバケットにあるけれど、何も配信していない状態です。中身を見るときは、マシン1台に環境変数を1つ設定します。web/currentが何と言おうと、そのマシンはそのビルドに固定されます。問題なければロールバックのコマンドで現行にします。名前はロールバックですが実際は「currentをこのバージョンに向ける」で、前に進むのも戻るのも同じ操作です。

ロールバック

#

古いバージョンはバケットに残っているので、ロールバックは同じコマンドを前のバージョンで実行するだけで、一覧表示のコマンドで何があるかが新しい順に見られます。前に進むデプロイと同じ待機とパージをします。まだ使う機会はありません。今のところ古いバージョンを消す仕組みはなく、小さいですし、ないよりあるほうがいいと思っています。

変わっていないこと

#

APIは今も専用のデプロイスクリプトで以前のやり方でデプロイしていますし、そうあるべきです。状態を持っていて、マイグレーションが走る場所ですから。Dockerfileも今まで通り2つのフロントエンドのビルドをイメージにコピーしています。これは意図的です。バケットの設定がない場合（ローカル開発やテストスイート）やバケットが読めない場合、配信の層はディスク上のそのディレクトリに倒れるので、ストレージ障害が起きても訪問者にはエラーページではなく最後のイメージと一緒に出たフロントエンドが届きます。バケットを一時的に外す必要があれば、環境変数1つで本番にその挙動を強制できます。

フロントエンドはAPIよりずっと頻繁に変わり、リリース1回が7分ではなく1分ほどになりました。意識しなくても、まとめて出す癖はなくなりました。

私が作っているマーケットプレイスアプリは、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つのリストで一致しなければならないなら、どちら向きの誤りが安全かを見極め、それを両方の写しの隣に書いてください。「ずれてよい、ただし許されるずれ方はこれだけ」のほうが、ずれない前提より優れています。
• ボットはベンダー名ではなくボット名でマッチさせること。 特に英語圏の外では、そのベンダーがユーザーの手元のブラウザも作っています。
• 離れた定数のあいだの不変条件は、大きな音で失敗する場所に置くこと。 インポート時はタダで、誰もスキップできません。

追記（2026年11月4日）：もうひとつ訂正です。これらの504は、オリジンが応答できなかったプローブではありません。Cloudflare自身のEarly Hintsのキャッシュ参照で、オリジンには一切届かず、そこでの504はそのURLに何もキャッシュされていなかったことを意味するだけです。Early Hintsをオフにしたのも最善の対処ではありませんでした。Linkレスポンスヘッダーを送ると機能が動き始め、これらのミスはヒットに変わりました。詳しくは「Cloudflareの504エラーは障害ではなかった：Early Hints（HTTP 103）とは」にまとめました。

結論から書くと、ゼロスケール（auto_stop_machines）のデメリットはコールドスタートの待ち時間です。停止中のFly.ioマシンにリクエストが来ると起動が終わるまで待たされます。私の環境では、マシンが起動するたびにentrypointがDjangoのマイグレーションとcollectstaticを実行し、バイトコードもどこにもキャッシュされていなかったので、25〜33秒かかっていました。この作業をイメージごとに1回だけ（FLY_IMAGE_REFをキーにしたRedisのロックで）実行し、ビルド時にcompileallを走らせるとコールドブートは約9秒に。さらにauto_stop_machinesを'stop'から'suspend'に変えたところ（そのためにswapを外す必要がありました）、復帰は約3秒になりました。

Cloudflare のダッシュボードでトラフィックの急増を調べに行ったら、その下にもっとひどいものが埋まっていました。1日のうちにアプリが処理したリクエストの22%が失敗していたのです。アラートは一つも鳴っていません。ヘルスチェックはすべて緑。ログも完全に健全に見えました。失敗したリクエストが、そもそもアプリケーションに届いていなかったからです。

原因は自分で書いたコンテナの起動スクリプトでした。まっとうな処理を、まったく間違ったタイミングで実行していました。

急増は囮だった

#

もともと調べたかったのは、中央値が毎時121件のところに約4,900件が集中した1時間です。ユニークな訪問者は42人。1人あたり110リクエストで、人間のブラウジングではありません。

スキャナーでした。ボットが1体、存在しないサブドメインをでっち上げながら、それぞれにシークレットを要求して回っていました。

api-stage-asia.example.com/.env.local
api-us-east-1-demo.example.com/.env
api-eu-uat.example.com/wp-config.php~
app-test-us-east-1.example.com/actuator/configprops
prod-api-use2.example.com/.env.local
relay.example.com/.env.production

30ほどのホスト名、思いつく限りの .env の変種、そして Django アプリに向けた、ある Java フレームワークの actuator エンドポイント。すべて正規ホストへの301になり、何も返していません。退屈で、実際に無害でした。

ただ、分析画面を開いたついでに同じ日をステータスコードで集計しました。本当の問題はそこにありました。

22%です。しかもサイト全体に均等ではなく、いちばん痛いところに正確に集中していました。

どれもモバイルアプリが30秒ごとにポーリングしているエンドポイントです。つまりこれは抽象的なエラー率の数字ではありませんでした。ユーザーの端末が1日中、おそらく何週間も、未読バッジを静かに読み込めずにいたということです。

ログが健全に見えた理由

#

最初はアプリが遅くなったのだろうと考えました。違いました。最悪の時間帯のアプリケーション側のリクエストログをアーカイブから取り出しました。

[2026-09-08 01:00:29] "GET /api/notifications/unread/" 304 61.615
[2026-09-08 01:00:29] "GET /api/notifications/"        304 63.568
[2026-09-08 01:00:59] "GET /api/notifications/unread/" 304 58.742
[2026-09-08 01:00:59] "GET /api/notifications/"        304 105.438

44〜105ミリ秒、すべて304。オリジンは速かったのです。

これが重要な手がかりで、ルールとして書いておく価値があります。エッジがオリジンの知らないエラーを報告しているなら、リクエストは到達する前に死んでいます。 アプリケーションログを読むのをやめて、その手前にあるものを見てください。

私の場合は Fly.io のプロキシで、答えはマシンのスケジューリング方法にありました。

ゼロスケールはコストの約束であって、レイテンシの約束ではない

#

私の設定はこうです。一見すると妥当でしょう。

[http_service]
  auto_stop_machines = 'stop'
  auto_start_machines = true
  min_machines_running = 1

アイドルのマシンは停止し、トラフィックが来れば再び起動する。使った分だけ払う。トラフィックにムラのある小さなアプリならまさに望む挙動で、だからこそマシンを10台定義していても普段は1台しか動いていませんでした。

この方式が隠している請求書はレイテンシです。停止中のマシンにリクエストが来れば、誰かがそのマシンの起動を待つことになります。起動がプロキシの我慢より長ければ、その誰かは504を受け取ります。

では私のマシンの起動には何秒かかっていたのか。一度も測っていませんでした。ログアーカイブは知っています。起動スクリプトが各フェーズを出力し、すべての行にマシンIDが付いているからです。

WITH s AS (
  SELECT instance, timestamp,
         CASE WHEN message ILIKE '%Starting app server%' THEN 'begin'
              WHEN message ILIKE '%Migrations complete%' THEN 'migrated'
              WHEN message LIKE  '%"GET /healthz%'       THEN 'serving' END AS phase
  FROM logs
  WHERE app = 'myapp' AND timestamp::date = '2026-09-08'
)
SELECT instance,
       min(timestamp) FILTER (WHERE phase = 'begin')    AS started,
       min(timestamp) FILTER (WHERE phase = 'migrated') AS migrated,
       min(timestamp) FILTER (WHERE phase = 'serving')  AS first_serve
FROM s GROUP BY instance

すべてのマシンで一貫して出た答えです。

そして、それが何回起きているかを数えました。

SELECT count(*) AS starts, count(DISTINCT instance) AS machines
FROM logs
WHERE app = 'myapp' AND timestamp::date = '2026-09-08'
  AND message ILIKE '%Starting app server%'
-- starts: 92, machines: 10

1日にコールドスタートが92回。そのたびに、そのマシンへ振られたリクエストがタイムアウトする30秒の窓が開いていました。22%はもう謎ではありません。

原因は自分の entrypoint の中にあった

#

すべてのマシンが、リクエストを1件処理する前に実行していたものです。

# entrypoint.sh, run on every machine start
echo "Running migrations..."
python manage.py migrate --noinput

echo "Running collectstatic in background..."
python manage.py collectstatic --noinput &

exec "$@"    # then start the app server

「1日に92回」を思い浮かべながらもう一度読んでみてください。

migrate は完全な Django の起動です。全モデルをインポートし、Postgres に接続し、マイグレーションテーブルを問い合わせ、やることがないと判断する。共有CPUでは、何も達成しないために10秒かかります。collectstatic は2回目の完全な Django 起動で、そのうえ静的ファイルをオブジェクトストレージにアップロードし、Web サーバーが立ち上がろうとしているまさに同じ単一コアを奪い合います。アプリサーバーが3回目の起動です。

Python インタプリタが3つ、うち2つはすでに済んだ作業を繰り返しながら、マシンが目覚めるたびに毎回。

そう書いた理由はまっとうで、同じような形になっているコードは多いはずです。マイグレーションはどこかで走らせる必要があり、Fly の release_command は以前ハングしたことがあり、entrypoint はデプロイ時に必ず実行される唯一の場所だからです。デプロイ作業を置く場所としては正しい。ただマシン起動ごとに置く場所としては正しくない。そしてマシンが自分で止まったり起きたりし始めた瞬間、その2つはもう同じ出来事ではありません。

バグの全体はこれで、よくある種類だと思います。

リリースに属する作業が、マシン起動ごとに実行されていました。ゼロスケールが1つの出来事を92個に変えたのです。

解法: リリースを一度だけ確保する

#

あるイメージで起動する8台目のマシンでマイグレーションが走る必要はありません。そのイメージについて一度走ればよく、残りはそれが済んだと知ればよいだけです。

つまり、デプロイごとに名前が変わるロックです。Fly はその名前を FLY_IMAGE_REF として無料で渡してくれますし、Redis はすでにありました。全体が Django より前に走る小さなスクリプトなので、よくあるケースの答えはフレームワークの起動ではなくミリ秒で済みます。

# release_gate.py: runs before Django exists. Exit code 0 means "prepare this release".
import os, time

PREPARE, SKIP = 0, 1
LOCK_TTL, WAIT, POLL = 300, 240, 2
_sleep, _monotonic = time.sleep, time.monotonic    # aliases, so tests can replace them


def release_id() -> str:
    """Something that changes exactly when the deployed image does."""
    return os.getenv("FLY_IMAGE_REF") or os.getenv("FLY_MACHINE_VERSION") or ""


def claim(client, release: str) -> int:
    if client is None or not release:   # no Redis, or no idea which release: behave as before
        return PREPARE
    done_key, lock_key = f"release:{release}:done", f"release:{release}:lock"
    if client.get(done_key):            # somebody already did it for this image
        return SKIP

    owner = os.getenv("FLY_MACHINE_ID", "unknown")
    if client.set(lock_key, owner, nx=True, ex=LOCK_TTL):
        return PREPARE                  # we won the race; we do the work

    # Someone else is preparing. Wait for them, because serving requests
    # against a half-migrated schema is worse than starting slowly.
    deadline = _monotonic() + WAIT
    while _monotonic() < deadline:
        _sleep(POLL)
        if client.get(done_key):
            return SKIP
        if client.set(lock_key, owner, nx=True, ex=LOCK_TTL):
            return PREPARE              # the owner died and its lock expired; take over
    return PREPARE                      # waited long enough; do it ourselves

# ... plus `done` (sets done_key) and a main() that treats any Redis error as PREPARE