Nginx 故障排查
下面是一份 生产级《Nginx 故障排查指南》，从日志、命令、进程、upstream、反代、SSL、前端静态文件、性能、连接、超时等全链路排查。 这是企业真正使用的排查方式，一步步按这个查，快速定位 99% 的 Nginx 故障。
- 检查配置语法是否有错
- 检查 Nginx 是否启动、端口是否监听
- 查看 error.log（最关键）
- 检查 upstream 服务是否可访问
- 检查访问路径是否匹配正确的 location
- 确定反向代理是否走了正确的 target & header
- 检查系统层网络/防火墙/SElinux
无论你的 Nginx 是反向代理、静态资源、HTTPS、HTTP/2、前端项目，都可以依照这套流程排查。
nginx -t
错误示例：
invalid number of arguments in …duplicate location …unexpected “}” …invalid parameter …
如果 nginx -t 有错误，先解决再看其他问题。
之后重载：
nginx -s reload
ps aux | grep nginx
如果没有 worker 进程，说明 Nginx 根本没启动。
检查监听端口：
ss -lntp | grep nginx
例如：
0 0 0.0.0.0:80 LISTEN nginx
0 0 0.0.0.0:443 LISTEN nginx
如果 nginx 不监听端口，说明配置错误或未成功 reload。
默认路径：
/var/log/nginx/error.log
或你自定义的：
/data/nginx/logs/default/nginx/error.log
常见错误：
| 日志信息 | 说明 |
|---|---|
| connect() failed (111: Connection refused) | upstream 服务没开或端口不对 |
| upstream timed out | 后端太慢、网络不通 |
| no live upstreams | upstream 全挂了 |
| open() “/xxx” failed (2: No such file…) | root/alias 路径拼错 |
| SSL_do_handshake() failed | 证书或协议问题 |
| client intended to send too large body | 上传大小超过 client_max_body_size |
| directory index of “/xxx” is forbidden | 缺少 index 或权限不足 |
大部分 BUG 看 error.log 就能 30 秒定位。
upstream 是否真的能访问？
在服务器上直接命令：
curl -I http://127.0.0.1:8000/
curl -I http://backend-server-ip:8000/
如果 curl 都访问不了，Nginx 肯定访问不了。
如果反代 HTTPS 服务，必须加：
proxy_ssl_server_name on;
否则访问微信 API / Google / Cloud 服务会报错。
如果 upstream 是内网 Docker，要检查：
docker inspect your-container
对应 IP / Port 是否对得上。
例如你想匹配 /admin/：
❌ 错误的：
location /admin {
✅ 正确的：
location /admin/ {
React/Vue/Umi SPA 入口：
try_files $uri $uri/ /admin/index.html;
alias 必须加 “/” 结尾：
❌ 错误：
alias /data/www/admin;
✅ 正确：
alias /data/www/admin/;
最容易出问题的是 Host：
必须用：
proxy_set_header Host $http_host;
否则后端可能判断错域名或 301 重定向循环。
其他必备 header：
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
排查时可以把请求头打印出来：
curl -I http://your-server -H "Debug: 1"
并在后端记录 header。
查看证书是否配置正确
ssl_certificate /etc/nginx/ssl/example.crt;
ssl_certificate_key /etc/nginx/ssl/example.key;
常见错误：
| 错误 | 说明 |
|---|---|
| SSL: error:0B080074:x509… | key 与 cert 不匹配 |
| PEM lib | 格式错误 |
| no certificate found | 路径错 |
检查证书权限
chmod 600 *.key
检查 HTTP/2 是否正确启用
新写法：
listen 443 ssl;
http2 on;
worker_connections 不够会报：
could not create new connection
查看当前连接数：
netstat -anp | grep :80 | wc -l
文件描述符不足
查看：
ulimit -n
不足则：
ulimit -n 200000
并修改：
/etc/security/limits.conf
检查 CPU/内存 是否被打满
top -c
错误日志：
open() "/etc/nginx/html/index.html" failed (2: No such file or directory)
说明 root 配置不对，Nginx 拼出来的路径不存在。
打印最终路径：
location / {
echo $document_root;
echo $request_filename;
}
（需 ngx_echo 模块）
前端报：
CORS header 'Access-Control-Allow-Origin' missing
检查：
add_header Access-Control-Allow-Origin *;
add_header Access-Control-Allow-Headers *;
add_header Access-Control-Allow-Methods GET,POST,PUT,DELETE,OPTIONS;
并且 OPTIONS 必须返回 204：
location /api/ {
if ($request_method = OPTIONS) {
return 204;
}
}
是否被防火墙、iptables 拦住？
iptables -L -n
SELinux 可能导致 Nginx 无法访问目录
查看：
getenforce
如果是 Enforcing：
setenforce 0
nginx -t # 检查配置
systemctl status nginx # 状态
ps aux | grep nginx # 查看进程
ss -lntp | grep nginx # 查看监听端口
tail -f /var/log/nginx/error.log # 查看错误日志
curl -I http://127.0.0.1 # 本地连通性
curl -I http://backend-ip:port # upstream 连通性
netstat -anp | grep :80 # 查看连接数
ulimit -n # 查看文件描述符限制