Skip to main content

第25章：デバッグの型（exec / 状態確認 / ポート / 依存）🕵️‍♂️🧩

「docker compose upしたのに動かない…😇」は、**“いつものこと”**です。なので今回は、焦らずに原因を切り分けるための 定番の型（チェック順）を身につけます💪✨ ComposeはCompose Specificationが推奨フォーマットなので、以降のコマンドや考え方もその前提でOKです🧠📄 (Docker Documentation)

この章のゴール 🎯​

  • 「今なにが起きてる？」を 30秒で把握できる 👀⚡
  • 「ログ → ポート → コンテナ内 → 依存関係」の順で、迷子にならない 🧭
  • “ありがち事故”を見た瞬間に、次に打つコマンドが出る 🧰✨

1) まずは30秒で“現状把握”する ⏱️👀​

最初にやるのは、推測じゃなく事実を見ることです📌

✅ ① いま動いてる？落ちてる？（一覧）​

docker compose ps
  • Up なら稼働中
  • Exited / Restarting なら 落ちてる or 落ち続けてる
  • Ports に期待の 0.0.0.0:xxxx->yyyy が出てるかもチェック🚪

Windowsで「そもそもDockerが怪しい」時は、Docker DesktopがWSL2バックエンドで動く構成が一般的なので、WSL連携が切れてないかも疑います🪟🧊 (Docker Documentation)

✅ ② compose.yaml が“実際どう解釈されたか”を見る（超重要）​

docker compose config

docker compose config は、変数展開や短縮記法の展開も含めて 最終形を表示してくれます🧠 「サービス名typo」「envが空」「ポート設定が意図と違う」みたいな事故が一発で見つかります🔎✨ (Docker Documentation)

2) ログで“死因”を特定する 🧾🔍​

落ちてる時は、ほぼログに答えがあります（ほんとに）🙏

✅ まずは全部のログを追う​

docker compose logs -f

-fで追従、--tailで末尾だけ、--sinceで「直近だけ」もできます📌 (Docker Documentation)

✅ 次に“犯人サービス”に絞る（ここが速い）​

docker compose logs -f --tail=200 api
docker compose logs -f --tail=200 worker
docker compose logs -f --tail=200 db
docker compose logs -f --tail=200 redis

ログの読み方のコツ 🧠✨​

  • 接続系：ECONNREFUSED / ENOTFOUND / timeout
  • 認証系：password authentication failed
  • 移行系：migration / schema / relation does not exist
  • ポート系：address already in use / bind

3) ポートの確認（ホスト側 vs コンテナ側）🌐🚪​

「ブラウザで localhost:xxxx 開かない！」は、だいたいここです🫠

✅ “公開ポート”を確実に知る​

docker compose port api 3000

これで「ホスト側の何番ポートに出てるか」を表示できます📣 (docs.docker.jp)

✅ ポートの勘違いあるある 🧠💥​

  • コンテナ内の localhost は“そのコンテナ自身”

    • APIからDBへ繋ぐのに localhost:5432 はだいたい間違い
    • Composeでは基本 サービス名（例：db）で接続 です🕸️📡

  • ポート公開の基本概念（ホストに公開する/しない）はここが公式でまとまってます📘 (Docker Documentation)

4) コンテナの中に入って“事実確認”する（exec）🕵️‍♂️🧪​

ログだけだと「本当に繋がる？」が分からないので、中から確かめます。

✅ exec の基本（まずこれ）​

docker compose exec api sh

docker compose exec はComposeサービスに対して docker exec 相当を実行するコマンドです🧰（TTYもデフォルトで割り当て） (Docker Documentation)

🐘 DB（Postgres）が生きてるか：dbコンテナで確認​

Postgres公式イメージ側には psql が入ってるので、ここが一番ラクです😺

docker compose exec db psql -U postgres -d postgres -c "select 1;"
  • これが通れば DBはだいたいOK ✅
  • 通らなければ、POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB あたりのenvや初期化が怪しい🤔

🟥 Redis が生きてるか：redis-cli で即チェック​

docker compose exec redis redis-cli ping

PONG が返ればOK🎉

