network-troubleshooting

网络故障排查

此技能提供简明且以安全为先的决策指南，用于诊断开发者遇到的网络故障。诊断必须保持只读，并限定目标范围——这不是自动修复工具包。

安全边界

以下边界适用于下方工作流的每个步骤，即使有人提出要求，也绝不能放宽：

• 优先使用只读诊断和项目提供的可信诊断脚本。
• 默认将发生故障的主机、URL、注册表或服务作为探测目标——不要探测无关主机。
• 探测无关的外部服务前，请先征求同意。
• 切勿在共享输出中打印代理 URL、凭据、令牌、认证标头、包索引 URL、配置中的注册表主机名或原始配置值。
• 为限定目标范围在本地诊断时，可以收集内部主机和 URL；但除非用户明确同意包含这些信息，否则分享日志或报告前必须将其替换为占位符。
• 切勿转储 npm、pnpm、yarn、pip、Git、Docker、shell、操作系统代理、VPN 或证书存储中的本地配置。
• 切勿禁用、绕过或跳过 TLS 或证书验证（不得使用 -k/--insecure、NODE_TLS_REJECT_UNAUTHORIZED=0、verify=False），即使只是暂时“测试一下”也不行。
• 未经用户明确批准具体操作，切勿更改操作系统网络、DNS、代理、包管理器、Git、Docker、shell、VPN 或信任存储设置。

工作流

1. 收集 — 记录完整的错误文本、发生故障的命令、目标主机/URL/端口、操作系统/shell、代理/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 — 分别检查证书和 HTTP 状态，以免将非 2xx 响应误判为证书故障：

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 或操作系统网络配置。
• 如果无需打印值即可检查相关设置是否存在，则只报告设置是否存在。
• 如果可用命令会打印 URL、令牌、内部主机名、身份验证标头或完整配置值，则不要运行该命令。
• 只有当失败的操作已经访问了该软件包注册表，或用户批准了确切的探测目标后，才探测软件包注册表。

由用户批准的修复选项

将以下选项作为供用户批准的选择提出——绝不要自动应用。

诊断结果	安全建议
目标服务未在监听	检查本地或远程服务是否正在运行，以及预期端口是否正确。
DNS 查询失败	检查主机名、hosts 文件配置预期、DNS 服务状态，或已批准的 DNS 更改。
代理似乎是必需的或不可用	询问用户是否希望启动或调整代理/VPN，然后仅验证已批准的目标。
TLS 证书已过期	更新或更换证书、修正系统时间、安装受信任的本地开发 CA，或更新信任存储。绝不要绕过 TLS 验证。
TLS 未知 CA	在用户确认来源和范围后，将正确的 CA 导入相应的信任存储。
HTTP 407	在更改凭据或工具设置前，询问用户确认代理身份验证要求。
HTTP 403	检查身份验证、API 密钥范围、IP 允许列表、CORS 策略或服务策略。
HTTP 502/503/504	视为上游或网关不稳定；经批准后检查状态页，并采用退避策略重试。
软件包安装超时	讨论已批准的注册表、代理或网络路径选项，不打印或更改已存储的配置值。
Git 网络故障	讨论已批准的远程 URL、代理、凭据、TLS 或网络路径选项，不自动更改全局 Git 设置。
Docker 拉取失败	讨论经用户批准的注册表镜像、代理或守护进程设置，作为配置更改。

验证

• 进行任何经用户批准的更改后，尽可能重新运行最初失败的命令。
• 如果需要改用更小范围的检查，则将检查范围限定为同一个失败的主机、URL、注册表或服务。
• 在建议下一步之前，始终解释每项诊断结果的含义。