【Day 52】「コンテナが即座に終了する(Exit 0 / Exit 1)」時の原因究明法 〜初心者が最もハマる起動直後クラッシュの完全切り分け!PID 1の終了条件・logs/inspect/entrypoint調査・C#起動時例外ハンドリング&Git差分特定〜
「docker run したのに、1秒後には docker ps から消えている!?」
いよいよ今回から第11部: 現場のトラブルシューティングと運用ノウハウに突入します!
Dockerを現場に導入した開発者が最初に必ず直面し、最も時間を溶かしてしまうトラブル――それが「コンテナを起動したはずなのに、エラー画面すら出さずに即座に終了(Exited)してしまう現象」です。
従来のWindows ServerやVMでは、Webアプリが起動に失敗してもOS自体は動き続けるため、RDP接続してイベントビューアーやIISログをゆっくり確認できました。しかしDockerでは、アプリが落ちた瞬間にコンテナ自体が停止し、docker exec -it で中に入ることもできなくなります。
本講義(Day 52)では、コンテナが終了する絶対条件「PID 1ルール」の理解から、logs / inspect / --entrypoint sh を使ったプロの切り分け3ステップ、そしてC#(Program.cs)の起動時未処理例外対策とGit差分特定まで、即死コンテナを3分で解決する実践ノウハウを徹底解説します!
📋 本講義の目次・学習ロードマップ
- 【図解①】コンテナが即座に終了する根本原因(PID 1の絶対ルール) 〜なぜ裏方起動ではダメなのか?〜
- 【図解②】即死コンテナ原因究明の3ステップ 〜logs ➔ inspect ➔ --entrypoint sh で完全解剖〜
- 【図解③】終了コード(Exit 0 / Exit 1 / Exit 137等)の読み解き方と対策 〜番号が語る真実〜
- 【C#/.NET実践】Program.csの起動時例外ハンドリングとOptions事前検証 〜無言クラッシュの撲滅〜
- 【図解④】Git差分追跡(git diff / git bisect)による原因コミット特定と復旧
- まとめ・FAQ・次回予告
1. コンテナが即座に終了する根本原因(PID 1の絶対ルール)
「イメージのビルドは成功したのに、docker run -d で起動した直後に docker ps を見たら何も表示されない……」
この現象を理解する上で最も重要なのが、「コンテナは仮想マシン(OS)ではなく、隔離された1つの主役プロセス(PID 1)の箱である」という大原則です。
物理サーバーやVM(Hyper-V / VMware)では、OSのカーネルやバックグラウンドサービス群(systemd、Windowsサービス、IIS)が常に動いているため、あるアプリが1つ終了してもサーバー自体は生き続けます。
一方、Dockerコンテナの寿命は「CMD や ENTRYPOINT で起動された最初のプロセス(PID 1)の寿命」と完全にイコールです。
Linuxのサーバー設定に慣れたエンジニアほど、DockerfileのCMDに
service nginx start や ./start.sh & のように「バックグラウンドで起動してすぐ制御を返すコマンド」を書いてしまいがちです。すると何が起きるでしょうか?「起動コマンド(PID 1)」が「裏方でアプリを起動した直後に『仕事完了!』と言って終了(Exit 0)」するため、Dockerは「主役が終わったからコンテナの役割は終わった」と判断して、裏で動き始めたばかりのアプリごとコンテナを即座に終了させてしまいます。
コンテナ内では必ず
dotnet MyApp.dll や nginx -g "daemon off;" のように、フォアグラウンド(前面)で常駐し続けるプロセスを起動しなければなりません。
2. 即死コンテナ原因究明の3ステップ
停止してしまったコンテナに対して docker exec -it my-app bash を実行しても、Error response from daemon: Container ... is not running と怒られて中に入ることができません。
即死コンテナに遭遇した際は、焦ってDockerfileを闇雲に書き換えるのではなく、以下のプロフェッショナルの切り分け3ステップを順番に実行してください。
ステップ①:docker ps -a と docker logs で「最後の遺言」を読む
docker ps は稼働中コンテナしか表示しません。停止したコンテナのIDや名前を確認するには -a オプションを付け、直後に docker logs で標準出力(stdout)・標準エラー出力(stderr)を確認します。これはWindows運用における「イベントビューアー」に相当する最優先の調査です。
# 1. 停止済みコンテナの一覧と終了ステータスを表示
$ docker ps -a
CONTAINER ID IMAGE COMMAND STATUS NAMES
f8e7d6c5b4a3 my-api:v1 "dotnet MyApi.dll" Exited (1) 5 seconds ago api-server
# 2. クラッシュ直前のログ(スタックトレース等)を出力
$ docker logs api-server --tail 100
ステップ②:docker inspect で「終了コード」と「OOMKill」を確定させる
もし docker logs に何も出ていない場合は、docker inspect でコンテナの終了状態メタデータを直接抽出します。特にExitCode(終了コード)とOOMKilled(メモリ上限超過による強制殺害)の確認が決定打になります。
# 終了コード・OOMKilled・エラーメッセージを一発抽出
$ docker inspect api-server --format '{{.State.Status}} | ExitCode={{.State.ExitCode}} | OOM={{.State.OOMKilled}} | Error={{.State.Error}}'
exited | ExitCode=137 | OOM=true | Error=
ステップ③:--entrypoint sh で「起動コマンドを乗っ取り」内部潜入調査
「アプリが即死するせいで中に入って調査できない!」というジレンマを突破する最強の奥義が、--entrypoint sh(または bash)による起動時エントリーポイントの上書きです。本来の dotnet MyApi.dll を実行する代わりにシェルを起動させることで、コンテナを生かしたまま内部のファイル構成・環境変数・権限を調査し、手動でコマンドを叩いてエラーを目の前で再現できます。
# 本来のアプリ起動をスキップし、シェルで使い捨て起動(--rm)
$ docker run -it --rm --entrypoint sh my-api:v1
# Docker Compose環境(ネットワークや環境変数も引き継いで調査したい場合)
$ docker compose run --rm --entrypoint sh web-api
# コンテナ内でファイルを点検し、手動でアプリを起動してみる
/app # ls -la
/app # env | grep ASPNETCORE
/app # dotnet MyApi.dll
3. 終了コード(Exit 0 / Exit 1 / Exit 137等)の読み解き方と対策
docker ps -a の Exited (数字) に表示される終了コードは、コンテナがなぜ止まったのかを教えてくれる重要な診断シグナルです。特に頻出する Exit 0 と Exit 1 の違いを正確に押さえましょう。
| 終了コード | 意味・ステータス | 現場でよくある原因 | 解決策・アクション |
|---|---|---|---|
| Exit 0 | 正常終了 |
・バックグラウンド(デーモン)起動して即制御が返った ・ ubuntu等の汎用イメージをコマンド指定なしで起動した・C#バッチ処理が正常に完了した |
Web系ならフォアグラウンド実行に変更(daemon off;等)。常駐Workerなら無限待機ループやHost.Run()が呼ばれているか確認。
|
| Exit 1 | アプリ異常終了 |
・C#の起動時未処理例外(DB接続失敗・NullReference等) ・ appsettings.jsonや必須環境変数の欠落・ポート権限や設定ファイルの構文エラー |
docker logs で例外メッセージを確認。出ない場合は --entrypoint sh で手動実行して原因を特定。
|
| Exit 126 | 実行権限なし | entrypoint.sh 等のスクリプトに +x(実行権限)が付いていない。 |
Dockerfileで RUN chmod +x ./entrypoint.sh を追加し、Gitの実行ビットを確認。 |
| Exit 127 | コマンド未発見 | パス間違い、Chiseled等にshがない、またはWindowsの改行コードCRLF(^M)の混入。 |
WORKDIR と COPY 先の一致、.gitattributes でのLF固定を確認(Day 54で詳解)。 |
| Exit 137 | SIGKILL強制終了 | コンテナがメモリ上限を超えてOOM Killerに殺された、または docker kill された(128 + 9)。 |
docker inspect で OOMKilled: true を確認し、Composeのメモリ制限や.NET GCヒープ上限を見直す。 |
| Exit 139 | セグフォ異常 | OS/CPUアーキテクチャ不一致(ARM64 Mac用イメージをx64サーバーで実行等)やネイティブライブラリ破損。 | --platform linux/amd64 指定や、FROM ベースイメージとビルド環境のプラットフォーム統一を確認。 |
Day 47で学んだ .NET Chiseled イメージ にはセキュリティ強化のため
sh すら入っていません。その場合は慌てず、①一時的に docker cp <container>:/app ./debug-app で停止済みコンテナからファイル一式をホスト側へ取り出して中身を確認するか、②Docker 25以降の docker debug <container> コマンド(別ツールボックスコンテナをアタッチして調査する機能)を活用しましょう!
4. 【C#/.NET実践】Program.csの起動時例外ハンドリングと事前検証
C# / ASP.NET Core アプリがコンテナ起動直後に Exit 1(あるいは Exit 134) で落ちる現場原因のナンバーワンは、「DBサーバーがまだ準備できていない状態での起動時マイグレーション失敗」や「環境変数の設定漏れによる起動直後のNullReferenceException」です。
さらに悪いことに、ログをファイル出力だけに頼っていると、docker logs に何も残らず「原因不明の無言クラッシュ」になってしまいます。
起動時クラッシュを100%可視化する Program.cs の鉄壁パターン
コンテナ前提のC#アプリケーションでは、①起動設定の即時バリデーション(ValidateOnStart)と、②未処理例外の標準エラー出力(Console.Error)への確実なフラッシュを実装するのがプロの定石です。
// Program.cs - コンテナ即死時の原因を docker logs に確実に残す実装例
using System.ComponentModel.DataAnnotations;
try
{
var builder = WebApplication.CreateBuilder(args);
// 1. 必須設定(接続文字列など)を起動直後に検証する(Fail Fast)
builder.Services.AddOptions<DatabaseOptions>()
.Bind(builder.Configuration.GetSection("Database"))
.ValidateDataAnnotations()
.ValidateOnStart(); // ★ 不備があればリクエスト受付前に明確なエラーで停止!
// コンテナ向け標準出力ロガーを明示的に構成
builder.Logging.ClearProviders();
builder.Logging.AddConsole();
var app = builder.Build();
// 2. DB接続確認やマイグレーションにリトライと詳細ログを入れる
using (var scope = app.Services.CreateScope())
{
var logger = scope.ServiceProvider.GetRequiredService<ILogger<Program>>();
var connStr = builder.Configuration.GetConnectionString("DefaultConnection");
if (string.IsNullOrWhiteSpace(connStr))
{
throw new InvalidOperationException(
"環境変数 ConnectionStrings__DefaultConnection が未設定です。.env または docker-compose.yml を確認してください。");
}
logger.LogInformation("アプリケーションの初期化チェックが完了しました。");
}
app.MapGet("/healthz", () => Results.Ok("Healthy"));
app.Run();
}
catch (Exception ex)
{
// 3. DIやLogger構築前に落ちても docker logs に必ず残るよう Console.Error に出力
Console.Error.WriteLine($"[FATAL STARTUP ERROR] コンテナ起動時に致命的な例外が発生しました: {ex}");
Console.Error.Flush();
Environment.ExitCode = 1; // 明確に異常終了コード 1 を返す
}
public class DatabaseOptions
{
[Required(ErrorMessage = "Database:Host の設定が必須です。")]
public string Host { get; set; } = string.Empty;
}
設定値ミスを抱えたままコンテナが中途半端に動き続けると、後になって本番リクエストが来た瞬間に初めて
NullReferenceException を吐くという最悪の障害になります。ValidateOnStart() とトップレベルの try-catch を組み合わせることで、「設定ミスがあれば起動時に明確な日本語/英語ログを docker logs に残して潔く Exit 1 で止まる」ようになり、原因究明時間が数十分から数秒へと劇的に短縮されます!
5. 【Git連携】直前のGitコミット差分から原因特定&安全ロールバック
「昨日まで問題なく動いていたコンテナが、今日のデプロイや git pull の直後から突然 Exit 1 で落ち始めた!」
ここでDocker×Git(IaC)の本領が発揮されます。従来の手動構築サーバーでは「誰がいつ何の設定を書き換えたか」を記憶から辿るしかありませんでしたが、DockerfileもComposeもC#コードもすべてGit管理している現代の現場では、Gitの履歴を見るだけで犯人(原因変更)が数秒で特定できます。
# 1. 直近のコミット履歴と変更ファイル一覧を確認
$ git log -n 5 --stat
# 2. 直前のコミットで Dockerfile / docker-compose.yml / Program.cs に何が変わったか比較
$ git diff HEAD~1 -- Dockerfile docker-compose.yml src/Program.cs
# 3. 怪しいコミットを特定したら、本番復旧を優先して安全に打ち消しコミットを作成
$ git revert <問題のコミットハッシュ>
# 4. クリーンに再ビルド&起動して即復旧
$ docker compose up -d --build
🛡️ 「原因がすぐ分からない時」のGit運用3つの鉄則
- まず復旧、調査は別ブランチで: 稼働中の本番・ステージングが即死している場合は、原因究明に固執せず
git revertや前の正常タグのイメージ(Day 44)へ即座に切り戻す。 git bisectで二分探索: どのコミットから起動しなくなったか不明な場合でも、動いていたコミットと壊れたコミットを指定してgit bisectを使えば最小回数で原因コミットを自動特定できる。- 設定の欠落もGitで守る:
.envの新項目追加漏れで即死する事故を防ぐため、.env.exampleの更新をPRレビューの必須チェック項目にする。
6. まとめ・FAQ(よくある質問)・次回予告
🎯 Day 52 の重要理解ポイント総括
- PID 1 ルールがすべて: コンテナはフォアグラウンドの主役プロセスが終了した瞬間に停止する。裏方(バックグラウンド)起動コマンドは即死(Exit 0)の原因になる。
- 調査は必ず「3ステップ」で: ①
docker logsで遺言を読む ➔ ②docker inspectで終了コードとOOMを確認 ➔ ③--entrypoint shで乗っ取って中から手動実行する。 - Exitコードの意味を知る:
0は完了/待機不足、1はアプリ例外/設定漏れ、126/127は権限や改行コード、137はメモリ不足(OOMKilled)を疑う。 - C#の標準出力フラッシュとGit追跡: 起動時例外は必ず
Console.Errorへ出して終了コード1で落とし、変更トラブル時はgit diffとgit revertで即座に原因特定・復旧する。
💬 よくある質問(FAQ)
Q. 確認のためだけに、コンテナを「絶対に終了しない状態」で強制起動させておく小技はありますか?
A. あります!docker run -d --entrypoint tail my-image -f /dev/null(またはCompose側で entrypoint: ["tail", "-f", "/dev/null"])と指定すると、何もせず待機し続けるPID 1が動くため、後から docker exec -it で何度でも入ってじっくり調査できます。
Q. docker-compose.yml に restart: always を書いていたら、Exit 1 で無限再起動ループに入ってログが流れてしまいます。
A. 再起動ループ中はステータスが Restarting になり、docker ps だけでは見落としがちです。まずは docker compose logs --tail 50 <サービス名> で原因の例外を1回分だけ抜き出し、docker compose down で止めた上で docker compose run --rm --entrypoint sh <サービス名> で単体デバッグしてください。
Q. C#アプリがローカル(Visual Studio F5)では動くのに、Dockerで起動すると即座に Exit 1 で落ちます。
A. 最も多い原因は①WindowsのローカルDB(localhost)へ接続しようとしている(コンテナ内では db サービス名や host.docker.internal が必要)、②appsettings.Development.json のみに書かれた設定に依存している、③Linuxの大文字・小文字を区別するファイルパスでファイルが見つからない、の3点です。--entrypoint sh で dotnet MyApp.dll を直接叩けば一発で判明します。
次回【Day 53】WSL2のメモリバカ食い・ディスク肥大化の解決と最適化 〜Cドライブ圧迫とvmmem暴走を完全解消する.wslconfig&vhdx圧縮マニュアル〜
「Dockerを毎日使っていたら、タスクマネージャーの『Vmmem』がメモリを16GBも食い潰してPCがカクつく!」「コンテナを消したはずなのにCドライブの空き容量が戻らない!」
Windows開発者なら誰もが一度は悲鳴を上げるWSL2特有のメモリ・ディスク肥大化問題の仕組みと、.wslconfig・vhdx圧縮・配置最適化による劇的改善テクニックを完全解説します!
コメント
コメントを投稿