Nginx 502 Bad Gateway 完全排查指南:5 大根因定位 + 10 分钟快速修复 + 永久监控方案
1. Nginx 502 Bad Gateway 完全排查指南:5 大根因定位 + 10 分钟快速修复 + 永久监控方案
核心收益:
- • 系统化诊断流程,10 分钟定位 502 错误根因
- • 提供自动化诊断脚本与 Prometheus 监控配置
2. 适用场景 & 前置条件
| |
|---|
| Web 应用偶发或持续出现 502 错误,需快速定位与修复 |
| Nginx 反向代理 + 后端应用服务器(PHP-FPM/Tomcat/Node.js/Python 等) |
| RHEL/CentOS 7.9+ 或 Ubuntu 20.04+ |
| |
| PHP-FPM 7.4+ / Tomcat 8.5+ / Node.js 14+ / Python/Django/Flask |
| |
| |
| |
| 熟悉 Linux 命令、HTTP 协议、Nginx 配置、日志分析 |
3. 反模式警告(何时不适用)
⚠️ 以下场景不推荐使用本方案:
- 1. 502 错误来自上游 CDN:如果 CDN 返回 502,问题在 CDN 层,需联系 CDN 服务商
- 2. Nginx 作为纯静态服务器:无反向代理配置,不会出现 502(会是 404/403)
- 3. 客户端网络问题:客户端看到 502 但服务器日志无记录,问题在客户端或中间网络
- 4. 云负载均衡返回 502:问题在 ALB/ELB/SLB,需检查云平台健康检查配置
- 5. Nginx 未启动或崩溃:返回连接拒绝(Connection Refused),不是 502
替代方案对比:
4. 环境与版本矩阵
| | | |
|---|
| RHEL 8.7+ / CentOS Stream 9 | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
版本差异说明:
- • Nginx 1.18 vs 1.24:proxy_connect_timeout 默认值差异(60s vs 60s,一致)
- • PHP-FPM 7.4 vs 8.2:默认进程管理方式(dynamic vs ondemand)影响连接处理
5. 阅读导航
📖
建议阅读路径:
快速上手(10分钟):→ 章节6(快速清单) → 章节7(实施步骤 Step 1-3) → 章节15(自动诊断脚本)
深入理解(35分钟):→ 章节8(最小必要原理) → 章节7(实施步骤完整版) → 章节10(可观测性) → 章节12(最佳实践)
故障排查:→ 章节9(5 大根因分析) → 章节11(故障排查表) → 章节7(对应修复步骤)
6. 快速清单(Checklist)
- • [ ] 收集错误现象(是偶发还是持续,影响范围)
- • [ ] 备份 Nginx 配置(
cp -r /etc/nginx /etc/nginx.bak)
- • [ ] 检查 Nginx 错误日志(
tail -f /var/log/nginx/error.log) - • [ ] 验证后端服务运行状态(
systemctl status php-fpm / systemctl status tomcat) - • [ ] 测试后端服务连通性(
curl http://127.0.0.1:9000 / telnet 127.0.0.1 8080) - • [ ] 检查 Nginx upstream 配置(
nginx -t) - • [ ] 排查 SELinux/防火墙(
getenforce / iptables -L)
- • [ ] 重载 Nginx 配置(
nginx -t && systemctl reload nginx)
- • [ ] 测试访问恢复(
curl -I http://yourdomain.com) - • [ ] 观察错误日志 5 分钟(
tail -f /var/log/nginx/error.log) - • [ ] 配置监控告警(Prometheus + Grafana)
7. 实施步骤(核心内容)
架构与数据流说明(文字描述)
系统架构:
客户端(浏览器)
↓
Nginx 反向代理(监听 80/443)
↓
upstream 后端服务池
├─ PHP-FPM(127.0.0.1:9000 或 /var/run/php-fpm.sock)
├─ Tomcat(127.0.0.1:8080)
├─ Node.js(127.0.0.1:3000)
└─ Python/Django(127.0.0.1:8000)
↓
应用逻辑处理
↓
数据库/缓存(MySQL/Redis)
502 错误可能发生的 3 个关键位置:
- 1. 位置 1:Nginx → 后端服务连接建立阶段
- • 错误日志:
connect() failed (111: Connection refused)
2. 位置 2:Nginx → 后端服务数据传输阶段- • 错误日志:
upstream timed out (110: Connection timed out)
3. 位置 3:Nginx upstream 连接池管理- • 错误日志:
no live upstreams while connecting to upstream
正常请求流程:
- 1. 客户端发送 HTTP 请求到 Nginx(端口 80/443)
- 2. Nginx 根据 location 规则匹配到 upstream
- 3. Nginx 从 upstream 连接池获取或新建连接到后端服务
- 4. 后端服务处理请求并返回响应(HTTP 200)
- 6. 连接保持或关闭(根据 keepalive 配置)
502 错误触发条件:
- • Nginx 成功接收客户端请求(Nginx 正常运行)
- • Nginx 尝试连接后端服务失败或收到无效响应
- • Nginx 返回 502 Bad Gateway 给客户端
Step 1: 快速定位问题层(Nginx 日志分析)
目标: 通过 Nginx 日志确定 502 错误类型与后端服务状态
RHEL/CentOS 命令:
# 实时查看 Nginx 错误日志
tail -f /var/log/nginx/error.log
# 统计最近 1 小时的 502 错误数量
grep "502" /var/log/nginx/access.log | grep "$(date +%d/%b/%Y:%H)" | wc -l
# 提取 upstream 相关错误(最近 100 行)
tail -n 100 /var/log/nginx/error.log | grep -E "upstream|connect|timed out"
# 查看 Nginx 访问日志中的 502 记录(带时间戳)
awk '$9 == 502' /var/log/nginx/access.log | tail -20
Ubuntu/Debian 命令:
# 实时查看 Nginx 错误日志
tail -f /var/log/nginx/error.log
# 统计最近 1 小时的 502 错误数量
grep "502" /var/log/nginx/access.log | grep "$(date +%d/%b/%Y:%H)" | wc -l
# 提取 upstream 相关错误(最近 100 行)
tail -n 100 /var/log/nginx/error.log | grep -E "upstream|connect|timed out"
# 查看 Nginx 访问日志中的 502 记录(带时间戳)
awk '$9 == 502' /var/log/nginx/access.log | tail -20
关键日志模式识别:
模式 1:连接拒绝(后端服务未启动)
2025/01/15 10:23:45 [error] 12345#12345: *67890 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.100, server: example.com, request: "GET /api/users HTTP/1.1", upstream: "http://127.0.0.1:9000/api/users", host: "example.com"
模式 2:连接超时(后端服务无响应)
2025/01/15 10:25:30 [error] 12345#12345: *67891 upstream timed out (110: Connection timed out) while connecting to upstream, client: 192.168.1.100, server: example.com, request: "GET /api/slow HTTP/1.1", upstream: "http://127.0.0.1:8080/api/slow", host: "example.com"
模式 3:读取超时(后端处理慢)
2025/01/15 10:27:10 [error] 12345#12345: *67892 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 192.168.1.100, server: example.com, request: "POST /api/process HTTP/1.1", upstream: "http://127.0.0.1:3000/api/process", host: "example.com"
模式 4:无可用 upstream(连接池耗尽)
2025/01/15 10:29:00 [error] 12345#12345: *67893 no live upstreams while connecting to upstream, client: 192.168.1.100, server: example.com, request: "GET /api/data HTTP/1.1", upstream: "http://backend/api/data", host: "example.com"
执行后验证:
# 确认日志文件存在且有内容
ls -lh /var/log/nginx/error.log
# 预期输出:-rw-r--r-- 1 nginx nginx 12M Jan 15 10:30 /var/log/nginx/error.log
# 检查日志是否实时更新
stat /var/log/nginx/error.log | grep Modify
# 预期输出:Modify: 2025-01-15 10:30:45(应为当前时间附近)
常见错误示例:
# 错误1:日志文件不存在
tail: cannot open '/var/log/nginx/error.log'for reading: No such file or directory
# 解决:检查 Nginx 配置 error_log 指令路径
# 错误2:权限不足
tail: /var/log/nginx/error.log: Permission denied
# 解决:使用 sudo 或切换到 root 用户
Step 2: 检查后端服务健康状态
目标: 验证后端服务(PHP-FPM/Tomcat/Node.js 等)是否正常运行
场景 A:PHP-FPM 后端
RHEL/CentOS 命令:
# 检查 PHP-FPM 服务状态
systemctl status php-fpm
# 查看 PHP-FPM 进程
ps aux | grep php-fpm
# 检查 PHP-FPM 监听端口或 socket
ss -tlnp | grep php-fpm
# 或检查 socket 文件
ls -l /var/run/php-fpm/php-fpm.sock
# 查看 PHP-FPM 错误日志
tail -f /var/log/php-fpm/error.log
# 检查 PHP-FPM 配置
php-fpm -t
Ubuntu/Debian 命令:
# 检查 PHP-FPM 服务状态
systemctl status php8.2-fpm
# 查看 PHP-FPM 进程
ps aux | grep php-fpm
# 检查 PHP-FPM 监听端口或 socket
ss -tlnp | grep php-fpm
# 或检查 socket 文件
ls -l /run/php/php8.2-fpm.sock
# 查看 PHP-FPM 错误日志
tail -f /var/log/php8.2-fpm.log
# 检查 PHP-FPM 配置
php-fpm8.2 -t
场景 B:Tomcat 后端
RHEL/CentOS 与 Ubuntu 通用命令:
# 检查 Tomcat 服务状态
systemctl status tomcat
# 查看 Tomcat 进程
ps aux | grep tomcat
# 检查 Tomcat 监听端口
ss -tlnp | grep 8080
# 查看 Tomcat 日志
tail -f /opt/tomcat/logs/catalina.out
# 测试 Tomcat 响应
curl -I http://127.0.0.1:8080
场景 C:Node.js/Python 后端(PM2 管理)
通用命令:
# 检查 PM2 进程列表
pm2 list
# 查看特定应用日志
pm2 logs app-name --lines 50
# 检查应用监听端口
ss -tlnp | grep node
# 或 Python
ss -tlnp | grep python
# 重启应用
pm2 restart app-name
执行后验证:
# PHP-FPM 验证(TCP 模式)
echo"" | php-cgi -b 127.0.0.1:9000
# 预期输出:PHP 信息或错误提示
# PHP-FPM 验证(Unix Socket 模式)
ls -l /var/run/php-fpm/php-fpm.sock
# 预期输出:srw-rw---- 1 nginx nginx 0 Jan 15 10:00 /var/run/php-fpm/php-fpm.sock
# Tomcat 验证
curl -s http://127.0.0.1:8080 | grep -i "tomcat"
# 预期输出:包含 "Tomcat" 字样的 HTML
常见错误示例:
# 错误1:PHP-FPM 未启动
Unit php-fpm.service could not be found.
# 解决:
yum install -y php-fpm # RHEL
apt install -y php8.2-fpm # Ubuntu
# 错误2:Socket 文件不存在
ls: cannot access '/var/run/php-fpm/php-fpm.sock': No such file or directory
# 解决:检查 PHP-FPM 配置 listen 参数,确保路径正确并启动服务
# 错误3:端口未监听
ss -tlnp | grep 8080
# 无输出
# 解决:检查后端服务配置端口并重启服务
Step 3: 验证网络连通性(curl/telnet 测试)
目标: 从 Nginx 服务器测试到后端服务的网络连通性
测试 HTTP 后端(Tomcat/Node.js/Python):
# 测试 HTTP 连接(GET 请求)
curl -v http://127.0.0.1:8080/
# 测试 HTTP 连接(带超时)
curl -v --connect-timeout 5 --max-time 10 http://127.0.0.1:8080/
# 测试特定 URI
curl -I http://127.0.0.1:8080/api/health
# 使用 telnet 测试端口连通性
telnet 127.0.0.1 8080
# 输入 GET / HTTP/1.0 后按两次回车
测试 FastCGI 后端(PHP-FPM TCP 模式):
# 使用 cgi-fcgi 工具测试
# 安装工具(RHEL)
yum install -y fcgi
# 安装工具(Ubuntu)
apt install -y libfcgi-bin
# 测试 FastCGI
SCRIPT_FILENAME=/var/www/html/index.php \
REQUEST_METHOD=GET \
cgi-fcgi -bind -connect 127.0.0.1:9000
测试 Unix Socket(PHP-FPM Socket 模式):
# 使用 socat 测试(需安装)
yum install -y socat # RHEL
apt install -y socat # Ubuntu
# 测试 socket 连通性
echo -e "GET / HTTP/1.0\r\n\r\n" | socat - UNIX-CONNECT:/var/run/php-fpm/php-fpm.sock
执行后验证:
# HTTP 测试成功示例
curl -I http://127.0.0.1:8080/
# 预期输出:
# HTTP/1.1 200 OK
# Server: Apache-Coyote/1.1
# Content-Type: text/html;charset=UTF-8
# Telnet 测试成功示例
telnet 127.0.0.1 8080
# 预期输出:
# Trying 127.0.0.1...
# Connected to 127.0.0.1.
# Escape character is '^]'.
常见错误示例:
# 错误1:连接拒绝
curl: (7) Failed to connect to 127.0.0.1 port 8080: Connection refused
# 根因:后端服务未启动或端口配置错误
# 错误2:连接超时
curl: (28) Connection timed out after 5001 milliseconds
# 根因:防火墙阻断或后端服务无响应
# 错误3:读取超时
curl: (28) Operation timed out after 10000 milliseconds with 0 bytes received
# 根因:后端服务处理慢,超过超时时间
Step 4: 分析 Nginx 配置(upstream/proxy 参数)
目标: 检查 Nginx upstream 配置是否正确,proxy 参数是否合理
检查配置语法:
# 测试 Nginx 配置语法
nginx -t
# 查看当前生效的配置
nginx -T | less
检查 upstream 配置:
# 查看 upstream 定义
grep -A 10 "upstream" /etc/nginx/nginx.conf /etc/nginx/conf.d/*.conf
典型 upstream 配置示例:
场景 A:PHP-FPM(Unix Socket)
upstream php_backend {
server unix:/var/run/php-fpm/php-fpm.sock;
# 或 TCP 模式
# server 127.0.0.1:9000;
}
server {
listen80;
server_name example.com;
root /var/www/html;
index index.php;
location~ \.php$ {
try_files$uri =404;
fastcgi_pass php_backend;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
# 关键超时参数
fastcgi_connect_timeout60s;
fastcgi_send_timeout60s;
fastcgi_read_timeout60s;
}
}
场景 B:Tomcat/Node.js(HTTP 反向代理)
upstream app_backend {
server127.0.0.1:8080 max_fails=3 fail_timeout=30s;
# 多后端负载均衡
# server 127.0.0.1:8081 max_fails=3 fail_timeout=30s;
# server 127.0.0.1:8082 max_fails=3 fail_timeout=30s backup;
# 连接池配置
keepalive32;
keepalive_timeout60s;
}
server {
listen80;
server_name example.com;
location / {
proxy_pass http://app_backend;
# 关键 proxy 参数
proxy_connect_timeout60s;
proxy_send_timeout60s;
proxy_read_timeout60s;
# 请求头转发
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;
# HTTP 版本与连接保持
proxy_http_version1.1;
proxy_set_header Connection "";
}
}
关键参数解释:
- 1.
proxy_connect_timeout 60s:Nginx 连接到后端服务器的超时时间
2. proxy_read_timeout 60s:Nginx 等待后端服务器响应的超时时间3. max_fails=3 fail_timeout=30s:健康检查参数执行后验证:
# 检查配置语法
nginx -t
# 预期输出:
# nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
# nginx: configuration file /etc/nginx/nginx.conf test is successful
# 查看 upstream 配置
nginx -T | grep -A 20 "upstream"
# 预期输出:显示 upstream 定义块
# 重载配置
systemctl reload nginx
常见配置错误:
错误 1:upstream 拼写错误
# 错误配置
upstream php_backend {
server unix:/var/run/php-fpm.sock; # socket 路径错误
}
解决:确认 socket 路径与 PHP-FPM 配置一致
错误 2:proxy_pass 语法错误
# 错误配置
location / {
proxy_pass http://127.0.0.1:8080/; # 带尾部斜杠会导致 URI 拼接问题
}
解决:理解 proxy_pass 有无尾部斜杠的差异
- •
proxy_pass http://backend; → 转发完整 URI - •
proxy_pass http://backend/; → 转发去除 location 前缀的 URI
错误 3:fastcgi_pass 路径错误
# 错误配置
fastcgi_pass unix:/run/php/php-fpm.sock; # Ubuntu 路径
# 但实际 socket 在 /var/run/php-fpm/php-fpm.sock(RHEL)
解决:根据系统差异调整路径
Step 5: 系统层排查(SELinux/防火墙/资源)
目标: 排查系统层面的限制与资源瓶颈
检查 SELinux(仅 RHEL/CentOS):
# 查看 SELinux 状态
getenforce
# 输出:Enforcing(强制)/ Permissive(宽容)/ Disabled(禁用)
# 查看 SELinux 拒绝日志
ausearch -m avc -ts recent | grep nginx
# 临时禁用 SELinux(测试用)
setenforce 0
# 永久禁用 SELinux(编辑配置)
sed -i 's/^SELINUX=enforcing/SELINUX=disabled/' /etc/selinux/config
# 需重启生效
# 配置 SELinux 允许 Nginx 连接网络
setsebool -P httpd_can_network_connect 1
# 配置 SELinux 允许 Nginx 连接数据库
setsebool -P httpd_can_network_connect_db 1
检查防火墙:
RHEL/CentOS(firewalld):
# 查看防火墙状态
systemctl status firewalld
# 查看已开放端口
firewall-cmd --list-all
# 临时禁用防火墙(测试用)
systemctl stop firewalld
# 永久开放端口(如需)
firewall-cmd --permanent --add-port=8080/tcp
firewall-cmd --reload
Ubuntu/Debian(ufw 或 iptables):
# 查看 ufw 状态
ufw status
# 临时禁用 ufw(测试用)
ufw disable
# 查看 iptables 规则
iptables -L -n -v
# 临时清空 iptables 规则(测试用,危险操作)
iptables -F
检查系统资源:
# 检查 CPU 使用率
top -bn1 | head -20
# 检查内存使用
free -h
# 检查磁盘空间
df -h
# 检查文件描述符限制
ulimit -n
# 检查进程数限制
ulimit -u
# 查看 Nginx worker 进程的文件描述符
cat /proc/$(pgrep nginx | head -1)/limits | grep "open files"
检查后端服务资源限制:
# PHP-FPM 进程数限制
grep -E "pm.max_children|pm.start_servers" /etc/php-fpm.d/www.conf
# Tomcat 内存配置
grep -E "Xms|Xmx" /opt/tomcat/bin/setenv.sh
# 检查端口连接数
ss -ant | grep 8080 | wc -l
执行后验证:
# SELinux 测试
# 临时禁用后测试 502 是否消失
setenforce 0
curl -I http://yourdomain.com
# 如果恢复正常,说明是 SELinux 问题
# 防火墙测试
systemctl stop firewalld
curl -I http://yourdomain.com
# 如果恢复正常,说明是防火墙问题
# 恢复测试环境
setenforce 1
systemctl start firewalld
常见系统层问题:
问题 1:SELinux 阻止 Nginx 连接后端
# 错误日志
connect() to unix:/var/run/php-fpm.sock failed (13: Permission denied)
# 解决方案
setsebool -P httpd_can_network_connect 1
# 或临时禁用 SELinux 测试
setenforce 0
问题 2:文件描述符耗尽
# 错误日志
accept4() failed (24: Too many open files)
# 解决方案
# 编辑 /etc/security/limits.conf
nginx soft nofile 65536
nginx hard nofile 65536
# 编辑 Nginx systemd 配置
mkdir -p /etc/systemd/system/nginx.service.d
cat > /etc/systemd/system/nginx.service.d/limits.conf <<EOF
[Service]
LimitNOFILE=65536
EOF
systemctl daemon-reload
systemctl restart nginx
问题 3:后端服务进程数不足
# PHP-FPM 配置调整
# 编辑 /etc/php-fpm.d/www.conf
pm = dynamic
pm.max_children = 50 # 最大子进程数(根据内存调整)
pm.start_servers = 10 # 启动时进程数
pm.min_spare_servers = 5 # 最小空闲进程
pm.max_spare_servers = 15 # 最大空闲进程
# 重启 PHP-FPM
systemctl restart php-fpm
Step 6: 永久修复方案(配置优化 + 监控)
目标: 根据根因应用永久修复方案,配置监控告警
修复方案汇总:
根因 1:后端服务未启动 → 自动重启 + 健康检查
# 配置 systemd 自动重启
mkdir -p /etc/systemd/system/php-fpm.service.d
cat > /etc/systemd/system/php-fpm.service.d/restart.conf <<EOF
[Service]
Restart=always
RestartSec=10s
EOF
systemctl daemon-reload
systemctl restart php-fpm
根因 2:响应超时 → 增加超时参数 + 优化后端性能
# Nginx 配置优化
http {
# 全局超时配置
proxy_connect_timeout120s;
proxy_send_timeout120s;
proxy_read_timeout300s; # 针对慢查询场景
fastcgi_connect_timeout60s;
fastcgi_send_timeout180s;
fastcgi_read_timeout300s;
}
根因 3:连接池耗尽 → 增加后端进程数 + keepalive
# Nginx upstream 优化
upstream app_backend {
server127.0.0.1:8080;
keepalive64
; # 增加连接池大小
keepalive_timeout300s; # 连接保持时间
keepalive_requests1000; # 单连接最大请求数
}
server {
location / {
proxy_pass http://app_backend;
proxy_http_version1.1;
proxy_set_header Connection ""; # 重用连接
}
}
根因 4:SELinux/防火墙 → 配置白名单
# SELinux 永久配置
setsebool -P httpd_can_network_connect 1
setsebool -P httpd_can_network_connect_db 1
# 防火墙永久配置(如需开放外部访问后端)
firewall-cmd --permanent --add-port=8080/tcp
firewall-cmd --reload
根因 5:配置错误 → 标准化配置模板
# 创建配置模板目录
mkdir -p /etc/nginx/templates
# 使用版本控制管理配置
cd /etc/nginx
git init
git add .
git commit -m "Initial Nginx configuration"
# 配置变更流程:测试 → 备份 → 应用 → 验证
nginx -t && \
cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak.$(date +%Y%m%d%H%M%S) && \
systemctl reload nginx && \
sleep 3 && \
curl -I http://localhost
8. 最小必要原理
502 Bad Gateway 错误机制:
502 错误是 HTTP 状态码,表示作为网关或代理的服务器(Nginx)从上游服务器(后端应用)收到无效响应。
触发条件:
- 2. Nginx 尝试将请求转发到 upstream 后端服务
与其他错误码的区别:
- • 500 Internal Server Error:Nginx 自身处理错误(配置错误、脚本错误)
- • 503 Service Unavailable:Nginx 主动拒绝服务(过载保护、维护模式)
- • 504 Gateway Timeout:Nginx 等待后端响应超时(与 502 类似,但强调超时)
Nginx upstream 健康检查机制:
- • 参数
max_fails=3 fail_timeout=30s 含义: - • 30 秒内失败 3 次 → 标记后端为 down
- • 标记 down 后的 30 秒内不再转发请求到该后端
- • 主动检查:需 Nginx Plus 商业版或第三方模块(nginx_upstream_check_module)
为什么 PHP-FPM 使用 Unix Socket 更快?
- • TCP 模式:127.0.0.1:9000(经过 TCP/IP 协议栈)
- • Unix Socket 模式:/var/run/php-fpm.sock(本地 IPC,无网络开销)
- • 性能差异:Socket 延迟 < 0.1ms,TCP 延迟 0.5-1ms
连接保持(keepalive)的重要性:
- • 无 keepalive:每个请求建立新连接(三次握手开销)
- • 有 keepalive:复用连接,减少 CPU 与延迟
- • 建议配置:
keepalive 32;(根据并发调整)
9. 可观测性(监控 + 告警 + 性能)
9.1 Nginx 日志分析脚本
脚本路径:/opt/scripts/nginx_502_analyzer.sh
#!/bin/bash
# Nginx 502 错误分析脚本
LOG_FILE="/var/log/nginx/access.log"
ERROR_LOG="/var/log/nginx/error.log"
TIME_RANGE="1 hour ago"
echo"==== Nginx 502 错误分析(最近 1 小时)===="
echo""
# 1. 统计 502 错误总数
TOTAL_502=$(grep "502"${LOG_FILE} | grep "$(date --date="${TIME_RANGE}" +%d/%b/%Y:%H)" | wc -l)
echo"502 错误总数: ${TOTAL_502}"
# 2. 按 URL 统计 502 错误
echo""
echo"Top 10 502 错误 URL:"
awk '$9 == 502 {print $7}'${LOG_FILE} | sort | uniq -c | sort -rn | head -10
# 3. 按客户端 IP 统计
echo""
echo"Top 10 502 错误来源 IP:"
awk '$9 == 502 {print $1}'${LOG_FILE} | sort | uniq -c | sort -rn | head -10
# 4. 提取 error.log 中的 upstream 错误
echo""
echo"Upstream 错误统计:"
grep -E "upstream|connect|timed out"${ERROR_LOG} | tail -20
# 5. 检查后端服务状态
echo""
echo"后端服务状态检查:"
systemctl is-active php-fpm tomcat nginx 2>/dev/null || echo"部分服务未安装或未运行"
# 6. 检查端口监听
echo""
echo"后端服务端口监听:"
ss -tlnp | grep -E ":8080|:9000|:3000"
echo""
echo"==== 分析完成 ===="
使用方法:
chmod +x /opt/scripts/nginx_502_analyzer.sh
/opt/scripts/nginx_502_analyzer.sh
9.2 Prometheus 监控配置
node_exporter textfile collector 脚本:
#!/bin/bash
# 路径:/opt/prometheus/nginx_502_exporter.sh
TEXTFILE="/var/lib/node_exporter/textfile_collector/nginx_502.prom"
ACCESS_LOG="/var/log/nginx/access.log"
# 统计最近 5 分钟的 502 错误数
COUNT_502=$(grep "502"${ACCESS_LOG} | grep "$(date --date='5 minutes ago' +%d/%b/%Y:%H:%M)" | wc -l)
# 统计总请求数
TOTAL_REQUESTS=$(wc -l ${ACCESS_LOG})
# 计算 502 错误率
if [ ${TOTAL_REQUESTS} -gt 0 ]; then
ERROR_RATE=$(echo"scale=4; ${COUNT_502} / ${TOTAL_REQUESTS} * 100" | bc)
else
ERROR_RATE=0
fi
# 输出 Prometheus 指标
cat > ${TEXTFILE} <<EOF
# HELP nginx_502_errors_total Total number of 502 errors in last 5 minutes
# TYPE nginx_502_errors_total gauge
nginx_502_errors_total ${COUNT_502}
# HELP nginx_502_error_rate 502 error rate percentage
# TYPE nginx_502_error_rate gauge
nginx_502_error_rate ${ERROR_RATE}
# HELP nginx_requests_total Total number of requests
# TYPE nginx_requests_total counter
nginx_requests_total ${TOTAL_REQUESTS}
EOF
定时任务:
# 每 1 分钟采集一次
crontab -e
* * * * * /opt/prometheus/nginx_502_exporter.sh
Prometheus 告警规则:
# prometheus_rules.yml
groups:
-name:nginx_502_alerts
interval:30s
rules:
# 告警1:502 错误率超过 5%
-alert:High502ErrorRate
expr:nginx_502_error_rate>5
for:2m
labels:
severity:critical
annotations:
summary:"Nginx 502 错误率过高(实例:{{ $labels.instance }})"
description:"过去 5 分钟 502 错误率为 {{ $value }}%,超过阈值 5%"
# 告警2:502 错误数突增
-alert:Sudden502ErrorSpike
expr:rate(nginx_502_errors_total[5m])>10
for:1m
labels:
severity:warning
annotations:
summary:"Nginx 502 错误突增(实例:{{ $labels.instance }})"
description:"过去 5 分钟 502 错误速率为 {{ $value }} 次/秒"
# 告警3:后端服务异常(结合 node_exporter systemd 指标)
-alert:BackendServiceDown
expr:node_systemd_unit_state{name=~"php-fpm.service|tomcat.service",state="active"}==0
for:30s
labels:
severity:critical
annotations:
summary:"后端服务停止(服务:{{ $labels.name }})"
description:"{{ $labels.name }} 在实例 {{ $labels.instance }} 上未运行"
Grafana 面板建议:
{
"panels":[
{
"title":"502 错误率(5 分钟)",
"targets":[{"expr":"nginx_502_error_rate"}
],
"type":"graph",
"yaxes":[{"format":"percent"}]
},
{
"title":"502 错误数趋势",
"targets":[{"expr":"rate(nginx_502_errors_total[5m])"}],
"type":"graph"
},
{
"title":"后端服务状态",
"targets":[{"expr":"node_systemd_unit_state{name=~'php-fpm.service|tomcat.service'}"}],
"type":"stat",
"fieldConfig":{"mappings":[{"value":1,"text":"运行"},{"value":0,"text":"停止"}]}
}
]
}
9.3 性能基准测试
测试 502 错误恢复时间:
#!/bin/bash
# 持续请求测试脚本
URL="http://yourdomain.com/api/test"
INTERVAL=0.5
whiletrue; do
TIMESTAMP=$(date +"%Y-%m-%d %H:%M:%S")
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}"${URL})
RESPONSE_TIME=$(curl -s -o /dev/null -w "%{time_total}"${URL})
if [ "$HTTP_CODE" == "502" ]; then
echo"${TIMESTAMP} - HTTP ${HTTP_CODE} - ${RESPONSE_TIME}s [FAILED]"
else
echo"${TIMESTAMP} - HTTP ${HTTP_CODE} - ${RESPONSE_TIME}s [OK]"
fi
sleep${INTERVAL}
done
使用 wrk 压力测试:
# 安装 wrk
yum install -y wrk # RHEL
apt install -y wrk # Ubuntu
# 压力测试(10 线程,100 并发,30 秒)
wrk -t10 -c100 -d30s --latency http://yourdomain.com/
# 观察 502 错误率
grep "Non-2xx" wrk 输出
10. 常见故障与排错(5 大根因详解)
| | | | |
|---|
| 根因 1:后端服务未启动 | systemctl status php-fpm | |
systemctl start php-fpm | 配置自动重启(systemd Restart=always) |
| 根因 2:响应超时 | tail -f /var/log/nginx/error.log | grep timeout | | 增加 proxy_read_timeout 300s | |
| 根因 3:连接池耗尽 | ss -ant | grep ESTAB | wc -l | | 增加 pm.max_children(PHP-FPM) | |
| 根因 4:SELinux 阻断 | ausearch -m avc -ts recent | grep nginx | | setenforce 0 | setsebool -P httpd_can_network_connect 1 |
| 根因 5:配置错误 | nginx -t | | 修正配置 + systemctl reload nginx | |
根因 1:后端服务未启动或崩溃
典型日志特征:
connect() failed (111: Connection refused) while connecting to upstream
完整诊断流程:
# 1. 检查后端服务状态
systemctl status php-fpm tomcat
# 2. 查看进程
ps aux | grep -E "php-fpm|java.*tomcat"
# 3. 检查端口监听
ss -tlnp | grep -E ":9000|:8080"
# 4. 查看后端服务日志
tail -f /var/log/php-fpm/error.log
tail -f /opt/tomcat/logs/catalina.out
# 5. 尝试启动服务
systemctl start php-fpm
永久修复:
# 配置 systemd 自动重启
mkdir -p /etc/systemd/system/php-fpm.service.d
cat > /etc/systemd/system/php-fpm.service.d/restart.conf <<EOF
[Service]
Restart=always
RestartSec=10s
StartLimitBurst=5
StartLimitIntervalSec=60s
EOF
systemctl daemon-reload
根因 2:后端服务响应超时
典型日志特征:
upstream timed out (110: Connection timed out) while reading response header from upstream
完整诊断流程:
# 1. 检查 Nginx 超时配置
grep -E "proxy_read_timeout|fastcgi_read_timeout" /etc/nginx/nginx.conf
# 2. 手动测试后端响应时间
time curl -I http://127.0.0.1:8080/slow-api
# 3. 检查后端服务性能
top -p $(pgrep php-fpm | head -1)
# 4. 检查数据库慢查询
mysql -e "SHOW FULL PROCESSLIST;" | grep -v Sleep
# 5. 临时增加超时时间测试
# 编辑 Nginx 配置
proxy_read_timeout 300s;
nginx -t && systemctl reload nginx
永久修复:
# Nginx 配置优化
http {
# 根据业务场景调整
proxy_connect_timeout60s;
proxy_send_timeout120s;
proxy_read_timeout300s; # 针对慢查询场景
fastcgi_read_timeout300s;
}
后端性能优化(PHP-FPM 示例):
# /etc/php-fpm.d/www.conf
request_terminate_timeout = 300s # 与 Nginx 超时对齐
pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 15
根因 3:连接池耗尽或进程数不足
典型日志特征:
no live upstreams while connecting to upstream
完整诊断流程:
# 1. 检查当前连接数
ss -ant | grep ESTAB | grep -E ":9000|:8080" | wc -l
# 2. 检查 PHP-FPM 进程数
ps aux | grep php-fpm | wc -l
# 3. 查看 PHP-FPM 状态页(需配置)
curl http://127.0.0.1/php-fpm-status
# 4. 检查 Nginx upstream 配置
grep -A 5 "upstream"
/etc/nginx/nginx.conf
# 5. 查看系统资源
top
free -h
永久修复:
# Nginx upstream 优化
upstream php_backend {
server127.0.0.1:9000;
keepalive64; # 增加连接池
keepalive_timeout300s;
keepalive_requests1000;
}
server {
location~ \.php$ {
fastcgi_pass php_backend;
fastcgi_keep_connon; # 启用 FastCGI 连接保持
}
}
PHP-FPM 进程池调优:
# 计算公式:pm.max_children = 总内存 / 单进程内存
# 示例:8GB 服务器,PHP-FPM 单进程 50MB
# pm.max_children = 8192MB / 50MB ≈ 160(留 20% 余量 → 128)
pm = dynamic
pm.max_children = 128
pm.start_servers = 32
pm.min_spare_servers = 16
pm.max_spare_servers = 48
pm.max_requests = 1000# 防止内存泄漏
根因 4:SELinux 或防火墙阻断
典型日志特征:
connect() to unix:/var/run/php-fpm.sock failed (13: Permission denied)
完整诊断流程:
# 1. 检查 SELinux 状态
getenforce
# 2. 查看 SELinux 拒绝日志
ausearch -m avc -ts recent | grep nginx
# 3. 临时禁用 SELinux 测试
setenforce 0
curl -I http://yourdomain.com
# 如果恢复正常,确认是 SELinux 问题
# 4. 检查防火墙
systemctl status firewalld
iptables -L -n | grep 8080
# 5. 检查 socket 文件权限
ls -lZ /var/run/php-fpm/php-fpm.sock
永久修复(SELinux):
# 方案 1:配置 SELinux 布尔值
setsebool -P httpd_can_network_connect 1
setsebool -P httpd_can_network_connect_db 1
# 方案 2:调整文件上下文(socket 文件)
semanage fcontext -a -t httpd_sys_rw_content_t "/var/run/php-fpm(/.*)?"
restorecon -Rv /var/run/php-fpm
# 方案 3:生成自定义策略(高级)
ausearch -m avc -ts recent | audit2allow -M nginx_custom
semodule -i nginx_custom.pp
永久修复(防火墙):
# 开放必要端口(如果后端服务需外部访问)
firewall-cmd --permanent --add-port=8080/tcp
firewall-cmd --reload
根因 5:Nginx 配置错误
典型症状:
- • proxy_pass 语法错误导致请求转发失败
完整诊断流程:
# 1. 测试配置语法
nginx -t
# 2. 查看完整配置
nginx -T | less
# 3. 检查 upstream 定义
grep -A 10 "upstream" /etc/nginx/conf.d/*.conf
# 4. 验证 socket 路径
ls -l /var/run/php-fpm/php-fpm.sock
ls -l /run/php/php8.2-fpm.sock
# 5. 测试 proxy_pass 目标
curl -I http://127.0.0.1:8080/
常见配置错误汇总:
错误 1:socket 路径不匹配
# 错误配置(RHEL 系统使用了 Ubuntu 路径)
fastcgi_pass unix:/run/php/php-fpm.sock;
# 正确配置(RHEL)
fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
# 正确配置(Ubuntu)
fastcgi_pass unix:/run/php/php8.2-fpm.sock;
错误 2:proxy_pass 缺少协议前缀
# 错误配置
proxy_pass backend;
# 正确配置
proxy_pass http://backend;
错误 3:upstream 重复定义
# 错误:多个配置文件定义同名 upstream
# /etc/nginx/conf.d/site1.conf
upstream backend { ... }
# /etc/nginx/conf.d/site2.conf
upstream backend { ... } # 冲突
# 解决:使用唯一的 upstream 名称或在 http 块统一定义
永久修复:
# 1. 配置版本控制
cd /etc/nginx
git init
git add .
git commit -m "Production Nginx config"
# 2. 变更前自动备份
cat >> ~/.bashrc <<'EOF'
alias nginx-reload='nginx -t && cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak.$(date +%Y%m%d%H%M%S) && systemctl reload nginx'
EOF
# 3. 配置文件模板化(Ansible)
# 使用 Jinja2 模板根据系统自动选择路径
11. 变更与回滚剧本
灰度策略(配置变更流程)
# 1. 测试环境验证
# 在测试服务器应用新配置
scp /etc/nginx/nginx.conf test-server:/etc/nginx/
ssh test-server "nginx -t && systemctl reload nginx"
# 2. 生产环境备份
BACKUP_DIR="/backup/nginx/$(date +%Y%m%d_%H%M%S)"
mkdir -p ${BACKUP_DIR}
cp -r /etc/nginx ${BACKUP_DIR}/
# 3. 应用新配置
nginx -t
if [ $? -eq 0 ]; then
systemctl reload nginx
echo"配置重载成功"
else
echo"配置测试失败,未应用"
exit 1
fi
# 4. 验证健康检查(持续 2 分钟)
for i in {1..24}; do
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost)
if [ "$HTTP_CODE" != "200" ]; then
echo"健康检查失败,准备回滚"
cp -r ${BACKUP_DIR}/nginx /etc/nginx
systemctl reload nginx
exit 1
fi
sleep 5
done
echo"健康检查通过,变更成功"
回滚条件与命令
回滚触发条件:
快速回滚命令:
# 1. 恢复最近备份
LATEST_BACKUP=$(ls -t /backup/nginx/ | head -1)
cp -r /backup/nginx/${LATEST_BACKUP}/nginx /etc/nginx
# 2. 测试并重载
nginx -t && systemctl reload nginx
# 3. 验证
curl -I http://localhost
# 4. 记录回滚事件
echo"$(date) - 配置回滚到 ${LATEST_BACKUP}" >> /var/log/nginx/rollback.log
12. 最佳实践(决策性要点)
2. 超时参数梯度设置# 连接建立 < 数据发送 < 数据接收
proxy_connect_timeout60s;
proxy_send_timeout120s;
proxy_read_timeout300s;
- • 使用 Nginx Plus 或第三方模块实现主动健康检查
- • 配置 Prometheus 告警(502 错误率 > 1%)
4. 连接池优化
upstream backend {
server127.0.0.1:8080;
keepalive64;
keepalive_timeout300s;
keepalive_requests1000;
}
- • PHP-FPM:
pm.max_children = 总内存 * 0.8 / 单进程内存 - • Tomcat:
-Xmx 设置为物理内存 50-70%
13. FAQ(常见问题)
Q1: 502 和 504 错误有什么区别?A:
- • 502 Bad Gateway:Nginx 收到后端无效响应(连接失败/非 HTTP 协议)
- • 504 Gateway Timeout:Nginx 等待后端响应超时(连接成功但无响应)
Q2: 为什么有时候刷新页面 502 就消失了?A: 偶发 502 通常是后端服务短暂过载或连接池耗尽,刷新时请求被分配到空闲进程,恢复正常。需增加后端进程数或连接池。
Q3: 如何区分是 Nginx 问题还是后端问题?A:
- 1. 查看 Nginx error.log,有
upstream 关键字 → 后端问题 - 2. 直接 curl 后端服务(绕过 Nginx)→ 能访问说明 Nginx 配置问题
- 3. 检查 Nginx 进程与资源 → CPU/内存正常说明不是 Nginx 自身问题
Q4: PHP-FPM 使用 TCP 还是 Unix Socket?A:
- • Unix Socket:性能更好(延迟 < 0.1ms),推荐单机部署
- • 注意事项:Socket 需检查文件权限与 SELinux
Q5: 502 错误会被 CDN 缓存吗?A: 取决于 CDN 配置,默认不缓存 5xx 错误。但若 CDN 配置错误(如缓存所有响应),可能导致 502 被缓存,需清除 CDN 缓存。
Q6: 如何监控 502 错误率?A:
- • 方案 1:Nginx 日志分析 + Prometheus + Grafana
- • 方案 2:使用 Nginx Plus(商业版)内置监控
- • 方案 3:接入 APM 工具(如 New Relic/Datadog)
Q7: 后端服务正常但仍然 502?A: 检查以下项:
- 1. SELinux 阻断(
ausearch -m avc -ts recent) - 3. Nginx upstream 配置路径/端口错误
Q8: 可以通过增加 Nginx worker 进程数解决 502 吗?A: 不能。502 是后端问题,增加 Nginx worker 无效。应优化后端服务或增加后端实例数。
Q9: Docker 环境下如何排查 502?A:
# 检查容器状态
docker ps -a
# 查看容器日志
docker logs
# 进入容器调试
docker exec -it /bin/bash
# 检查容器网络
docker network inspect
Q10: 如何避免配置变更导致 502?A:
14. 附录:自动诊断脚本与完整配置
14.1 一键自动诊断脚本
脚本路径:/opt/scripts/nginx_502_auto_diagnosis.sh
#!/bin/bash
# Nginx 502 错误自动诊断脚本
# 用途:一键检查 5 大根因并输出诊断报告
set -e
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m'# No Color
echo"========================================"
echo" Nginx 502 错误自动诊断工具 v1.0"
echo"========================================"
echo""
# 根因 1:检查后端服务状态
echo -e "${YELLOW}[检查 1/5] 后端服务运行状态${NC}"
BACKEND_SERVICES=("php-fpm""php8.2-fpm""tomcat""nginx")
for service in"${BACKEND_SERVICES[@]}"; do
if systemctl is-active --quiet $service 2>/dev/null; then
echo -e "${GREEN}✓${NC}$service: 运行中"
else
echo -e "${RED}✗${NC}$service: 未运行或未安装"
fi
done
echo""
# 根因 2:检查端口监听
echo -e "${YELLOW}[检查 2/5] 后端服务端口监听${NC}"
PORTS=("9000""8080""3000""8000")
for port in"${PORTS[@]}"; do
if ss -tlnp | grep -q ":$port "; then
echo -e "${GREEN}✓${NC} 端口 $port: 已监听"
else
echo -e "${RED}✗${NC} 端口 $port: 未监听"
fi
done
echo""
# 根因 3:检查 Nginx 配置
echo -e "${YELLOW}[检查 3/5] Nginx 配置语法${NC}"
if nginx -t 2>&1 | grep -q "successful"; then
echo -e "${GREEN}✓${NC} Nginx 配置语法正确"
else
echo -e "${RED}✗${NC} Nginx 配置语法错误"
nginx -t
fi
echo""
# 根因 4:检查 SELinux 状态(仅 RHEL/CentOS)
echo -e "${YELLOW}[检查 4/5] SELinux 状态${NC}"
ifcommand -v getenforce &> /dev/null; then
SELINUX_STATUS=$(getenforce)
if [ "$SELINUX_STATUS" == "Enforcing" ]; then
echo -e "${YELLOW}⚠${NC} SELinux: $SELINUX_STATUS(可能阻止 Nginx 连接后端)"
echo" 检查拒绝日志: ausearch -m avc -ts recent | grep nginx"
else
echo -e "${GREEN}✓${NC} SELinux: $SELINUX_STATUS"
fi
else
echo -e "${GREEN}✓${NC} SELinux: 未安装(Ubuntu/Debian)"
fi
echo""
# 根因 5:检查最近 502 错误
echo -e "${YELLOW}[检查 5/5] 最近 502 错误统计${NC}"
ACCESS_LOG="/var/log/nginx/access.log"
ERROR_LOG="/var/log/nginx/error.log"
if [ -f "$ACCESS_LOG" ]; then
COUNT_502=$(grep " 502 "$ACCESS_LOG |
tail -100 | wc -l)
echo"最近 100 条日志中 502 错误: $COUNT_502 次"
if [ $COUNT_502 -gt 0 ]; then
echo"最近 502 错误 URL(Top 5):"
awk '$9 == 502 {print $7}'$ACCESS_LOG | tail -100 | sort | uniq -c | sort -rn | head -5
fi
else
echo -e "${RED}✗${NC} 访问日志不存在: $ACCESS_LOG"
fi
if [ -f "$ERROR_LOG" ]; then
echo""
echo"最近 upstream 错误(最后 10 条):"
grep -E "upstream|connect|timed out"$ERROR_LOG | tail -10
else
echo -e "${RED}✗${NC} 错误日志不存在: $ERROR_LOG"
fi
echo""
echo"========================================"
echo" 诊断完成"
echo"========================================"
echo""
echo"建议操作:"
echo"1. 检查未运行的后端服务: systemctl status "
echo"2. 查看详细错误日志: tail -f /var/log/nginx/error.log"
echo"3. 测试后端连通性: curl http://127.0.0.1:8080/"
echo"4. 如果是 SELinux 问题: setsebool -P httpd_can_network_connect 1"
echo""
使用方法:
chmod +x /opt/scripts/nginx_502_auto_diagnosis.sh
/opt/scripts/nginx_502_auto_diagnosis.sh
14.2 标准化 Nginx 配置模板
场景 A:PHP-FPM 后端(完整配置)
# /etc/nginx/conf.d/php-app.conf
upstream php_backend {
server unix:/var/run/php-fpm/php-fpm.sock; # RHEL/CentOS
# server unix:/run/php/php8.2-fpm.sock; # Ubuntu 22.04
# server 127.0.0.1:9000; # TCP 模式
keepalive16;
keepalive_timeout300s;
}
server {
listen80;
server_name example.com www.example.com;
root /var/www/html;
index index.php index.html;
access_log /var/log/nginx/php-app.access.log;
error_log /var/log/nginx/php-app.error.log warn;
location / {
try_files$uri$uri/ /index.php?$query_string;
}
location~ \.php$ {
try_files$uri =404;
fastcgi_pass php_backend;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
# 超时配置
fastcgi_connect_timeout60s;
fastcgi_send_timeout180s;
fastcgi_read_timeout300s;
# 连接保持
fastcgi_keep_connon;
# 缓冲配置
fastcgi_buffer_size64k;
fastcgi_buffers864k;
fastcgi_busy_buffers_size128k;
}
location~ /\.ht {
deny all;
}
}
场景 B:Tomcat/Spring Boot 后端(完整配置)
# /etc/nginx/conf.d/java-app.conf
upstream java_backend {
server127.0.0.1:8080 max_fails=3 fail_timeout=30s;
# 多实例负载均衡
# server 127.0.0.1:8081 max_fails=3 fail_timeout=30s;
# server 127.0.0.1:8082 max_fails=3 fail_timeout=30s backup;
keepalive32;
keepalive_timeout300s;
keepalive_requests1000;
}
server {
listen80;
server_name api.example.com;
access_log /var/log/nginx/java-app.access.log;
error_log /var/log/nginx/java-app.error.log warn;
location / {
proxy_pass http://java_backend;
# 超时配置(根据业务调整)
proxy_connect_timeout60s;
proxy_send_timeout120s;
proxy_read_timeout300s;
# 请求头转发
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;
# HTTP 版本与连接保持
proxy_http_version1.1;
proxy_set_header Connection "";
# 缓冲配置(针对大响应)
proxy_bufferingon;
proxy_buffer_size8k;
proxy_buffers328k;
proxy_busy_buffers_size64k;
# 错误处理
proxy_next_upstreamerror timeout invalid_header http_502 http_503;
proxy_next_upstream_tries2;
}
# 健康检查端点(不记录日志)
location /actuator/health {
proxy_pass http://java_backend;
access_logoff;
}
}
14.3 PHP-FPM 标准配置
# /etc/php-fpm.d/www.conf(RHEL)
# /etc/php/8.2/fpm/pool.d/www.conf(Ubuntu)
[www]
user = nginx ; RHEL
; user = www-data ; Ubuntu
group = nginx ; RHEL
; group = www-data ; Ubuntu
; 监听方式(二选一)
listen = /var/run/php-fpm/php-fpm.sock ; Unix Socket(推荐)
; listen = 127.0.0.1:9000 ; TCP
listen.owner = nginx
listen.group = nginx
listen.mode = 0660
; 进程管理
pm = dynamic
pm.max_children = 50; 最大子进程数(根据内存调整)
pm.start_servers = 10; 启动时进程数
pm.min_spare_servers = 5; 最小空闲进程
pm.max_spare_servers = 15; 最大空闲进程
pm.max_requests = 1000; 单进程最大请求数(防内存泄漏)
; 超时配置
request_terminate_timeout = 300s ; 与 Nginx fastcgi_read_timeout 对齐
; 慢日志
slowlog = /var/log/php-fpm/slow.log
request_slowlog_timeout = 5s
; 状态页(用于监控)
pm.status_path = /php-fpm-status
; PHP 配置
php_admin_value[error_log] = /var/log/php-fpm/error.log
php_admin_flag[log_errors] = on
php_admin_value[memory_limit] = 256M
php_admin_value[max_execution_time] = 300
15. 扩展阅读
官方文档:
- • Nginx 官方文档:http://nginx.org/en/docs/
- • Nginx HTTP Proxy 模块:http://nginx.org/en/docs/http/ngx_http_proxy_module.html
- • Nginx FastCGI 模块:http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html
- • PHP-FPM 官方文档:https://www.php.net/manual/en/install.fpm.php
深入技术博客:
- • Nginx 性能调优完全指南:https://www.nginx.com/blog/tuning-nginx/
- • 理解 Nginx upstream 健康检查:https://www.nginx.com/blog/nginx-plus-r15-released/
- • PHP-FPM 进程管理器深度解析:https://php-fpm.org/about/
社区资源:
- • Nginx 官方论坛:https://forum.nginx.org/
- • Stack Overflow Nginx 标签:https://stackoverflow.com/questions/tagged/nginx
- • ServerFault Nginx 问答:https://serverfault.com/questions/tagged/nginx
监控与可观测性:
- • Prometheus Nginx Exporter:https://github.com/nginxinc/nginx-prometheus-exporter
- • Grafana Nginx Dashboard:https://grafana.com/grafana/dashboards/12708
- • ELK Stack 日志分析:https://www.elastic.co/guide/en/logstash/current/plugins-inputs-nginx.html
案例研究:
- • 大规模 Nginx 502 错误排查案例:https://blog.cloudflare.com/502-bad-gateway/
- • PHP-FPM 性能优化实践:https://tideways.com/profiler/blog/php-fpm-performance-tuning
总结
本文系统化介绍了 Nginx 502 错误的 5 大根因(后端服务未启动、响应超时、连接池耗尽、SELinux 阻断、配置错误),提供了完整的诊断流程、修复方案与永久优化策略。
关键要点回顾:
- 1. 快速定位:通过 Nginx 日志识别错误模式(Connection refused / Timeout / No live upstreams)
- 2. 系统性排查:后端服务状态 → 网络连通性 → 配置正确性 → 系统限制
- 3. 永久修复:自动重启 + 超时优化 + 连接池调优 + 监控告警
- 4. 最佳实践:配置标准化、灰度变更、自动回滚、定期演练
推荐行动计划:
- 3. 长期建设:配置 Prometheus 监控、建立故障知识库、定期健康检查
通过本文的方法论与工具,您可以在 10 分钟内定位 95% 的 502 错误,并通过系统化优化彻底解决问题。