5) 依存関係の詰まりを潰す（起動順・待ち合わせ）⏳🩺​

「DBが起きる前にAPIが突っ込んで死ぬ」問題、めちゃ多いです😇

Composeは依存関係順にサービスを作り、service_healthy 指定の依存については healthcheckが通るまで待つ という流れが公式に整理されています🧠 (Docker Documentation)

✅ “依存で死んでる”時の見分け方​

  • api のログに ECONNREFUSED db:5432 みたいなのが連発
  • db がまだ starting / healthcheck未通過っぽい
  • docker compose ps で health: starting が見える（環境による）

✅ 典型のhealthcheck（例）​

※あなたの既存構成に合わせて調整してOK（雰囲気を掴む用）👇

services:
  db:
    image: postgres:17
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 3s
      retries: 20

  api:
    depends_on:
      db:
        condition: service_healthy

起動順まわりの考え方はこのページが一番読みやすいです📘 (Docker Documentation)

6) “よくある死に方”早見表 🧯📌​

症状 😵だいたい原因 🤔次に打つコマンド 🧰
api が即落ちるenv不足 / DB未起動 / migration失敗docker compose logs -f --tail=200 api (Docker Documentation)
ENOTFOUND dbサービス名違い / network想定違いdocker compose config でサービス名確認 (Docker Documentation)
ECONNREFUSED 127.0.0.1:5432コンテナ内localhost勘違い接続先を db:5432 に直す🧠
password authentication failedDB初期化済み＋env変更で不整合docker compose exec db psql ... で確認
port is already allocatedWindows側でポート衝突docker compose port api 3000 / ポート変更 (docs.docker.jp)
編集しても反映されないwatch/mountの問題docker compose up --watch の挙動確認 👀 (Docker Documentation)

7) デバッグ手順の“黄金ルート”✨🧭（迷ったらこれ）​

  1. 一覧：docker compose ps
  2. ログ：docker compose logs -f --tail=200 <怪しいサービス> (Docker Documentation)
  3. 設定の最終形：docker compose config (Docker Documentation)
  4. ポート：docker compose port api 3000 (docs.docker.jp)
  5. 中から確認：docker compose exec ... (Docker Documentation)
  6. 依存：healthcheck / service_healthy を疑う (Docker Documentation)

これだけで、初心者が詰まる原因の大半は潰せます😺👍

8) ミニ演習（手を動かすと一気に身につく）🏋️‍♂️✨​

演習A：ログから原因を当てる🧾🔍​

  1. api をわざと落とす（例：DB接続先を一瞬だけ間違える）
  2. docker compose logs -f --tail=200 api で「死因の一行」を探す🎯

演習B：ポート迷子を解決する🚪🧠​

  1. APIの公開ポートを変更（例：3000:3000 → 3001:3000）
  2. docker compose port api 3000 で“今の正解”を言い当てる📣 (docs.docker.jp)

演習C：依存の待ち合わせを体験する⏳🩺​

  1. DBにhealthcheckを入れる
  2. api を service_healthy 待ちにする
  3. 「DBが整ってからAPIが起動する」流れをログで観察👀 (Docker Documentation)

9) AIに投げると強い“質問テンプレ”🤖🧠​

Copilot等に聞くときは、これが鉄板です👇（秘密情報は貼らないよ⚠️）

  • ✅ 現象：何ができない？（例：APIが起動しない）
  • ✅ ログ抜粋：エラー周辺の20〜50行
  • ✅ compose config：該当サービス部分だけ
  • ✅ 期待：本当はどう動くべき？

例：

docker compose ps では api が Restarting です。
docker compose logs の末尾に "ECONNREFUSED db:5432" が出ます。
compose config の api 環境変数は DB_HOST=db, DB_PORT=5432 です。
考えられる原因と確認コマンドを、優先順に出して。

まとめ 🎉​

この章で一番大事なのは、チェック順を固定することです🧠✨ 「ログを見る → ポートを見る → 中から叩く → 依存を見る」 この型があるだけで、デバッグのストレスが激減します😌🍀

次章では、この“デバッグ筋”を活かして、データのバックアップ/リストアを手順化していきます📦🧯🚀