network-troubleshooting

ネットワークのトラブルシューティング

このスキルでは、開発者向けネットワーク障害を診断するための、簡潔で安全性を最優先した判断ガイドを提供します。診断は読み取り専用とし、対象を限定する必要があります。自動修復ツールキットではありません。

安全上の境界

以下の境界は、以降のワークフローのすべての手順に適用され、依頼された場合でも決して緩和してはなりません。

• 読み取り専用の診断と、プロジェクトから提供された信頼できる診断スクリプトを優先してください。
• 失敗しているホスト、URL、レジストリ、またはサービスを既定のプローブ対象にしてください。無関係なホストをプローブしないでください。
• 無関係な外部サービスをプローブする場合は、事前に確認してください。
• プロキシ URL、認証情報、トークン、認証ヘッダー、パッケージインデックス URL、設定に含まれるレジストリのホスト名、または設定の生の値を、共有する出力に決して表示しないでください。
• 対象を限定したローカル診断のために内部ホストや URL を収集してもかまいませんが、ユーザーが明示的に含めることを承認しない限り、ログやレポートを共有する前にプレースホルダーに置き換えてください。
• npm、pnpm、yarn、pip、Git、Docker、シェル、OS のプロキシ、VPN、または証明書ストアからローカル設定を決してダンプしないでください。
• TLS や証明書の検証を無効化、回避、またはスキップしないでください（-k／--insecure、NODE_TLS_REJECT_UNAUTHORIZED=0、verify=False は使用しないでください）。「試しに一時的に」行う場合も同様です。
• 変更する具体的な操作についてユーザーから明示的な承認を得ずに、OS のネットワーク、DNS、プロキシ、パッケージマネージャー、Git、Docker、シェル、VPN、または信頼ストアの設定を変更しないでください。

ワークフロー

1. 収集 — 正確なエラー文、失敗したコマンド、対象のホスト／URL／ポート、OS／シェル、プロキシ／VPN の状況、障害が単一の対象に影響しているのか複数の対象に影響しているのかを記録します。
2. 分類 — 以下のエラー分類表と症状を照合し、仮説を立てます。
3. 診断 — 失敗した対象に限定した読み取り専用のチェックのみを実行し、関連性の最も高い小規模なチェックから始めます。
4. 説明 — 修正を提案する前に、各診断結果を平易な言葉で解釈します。
5. 提案 — 修復方法を選択肢として提示し、状態を変更する前にユーザーから明示的な承認を得ます。
6. 検証 — 承認された変更を適用した後、元の失敗したコマンドを再実行するか、対象を限定した同等のチェックを実行します。

エラーの分類

エラーパターン	考えられるカテゴリ
ECONNREFUSED、ERR_CONNECTION_REFUSED、Connection refused	対象サービスまたはポートでリッスンしていません
ECONNRESET、socket hang up、Connection reset	対象、プロキシ、ファイアウォール、または中間装置によって接続が切断されました
ETIMEDOUT、ERR_CONNECTION_TIMED_OUT、timed out	ルーティング、ファイアウォール、プロキシ、または対象の可用性
ENOTFOUND、EAI_NONAME、ERR_NAME_NOT_RESOLVED、getaddrinfo	DNS またはホスト名の問題
ERR_PROXY_CONNECTION_FAILED、プロキシトンネルのエラー、HTTP 407	プロキシ設定またはプロキシ認証
UNABLE_TO_VERIFY_LEAF_SIGNATURE、CERT_HAS_EXPIRED、self signed、ERR_CERT_*	TLS 証明書またはローカルの信頼設定の問題
HTTP 403	認証、IP 許可リスト、CORS、またはポリシーによるブロック
HTTP 502、503、504	アップストリームサービス、ゲートウェイ、CDN、または一時的なサーバーの問題
npm ERR! network、パッケージインストールのタイムアウト、pip のタイムアウト	パッケージレジストリ、プロキシ、DNS、またはネットワーク経路の問題
fatal: unable to access、Git のフェッチ／プッシュのタイムアウト	Git リモート、プロキシ、DNS、TLS、またはネットワーク経路の問題

対象を限定した安全なチェック

最も関連性の高い小規模なチェックを選び、実行前にその内容を説明してください。具体的に失敗した <target-host>、<port>、<path> に必ず置き換えてください。より広範な対象や無関係な対象は使用しないでください。

接続性

Linux/macOS：

ping -c 4 <target-host>
curl -v telnet://<target-host>:<port> --connect-timeout 5

Windows PowerShell：

Test-Connection -ComputerName <target-host> -Count 4
Test-NetConnection -ComputerName <target-host> -Port <port>

DNS

Linux/macOS：

nslookup <target-host>
dig <target-host>

Windows PowerShell：

Resolve-DnsName <target-host>

HTTP

Linux/macOS：

curl -vvv -o /dev/null -w "HTTP %{http_code}\nTime: %{time_total}s\nDNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\n" https://<target-host>/<path>
curl -I https://<target-host>/<path>

