方舟 · Ark

Appearance

Web 应用故障排查与应急响应指南 ​

目标：从“只会照着教程部署”，进阶到“出了问题能自己定位并解决”。

当客户反馈“网站打不开”或“接口请求失败”时，切忌盲目重启服务器或乱改代码。请严格按照本文的排查模型逐步缩小问题范围。

1. 故障排查漏斗模型 ​

故障排查就像漏斗，必须从最外层的网络一直排查到最内层的应用和数据库。任何一步不通，都不要去查下一步。

text
请求发起
   │
   ▼
[1. DNS 解析] ─────── 域名是否正确解析到了服务器 IP？
   │
   ▼
[2. 网络连通性] ───── 服务器公网 IP 是否能 Ping 通？
   │
   ▼
[3. 端口与防火墙] ─── 80/443 或特定业务端口是否开放？
   │
   ▼
[4. Nginx 网关] ───── Nginx 是否在运行？配置是否正确拦截了请求？
   │
   ▼
[5. 应用服务] ─────── 后端 API 容器/进程是否存活？内部是否报错？
   │
   ▼
[6. 外部依赖] ─────── 数据库、Redis 或第三方接口是否挂了？

2. 分层排查实战命令 ​

根据上述漏斗模型，对应执行以下验证命令：

2.1 检查 DNS 与网络 ​

  • 命令：ping yourdomain.com
  • 目的：看返回的 IP 是否是你的服务器 IP。如果 IP 不对，去云平台检查 DNS 解析记录；如果超时，可能是禁 Ping 或服务器彻底宕机。

2.2 检查端口与防火墙 ​

  • 命令 (外部测试)：在本地电脑执行 telnet your_server_ip 80 或 curl -I http://your_server_ip。
  • 命令 (服务器内检查)：登录服务器执行 sudo netstat -tulpn | grep 80。
  • 判断：如果服务器内显示端口监听正常，但外部连不上，100% 是云平台安全组或系统防火墙 (ufw / firewalld) 没放行。

2.3 检查应用服务状态 ​

  • Docker 部署：docker ps 检查容器是否是 Up 状态。如果是 Exited，说明程序崩溃了。
  • Systemd 部署：systemctl status your-service 检查是否是 active (running)。

4. 常见 HTTP 错误码深度解析 ​

当请求成功到达服务器，但返回了错误页面时，错误码是定位问题的最佳线索。

🚨 502 Bad Gateway (网关错误) ​

这是 Nginx 最常见的报错。意思是 Nginx 正常收到了用户的请求，但Nginx 找不到后端服务。

  • 根本原因 1：后端程序根本没启动。
    • 排查：docker ps 看 API 容器是不是挂了。
  • 根本原因 2：Nginx 配置的转发端口写错了。
    • 排查：检查 proxy_pass http://127.0.0.1:5000; 这里的端口，后端真的在监听 5000 吗？
  • 根本原因 3：Docker 网络隔离。
    • 排查：如果 Nginx 和 API 都在容器里，proxy_pass 不能写 127.0.0.1，必须写 API 的容器名（且需在同一网络下）。

🚨 403 Forbidden (禁止访问) ​

  • 根本原因 1：文件/目录权限不足。
    • 排查：Nginx 运行用户（通常是 www-data 或 nginx）对前端静态文件目录没有读权限。执行 chmod -R 755 /path/to/web。
  • 根本原因 2：缺少默认首页。
    • 排查：访问了一个目录，但目录下没有 index.html，且 Nginx 没有开启目录浏览权限。

🚨 404 Not Found (未找到资源) ​

  • 前端资源 404：部署的路径写错了，或者 Nginx root / alias 路径配置不正确。
  • Vue/React 刷新 404：单页应用 (SPA) 路由未交给前端接管。
    • 修复：Nginx 配置中必须添加 try_files $uri $uri/ /index.html;。
  • API 接口 404：后端路由未匹配，或者 Nginx 反向代理配置少写了 /api 前缀。

🚨 500 Internal Server Error (服务器内部错误) ​

这是后端代码本身出了问题。Nginx 把请求交给了后端，后端代码在执行时抛出了未捕获的异常（Exception）。

  • 排查动作：立刻去看后端的日志！
    • Docker: docker logs --tail=100 your-api-container
    • Systemd: journalctl -u your-api-service -n 100
  • 常见原因：
    • 数据库连不上（密码错、IP错、防火墙拦截）。
    • 代码里存在空指针引用 (Null Reference)。
    • SQL 语法错误或缺少对应的表字段。

5. 服务突发中断应急响应 SOP ​

当接到“服务彻底挂了”的紧急通知时，按以下步骤处理：

Step 1: 止血与现场保护 ​

  1. 立即查看监控/资源状态：执行 htop 或 top。
    • 如果 CPU 或内存达到 100%，极有可能是遭到了 CC 攻击或存在严重的内存泄漏。
  2. 检查磁盘是否爆满：执行 df -h。
    • 如果磁盘使用率 100%：数据库会直接锁死，应用无法写入日志从而崩溃。立刻清理 /var/log 或 Docker 废弃镜像 (docker image prune -a)。

Step 2: 定位死因 ​

  1. 看系统状态：docker ps 看看哪些容器挂了。

  2. 抓取临终日志：不要急着重启！先抓取挂掉之前的日志：

    bash
    docker logs --tail=500 api-container > crash_log.txt

Step 3: 恢复服务 ​

  1. 如果是内存耗尽导致的 OOM (Out of Memory)，重启服务通常能短暂恢复业务。

    bash
    docker compose restart

  2. 如果是代码 Bug 或数据库锁死，联系研发紧急回滚上一版本。

Step 4: 预防复发 ​

  • 将故障原因、排查过程、最终解决方案整理为复盘文档，补充到本知识库中。
  • 考虑增加 Prometheus/Grafana 等自动化监控报警体系。

Generated by Ark Gardener based on ops practices.

方舟 · Ark

Copyright © 2026-present WhatHappenin