Nginx 作为 API 网关：性能优先的运维实战手册

场景

你正在 Kubernetes 集群中运行 Nginx 作为 API 网关，负责将外部流量路由到多个微服务。某天监控报警，API 响应时间从平均 80ms 飙升到 800ms，部分请求开始出现 502 和 504 错误。业务方反馈用户体验严重下降，但你不知道瓶颈在哪里。

症状

• API 请求延迟增大，特别是跨服务的调用。
• 上游（upstream）超时，Nginx 错误日志中出现 upstream timed out 或 no live upstreams。
• Nginx worker 进程 CPU 使用率接近 100%。
• 连接数达到 worker_connections 的限制，出现 accept failed 错误。
• 客户端收到 503 或 504 状态码。

诊断

1. 查看 Nginx 状态和日志

首先进入 Nginx Pod，检查错误日志和访问日志：

kubectl exec -it <nginx-pod> -n <namespace> -- /bin/bash

tail -f /var/log/nginx/error.log
tail -f /var/log/nginx/access.log

错误日志中的常见信号：

• worker_connections are not enough：连接数不足。
• upstream timed out (110: Connection timed out) while connecting to upstream：上游服务响应慢或不可达。
• recv() failed (104: Connection reset by peer)：上游服务主动断开连接，通常因为超时或崩溃。

2. 检查 Nginx 内置状态模块

如果启用了 ngx_http_stub_status_module，可以通过状态页查看活动连接数：

curl http://localhost:80/nginx_status

输出示例：

Active connections: 291
server accepts handled requests
 16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106

• Reading 和 Writing 过高说明请求繁忙，Waiting 是空闲连接。
• 如果 accepts 和 handled 相差较大，说明连接被丢弃。

3. 分析访问日志应答时间

启用 $request_time 和 $upstream_response_time 字段，在访问日志中查看下游和上游的耗时：

tail -n 100 /var/log/nginx/access.log | awk '{print $NF}' | sort | uniq -c | sort -rn | head -20

如果 $request_time 远大于 $upstream_response_time，则说明 Nginx 自身处理逻辑（如扩展、限流、SSL 握手）是瓶颈；如果两者相近，则瓶颈在上游服务。

4. 检查上游服务健康状态

如果使用 upstream 块配置了健康检查，检查上游服务是否在可用列表内：

kubectl get endpoints -n <namespace>
kubectl get pods -n <namespace> -o wide

也可以直接从 Pod 内 telnet 上游端口：

telnet <upstream-ip> <port>

命令和紧急处理

1. 调整 worker 进程和连接数

编辑 Nginx 配置，增加 worker_processes 和 worker_connections：

events {
    worker_connections 4096;
}

error_log /var/log/nginx/error.log warn;
worker_rlimit_nofile 65535;

然后重载配置：

nginx -t && nginx -s reload

2. 优化上游超时设置

在 location 或 server 块中调整代理超时：

location /api/ {
    proxy_read_timeout 15s;
    proxy_connect_timeout 5s;
    proxy_send_timeout 15s;
}

注意：超时太短会导致上游未完成处理就断开，太长则会占用 Nginx 连接导致资源泄漏。

3. 启用 Nginx 缓存

对不经常变化的响应启用缓存：

proxy_cache_path /tmp/nginx_cache levels=1:2 keys_zone=my_cache:10m max_size=1g inactivity=60m;

location /static/ {
    proxy_cache my_cache;
    proxy_cache_valid 200 60m;
    proxy_cache_valid 404 1m;
}

4. 限流保护

使用 limit_req 限制请求频率，防止突发流量拖垮后端：

limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

location /api/ {
    limit_req zone=api_limit burst=20 nodelay;
}

5. 检查内核参数

如果连接大量激增，可能需要调整系统级参数，例如在容器启动命令中增加 sysctl 设置：

sysctl -w net.core.somaxconn=65535
sysctl -w net.ipv4.ip_local_port_range="1024 65535"

风险控制

• 每次修改配置前，先复制原文件备份。
• 使用 nginx -t 检验配置语法。
• 对于生产环境，建议采用 canary 发布：先在一个实例上重载配置，观察无异常后再扩大到全部实例。
• 修改内核参数或全局配置时，需确认不会引起其他应用副作用。
• 避免在高峰期直接调整 worker_connections 到极大值，可能导致内存不足。

回滚

如果修改后故障加剧或出现新错误，立即回滚：

# 从备份恢复配置
cp /etc/nginx/nginx.conf.bak /etc/nginx/nginx.conf
nginx -t && nginx -s reload

如果配置是通过 ConfigMap 挂载的，使用 kubectl rollout 回滚：

kubectl rollout undo deployment/nginx-ingress -n <namespace>

验证

• 查看 error.log 是否还有新的超时或连接错误。
• 使用 load testing 工具（如 ab, wrk, k6）模拟业务流量，对比优化前后的 P95/P99 延迟。
• 监控 Nginx 的连接数、CPU、内存以及上游服务的响应时间。
• 观察 nginx_status 的 Waiting 连接是否回归正常。

何时提交 OpsGlobal 工单

如果遇到以下情况，建议立即联系 OpsGlobal 远程 SRE 团队：

• 优化调整后性能仍无改善，且无法定位根因。
• 需要 7x24 小时性能监控和主动告警。
• 集群规模较大，需要系统性调优 Nginx 及 Kubernetes 网络栈。
• 缺乏内部 SRE 专家，且问题影响生产可用性。

OpsGlobal 提供专业的 Nginx 和 API 网关运维支持，包括性能优化、故障诊断、安全加固和自动化运维，帮助您减少 MTTR，提升业务稳定性。