株式会社renue
renueについて
renueは、AIで業務を実装する会社です
AIコンサルティングから図面AI・広告運用エージェント・コールセンターAIまで、実際に動いているサービスをご覧いただけます。renueが何をしている会社か、まずはサービス一覧からご確認ください。
デプロイが通らない——6ステージのどこで止まっているかを特定せよ
「デプロイが動かない」「本番に反映されない」——この報告を受けたとき、最初にやるべきことは6ステージのどこでコケているかを特定することです。闇雲にログを見たり、再デプロイを繰り返しても問題は解決しません。
デプロイトラブルに直面した新人エンジニアには、事故対応のたびに原因と復旧手順を理解し、学びを次の対応に生かす視点が役立ちます。本記事では、確認する場所を整理するために、以下の6ステージで切り分けます。
デプロイの6ステージ
1. PR立てる 2. PRマージ 3. ビルド 4. デプロイ 5. イメージpull 6. 再起動
デプロイ障害の切り分けは、この6ステージのどこで止まっているかを上から順に確認することが基本です。
各ステージの典型的な障害パターン
ステージ1-2：PRとマージ
| 障害 | 原因 | 対策 |
|---|---|---|
| マージできない | コンフリクトが発生している | ベースブランチを最新化してコンフリクト解消 |
| CIが通らない | テスト失敗・lint エラー | ローカルでCI相当のチェックを実行してから push |
ステージ3：ビルド
ビルドは最も障害が発生しやすいステージです。
| 障害 | 原因 | 対策 |
|---|---|---|
| ビルド失敗 | CIが不十分でビルド不可能なマージが通った | CI にビルドチェックを追加 |
| 依存解決エラー | パッケージ追加やDockerfile編集時に発生しがち | lockfile を更新してコミット |
| ローカルで成功するがCIで失敗 | ベースイメージ・OS・環境変数の差異 | ベースイメージをダイジェストでピン留め |
| リソース不足 | CPU/メモリ/ディスク制約でOOMやファイル書き込みエラー | ビルドエージェントのリソースを確認・拡張 |
ステージ4：デプロイ
| 障害 | 原因 | 対策 |
|---|---|---|
yarn build成功だがデプロイ失敗 | デプロイ環境固有のエラー | デプロイログを確認し環境差分を特定 |
| マイグレーション失敗 | DB スキーマ変更が既存データと衝突 | 追加する制約を既存データが満たすかを検証し、違反値を修正してから適用。冪等性（繰り返しても結果が変わらない性質）の確保と、既存データの整合性は別に確認 |
ステージ5：イメージpull
| 障害 | 原因 | 対策 |
|---|---|---|
| イメージが見つからない | push先のACR/ECRとVM参照先が異なる | レジストリURLの一致を確認 |
| キャッシュで古いイメージが使われる | latestタグ固定でキャッシュが残る | git commit SHAタグを付与し、デプロイでもそのタグまたは対応するダイジェストを指定 |
| ディスク容量不足 | 旧イメージが残りディスクを圧迫 | pull前にdocker image pruneで整理（既定はタグがなく、どのコンテナからも参照されないdanglingイメージのみ） |
| 認証エラー | ACR/ECRのトークン期限切れ | pull前にdocker loginを再実行 |
VM上に旧イメージが残存してディスクを圧迫していないか、docker system dfでDockerのディスク使用量を確認します。pull時のディスク容量エラーが出ている場合は、空き容量と削除対象を確認してから整理します。
ステージ6：再起動
| 障害 | 原因 | 対策 |
|---|---|---|
| 自動再起動しない | Webhookの設定が不十分 | デプロイフック/Webhookの設定を確認 |
| 起動後にエラー | マイグレーション自動実行でサーバー起動失敗 | マイグレーションと起動を分離 |
| ヘルスチェック通過だが機能エラー | ヘルスチェックがDB接続を含まない | ヘルスチェック内容を拡充、起動時のログ出力も確認 |
特に注意すべきは「ヘルスチェックが通っているのにコア機能が動かない」パターンです。/healthがDB接続チェックを含まない場合、DBの障害を見逃し、「画面は表示されるが、DBを使う主要機能がエラー」という状態を検知できないことがあります。
切り分けの実践手順
ステップ1：直近のGitHub Actionsを確認
まずGitHub Actionsのワークフロー実行ログでジョブとステップの成否を確認し、ステージ1-4のどこで止まっているかを特定します。
ステップ2：コンテナの状態を確認
docker compose ps # コンテナの状態（Up/Exited） docker compose logs --tail=30 # 直近のログ
Up状態でもログにエラーが出ている場合は、ステージ6の問題です。
ステップ3：疎通テスト
curl http://localhost:3000 # FE → 200 or 302 curl http://localhost:8000/health # BE → healthy （フロント経由でのバックエンド疎通も同様に確認）
FE単体は通るがFE→BEが通らない場合は、まずAPI呼び出し元がFEコンテナ内かブラウザ内かを分けます。コンテナ間では共通のComposeネットワーク、サービス名、コンテナ側ポートを確認します。ブラウザからの呼び出しではブラウザから到達できるAPI URLと、別オリジンの場合はCORS設定を確認し、どちらもAPI接続先の設定、BEの待受アドレス・ポート、BEのログを照合します。
ステップ4：Bastionトンネルでブラウザ確認
閉域VM環境では、Bastionトンネル経由でブラウザからアクセスし、画面表示だけでは検知できない問題を拾います。
イメージタグ戦略：latestの罠
Docker イメージをlatestタグだけで管理すると、「どのコミットがデプロイされているかわからない」状態になります。
推奨タグ戦略
docker build \
-t registry.example.com/app:latest \
-t registry.example.com/app:${GIT_SHA} \
.
latestに加えてgit commit SHAのタグを付けてレジストリへpushし、デプロイでもそのSHAタグまたは対応するイメージダイジェストを指定します。SHAタグを上書きしない運用とし、ビルド時のコミット・ダイジェストを記録して実際に起動したイメージと照合すれば、追跡やロールバックに使えます。タグを付けても起動側がlatestを参照したままでは、どのコミットが稼働しているかは確定できません。
ダウンタイム最小化のデプロイ手順
本番環境でのコンテナ更新では、ダウンタイムを最小化する手順が重要です。
- 新イメージをpull（旧コンテナ稼働中）：pull失敗時は旧コンテナが動いたまま→影響なし
- 旧コンテナを停止・削除：ここからダウンタイム開始
- 新コンテナを起動：ヘルスチェックと主要機能への疎通で、利用可能（ready）になったことを確認してダウンタイム終了
- 旧イメージを回収：
docker image prune -fでdanglingイメージを削除。-fは確認省略で、削除対象を広げません。旧SHAタグ付きイメージは残ります。-aを付けると既存コンテナが参照しないタグ付きイメージも対象になるため、ロールバック用に残す世代を確認してから整理します。
pullを停止前に実行すれば、その待ち時間を停止時間から除けます。ダウンタイムは「コンテナ停止→起動→ready確認」の間で、Composeも起動しただけではreadyを待たない点に注意が必要です。所要時間はアプリの初期化、依存サービス、ヘルスチェック間隔で変わるため、更新手順を通して測定します。
Apple Silicon環境の罠
Apple Silicon（M1/M2/M3）のMacでビルドしても、出力イメージの対象プラットフォームはMacの機種だけでは決まりません。対象プラットフォームの既定値はビルドを実行するBuildKitデーモンのものです。linux/arm64向けだけのイメージは、エミュレーションのないLinux AMD64のVMではそのまま動作しません。AMD64向けに配布するなら、--platform linux/amd64を指定するか、amd64を含むマルチプラットフォームイメージをビルドします。
docker build --platform linux/amd64 -t registry/app:latest .
配布先とイメージのアーキテクチャが合わない場合、pull時に一致するmanifestが見つからない、または実行時にエラーになることがあります。push後はdocker buildx imagetools inspectでレジストリ上の対象プラットフォームを確認し、配布先に合うものが含まれているか確かめます。
まとめ：デプロイ障害切り分けチェックリスト
| ステージ | 確認項目 | よくある原因 |
|---|---|---|
| 1. PR | PRが作成できているか | ブランチ保護ルール、権限不足 |
| 2. マージ | コンフリクトなくマージできたか | コンフリクト、CI不通過 |
| 3. ビルド | GitHub Actionsが成功しているか | 依存解決エラー、Dockerfile変更 |
| 4. デプロイ | デプロイジョブが成功しているか | マイグレーション失敗、環境差分 |
| 5. pull | 正しいイメージがpullできているか | レジストリURL不一致、ディスク不足、認証切れ |
| 6. 再起動 | コンテナがUp＋ログにエラーなしか | Webhook未設定、ヘルスチェック不足 |
デプロイ障害は「事故対応して覚える」ものです。しかし、6ステージフレームワークを知っていれば、パニックにならず体系的に切り分けができます。次にデプロイが止まったとき、この6ステージのどこかを必ず確認してください。
関連記事：障害対応・開発プロセスの完全ガイド
障害対応・インフラ連載として、以下の記事も合わせてお読みください。
- エラー読解：エラーメッセージ読解術｜まず簡単な方から試す
- マイグレーション：マルチORM環境のDBマイグレーション管理
- 閉域デプロイ：閉域ネットワーク環境へのAIアプリデプロイ完全ガイド
- Gitワークフロー：AIエージェント時代のGitワークフロー設計
- ポストモーテム：AI開発プロジェクトのポストモーテム設計
AI開発のインフラ・デプロイでお悩みの方は、renueにご相談ください。
