第5章 デプロイと運用

学習目標

• プレビューデプロイと本番デプロイが、それぞれどのような条件で作られ、何に使われるかを説明する。
• 環境ごとに環境変数を設定し、いつ反映されるかを理解する。
• デプロイ前の点検と直後の確認を、自分のアプリに合わせて作り、使う。
• 障害が起きたら、ログで発生時点と場所を絞り込み、まず直前の正常なバージョンへ復旧する。
• ロールバック後に変わる点と、ロールバックでは元に戻らないもの（データ、設定）を区別する。

はじめに

金曜日の夜7時、1人で運営する予約アプリに新機能をデプロイした開発者が、10分後に「ログインできません」というメッセージを受け取ります。このとき、取れる行動は2つです。原因が見つかるまで本番の画面に張り付いて修正するか、1分以内に昨日の正常なバージョンに戻してから、落ち着いて原因を探すかです。前者はユーザーが障害に遭う時間を長引かせ、急いで修正したコードが2つ目の障害を招くこともあります。

デプロイは運用の始まりです。公開した瞬間から、実際のユーザー、データ、費用が関わるため、3つの準備が必要です。公開前にユーザーと同じ条件で確かめる方法、問題に気づく方法、そして戻る方法です。

この章は、個人開発者によく使われているVercelを例に、これら3つを扱います。プレビューと本番の違い、環境変数、デプロイの前後の点検、ログとモニタリング、ロールバックと障害対応を順番に見ます。「さらに深く」では、データの変更、段階的な公開、無料プランにおける運用の制約を確認します。プラットフォームが異なっても、原理は同じです。

重要な概念

デプロイが行うこと

デプロイ（deployment）は、自分のコンピューターで動くアプリをインターネット上に公開し、誰でも使えるようにすることです。お客さまを迎える実店舗が本番（production、運用環境）、開店前に知人だけを招くリハーサル会場がプレビュー（preview）です。リハーサルで問題を見つければ、本番のお客さまはその不具合に遭遇せずに済みます。

Vercelのドキュメントは、デプロイを「プロジェクトのビルドに成功した結果」と定義し、デプロイするたびに固有のURLが作られると説明しています。デプロイは、Gitのプッシュ、CLI、デプロイフック、REST APIで作ることができます。大切な性質は、デプロイが1つずつ別々に保管されることです。新しいデプロイを作っても、以前のデプロイは保存ポリシーに従って削除されるまでそのまま残り、ドメインがどのデプロイを指すかだけが変わります。ロールバックが速い理由は、ここにあります。

プレビューと本番

Vercelのドキュメントで確認した基本的な動作は、次のとおりです。

初回のデプロイのルールは、意外な結果を生みます。機能ブランチから初めて接続してデプロイしても、そのデプロイが本番になります。新しいプロジェクトに、すぐに本番ドメインを割り当てられるようにするための設計です。

プレビューURLには2種類あります。ブランチURLは、そのブランチの最新のデプロイを指し続け、コミットURLは、特定のコミットのデプロイを固定して指します。「常に最新の作業」を見せるときはブランチURLを、特定の時点を比較したり記録したりするときはコミットURLを使います。ProとEnterpriseのプランでは、stagingなどのカスタム環境を別に作ることもできます。

プレビューを共有するとき

プレビューはリハーサルの舞台ですが、インターネットに開かれた舞台でもあります。URLを知っている人が入れるなら、プレビューに表示されるデータや機能がそのまま露出します。VercelのDeployment Protectionは、誰がデプロイURLにアクセスできるかを決めます。ドキュメントによると、推奨される保護範囲であるStandard Protectionは、本番ドメインを除くすべてのデプロイを保護し、すべてのプランで使えます。保護方法のうち、Vercel Authenticationは適切な権限を持つVercelユーザーだけが入れるようにし、パスワード保護はHobbyプランでは使えません。

プレビューで守るべき原則は、3つあります。

1. プレビューにはテスト用のキーとテスト用のデータベースを使います。実際の決済や実際のメール送信が行われないようにします。
2. 外部の人に見せるときは、保護を無効にする代わりに、プラットフォームが提供するアクセス方法を使います。
3. プレビューの画面に実際の個人情報が表示されていないか、共有する前に確認します。

環境ごとに異なる環境変数