Windows PowerShell：

$uri = "https://<target-host>/<path>"
try {
  $resp = Invoke-WebRequest -Uri $uri -Method Head -TimeoutSec 10
  "HTTP status: $([int]$resp.StatusCode)"
} catch [Net.WebException] {
  if ($_.Exception.Response) {
    "HTTP status: $([int]$_.Exception.Response.StatusCode)"
  } else {
    "HTTP request failed: $($_.Exception.Message)"
  }
}

TLS

Linux/macOS：

openssl s_client -connect <target-host>:<port> -servername <target-host> -showcerts </dev/null
echo | openssl s_client -connect <target-host>:<port> -servername <target-host> 2>/dev/null | openssl x509 -noout -subject -issuer -dates

Windows PowerShell — 2xx 以外の応答を証明書エラーと誤判定しないよう、証明書と HTTP ステータスを別々に確認してください：

try {
  $req = [Net.HttpWebRequest]::Create("https://<target-host>:<port>/<path>")
  $req.Method = "HEAD"
  $req.Timeout = 5000
  try {
    $resp = $req.GetResponse()
  } catch [Net.WebException] {
    $resp = $_.Exception.Response
    if ($req.ServicePoint.Certificate) {
      $cert = $req.ServicePoint.Certificate
      "Cert subject: $($cert.Subject)"
      "Cert expires: $($cert.GetExpirationDateString())"
    }
    if ($resp) {
      "HTTP status: $([int]$resp.StatusCode) $($resp.StatusDescription)"
      $resp.Close()
    } else {
      "TLS/network error: $($_.Exception.Message)"
    }
    return
  }
  $cert = $req.ServicePoint.Certificate
  if ($cert) {
    "Cert subject: $($cert.Subject)"
    "Cert expires: $($cert.GetExpirationDateString())"
  }
  "HTTP status: $([int]$resp.StatusCode) $($resp.StatusDescription)"
  $resp.Close()
} catch {
  "TLS/network error: $($_.Exception.Message)"
}

プロキシとパッケージマネージャー

• プロキシ、パッケージマネージャー、Git、Docker、OS のネットワーク設定を直接読み取らないでください。
• 値を表示せずに確認できる場合は、関連する設定が存在するように見えるかどうかだけを報告してください。
• 使用可能なコマンドで URL、トークン、内部ホスト名、認証ヘッダー、または設定値全体が表示される場合は、そのコマンドを実行しないでください。
• パッケージレジストリの確認は、失敗した操作がすでに対象としていた場合、またはユーザーがその確認対象を明示的に承認した後に限って行ってください。

ユーザー承認のもとで実施する修正案

以下はユーザーが承認する選択肢として提示してください。自動で適用してはいけません。

診断	安全な対処法
対象サービスがリッスンしていない	ローカルまたはリモートのサービスが実行中か、想定されるポートが正しいかを確認してください。
DNS 名前解決に失敗する	ホスト名、hosts ファイルに関する想定、DNS サービスの状態、または承認済みの DNS 変更を確認してください。
プロキシが必要と思われる、または利用できない	ユーザーにプロキシ／VPN を起動または調整するか確認してから、承認された対象のみを検証してください。
TLS 証明書の有効期限が切れている	証明書を更新または置き換える、システム時刻を修正する、信頼できるローカル開発 CA をインストールする、または信頼ストアを更新してください。TLS 検証を回避してはいけません。
TLS の CA が不明	ユーザーが提供元と適用範囲を確認した後、適切な信頼ストアに正しい CA をインポートしてください。
HTTP 407	認証情報またはツール設定を変更する前に、プロキシ認証の要件をユーザーに確認してください。
HTTP 403	認証、API キーのスコープ、IP 許可リスト、CORS ポリシー、またはサービスのポリシーを確認してください。
HTTP 502／503／504	上流またはゲートウェイの不安定さとして扱ってください。承認を得たうえでステータスページを確認し、バックオフを行って再試行してください。
パッケージのインストールがタイムアウトする	保存済みの設定値を表示または変更せずに、承認済みのレジストリ、プロキシ、またはネットワーク経路の選択肢について相談してください。
Git のネットワーク障害	グローバルな Git 設定を自動で変更せずに、承認済みのリモート URL、プロキシ、認証情報、TLS、またはネットワーク経路の選択肢について相談してください。
Docker の pull に失敗する	ユーザー承認の設定変更として、承認済みのレジストリミラー、プロキシ、またはデーモン設定について相談してください。

検証

• ユーザー承認済みの変更を行った後は、可能な限り元の失敗したコマンドを再実行してください。
• 代わりにより限定的な確認が必要な場合は、同じ障害が発生したホスト、URL、レジストリ、またはサービスを対象にしてください。
• 次の手順を推奨する前に、各診断結果が何を意味するのかを必ず説明してください。