Apache虚拟主机支持WebSocket的核心是透传Upgrade握手并维持长连接，须启用mod_proxy、mod_proxy_http、mod_proxy_wstunnel三模块；ProxyPass必须用ws://前缀且置于HTTP规则之前；Timeout、KeepAliveTimeout等参数需延长，并确保Upgrade/Connection头不被清洗。
要让 apache 虚拟主机真正支持 websocket 协议，核心不是“让 apache 处理 websocket”，而是正确透传 upgrade 握手请求并维持长连接隧道。mod_proxy_wstunnel 就是为此设计的专用代理模块，它不解析 websocket 帧，只确保 upgrade: websocket 和 connection: upgrade 头完整抵达后端服务。
以下配置需逐项落实，缺一不可：
1. 确认模块已启用且依赖完整mod_proxy_wstunnel 不能单独工作，必须同时加载：
-
mod_proxy（基础代理框架） -
mod_proxy_http（wstunnel内部依赖其建立底层连接） -
mod_proxy_wstunnel（主模块）
检查命令：
httpd -M | grep -E "(proxy|wstunnel)"
应看到三者均显示 shared。若缺失，Debian/Ubuntu 执行：
sudo a2enmod proxy proxy_http proxy_wstunnel sudo systemctl restart apache2
2. 虚拟主机内配置必须满足语义与顺序要求
WebSocket 规则必须写在通用 HTTP 规则之前，且 ProxyPass 必须显式使用 ws:// 或 wss:// 协议前缀——这是触发 mod_proxy_wstunnel 的唯一开关。
正确示例（在 <VirtualHost> 块中）：
ProxyRequests Off ProxyPreserveHost On # ✅ WebSocket 专用路由（前置！协议必须是 ws://） ProxyPass "/ws/" "ws://127.0.0.1:8080/ws/" keepalive=On ProxyPassReverse "/ws/" "ws://127.0.0.1:8080/ws/" # ✅ 普通 HTTP 请求放后面 ProxyPass "/" "http://127.0.0.1:8080/" ProxyPassReverse "/" "http://127.0.0.1:8080/"
⚠️ 错误写法（会导致握手成功但后续帧异常）：
FastAPI + Flask 混合部署最佳实践，解决路由定义、API 代理等常见问题，适用于同时运行 FastAPI API 与 Flask 前端的场景。
-
ProxyPass "/ws/" "http://127.0.0.1:8080/ws/"（走mod_proxy_http，不处理升级） - 路径末尾
/不一致（如前端/ws对后端/ws/），可能破坏Sec-WebSocket-Location头
3. 关键超时与连接参数必须显式延长
WebSocket 是长连接，Apache 默认 Timeout 60 和 ProxyTimeout 60 会主动断开空闲连接，造成“静默掉线”。
在虚拟主机内添加：
Timeout 3600 ProxyTimeout 3600 KeepAlive On KeepAliveTimeout 300 MaxKeepAliveRequests 0
说明：
-
KeepAliveTimeout 300应大于后端心跳间隔（如后端每 30 秒发 ping，则此值至少设为 60+） -
MaxKeepAliveRequests 0表示不限制单连接请求数，避免频繁重连
4. 确保关键请求头未被清洗或覆盖
某些安全模块（如 ModSecurity）或 CDN 可能剥离 Upgrade 和 Connection 头。可在配置中强制补全：
RequestHeader set Connection "upgrade" RequestHeader set Upgrade "websocket"
同时确认没有 ProxyBadHeader Ignore（默认值可能导致部分头被丢弃），如有则改为：
ProxyBadHeader Start
后端服务必须能响应 ping 帧，否则 Apache 会在若干次无 pong 后关闭连接。Node.js 的 ws 库默认支持；Spring Boot 需注册 PongMessageHandler；Go 的 gorilla/websocket 需调用 conn.SetPingHandler() 并保证读循环持续运行。
不复杂但容易忽略的是头透传和超时设置。