Vercelでは、Production、Preview、Development（ローカル）、そしてカスタム環境ごとに、環境変数を別々に設定します。同じ名前の変数でも環境ごとに異なる値を設定できるので、プレビューにはテスト用の決済キーを、本番には実際の決済キーを入れる、といった使い方をします。Previewの変数は特定のブランチにだけ別の値を設定することもでき、ブランチごとの値が、同じ名前の一般のPreviewの値を上書きします。ローカル開発用の値はvercel env pullで取得しますが、取得したenvファイルが.gitignoreに含まれるかを先に確認します。変数ごとに、Config（権限のあるメンバーが読み取れる）とSecret（保存後は書き込みだけが可能）の種類を選ぶこともできます。

新しい機能が新しい環境変数を使うなら、その変数が必要なすべての環境に設定されているかを確認します。Previewだけに設定してProductionを忘れると、プレビューでは動いていた機能が本番で失敗し、逆ならプレビューで失敗します。

開発サーバーとビルドは違う

開発サーバー（npm run dev）で問題なく動いていたアプリが、デプロイで失敗することはよくあります。デプロイでは開発サーバーではなく、ビルド（npm run build）を経るため、ビルド段階でしか現れないエラーがあるからです。型エラーでビルドが止まる、ビルド中に事前レンダリングされるページがまだ存在しないデータを参照する、ビルド時に必要な環境変数が不足している、といった場合です。デプロイ前には、ローカルでも一度ビルドコマンドを実行します。

Vercelでは、ビルドログはデプロイ画面で、ランタイムログ（アプリが実行中に残す記録）はLogs画面で確認します。ビルドは成功したのに、特定の機能だけが500を返すなら、ランタイムログを見ます。

デプロイ前の点検

点検表には、チェックの印だけでなく、確認したことと確認できなかったことを一緒に書きます（第2章）。

デプロイ直後の確認

デプロイ成功の表示はビルドが終わったというだけで、ユーザーが使えるという意味ではありません。直後の数分以内に主要な流れを素早く確かめることをスモークテスト（smoke test）と呼びます。新しい機械を動かしたとき、まず煙が出ないかを見ることに由来します。本番のアドレスを開き、ログインし、主要機能を1回実行し、再読み込みで保存結果を確かめ、コンソールとランタイムログに新しいエラーがないかを見ます。

本番設定で作ったデプロイをユーザーに公開する前に確認したい場合は、Vercelの段階的な本番デプロイを使います。ドキュメントによると、Environments設定のProductionでBranch Trackingを開き、Auto-assign Custom Production Domainsを無効にすると、本番ブランチのデプロイが作成されても、すぐには本番ドメインへ接続されず、手動での昇格を待ちます。生成されたデプロイURLで確認してから昇格（promote）すると、再ビルドせずに、ドメインの参照先だけがそのデプロイに移ります。ただし、このデプロイは本番用の環境変数を使い、実際の本番サービスや本番データにアクセスする点に注意してください。

ログとモニタリング

ログは、アプリが実行中に残す記録で、モニタリングは、エラー率や応答時間などの指標を継続的に見守ることです。両者の役割は異なります。モニタリングは「何かがおかしい」ことを知らせ、ログは「何が、どこでおかしいか」を教えます。

Vercelのランタイムログでは、関数の呼び出し記録とconsole.logの出力が、リクエスト単位にまとめられます。ドキュメントによると、ステータスコード400番台のリクエストは警告、500番台のリクエストはエラーと表示されます。パス、ステータスコード、環境、ブランチ、デプロイなどで絞り込むこともできます。CLIのvercel logsは、既定では最近30分間の最新100件を表示します。それ以前のログを見るには--sinceで範囲を広げ、特定のデプロイだけを見るには--deploymentで指定します。

障害が起きたら、推測で修正する前に、ログで3つの点を確認します。いつから、どの要求で、どんなエラーが起きたかです。エラーが増えた時刻がデプロイの時刻と重なるなら、そのデプロイが最も有力な原因です。

ログには保存期間があるため、確認が遅れると消えている場合があります。そのため、主要アドレスの定期的な外部チェック、エラー率上昇時の通知、長期記録を送る外部ストレージを設けます。通知時に誰が何をするかまで決めて、モニタリングは完成します。

ロールバック：直前の正常なバージョンに戻る

ロールバック（rollback）は、問題が起きたデプロイの代わりに、以前の正常なデプロイへ戻すことです。VercelのInstant Rollbackは、再ビルドせず、ドメインを以前の本番デプロイに即座に戻します。公式ドキュメントで確認した注意点は、次のとおりです。

