除錯圖鑑：容器出事時的系統化排查

不同類型的問題，排查路徑完全不同。花十秒鐘分類，勝過亂試十分鐘。

問題發生在哪個階段？
│
├─ ① docker build 就失敗          → 建置類（本章第 2 張卡）
│
├─ ② build 成功，但容器起不來      → 啟動類（第 3 張卡）
│     docker ps 看不到／狀態是 Exited 或 Restarting
│
├─ ③ 容器 Up，但連不到／功能不通    → 網路類（第 4 張卡，ch07 延伸）
│
├─ ④ 一開始正常，跑一陣子掛掉      → 執行期類（第 5 張卡）
│
└─ ⑤ 能跑但很慢                   → 效能類（第 5 張卡）

三個萬用起手式（不管哪一類都先做）

docker compose ps -a       # ① 現在到底有哪些容器、什麼狀態（-a 才看得到已結束的）
docker compose logs --tail 100 <服務>   # ② 它自己怎麼說
docker inspect <容器>      # ③ 它實際被設定成什麼樣（不是你以為的那樣）

症狀 A：COPY failed: file not found

ERROR: failed to compute cache key: "/target/app.jar" not found

• 原因 1：檔案真的不存在——你忘了先 mvn package。
• 原因 2：檔案被 .dockerignore 排除了（很常見！你排除了 target/，卻又想 COPY target/app.jar）。
• 原因 3：路徑在 build context 之外（../ 拿不到，ch08）。
• 驗證：

  docker build --progress=plain . 2>&1 | head -50   # 看完整輸出
  ls -la target/                                     # 檔案真的在嗎

症狀 B：apt-get install 噴 404

• 原因：RUN apt-get update 被寫成獨立一層並被快取住，套件索引過期（ch08）。
• 解法：update 和 install 串在同一個 RUN；或臨時 docker build --no-cache。

症狀 C：建置超級慢、或 Sending build context 好幾 GB

• 原因：沒有 .dockerignore，target/、node_modules/、.git/ 全被送進去（ch08）。
• 順便檢查：Maven 依賴是不是每次都重下？→ 用 COPY pom.xml 先裝依賴 ＋ BuildKit cache mount（ch08、ch09）。

症狀 D：exec format error（在建置或執行時）

• 原因：架構不符——在 M 系列 Mac 建的 arm64 映像丟到 x86 機器（ch04）。
• 解法：docker build --platform linux/amd64 ... 或用 buildx 建多架構。

症狀 E：我改了 Dockerfile，但好像沒生效

• 原因：快取命中了你以為會重跑的層。記住 RUN 只比對「指令字串」不檢查實際結果（ch08）。
• 驗證：docker build --no-cache . 看看是不是快取問題；docker history 看每層的產生指令。

Exit code 是容器留給你的第一手線索，它會告訴你「是誰殺的、怎麼死的」。

docker ps -a                        # 看 STATUS 欄的 Exited (N)
docker inspect <容器> --format '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}'

Exit Code 對照（背起來很值得）

• 0：正常結束。如果你預期它常駐卻拿到 0 → 主程式做完事就退出了（ch05：容器的命等於 PID 1 的命；例如 daemon 化、或 docker run ubuntu 沒給 -it）。
• 1：應用程式自己的錯誤。去看 docker logs，答案在裡面（設定錯誤、找不到檔案、連不上相依服務…）。
• 125：Docker 本身的錯誤——指令參數打錯、映像不存在。
• 126：指令找到了但不能執行——沒有執行權限（腳本忘了 chmod +x），或腳本的換行是 Windows 的 CRLF（bad interpreter）。
• 127：指令根本不存在——打錯字，或精簡映像裡沒有那個工具（distroless 沒有 bash！ch10）。
• 137：被 SIGKILL 殺掉（128+9）。檢查 OOMKilled: true → 記憶體超過 cgroup 上限（ch02、ch09）。也可能是 docker stop 寬限期到了強制砍（ch05）。
• 139：Segmentation fault（128+11）——原生程式碼崩潰，常見於架構不符或 JNI 函式庫問題。
• 143：收到 SIGTERM 後正常結束（128+15）。這其實是好消息——代表優雅關機生效了（ch05）。

症狀：容器一直 Restarting（CrashLoop）

docker compose logs --tail 200 <服務>      # 抓崩潰前的最後訊息
docker compose ps -a                        # 看重啟次數

• 重啟策略不是解方：如果是設定錯誤導致啟動即崩潰，重啟一萬次也一樣（ch05）。先看 logs 找真正的死因。
• 如果日誌太快滾掉看不到，暫時把 restart 拿掉，或用：

  docker run --rm -it --entrypoint sh myapp:1.0
  # 手動進去，自己執行啟動指令，看完整錯誤

  這招非常有用——繞過 entrypoint 直接進容器，逐步驗證。

症狀：日誌完全是空的

• 原因 1：應用把日誌寫進容器內的檔案，而不是 stdout（ch05）。
• 原因 2：程式根本沒啟動就死了 → 檢查 exit code 125/126/127。
• 原因 3：docker logs 抓的是 PID 1 的輸出，而你的程式是被 shell 包起來的子行程（shell form，ch05）。用 docker top 確認誰是 PID 1。

ch07 給過五步驟，這裡補上更完整的判斷邏輯。關鍵是先確定「是誰連不到誰」。

情境 A：你（宿主機）連不到容器

docker ps        # PORTS 欄有沒有 0.0.0.0:8080->8080/tcp？

