在 apache 中配置 websocket 代理出现 connection header error，通常是因为反向代理模块未正确识别或透传 upgrade 请求头。解决该问题的核心做法是确保 mod_proxy、mod_proxy_http 和 mod_proxy_wstunnel 三个模块均已加载，并在虚拟主机配置中使用 proxypass 和 proxypassreverse 指令显式指定 wss:// 协议进行转发。
如何检查并启用必要的 Apache 模块
要解决连接错误，第一步是确认服务器已加载处理 WebSocket 升级所需的模块。Apache 默认可能只加载基础的代理模块，而缺少专门处理 WebSocket 隧道功能的模块。你需要通过命令行工具检查当前加载的模块列表，或者查看配置文件中的 LoadModule 指令。如果缺少 mod_proxy_wstunnel，即使配置了正确的路径，代理也无法正确处理 HTTP 到 WebSocket 的协议切换。
# Debian/Ubuntu 系统启用模块的命令 sudo a2enmod proxy sudo a2enmod proxy_http sudo a2enmod proxy_wstunnel # 重启 Apache 使配置生效 sudo systemctl restart apache2
在 CentOS/RHEL 等系统中，模块通常以文件形式存在于 /etc/httpd/conf.modules.d/ 目录下。你可以检查是否存在对应的 .conf 文件并确保未被注释。启用模块后，必须重启 Apache 服务才能生效。这一步解决了因底层支持缺失导致的连接失败问题，为后续的路由配置奠定基础。
如何在 VirtualHost 中正确配置 ProxyPass 规则
配置的核心在于使用 ProxyPass 指令将特定 URL 路径映射到后端 WebSocket 服务地址。关键在于协议前缀必须使用 wss://（WebSocket Secure）或 ws://，而不是普通的 http://。Apache 会根据这个前缀自动选择正确的处理逻辑，包括处理 Connection: Upgrade 和 Upgrade: websocket 头部。同时，必须配置 ProxyPassReverse 以确保后端返回的重定向或错误信息中的地址能被正确修正。
通过Apache Tika Server REST API从1400多种文件格式中提取文本和元数据。处理PDF、DOCX、PPTX、电子邮件归档以及带有MIME类型检测的嵌入式文档提取。
<VirtualHost *:443>
ServerName example.com
SSLEngine on
SSLCertificateFile /path/to/cert.pem
SSLCertificateKeyFile /path/to/key.pem
# 关键配置：使用 wss:// 协议进行代理
ProxyPreserveHost On
ProxyPass /ws/ wss://localhost:8080/ws/
ProxyPassReverse /ws/ wss://localhost:8080/ws/
# 其他静态资源或 API 代理
ProxyPass /api/ http://localhost:3000/api/
ProxyPassReverse /api/ http://localhost:3000/api/
</VirtualHost>
上述配置中，ProxyPreserveHost On 确保了原始请求的 Host 头被传递给后端，这对于某些依赖域名鉴权的 WebSocket 服务很重要。路径 /ws/ 是客户端连接的入口，而后端实际监听的是 localhost:8080 上的相同路径。这种映射方式避免了 Apache 尝试解析 WebSocket 帧内容，而是将其作为二进制流直接隧道传输。如果后端服务不支持 WSS（即没有 SSL），则前端 Apache 仍需处理 SSL 终止，此时 ProxyPass 指向后端的 ws://，但 Apache 自身保持 https 连接。
当后端服务返回非 101 状态码时如何处理
如果配置正确但仍报错，常见原因是后端服务未能正确响应 WebSocket 握手，返回了 400 或 500 错误而非预期的 101 Switching Protocols。这通常发生在后端应用未正确实现 WebSocket 协议栈，或者 Apache 配置的 URL 路径与后端注册的路径不匹配。例如，客户端连接 /ws，而后端只注册了 /websocket，导致握手失败。此外，防火墙或负载均衡器拦截了 Upgrade 请求也会导致此问题。
// Node.js 示例：确保路径匹配
const WebSocket = require('ws');
const wss = new WebSocket.Server({ noServer: true });
server.on('upgrade', (request, socket, head) => {
// 注意：这里的路径必须与 Apache ProxyPass 中定义的后端路径一致
if (request.url === '/ws/') {
wss.handleUpgrade(request, socket, head, (ws) => {
wss.emit('connection', ws, request);
});
} else {
socket.destroy();
}
});
验证方法是通过浏览器开发者工具的 Network 面板查看 WebSocket 握手阶段的 HTTP 响应。如果状态码不是 101，检查后端日志确认是否收到了 Upgrade 请求。确保 Apache 配置中的 ProxyPass 目标路径与后端应用监听的精确路径完全一致，包括尾部斜杠。如果后端服务位于 Docker 容器内，还需确认端口映射和网络模式允许 Apache 进程访问后端服务地址。
