Caddy服务器中HTTP/2 WebSocket连接问题分析与解决方案

问题背景

在Caddy服务器的最新版本中，当启用响应编码功能时，部分HTTP/2 WebSocket连接会出现握手失败的情况。这个问题特别出现在客户端需要发送第一条消息的WebSocket协议中，而服务器端由于编码功能的实现方式导致响应被延迟发送。

技术原理分析

HTTP/2协议下的WebSocket连接与传统的HTTP/1.1实现有所不同。在HTTP/1.1中，WebSocket升级过程会立即发送101状态码响应，而在HTTP/2中，服务器会先返回200状态码表示连接成功建立。

Caddy的编码中间件在处理响应时，会先检查响应内容是否可以被编码（如gzip、zstd等）。为了实现这一功能，编码中间件会延迟发送响应状态码，直到确定响应内容是否需要编码。这种延迟机制在普通HTTP请求中工作良好，但在WebSocket场景下会导致问题。

问题根源

当WebSocket协议要求客户端先发送第一条消息时，由于编码中间件延迟发送响应状态码，客户端会认为握手尚未完成，从而导致连接卡住。具体表现为：

1. 客户端发送包含accept-encoding头部的WebSocket升级请求
2. 编码中间件包装响应写入器，延迟状态码发送
3. 服务器等待客户端发送第一条消息
4. 客户端等待服务器完成握手响应
5. 双方陷入死锁状态

解决方案

目前推荐的临时解决方案是使用条件匹配来排除HTTP/2 WebSocket请求的编码处理：

@not_h2_ws not {
    header :protocol *
    method CONNECT
    protocol http/2
}
encode @not_h2_ws zstd gzip

从技术实现角度看，更完善的解决方案应该考虑以下几点：

1. 对于所有CONNECT方法请求（包括WebSocket），应默认跳过编码处理
2. 在编码中间件中识别WebSocket升级请求，无论使用HTTP/1.1还是HTTP/2协议
3. 正确处理HTTP/2特有的:protocol伪头部与HTTP/1.1头部的转换

协议规范要求

根据相关RFC规范：

• HTTP/1.1 WebSocket使用101状态码表示协议切换成功
• HTTP/2和HTTP/3中的CONNECT方法使用200状态码表示隧道建立成功
• WebSocket over HTTP/2不再使用Sec-WebSocket-Key和Sec-WebSocket-Accept头部，而是使用:protocol伪头部

实现建议

未来的Caddy版本应考虑以下改进：

1. 在编码中间件中明确识别并跳过所有WebSocket请求的编码处理
2. 确保HTTP/2 WebSocket请求能正确转换为HTTP/1.1格式的后端请求
3. 保持对非成功WebSocket升级请求的编码支持，以便返回自定义错误页面

这个问题展示了在实现现代Web协议时需要考虑的各种边缘情况，特别是在协议转换和中间件处理链中的交互问题。通过深入理解各层协议的工作原理，才能设计出既符合规范又稳定可靠的解决方案。