Nginx 作为 API 网关：中间件性能故障排查实战指南

场景

某电商平台将 Nginx 用作 API 网关，所有微服务请求都通过该层。最近业务量增长，网关偶尔出现高延迟和 5xx 错误，特别是上游服务响应慢时。我们接到工单，需要对 Nginx 网关中间件进行性能调优和故障排查。

症状

• 部分消费者报告 API 响应时间从平均水平 200ms 上升到 1s 或以上。
• Nginx 错误日志出现大量 "upstream timed out" 和 "connection refused"。
• 系统负载显示 Nginx worker CPU 占用高，但内存使用正常。
• 监控图表显示活动连接数接近 worker_connections 限制。

诊断

首先，检查 Nginx 配置和运行状态。

1. 确认 Nginx 进程和配置 bash nginx -t # 验证配置语法 nginx -V # 查看编译选项和模块 ps aux | grep nginx

2. 分析日志 bash tail -f /var/log/nginx/access.log | awk '{print $7, $9, $10, $11}' | sort | uniq -c | sort -nr | head -20 检查状态码分布，确定 5xx 是否集中。错误日志通常位于 /var/log/nginx/error.log。

3. 检查上游响应性能 bash curl -w 'time_total: %{time_total}s time_connect: %{time_connect}s time_ttfb: %{time_starttransfer}s\n' -o /dev/null http://upstream-service/health time_connect 和 time_ttfb 之差表示上游处理时间。如果上游慢，问题可能不在 Nginx。

4. 检查连接数和 worker 利用率 bash # 查看 Nginx 状态页（需配置 stub_status） curl http://localhost/nginx_status # 或者使用 netstat 统计连接 netstat -an | grep :80 | wc -l

5. 抓包或使用慢日志 如果怀疑中间件逻辑（如 rewrite、proxy_pass、限流）导致延迟，可临时开启 Nginx 的 debug 日志或使用 strace 跟踪 worker 进程。

命令

在诊断后，我们执行以下命令进行针对性处理：

• 调整 worker 进程数和连接限制：编辑 nginx.conf，增加 worker_processes 以匹配 CPU 核数，提高 worker_connections。 bash worker_processes auto; events { worker_connections 4096; }

• 配置上游超时和重试：在 location 中调整 proxy_connect_timeout、proxy_send_timeout、proxy_read_timeout。例如： nginx proxy_connect_timeout 5s; proxy_read_timeout 10s; proxy_send_timeout 10s;

• 启用缓存或压缩：如果 API 响应可缓存，添加 proxy_cache；对文本类响应启用 gzip，减少传输量。

• 检查当前配置： bash nginx -T # 导出完整配置 保存配置并测试： bash nginx -t && nginx -s reload

风险控制

• 重载前备份配置：cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak。
• 避免使用 nginx -s stop，优雅重载 reload 不会中断服务。
• 逐项调整，一次只改一个参数，使用 ab 或 wrk 压测验证效果，防止引入新问题。
• 如果并发过高，考虑调整内核参数 net.ipv4.ip_local_port_range 和 net.core.somaxconn，但需谨慎，可能影响宿主机。

回滚

如果调整导致问题恶化，执行回滚：

1. 恢复备份配置： bash cp /etc/nginx/nginx.conf.bak /etc/nginx/nginx.conf
2. 验证配置： bash nginx -t
3. 优雅重载： bash nginx -s reload

验证

• 功能验证：调用关键 API，确认响应码和响应时间恢复。
• 压力验证：使用 ab -n 10000 -c 500 http://your-gateway/api 观察吞吐量、延迟和错误率。
• 监控检查：确认 Nginx active connections 下降，5xx 率降低，日志中超时消失。

何时提交 OpsGlobal 工单

如果出现以下情况，请提交 OpsGlobal 工单：

• 应用层无法定位瓶颈，可能需要调整内核参数或升级服务器。
• Nginx 配置优化后仍无法满足 SLA，需要更高级的负载均衡或网关方案（如 Kong、Envoy）。
• 涉及多团队协作，需要全局流量策略或安全审计。
• 您需要 7x24 小时监控和应急响应，OPsGlobal 专业 SRE 团队可提供帮助。