HTTP/3基于QUIC传输协议，天生具备多路复用与低延迟特性。CONNECT-UDP是HTTP/3标准中的一项扩展方法，它允许客户端向代理服务器发送带有:method为CONNECT-UDP的伪头部请求，从而在已建立的QUIC连接内打开一条专门转发UDP报文的流。对于Ruby开发者而言，借助社区中的异步网络库，可以用较少代码实现这套隧道机制，将DNS查询、游戏协议或IoT设备报文通过HTTP/3代理安全送出内网。
CONNECT-UDP协议基础与Capsule格式解析
在HTTP/3中，CONNECT-UDP请求并不携带传统实体主体，而是依靠:authority与:path伪头部指明目标UDP端点。代理收到请求后，若策略允许，则返回状态码200，随后双方进入Capsule交换阶段。Capsule是一种长度前缀的二进制帧，用于封装UDP载荷或控制信息，例如UDP_DATAGRAM类型负责承载真实数据报。
每个Capsule由变长整数表示的类型字段与长度字段开头，紧接着是对应内容。Ruby中可以用StringIO配合位运算解析这些变长整数。理解该格式是实现转发器的前提，因为错误解析会导致流提前终止。相比HTTP/2的CONNECT方法仅支持TCP，CONNECT-UDP在单一QUIC流上支持无序交付，更适合实时性要求高的场景。
下面给出一个简化的Capsule编码示例，展示如何构造一个UDP_DATAGRAM胶囊。注意代码内所有尖括号均已转义以符合HTML展示要求，实际网络发送时应为原始字节。
require 'stringio'
def write_varint(io, value)
# 变长整数编码，每字节最高位为延续标志
bytes = []
loop do
bytes.unshift(value & 0x7f)
value >>= 7
break if value == 0
end
bytes.each_with_index do |b, i|
io.write([b | (i < bytes.length - 1 ? 0x80 : 0)].pack('C'))
end
end
def build_udp_datagram(payload)
io = StringIO.new
write_varint(io, 0x00) # Capsule类型 UDP_DATAGRAM
write_varint(io, payload.bytesize)
io.write(payload)
io.string
end
capsule = build_udp_datagram("hello udp")
puts capsule.bytesize
基于Ruby异步框架建立QUIC与代理隧道
Ruby原生标准库并未内置QUIC支持，因此通常引入async-quic或绑定libquiche的宝石。建立连接时，客户端先完成QUIC握手，再于新开流上发送CONNECT-UDP请求头。由于QUIC流是双向的，代理可将后端UDP socket收到的报文通过同一流回传，无需额外端口。
在隧道维持阶段，程序需要并发读取QUIC流与本地或远端UDP socket。可以利用Async::Reactor创建两个任务：一个负责将Capsule解包后写入UDP socket，另一个将socket读取的数据包封装为Capsule写入流。这种结构清晰分离了协议转换与IO调度，也方便插入日志与限流逻辑。
以下片段演示了请求头的构造与发送逻辑，其中伪头部使用数组形式传递，符合HTTP/3帧层要求。真实环境还需处理SETTINGS帧中是否启用扩展的协商结果。
headers = [ [':method', 'CONNECT-UDP'], [':scheme', 'https'], [':authority', 'proxy.ippipp.com'], [':path', '/target-host/443/'] ] def send_connect(stream, headers) # 假设stream支持write_head方法序列化HPACK stream.write_head(headers) stream.flush end # 伪代码：在已建立QUIC连接conn上打开流 stream = conn.open_stream send_connect(stream, headers) response = stream.read_head if response[':status'] == '200' puts '隧道已建立' end
UDP报文转发逻辑与常见安全陷阱
转发核心是把Capsule内的UDP负载投向目标地址，并把回包重新胶囊化。Ruby的UDPSocket可绑定临时端口，调用send时指定目标。需要维护一张映射表，关联QUIC流ID与远端地址，因为同一代理可能服务多个客户端。若目标地址未做白名单校验，攻击者可借代理发起反射放大攻击。
另一个易错点在于MTU与分片。QUIC流虽能传输任意长度，但Capsule长度字段限制单帧不超过变长整数上限。大报文应切分或依靠IP层路径MTU发现。同时，代理应限制每流缓冲区的字节数，防止慢速客户端耗尽内存。以下是转发任务的骨架示例。
require 'socket'
udp = UDPSocket.new
clients = {} # stream_id => [addr, port]
def forward_to_udp(udp, capsule_payload, target)
udp.send(capsule_payload, 0, target[0], target[1])
end
def loop_read_udp(udp, stream)
while true
msg, addr = udp.recvfrom(65535)
capsule = build_udp_datagram(msg)
stream.write(capsule)
end
end
除技术实现外，运维上应当配置明确的访问控制。例如仅允许特定:authority后缀的CONNECT-UDP，并在应用层记录每流流量。这样即便Ruby脚本简单，也能在 production 环境稳定运行，为企业提供轻量级UDP出口方案。
RubyHTTP/3CONNECT-UDP修改时间：2026-08-18 07:48:28