mcpField
T
troubleshoot

troubleshoot

github.com/mwguerraクラウド・DevOps3637 回インストール26 週間前に更新
リポジトリ

troubleshoot について

troubleshootは、Dockerの一般的な問題を診断・解決するスキルで、Docker Composeサービスを管理する開発者や運用担当者向けです。起動、ネットワーク、権限、データ永続化、ヘルスチェックの診断コマンドと対処法をまとめています。

主な機能

  1. 01コンテナの起動失敗を診断
  2. 02ネットワークとポート競合を調査
  3. 03権限とデータ永続化の問題に対処
  4. 04ヘルス状態とディスク容量を確認
  5. 05Docker Composeのトラブルシューティングコマンド

活用シーン

  1. 01Composeコンテナが起動しない原因を特定
  2. 02コンテナ間通信やポート競合を調査
  3. 03データ消失、権限、ヘルスチェックの問題を調査

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/mwguerra/claude-code-plugins --skill troubleshoot

インストール後、Claude Code で/troubleshootを入力して読み込まれたか確認します。

詳細

Docker トラブルシューティングスキル

概要

このスキルは、Docker でよくある問題の診断と解決に役立ちます。

  • コンテナーの起動失敗
  • ネットワークの問題
  • 権限エラー
  • ポートの競合
  • データの永続化に関する問題
  • ヘルスチェックの失敗

プロセス

1. ドキュメントを参照する

関連ドキュメントを読みます。

  • よくある問題については 17-troubleshooting.md
  • ポートの問題については 15-port-conflicts.md
  • 再起動の問題については 16-restart-strategies.md
2. 問題を診断する

情報を収集します。

# Check container status
docker compose ps -a

# View logs
docker compose logs servicename

# Check configuration
docker compose config

# Inspect container
docker inspect containername
3. 解決策を適用する

よくある問題と解決策

コンテナーが起動しない

診断：

docker compose logs servicename
docker inspect --format='{{.State.ExitCode}}' containername

解決策：

  • ログでエラーメッセージを確認する
  • 設定の構文を確認する
  • 依存サービスが実行中か確認する
  • イメージが存在するか確認する
ポートがすでに使用中

診断：

lsof -i :3000
# or
netstat -tulpn | grep 3000

解決策：

# Kill process
kill $(lsof -t -i:3000)

# Or change port in compose
ports:
  - "3001:3000"
権限が拒否される

診断：

docker compose exec app ls -la /app/data

解決策：

# Fix in compose
services:
  app:
    user: "1000:1000"

# Or fix in container
docker compose exec -u root app chown -R appuser:appgroup /app/data
データが消える

診断：

docker volume ls
docker compose config | grep -A5 "volumes:"

解決策：

# Use named volumes instead of anonymous
volumes:
  - postgres_data:/var/lib/postgresql/data  # Named (persists)
  # NOT: - /var/lib/postgresql/data  # Anonymous (deleted)
コンテナーから別のコンテナーに接続できない

診断：

docker network inspect networkname
docker compose exec app ping db
docker compose exec app nslookup db

解決策：

# Ensure same network
services:
  app:
    networks:
      - backend
  db:
    networks:
      - backend

networks:
  backend:
ヘルスチェックが失敗する

診断：

docker inspect --format='{{json .State.Health}}' containername | jq

解決策：

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s  # Give time to start
ディスク容量不足

診断：

docker system df
docker system df -v

解決策：

# Clean unused resources
docker system prune -a --volumes
ビルドキャッシュの問題

解決策：

docker compose build --no-cache
docker builder prune -a

デバッグコマンド

# Shell into running container
docker compose exec app sh

# Shell into failed container
docker compose run --entrypoint sh app

# View resource usage
docker stats

# View container processes
docker compose top

# View real-time events
docker events

# Copy files from container
docker compose cp app:/app/logs ./logs

すばやく確認するためのチェックリスト

  1. コンテナーが実行中か確認する： docker compose ps
  2. ログを確認する： docker compose logs servicename
  3. ネットワークを確認する： docker network ls
  4. ボリュームを確認する： docker volume ls
  5. リソースを確認する： docker stats
  6. 設定を検証する： docker compose config
  7. ディスク容量を確認する： docker system df

エラーメッセージのリファレンス

エラー原因解決策
"port is already allocated"ポートが使用中プロセスを終了するか、ポートを変更する
"network not found"ネットワークがないネットワークを作成するか、名前を確認する
"volume not found"ボリュームがないボリュームを作成するか、名前を確認する
"no such service"サービス名の誤記compose.yaml を確認する
"unauthorized"認証の問題docker login
"image not found"イメージがないdocker compose pull
"permission denied"ファイル権限所有者または権限を修正する
"out of memory"メモリー制限制限を引き上げるか、アプリを最適化する

コメント

Markdown 対応