Nginx 作为广泛使用的反向代理服务器，常常会在实际运维中遇到一些典型问题。本文将系统梳理常见的错误类型、原因分析、解决方案及排查技巧，帮助开发者和运维人员更高效地解决问题。

⸻

1️⃣ 502 Bad Gateway
问题描述：Nginx 接收到客户端请求，但无法正确从上游（Upstream）服务器获取响应。

常见原因及解决方案：
• 后端服务未启动或崩溃
• 检查：systemctl status 或 ps aux | grep <服务名>，确认服务状态。
• 解决：启动或重启后端服务。
• 防火墙/安全组阻断
• 检查：telnet <后端IP> <端口> 或 curl -v http://后端:端口。
• 解决：放行端口。
• Nginx 配置错误
• 检查：确保 proxy_pass 或 upstream 地址和端口正确。
• 解决：修正配置后重载：nginx -s reload。
• 后端超时
• 解决：增加超时时间，如 proxy_connect_timeout 60s; proxy_send_timeout 60s; proxy_read_timeout 60s;。
• 应用进程数不足（如 PHP-FPM）
• 检查：查看 PHP-FPM 状态或使用 netstat 查看连接数。
• 解决：调整 pm.max_children，优化代码。

⸻

2️⃣ 504 Gateway Time-out
问题描述：Nginx 在指定时间内未从上游服务器收到响应。

常见原因及解决方案：
• 后端处理过慢
• 优化：优化数据库、API 调用或应用性能；增加 proxy_read_timeout。
• 网络延迟或丢包
• 排查：使用 ping、traceroute 或 mtr 检查网络问题，与云厂商沟通。

⸻

3️⃣ 客户端真实 IP 丢失
问题描述：后端只能看到 Nginx 的 IP，无法获取真实客户端 IP。

解决方案：
在 Nginx 配置中添加以下指令：

proxy_set_header Host $host;
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;

⚠️ 后端需要解析 X-Forwarded-For 头部。

⸻

4️⃣ WebSocket 代理失败
问题描述：Nginx 默认不处理 WebSocket 协议升级。

解决方案：需要手动配置支持 WebSocket 协议升级。

location /ws/ {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;
}


⸻

5️⃣ 负载均衡不生效
常见原因及解决方案：
• upstream 配置不当：确保 upstream 配置放在 http 块内。
• 负载均衡算法问题：默认轮询（round-robin），可使用 ip_hash（会话保持）、least_conn（最少连接）等。
• 后端健康检查：使用 max_fails、fail_timeout 设置健康检查。
• 域名解析问题：社区版需要 resolver 配合变量。

resolver 8.8.8.8 valid=30s;



⸻

6️⃣ 静态文件访问异常或慢
常见原因及解决方案：
• 路径错误：检查 alias 或 root 配置是否正确。
• 权限不足：确保 Nginx 用户对文件有读取权限。
• 优化静态资源：设置缓存和过期时间。

location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ {
root /path/to/static/files;
expires 30d;
access_log off;
}



⸻

7️⃣ 大文件上传失败（413 Request Entity Too Large）
问题描述：Nginx 默认请求体限制过小，导致大文件上传失败。

解决方案：
• 增加 client_max_body_size 配置：

client_max_body_size 100m;



⚠️ 同时检查后端应用的上传限制。

⸻

8️⃣ SSL/TLS 报错
常见原因及解决方案：
• 证书链不完整：使用 fullchain.pem。
• 协议配置不当：启用现代协议，确保 TLSv1.2 和 TLSv1.3 可用。

ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;



⸻

9️⃣ 缓存未命中或性能差
常见原因及解决方案：
• 后端响应缓存：

proxy_cache my_cache;
proxy_cache_valid 200 1m;


• 静态资源缓存：

expires 30d;
add_header Cache-Control "public";



⸻

防刷与限流

目的：防止恶意高并发请求，保护服务器资源。

配置示例：

limit_conn_zone $binary_remote_addr zone=addr:10m;
limit_req_zone $binary_remote_addr zone=one:10m rate=10r/s;

location / {
limit_conn addr 10;
limit_req zone=one burst=20 nodelay;
}


⸻

通用排查技巧
1. 查看日志：
• 错误日志：tail -f /var/log/nginx/error.log
• 访问日志：检查请求流向。
2. 配置检查：
• nginx -t：检查配置文件是否有误。
• nginx -s reload：平滑重载 Nginx 配置。
3. 常用命令：
• ss -lntp：查看监听端口。
• lsof -i :80：查看端口占用情况。
• nginx -V：查看 Nginx 编译时的模块。
• curl -v http://localhost:端口：本地测试。

⸻

✅ 总结

Nginx 的常见问题大致可分为：
• 错误码类（502、504）。
• 功能类（客户端 IP、WebSocket、负载均衡、上传、SSL 配置等）。
• 性能类（静态资源、缓存、限流）。

通过结合 日志、配置检查、网络排查 三个步骤，大部分问题可以快速定位并解决，保障 Nginx 的稳定运行。

阅读原文：原文链接