Web 服务器与网关 / 系统课时

配置代理错误回退

配置代理错误回退

本课解决反向代理访问失败时的用户体验和故障隔离问题,通过 proxy_intercept_errors、命名位置和备用页面配置,让 Nginx 在合适场景接管错误响应,同时保留应用自身的业务错误处理能力。

学习目标

  • 理解 Nginx 接管上游错误响应的条件。
  • 掌握错误页面和备用位置的配置方法。
  • 能够判断网关错误处理与应用错误处理的边界。

理解代理错误处理边界

反向代理中的错误并不都应该由 Nginx 处理。认证失败、业务校验失败等应用错误通常需要保留应用响应,而网关无法连接上游、服务不可用等基础设施错误更适合由 Nginx 提供统一回退。

proxy_intercept_errors 可以让 Nginx 拦截指定 HTTP 状态码,并按照 error_page 规则返回备用内容。

配置错误拦截与备用页面

下面示例将上游服务返回的 502、503、504 交给 Nginx 处理,并跳转到命名位置生成统一响应。

nginx
server {
    listen <PORT>;

    location / {
        proxy_pass http://backend;
        proxy_intercept_errors on;

        error_page 502 503 504 = @gateway_fallback;
    }

    location @gateway_fallback {
        default_type text/plain;
        return 503 "service temporarily unavailable";
    }
}

预期输出

text
HTTP/1.1 503 Service Unavailable
service temporarily unavailable

命名位置不会直接暴露 URL 路径,只作为内部跳转目标使用,适合集中管理网关级错误响应。

选择回退策略

错误回退应根据故障类型设计。对于短暂网络异常,可以返回统一提示并配合客户端重试;对于业务异常,应让应用返回详细错误信息,避免网关覆盖关键上下文。

实际生产环境中,还可以结合静态错误页、监控标记和请求 ID,让用户看到稳定提示,同时方便运维定位。

验证错误处理链路

测试时需要模拟不同状态码,确认只有目标错误被拦截。可以通过临时修改 upstream、关闭后端实例或使用测试接口返回错误码进行验证。

排查问题时重点检查 error_page 状态码范围、proxy_intercept_errors 是否开启,以及备用 location 是否能够正常返回内容。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置代理错误回退

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通