关键是要组合配置ProxyErrorOverride、ErrorDocument、ProxyPass !排除路径及状态码控制:必须为502/503等显式设置ErrorDocument指向本地URI,用ProxyPass /errors/ !排除该路径以防被代理,并确保错误页响应保持原始状态码。

要在 Apache 中用 mod_proxy 实现后端异常时返回自定义错误页(如 502/503),并支持兜底重定向,关键不是只开 ProxyErrorOverride,而是组合配置 ErrorDocument、路径排除和状态码控制。默认情况下,代理产生的错误不会被自动接管,必须显式声明。
必须显式为每个异常状态码配置 ErrorDocument
ProxyErrorOverride On 本身不提供页面,它只是“允许”你用 ErrorDocument 替换代理错误。没配就无效。
- 为常见代理错误添加本地错误页映射,例如:
ErrorDocument 502 /errors/50x.htmlErrorDocument 503 /errors/50x.htmlErrorDocument 504 /errors/50x.html - 路径必须以
/开头,是 Apache 可直接服务的 URI,不能是文件系统路径或外部 URL - 确保该路径下的 HTML/CSS/JS 都放在 DocumentRoot 下对应位置,比如
/var/www/html/errors/50x.html
用 ProxyPass ! 排除错误页路径,防止被再次代理
如果错误页路径(如 /errors/)也被 ProxyPass / http://backend/ 捕获,Apache 会把请求转发给后端,导致 404 或循环错误。
- 在
ProxyPass规则之后,立即添加排除规则:ProxyPass /errors/ ! - 这个
!表示“不代理”,让 Apache 直接从本地文件系统响应 - 同样要排除其他静态资源路径,比如
/static/、/css/等,避免资源加载失败
确保错误页响应保持原始状态码
浏览器是否显示自定义页,取决于响应头中的状态码是否匹配。若错误页是 PHP 动态生成的,需手动维持原状态码。
- 静态 HTML 页面默认继承原始状态码(502/503),无需额外操作
- 若用 PHP 输出错误页,开头加:
- 避免在页面中做 302 重定向,否则浏览器看到的是 302 而非 502,错误页逻辑失效
兜底重定向:所有后端不可用时跳转到维护页
当负载均衡器检测到全部后端离线(如 mod_proxy_balancer 中无健康成员),可配合 mod_rewrite 做最终跳转。
- 启用
mod_rewrite并在虚拟主机中添加:RewriteCond %{ENV:balancer_worker_route} ^$RewriteRule ^(.*)$ /maintenance.html [R=503,L] - 更稳妥的方式是用
ErrorDocument 503 /maintenance.html+ProxyErrorOverride On,再确保/maintenance.html路径被ProxyPass /maintenance.html !排除 - 维护页建议纯静态,不含 JS 渲染逻辑,保证极端情况下也能快速加载











