Apache的ProxyPass本身不处理502错误，需四步协同：启用ProxyErrorOverride、显式配置ErrorDocument 502、用ProxyPass /errors/ !排除路径、动态页手动设http_response_code(502)。
Apache 的 ProxyPass 本身不处理 502 错误，它只负责把请求转发给后端；当后端不可达、拒绝连接或响应异常时，mod_proxy 模块会生成 502 响应，但默认显示 Apache 自带的简陋错误页。要展示自定义页面，必须组合四点配置：开启接管开关、映射错误页路径、排除该路径被再次代理、确保状态码正确返回。
必须启用 ProxyErrorOverride 开关
这是前提条件，但只是“允许接管”，不是“自动接管”：
- 在虚拟主机或目录配置中添加：
ProxyErrorOverride On - 该指令默认是
Off，不写就完全无效 - 单独启用无作用——必须配合
ErrorDocument才生效
为 502 显式配置 ErrorDocument
不能依赖通用规则，必须逐个声明状态码对应的本地 URI：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
ErrorDocument 502 /errors/502.html- 路径必须以
/开头，且是 Apache 能直接服务的 Web 路径（如/var/www/html/errors/502.html） - 不能写成文件系统绝对路径（如
/var/www/errors/502.html）或外部 URL（如https://example.com/502.html）
用 ProxyPass ! 排除错误页路径
如果主代理规则是 ProxyPass / http://backend/，而错误页放在 /errors/，不加排除会导致 Apache 把对 /errors/502.html 的请求也转发给后端，造成 404 或循环失败：
- 在
ProxyPass / http://backend/规则之前或同一配置段中添加：ProxyPass /errors/ ! - 同样建议排除静态资源路径：
ProxyPass /static/ !、ProxyPass /css/ ! - 确保这些路径下的文件真实存在于 DocumentRoot 对应位置
动态错误页需手动维持 502 状态码
如果是 PHP 或其他脚本生成的错误页，默认响应头是 200 OK，浏览器无法识别为错误页，接管逻辑失效：
- PHP 文件开头加：
<?php http_response_code(502); ?> - 避免在错误页中使用
header("Location: ...")，否则状态码变成 302，彻底绕过错误处理 - 纯静态 HTML 页面无此问题，Apache 默认保留原始 502 状态码