• ロールバックしたデプロイは、その当時の設定に戻ります。プロジェクト設定で変更した環境変数は反映されず、cronジョブの定義も、そのデプロイのものに戻ります。
• ロールバック後は、本番ドメインの自動割り当てが無効になります。本番ブランチに新しいコミットが入っても、本番ドメインはロールバックしたデプロイを指したままです。通常の流れに戻るには、ダッシュボードのUndo Rollbackか、vercel promoteで別のデプロイを昇格させます。
• Hobbyプランでは直前のデプロイにだけ、ProとEnterpriseでは、本番ドメインに接続されたことがあるデプロイならどれにでもロールバックできます。本番に接続されたことがないプレビューデプロイは対象外です。
• ロールバックの確認段階では、外部APIとデータベースの動作の変化について注意が促されます。ロールバックはコードを元に戻すだけで、データを元に戻すものではありません。

ロールバックは、プラットフォーム上のデプロイを元に戻すだけで、Gitの履歴はそのままです。問題のあるコミットは依然としてmainに残っているため、次のデプロイが同じ問題を再び公開しないよう、修正コミットを送るか、問題のコミットをrevertします（第3章）。

障害対応の順序

障害が起きたときの順序は、救急室での順序と同じです。原因を解明する前に、まず出血を止めます。

1. 影響を確認する。 どの機能が、いつから、どれだけのユーザーに対して失敗しているかを確認します。
2. 復旧する。 最近のデプロイが有力な原因で、データ構造の変更がなければ、直前の正常なデプロイへロールバックします。
3. 原因を探す。 ランタイムログとdiffで原因を絞り込みます。本番の画面ではなく、ブランチで作業します。
4. 修正して検証する。 修正した内容をプレビューで確認します。
5. 通常の流れに戻す。 修正したデプロイを昇格させ、自動割り当てを再び有効にして、スモークテストを行います。
6. 記録する。 何がなぜ起きたか、何を変えて再発を防ぐかを書きます。点検表に1行加えることも、良い成果です。

さらに深く

コードは戻っても、データは戻らない

ロールバックが魔法のように感じられるのは、コードに対してだけです。新しいデプロイがデータベースの列名を変更したり、列を削除したりしていた場合、ロールバックした古いコードは、存在しない列を参照して失敗します。新しいコードが新しい形式で書き込んだデータを、古いコードでは読めないこともあります。時計を戻しても、その間に届いた荷物はそのまま残るのと同じです。

そのため、データ構造の変更は、どの時点でロールバックしてもアプリが壊れないよう、複数回のデプロイに分けます。一般に、拡張–縮小（expand–contract）方式と呼ばれます。

1. 拡張：新しい列を追加する。古い列は残す。
2. 両方に書く：新コードは両方に書き、読み取りは新しい列を優先し、なければ古い列を読む。
3. 移す：既存データを新しい列にコピーする。
4. 切り替え：新しい列だけを読み書きするコードに変える。
5. 縮小：どのコードも古い列を使わないと確認してから削除する。

各段階は、その直前の段階のコードと共存できるため、どのデプロイからロールバックしても、データとコードの整合性が保たれます。削除は最後に、元へ戻す必要がないと確信してから行います。データを削除したり上書きしたりするデプロイの前には、別途、バックアップと復元の確認が必要です。プレビューと本番が同じデータベースを使う場合は、プレビューのビルドだけで本番データが変更されるおそれがあるため、ビルド時にマイグレーションを実行する設定は避けます。

少しずつ公開する

すべてのユーザーに、新しいバージョンを一度に公開しない方法もあります。

機能フラグ（feature flag）は、コードには機能を組み込みながら、スイッチのオン・オフでユーザーに見せるかどうかを決める方法です。未完成の機能もオフにしたままmainへ頻繁にマージできるため、長期間維持する機能ブランチのマージ競合を減らせます。問題が起きたときは、デプロイせずにスイッチをオフにするだけで機能を無効にできます。

機能1つではなく、アプリ全体が一緒に変わるデプロイでは、ユーザーを分けて公開します。VercelのRolling Releases（ProとEnterprise）は、最初は訪問者の一部（例：10%）だけに新しいデプロイを送り、残りの訪問者は以前のデプロイにとどめ、2つのデプロイの指標を並べて比較できるようにします。段階を上げて100%まで昇格させるか、問題が見つかったらInstant Rollbackで元に戻します。

