Apache通过mod_proxy_wstunnel模块透传WebSocket握手并维持长连接，需启用mod_proxy、mod_proxy_http、mod_proxy_wstunnel三模块；ProxyPass必须用ws://或wss://前缀；超时参数Timeout和ProxyTimeout须同步设为3600；Upgrade和Connection头需强制保留。
Apache 本身不处理 WebSocket，配置目标不是让它“支持”协议，而是准确透传 Upgrade 握手请求并维持长连接隧道。核心靠 mod_proxy_wstunnel 模块实现，不是靠 mod_proxy_http 或其他代理模块。
必须启用三个依赖模块
缺一不可，否则配置无效：
-
mod_proxy：基础代理框架，必须先加载 -
mod_proxy_http：mod_proxy_wstunnel内部依赖它建立底层 TCP 连接，不是可选项 -
mod_proxy_wstunnel：唯一能识别Upgrade: websocket并触发隧道逻辑的模块
检查命令：httpd -M | grep -E "(proxy|wstunnel)"，应看到三者均标记为 shared。Debian/Ubuntu 用户可直接运行：sudo a2enmod proxy proxy_http proxy_wstunnel && sudo systemctl restart apache2
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
ProxyPass 必须用 ws:// 或 wss:// 前缀
这是触发 mod_proxy_wstunnel 的唯一开关。写成 http:// 看似能通，实则走 HTTP 代理流程，握手后帧传输必然异常。
- 正确写法（路径末尾
/必须前后一致）：ProxyPass "/ws/" "ws://127.0.0.1:8080/ws/"ProxyPassReverse "/ws/" "ws://127.0.0.1:8080/ws/" - WebSocket 规则必须放在通用 HTTP 规则之前，否则会被提前拦截：
✅ 先写/ws/，再写/
❌ 不要颠倒顺序 - 若前端是 HTTPS 站点且使用
wss://，Apache 需配置 SSL 证书；后端可用ws://（SSL 终止在 Apache），此时ProxyPass仍写ws://
关键超时参数必须同步调大
WebSocket 是长连接，Apache 默认 Timeout 和 ProxyTimeout 均为 60 秒，空闲即断，导致“静默掉线”。
- 在对应
<VirtualHost>中显式设置：Timeout 3600ProxyTimeout 3600 - 两个值必须相等且同时设置——
ProxyTimeout控制 socket 级超时，Timeout影响整体请求生命周期，不一致会导致行为不可控 - 不建议全局修改，仅在 WebSocket 专用站点中覆盖，避免安全风险
确保 Upgrade 和 Connection 头完整透传
这两个是 hop-by-hop 请求头，Apache 默认可能清洗。需强制保留：
- 添加配置：
RequestHeader set Upgrade "websocket"RequestHeader set Connection "upgrade" - 禁用干扰行为：不加
retry=0、timeout=等 HTTP 专用参数（mod_proxy_wstunnel不支持，加了会校验失败） - 负载均衡场景下，需用
stickysession=ROUTEID绑定客户端到同一后端节点，避免状态丢失