1. 沒有 PORTS 對應 → 忘了 -p／compose 沒寫 ports。注意 EXPOSE 不會開埠（ch07）。
2. 有 PORTS 但連不上 → 容器內的服務可能監聽在 127.0.0.1 而不是 0.0.0.0：

   docker compose exec app ss -lntp    # 看監聽位址

3. 埠寫反了 → -p 宿主機:容器，左外右內（ch07）。

情境 B：容器 A 連不到容器 B（最常見）

1. 先確認 B 真的健康：docker compose ps 看是不是 healthy；logs 看它有沒有真的啟動完成。
2. 位址寫錯——第一名的原因：寫成 localhost。應該用服務名稱（ch07）。
3. 埠寫錯：容器間要用容器內部埠，不是 -p 映射後的外部埠（ch07）。
4. 不在同一個網路（跨 compose 專案的頭號原因，ch11）：

   docker network inspect myapp_default | grep -A3 Containers

5. 名稱解析測試：

   docker compose exec app getent hosts sqlserver

情境 C：容器連不到外部網路

docker compose exec app ping -c 2 8.8.8.8        # 通不通
docker compose exec app getent hosts google.com   # DNS 解不解得開

• IP 通但 DNS 不通 → DNS 設定問題（公司 VPN、自訂 DNS 常見）。
• 都不通 → 網路模式是 none？宿主機防火牆擋住 docker0 的轉發？

沒有工具可用時的救星

# 精簡映像裡沒有 ping/curl/ss 時，開一個工具容器加入同一個網路
docker run --rm -it --network myapp_default nicolaka/netshoot bash
# 裡面有 ping / dig / curl / ss / tcpdump / nmap / iperf

# 或直接共用某個容器的網路 namespace，用它的視角看世界
docker run --rm -it --network container:myapp-app-1 nicolaka/netshoot bash

執行期崩潰：先確認是不是記憶體

docker inspect <容器> --format '{{.State.OOMKilled}} {{.State.ExitCode}}'
#  true 137  → 確定是 OOM

docker stats                # 即時看「已用 / 上限」，觀察是否持續攀升

• Java 應用：先檢查有沒有設 -XX:MaxRAMPercentage（ch09）。沒設的話 JVM 可能用了不合理的預設。
• 記憶體持續成長不下降 → 可能是真的記憶體洩漏。開啟 -XX:+HeapDumpOnOutOfMemoryError，事後 docker cp 撈出 dump 分析（ch09）。
• 不是 OOM 但一直重啟 → 看 healthcheck 是不是一直失敗（docker inspect 的 .State.Health.Log 有最近幾次的檢查結果）。

磁碟滿了（很常見，症狀千奇百怪）

docker system df -v        # 誰在吃空間（容器/映像/volume/建置快取）
df -h                      # 宿主機整體

• 四大兇手：停止但沒刪的容器、懸空映像、沒人用的 volume、建置快取（ch05）。
• 還有一個常被忽略的：容器的日誌檔。沒設輪替的話會無限長大：

  # compose 裡設定
  logging:
    driver: json-file
    options:
      max-size: '10m'
      max-file: '3'

效能問題

• 寫入很慢 → 資料寫在 overlay 可寫層而非 volume（ch03 的 Copy-on-Write 代價）。資料庫、大量檔案寫入一定要用 volume。
• Windows／macOS 上檔案存取極慢 → bind mount 經過檔案共享層（ch06）。只掛必要目錄，或把相依套件目錄改用 volume。
• CPU 被限制 → docker stats 看 CPU% 是不是一直貼在上限。cgroup 的 CPU 限制會讓 process 被強制暫停（throttling），對 Java 的 GC 影響特別明顯。
• Java 啟動慢 → 冷啟動本來就慢，記得 healthcheck 設 start_period（ch05）；真的在意就研究 CDS 或 GraalVM 原生映像。

間歇性問題（最難搞）

docker events                          # 即時看 Docker 層級發生了什麼
docker events --since 1h --filter 'container=myapp-app-1'
docker inspect <容器> --format '{{json .State.Health}}' | jq

docker events 會告訴你容器什麼時候 die、restart、被 OOM kill、健康狀態何時改變——對付「半夜自己重啟」這種問題非常有效。

inspect 的實用格式化（比翻整份 JSON 快很多）

# 結束狀態一次看完
docker inspect <容器> --format '{{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}}'

# 這個容器的 IP
docker inspect <容器> --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'

# 掛了哪些東西（「我改的檔案怎麼沒生效」第一站）
docker inspect <容器> --format '{{json .Mounts}}' | jq

# 實際生效的環境變數（驗證設定有沒有進去）
docker inspect <容器> --format '{{json .Config.Env}}' | jq

# 健康檢查的歷史紀錄
docker inspect <容器> --format '{{json .State.Health}}' | jq

其他常備工具

docker top <容器>              # 容器內的 process → 驗證誰是 PID 1（ch05）
docker diff <容器>             # 相對於映像，檔案系統改了什麼（ch03 可寫層）
docker cp <容器>:/path ./      # 撈檔案出來（heap dump、log）
docker stats --no-stream       # 資源用量快照
docker history <映像>          # 映像每層的來源與大小
docker compose config          # 合併後的最終設定（ch11）

繞過 entrypoint 直接進去看

# 容器啟動就死，來不及 exec 時的救命招
docker run --rm -it --entrypoint sh myapp:1.0

# 進去之後手動驗證
ls -la /app          # 檔案在不在、擁有者對不對
whoami               # 現在是什麼身分（ch10 的 USER）
env | sort           # 環境變數
java -version        # 執行環境
java -jar /app/app.jar   # 手動啟動，看完整錯誤

求助前先蒐集這些（也是給自己的檢查清單）