デプロイが切り替わる瞬間には、バージョンのずれ（version skew）も生じます。ユーザーのブラウザには古いバージョンのクライアントコードがあり、サーバー側は新しいバージョンという状態です。Vercelのドキュメントは、これをクライアントとサーバーが異なるバージョンで動くことでエラーが起きる現象と説明しています。Skew Protection（ProとEnterprise）は、同じデプロイのクライアントとサーバーの間で通信できるようにします。この固定の対象は、フレームワークが管理するリクエスト（静的ファイル、画面遷移、Server Actionsなど）です。自分で書いたfetch()リクエストには、別途デプロイIDを付ける必要があります。これらのプランで、2024年11月19日以降に対応フレームワークで作ったプロジェクトでは既定で有効で、Rolling Releasesを使う場合は併せて有効にするよう推奨しています。

小さなアプリの運用制約

無料プランで始めるアプリには、運用ツールにも制約があります。制約を知らないと、障害が起きたあとで初めて知ることになります。確認時点のVercelのドキュメントに基づく代表的なものは、次のとおりです。

短い保存期間ほど通知と外部記録が重要です。Hobbyのcronは指定した時刻から59分以内のいずれかの時点で動くので、正確な時刻を要する用途に向きません。数値は変わるため、暗記するより、プラン選択時にアプリの運用要件と制約を公式ドキュメントで照合します。

実務の場面

星明かり天文台：ドメインを接続する前に

観測体験の予約を受け付ける「星明かり天文台」の運営者チさんは、初めて予約金の決済機能を追加し、公開日を決めました。プレビューではテスト決済が問題なくでき、テストとビルドも通りました。チさんは、そのままmainにマージしようとして手を止めました。プレビューはテスト用のキーで動いていましたが、本番は初めて使う実際の決済キーと、実際のSMS送信キーで動きます。その組み合わせは、まだ誰も確認していませんでした。

チさんが検討した選択肢は、3つでした。

• すぐにマージする：プレビューで通ったので、本番でも動くはずだという期待です。しかし、環境変数と外部連携は環境ごとに異なります。最初の実際のお客さまが、試験の対象になってしまいます。この案は退けました。
• 本番ドメインで試し、問題があればロールバックする：確認はできますが、試している間はお客さまも同じ画面を使います。この案は退けました。
• 段階的な本番デプロイ：本番の設定でデプロイしますが、ドメインの接続は後に回します。この方法を選びました。

チさんはProductionのBranch TrackingでAuto-assign Custom Production Domainsを無効にし、mainへマージしました。本番デプロイは作られましたが、ドメインは以前のものを指したままでした。生成されたデプロイURLで少額の実決済による予約を試すと、決済と予約は成功しても、お客さまへの予約確定SMSが届きませんでした。ランタイムログには、SMS送信段階でAPIキーがないと記録されていました。SMS_API_KEYをPreviewだけに設定していたのです。

チさんはProductionに値を設定し、変更は新しいデプロイだけに反映されることを思い出して、もう一度デプロイしました。新しいデプロイURLで決済、予約、予約確定のSMSまで確認してから、そのデプロイを昇格させました。再ビルドは行われず、ドメインの参照先だけが移りました。最後に試験の決済を返金し、自動割り当てを再び有効にしました。点検表の環境変数の行は、「新しい変数がProductionにあるか」から、「新しい変数が使われるすべての環境にあるか、本番デプロイURLで確認したか」に変わりました。

波のプール：土曜朝の500

レッスン申し込みアプリを運営する「波のプール」の開発者ヒョンさんは、土曜日の午前9時に「キャンセル待ち」機能をデプロイしました。9時12分に、通知が届きました。/api/lessonsのパスで、500エラーが普段の数十倍に増えていました。

ヒョンさんはまず影響を確認しました。ランタイムログをステータスコード500と該当パスで絞ると、9時2分から同じエラーが繰り返されていました。デプロイの時刻と重なっていました。レッスン一覧が全く開かず、大半の会員が影響を受けていました。今回のデプロイには、データベースのテーブルを変える作業は含まれていませんでした。

ヒョンさんは原因を調べる前に、ダッシュボードで直前の正常なデプロイへのInstant Rollbackを実行し、1分以内に一覧が再び開くようになりました。ロールバック後には自動割り当てが無効になると知っていたため、点検表の「ロールバック中」の欄に印を付けておきました。

その後で初めて原因を調べました。エラーはCannot read properties of undefined (reading 'length')で、新しいコードが各レッスンのキャンセル待ち一覧を読む行でした。一覧は任意項目なのに、常にあると仮定していました。機能導入前のレッスンには一覧自体がありません。プレビューのテストデータは新規レッスンだけだったので、見逃したのです。

