第19章：Nginx Upstream 高级配置与故障转移

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

1. 项目背景

支付中心某台节点因内存碎片导致 Full GC，响应时间从 20ms 拉长到 2s。网关仍持续将流量打到慢节点，触发重试风暴，最终把原本健康的节点也压到超时。团队意识到：会转发不等于会治理。

在复盘会上，运维团队给出一个关键结论：以前“能跑就行”的配置策略，在中级阶段会迅速失效。因为系统面对的已经不是单点问题，而是“流量规模 + 协议复杂度 + 组织协作成本”的复合压力。 因此本章不只讲参数含义，还会给出一套可复用的方法：先建基线，再做单变量实验，最后用故障注入验证边界。这套方法会贯穿中级篇后续章节。

从知识路径上看，本章与上一章《连接池管理与 Keepalive 优化》形成前后呼应：上一章解决的是“局部能力成立”，本章要进一步回答“在真实流量和复杂协作下如何稳定成立”。

2. 项目设计

场景：压测复盘会，大家盯着大屏上的“重试风暴”时序图——一台节点 GC 导致 2s 延迟，结果连锁反应把三台全拖垮了。

小胖：（嗦着奶茶）不就是一台机器挂了嘛，Nginx 不是会自动切换到别的节点吗？就跟外卖小哥跑不动了换一个一样。

小白：问题是 Nginx 默认只对 error 和 timeout 做重试。后端返回了 200 但处理很慢，在 Nginx 看来并不算“失败”——它还是会继续往那个慢节点发请求。

大师：小胖，你们家楼下有两家早餐铺。一家包子蒸得慢但也不说不卖，你还是天天去排队——其实另一家快多了。问题是你不知道那家慢的“其实已经不行了”。

小胖：所以 Nginx 就是个憨憨排队引导员，只要铺子没关门就让顾客往里扎？

大师：没错。所以我们需要三种机制：一是被动检测——连续失败 N 次就暂时拉黑（max_fails + fail_timeout）；二是主动避险——对 502/503 甚至超时也触发重试（proxy_next_upstream）；三是降级兜底——配一个 backup 节点，平时不用，出事了才顶上。

小白：如果一台节点恢复了，要怎么让它重新接流量？直接恢复会不会又被打垮？

大师：好眼力。这就涉及到 slow_start。好比早餐铺子重新开张，你不能把门口排队的 200 人全放进去——炉子还没热呢。slow_start 会让新恢复的节点在指定时间内从零慢慢提升权重，温柔地承接流量。

小胖：就跟新窗口开张先放 5 个人，等师傅手顺了再放 50 个，对吧？

技术映射：max_fails 定义失败计数阈值，fail_timeout 定义计数周期和拉黑时长。proxy_next_upstream 控制哪些响应码或异常触发重试。slow_start（仅商业版/plus 版）让恢复节点平滑上线，避免雪崩。

小白：还有一个隐患——如果重试的请求不是幂等的，比如支付下单，重试两次不就重复扣款了吗？

大师：你问到了最致命的问题。proxy_next_upstream 默认只对 GET/HEAD 这类幂等方法做重试，对 POST 不会自动重试。我们可以在配置里加上 non_idempotent 来强制开启——但必须确保后端接口做了幂等处理（比如用订单号去重）。

小胖：这就跟美团外卖没送到，你再下一单，结果俩单都送到了——钱花了，饭还吃不完。

技术映射：proxy_next_upstream_tries 限制总重试次数（包含首次），默认 0 即不限。生产环境建议设为 2~3，避免无限重试拖垮所有节点。配合 backup 节点形成“主集群 + 降级集群”的故障隔离架构。

3. 项目实战

环境准备

• 系统：Ubuntu 22.04 / Rocky Linux 9（任选其一）
• Nginx：1.31.0（建议开启 debug）
• 工具：wrk、curl、ss、jq、grpcurl（第21章需要）

sudo nginx -V
sudo nginx -t

步骤一：建立最小可运行配置

步骤目标：让核心路径先稳定跑通，保证后续实验有可信起点。

upstream pay_api {
server 10.0.1.11:8080 max_fails=2 fail_timeout=5s;
server 10.0.1.12:8080 max_fails=2 fail_timeout=5s;
server 10.0.1.13:8080 backup;
}
server {
listen 8080;
location /pay {
proxy_next_upstream error timeout http_502 http_503;
proxy_next_upstream_tries 2;
proxy_connect_timeout 300ms;
proxy_read_timeout 1s;
proxy_pass http://pay_api;
}
}

运行结果（预期）：

• nginx -t 输出 syntax is ok / test is successful
• 健康检查接口返回 200
• error.log 无持续性报错

可能遇到的坑：配置能通过但链路没通，多数是上游地址、证书路径或防火墙规则未对齐。

步骤二：做基线压测与指标采集

步骤目标：获得“优化前”与“优化后”的可比数据。

for i in {1..20}; do curl -s -o /dev/null -w '%{http_code}\\n' http://127.0.0.1:8080/pay; done
wrk -t6 -c600 -d45s http://127.0.0.1:8080/pay

建议记录指标：

• 吞吐：QPS / RPS
• 延迟：P50、P95、P99
• 稳定性：5xx 比例、连接失败率、重试比例
• 资源：CPU、内存、活动连接数

可能遇到的坑：压测机成为瓶颈，导致测试结果误判。建议压测端与被测端分离，且至少跑 2-3 轮取中位值。

步骤三：故障注入与回滚演练

步骤目标：确认异常场景下系统仍可控，发布后具备止损能力。

# 触发配置变更
sudo nginx -t && sudo nginx -s reload
# 回滚（示例）
sudo cp /etc/nginx/nginx.conf.bak /etc/nginx/nginx.conf
sudo nginx -t && sudo nginx -s reload

故障注入建议：

本章实战目标：设计可控的被动健康检查与故障转移策略，并验证在节点异常时业务成功率可维持 99.9%+。

完整代码清单

• 建议仓库目录：ops/nginx/ch19/
• 包含文件：nginx.conf、upstream.conf、bench.sh、rollback.sh、README.md
• 推荐把实验记录沉淀为 result.md，保留每次变更的指标截图与结论

测试验证

# 基础连通性验证（示例）
curl -i http://127.0.0.1:8080/health

验证要点：

• 关键接口返回码符合预期（2xx/4xx/5xx与设计一致）；
• 关键日志字段完整（如 request_id、upstream 耗时、状态码）；
• 在小流量压测下无异常错误峰值。

4. 项目总结

优点与缺点

适用场景

不适用场景：

• 单机低流量 demo 项目。
• 暂无监控与压测能力、难以形成验证闭环的团队。

注意事项

常见踩坑经验

• 只看平均延迟，忽略 P99 与错误率。
• 基线记录不完整，导致结论不可复验。
• “一把梭”改太多参数，上线后无法定位问题来源。

思考题

在阅读顺序上，建议你先完成本章的最小实验与故障演练，再进入《高级负载均衡算法实战》。这样能把“配置会写”升级为“结论可验证、变更可回退”的工程能力。

下一章预告：高级负载均衡算法实战

延伸阅读与资源

10倍开发者的 Dify 魔法书：从零构建全栈 AI 应用 后端工程师转型AI第一课-Ollama 与私有化大模型实战 大型语言模型(LLM) vLLM 高性能推理落地实战 Agent开发之LlamaIndex 实战修炼与源码进阶 大语言模型Transformers 实战修炼与源码剖析