docker-troubleshooting

Docker トラブルシューティング — 問題の診断とデバッグ

一般的な Docker の問題を診断し、解決するための体系的なアプローチです。

使用する場面

ユーザーが次のような内容に言及した場合は、必ずこのスキルを使用してください。

• 「docker のトラブルシューティング」、「docker のデバッグ」、「コンテナの問題」
• 「コンテナの起動に失敗」、「終了コード」、「クラッシュ」
• 「OOM」、「ディスク容量不足」
• 「ネットワークに接続できない」、「ネットワークの問題」
• 「docker daemon」、「daemon が起動していない」

診断フレームワーク

1. Check container state    → docker ps -a, docker inspect
2. Check logs               → docker logs --tail 100
3. Check resources          → docker stats, docker system df
4. Check exit code          → docker inspect --format='{{.State.ExitCode}}'
5. Interactive debug        → docker run --rm -it image sh

コンテナの起動失敗

終了コードのリファレンス

コード	意味	対処
0	成功	—
1	アプリケーションエラー	docker logs を確認します
125	Docker daemon のエラー	daemon の状態を確認します
126	コマンドを実行できません	権限を確認します
127	コマンドが見つかりません	CMD/ENTRYPOINT のパスを確認します
137	SIGKILL（OOM または docker kill）	メモリ制限を確認します
139	SIGSEGV（セグメンテーション違反）	アプリケーションのバグです
143	SIGTERM（正常な停止）	ヘルスチェックのタイムアウトを確認します

# Quick diagnosis
docker ps -a | grep Exited
docker inspect --format='{{.State.ExitCode}} {{.State.Error}}' container
docker logs container

ディスク容量の枯渇

# Check disk usage
docker system df

# What's using space?
docker system df -v   # Verbose breakdown

# Clean up
docker system prune -a     # Remove all unused: images, containers, volumes, networks
docker image prune -a      # Unused images only
docker volume prune        # Unused volumes only

# Log rotation (prevent future issues)
docker run --log-opt max-size=10m --log-opt max-file=3 myapp

OOM（メモリ不足）

# Check if container was OOM-killed
docker inspect --format='{{.State.OOMKilled}}' container

# Check memory usage
docker stats --no-stream

# Solution: increase memory limit
docker update --memory=1g --memory-swap=1g container

ネットワーク接続

# Check network configuration
docker network inspect bridge
docker exec container ip addr show
docker exec container ping other-container

# DNS check
docker exec container nslookup other-container
docker exec container cat /etc/resolv.conf

# Host networking check
iptables -t nat -L DOCKER -n   # Port forwarding rules

権限の問題

# Bind mount permission denied
# Solution 1: Match UID
docker run -u $(id -u):$(id -g) -v $PWD:/app myapp

# Solution 2: Fix permissions in entrypoint
# In entrypoint script: chown -R appuser:appgroup /data

# Docker socket permission
sudo usermod -aG docker $USER   # Add user to docker group
newgrp docker                    # Refresh group (or re-login)

ワークフロー — トラブルシューティングの手順

ステップ 1: 状態を確認: docker ps -a → 終了コードと OOMKilled を確認します
ステップ 2: ログを確認: docker logs --tail 100 <container> でエラー情報を取得します
ステップ 3: 詳しく調査: docker inspect → ネットワーク／マウント／リソース制限を確認します
ステップ 4: 対話形式でデバッグ: docker run -it --rm --entrypoint sh <image> で起動して調査します
ステップ 5: リソースを調査: docker stats + docker system df で CPU／メモリ／ディスクを確認します

注意点 — よくある落とし穴

• docker system prune は破壊的な操作です: 未使用のオブジェクトをすべて削除します。本番環境で確認せずに実行しないでください。→ 復旧方法: まず docker system df で削除対象を確認します。安全にクリーンアップするには --filter "until=24h" を追加します。確認なしで prune -a を実行しないでください。
• ログによってディスクが気付かないうちにいっぱいになります: JSON-file ドライバーでは、デフォルトでローテーションが有効になっていません。ログの多いアプリは、数時間でディスクをいっぱいにすることがあります。→ 復旧方法: docker run --log-opt max-size=10m --log-opt max-file=3 app を使用します。既存のログには truncate -s 0 $(docker inspect -f '{{.LogPath}}' myapp) を実行します。
• OOMKilled=TRUE なのにログにエラーがない: SIGKILL はログに記録できません。→ 復旧方法: docker inspect -f '{{.State.OOMKilled}}' myapp で確認します。メモリを増やすには docker update --memory 512m myapp を実行します。
• Exited (0) なのにサービスが動作しない: アプリケーションは起動したものの、ヘルスチェックの通過後にクラッシュしています。→ 復旧方法: docker logs --tail 100 myapp を実行します。アプリが 127.0.0.1 ではなく 0.0.0.0 でリッスンしているか確認します。docker exec myapp netstat -tlnp で検証します。

境界 — 対応範囲（適用できる場面とできない場面）

分類	場面	説明
✅ 対応可能	コンテナの起動失敗の調査	終了コードの分析 + docker logs + inspect
✅ 対応可能	ディスク／ログ／リソースの問題	docker system df + prune + ログローテーション
✅ 対応可能	OOM／CPU の調査	docker stats + --memory の制限 + OOMKilled
⚠️ 条件付き	ネットワークパケットレベルの分析	tcpdump／Wireshark とネットワークの知識が必要です
⚠️ 条件付き	カーネルレベルの問題	Linux カーネルのデバッグスキルが必要です
❌ 対象外	アプリケーションコードのバグ修正	開発者がコードを修正します
❌ 対象外	本番環境へのデプロイ	docker-production を使用します
❌ 対象外	セキュリティ脆弱性の修正	docker-security + docker-scout を使用します

このスキルを使用しない場面

❌ 対象外	✅ 代わりに使用
本番環境のセットアップ	docker-production
セキュリティの問題	docker-security
パフォーマンスの調整	docker-run（リソース制限）
Docker の基本	docker-basics

セキュリティと安定性

• 本番環境のコンテナに docker exec で入ると、機密データが露出するおそれがあります。ログを使ったデバッグを優先してください。
• docker system prune -a は未使用のイメージとボリュームをすべて削除します。本番環境では慎重に使用してください。
• --privileged を指定したデバッグツールでコンテナを調査すると、セキュリティ制御を回避できる場合があります。
• デバッグのために Docker ソケット（/var/run/docker.sock）をコンテナに公開しないでください。ルートアクセスを許可することになります。
• デバッグログはローテーションしてください。機密情報が含まれる場合があります。TTL を設定したログドライバーを使用してください。

📚 公式ドキュメントの参考情報

ドキュメント	URL
Docker エンジンのトラブルシューティング	https://docs.docker.com/engine/troubleshoot/
docker logs コマンド	https://docs.docker.com/reference/cli/docker/container/logs/
docker inspect	https://docs.docker.com/reference/cli/docker/inspect/
Docker CLI リファレンス	https://docs.docker.com/reference/cli/docker/
デーモンの設定	https://docs.docker.com/reference/cli/dockerd/
よくある質問（FAQ）	https://docs.docker.com/faq/

🧭 Docker Skills Journey

📍 現在のページ：docker-troubleshooting — トラブルシューティング

← 前へ：docker-production