ヒョンさんは機能ブランチで、一覧がなければ空の一覧として扱うように修正し、古いレッスンを模したテストデータを追加してテストを書きました。プレビューで新旧両方のレッスンを開いてからマージしました。予想どおり、本番画面は依然として戻した版のままでした。新しい本番デプロイを昇格してロールバック状態を解除し、スモークテスト後に点検表の印を消しました。

障害記録には3行が残りました。何が起きたか（既存データにないフィールドを読んだ）、なぜプレビューで見逃したか（テストデータが新しいものだけだった）、何を変えるか（プレビューに古い形式のサンプルを含める）。障害は12分、復旧は1分、修正は1時間でした。順番が逆なら、障害が1時間になっていたでしょう。

間違えやすいポイント

1. 「プレビューで動いたので本番でも動く。」 同じコードなら同じ結果になると思えます。しかし環境変数、外部連携、データは環境ごとに異なります。プレビュー通過は必要条件にすぎません。
2. 「環境変数を直せばすぐ反映される。」 設定画面で保存すれば終わりに思えます。しかし変更が適用されるのは新しいデプロイだけです。修正後に再デプロイします。
3. 「ロールバックすればデータも以前に戻る。」 「戻す」という名前から、全部戻るように思えます。しかし戻るのはコードとデプロイ当時の設定だけです。データ構造を変えたなら、まず互換性を確認します。
4. 「障害が起きたら、本番ですぐ直す。」 原因さえ見つければ早く終わりそうに思えます。しかし原因が不明なまま直すと障害が長引き、急な修正が新しい障害を招きます。先に直前の正常なデプロイへ復旧し、原因はブランチで探します。
5. 「ロールバック後は、修正コードをmainに送るだけでよい。」 普段どおりプッシュすれば反映されそうです。しかしロールバック後は自動割り当てが無効になっています。修正したデプロイを昇格して、通常の流れに戻します。
6. 「ビルドが成功したのでデプロイは成功だ。」 緑色の表示は安心を与えます。しかしビルド成功は、実行中にエラーがない保証ではありません。直後のスモークテストとランタイムログの確認が別途必要です。

ひと目でわかるまとめ

公式ドキュメントで確認する

• Vercel: Deployments — デプロイの定義、デプロイする方法、昇格
• Vercel: Environments — プレビューと本番が作られる条件、初回デプロイのルール、URLの種類、段階的な本番デプロイ
• Vercel: Environment variables — 環境ごとの変数、新しいデプロイだけに反映される変更
• Vercel: Deployment Protection — 保護範囲と方法、プラン別の提供
• Vercel: Runtime Logs — ログの絞り込み、vercel logs、プランごとの保存期間
• Vercel: Instant Rollback — ロールバックの動作、自動割り当ての解除と通常の流れへの復帰、プランごとの範囲
• Vercel: Rolling Releases — 一部のトラフィックへの先行公開
• Vercel: Usage & Pricing for Cron Jobs — プランごとのcronジョブの間隔と精度

セルフチェック

5-1. 新しいプロジェクトをVercelに初めて接続し、機能ブランチからvercelを--prodなしで実行しました。この初回はプレビューと本番のどちらですか。以後はどんなルールが適用されるかも説明してください。

5-2. 外注デザイナーに作業中の画面を見せます。デザイナーは数日間、随時アクセスして「常に最新の状態」を見たいと考えています。ブランチURLとコミットURLのどちらを共有しますか。もう一方の用途も説明してください。

5-3. 先週のデプロイへロールバックしたあと、今日プロジェクト設定で環境変数を1つ変えました。新しい値は現在稼働中のデプロイに適用されますか。本番に反映する方法を説明してください。

5-4. HobbyとProで、Instant Rollbackの対象に選べるデプロイの範囲をそれぞれ説明してください。

5-5. 2時間前のエラーを見るためにターミナルでvercel logs --environment productionを実行しても、その時刻の記録が見えません。既定の取得範囲と、過去の記録を見るために加えるオプションを説明してください。

5-6. 本番の環境変数でビルドしたデプロイを、本番ドメインに接続する前に自分で確認したい場合、Vercelで変更する設定と手順を説明してください。確認後の昇格では再ビルドされるかも答えてください。

5-7. 自分のアプリ（または練習用アプリ）に合うデプロイ前点検表を6行で作ってください。チェック、プレビューの流れ、環境変数、データ、外部連携、復旧地点を、それぞれ一行ずつ、実際の機能名を入れて書いてください。

実習課題