Nginx API 网关性能运维：实战现场指南

场景

您的团队在一个 Kubernetes 集群中运行着基于 Nginx 的 API 网关。最近，用户开始抱怨接口响应变慢，并出现间歇性的 504 错误。流量峰值并不异常，但网关的延迟指标明显恶化。您需要快速定位问题，恢复服务稳定性，并避免后续类似情况发生。

症状

• 延迟上升：请求的 p99 延迟从原来的 200ms 飙升至 2s 以上。
• 错误率增加：5xx 错误率上升，尤其是来自和上游服务连接超时的 504 错误。
• 资源消耗：Nginx 的 worker 进程 CPU 使用率接近 100%，内存占用也在增长。
• 用户反馈：移动端和外部客户的请求经常超时，影响业务。

诊断

诊断过程必须系统化。首先从最容易获取的数据开始：

1. 访问日志：检查 Nginx 的 access log，查看具体哪些请求变慢，是否有规律（如特定 URL、特定客户端）。
2. 错误日志：error log 往往会直接暴露异常，例如“upstream timed out”、“no live upstreams”等。
3. Nginx 状态指标：如果启用了 stub_status 或 vts 模块，可以通过 /status 获取连接数、请求频率等指标。
4. 上游响应时间：通过 $upstream_response_time 变量在日志中记录上游耗时，判断瓶颈是 Nginx 本身还是后端服务。
5. 配置审查：检查 worker_processes、worker_connections、keepalive、proxy_timeout 等关键参数是否与业务负载匹配。

常用命令

假设网关 Pod 标签为 app=gateway，以下命令帮助您逐步排查：

# 查看 Nginx 配置语法是否正确
kubectl exec -it <gateway-pod> -- nginx -t

# 查看最近 100 条 access log 和 error log
kubectl logs -l app=gateway --tail=100

# 获取 Nginx 编译参数和模块信息
kubectl exec <gateway-pod> -- nginx -V

# 测试网关响应时间和连接细节
curl -s -o /dev/null -w "total: %{time_total} connect: %{time_connect} starttransfer: %{time_starttransfer}" http://gateway.example.com/api/health

# 查看 Pod 资源使用情况
kubectl top pod <gateway-pod>

# 进入 Pod 检查配置和当前连接状态
kubectl exec -it <gateway-pod> -- /bin/bash
cat /etc/nginx/nginx.conf
cat /etc/nginx/conf.d/*.conf

如果问题更深入，可以临时使用 strace 跟踪系统调用，例如：

kubectl exec <gateway-pod> -- strace -p $(pgrep nginx worker) -c -f

但注意 strace 会产生额外开销，只在必要时进行。

风险控制

进行调整时，必须遵循安全操作原则：

1. 备份配置：在修改前，将当前 Nginx 配置完整备份到 ConfigMap 或 Git 仓库。
2. 优雅重载：使用 nginx -s reload 或向 master 进程发送 HUP 信号，而不是直接重启容器，避免连接中断。
3. 小步变更：每次只修改一个参数，并验证效果。例如先调整 proxy_read_timeout，再观察指标。
4. 金丝雀发布：如果使用 Deployment，可以先将新配置涂到一个副本上，调整流量比例验证。
5. 限流降级：如果上游服务已过载，可在网关层启用限流或熔断，保护后端。

回滚方案

如果修改导致情况恶化，立即执行回滚：

# 如果配置是通过 ConfigMap 挂载的，恢复旧版本 ConfigMap
kubectl rollout undo deployment/gateway

# 或者手动恢复 Nginx 配置文件并优雅重载
kubectl cp <backup-config> <gateway-pod>:/etc/nginx/nginx.conf
kubectl exec <gateway-pod> -- nginx -s reload

确保回滚后监控指标，确认问题不再持续。

验证

调整完成后，需要验证是否达到预期：

1. 监控指标：观察 p99 延迟、错误率、CPU 使用率是否恢复到正常范围。
2. 负载测试：在测试环境运行 ab 或 hey，模拟典型并发量。例如： bash hey -n 10000 -c 100 -H "Host: api.example.com" http://gateway.internal/api
3. 日志确认：访问日志中不再出现大量 upstream timeout，错误日志无异常。
4. 用户反馈：让业务方通过测试账号验证关键功能是否正常。

何时提交 OpsGlobal 工单

如果您遇到以下情况，说明问题可能超出应急范畴，建议提交 OpsGlobal 工单：

• 问题根因复杂：怀疑涉及内核参数、网络栈、DNS 解析、TLS 性能等，需要深入的系统级调优。
• 上游微服务众多：需要全面分析上游依赖的调用链，仅靠网关日志无法定位。
• Nginx 配置深度定制：涉及 Lua 脚本、第三方模块调优，或需要修改编译参数。
• 持续性能恶化：尽管做了常规调整，延迟和错误率仍在上升，可能有多重因素叠加。

OpsGlobal 的 SRE 专家可以提供从基础设施到应用层的全面排查，包括 kernel 调优、Node affinity 设计、服务网格集成等，但前提是您已尽力做了基础诊断。

记住，一次成功的运维干预，依赖于清晰的流程、谨慎的操作和及时的升级决策。