Caddy WebSocket 反向代理配置与常见错误

Caddy 普通请求成功，不代表 WebSocket 长连接已经配置正确。应按 Caddyfile、reverse_proxy、upstream、TLS 和超时的顺序检查，再结合 Caddy 日志定位握手或断连问题。

Caddy 在 WebSocket 代理链路中负责什么

先画出客户端、代理 IP、反向代理和目标服务的链路，确认每一跳使用的协议、主机、端口和认证。本文重点是 Caddy 的 WebSocket 反向代理；如果客户端前面还配置了代理 IP，应把客户端到 Caddy、Caddy 到 upstream 分开验证。

如何配置并验证 Caddy WebSocket 反向代理

先在 Caddyfile 中配置 reverse_proxy

从最小可复现的 Caddyfile 开始，只保留站点地址、reverse_proxy 和必要的 transport 设置。示例配置应以当前 Caddy 版本语法为准：

```caddyfile
example.com {
reverse_proxy 127.0.0.1:8080
}
```

先用 caddy validate --config /etc/caddy/Caddyfile 校验，再用普通 HTTP 和 WebSocket 请求分别验证。

确认 upstream、请求路径和 TLS/SNI

确认 upstream 地址、端口、目标路径和 TLS/SNI，避免请求被转发到错误服务或因证书名称不匹配而失败。

按普通 HTTP、握手和长连接的顺序验证

先验证普通 HTTP，再验证 WebSocket 握手、长连接和断线重连，分别记录状态码、响应头和关闭原因。并发和连接池行为可参考并发、QPS 与连接池。

从 Caddy 日志判断连接为什么关闭

结合 Caddy 日志和上游服务日志判断错误发生在哪一跳，并记录连接时长与客户端关闭码。

Caddy WebSocket 连接失败时怎么排查

如果尚不能确定问题发生在网络出口还是 Caddy 配置，可先用代理 IP 故障排查中心区分故障层级。

握手失败时检查路径和上游服务

握手失败先查请求路径、upstream 和目标服务是否支持升级连接。

TLS 报错或返回 407 时检查什么

TLS 错误检查证书、SNI 和目标域名；如果 407 来自客户端到前置代理的连接，优先核对代理认证信息与端口，而不是先改 Caddy 的 upstream。连接拒绝、TLS 或超时问题可继续参考timeout、connection refused、TLS 错误排查。

返回 502 或 504 时检查 upstream

502 先查 upstream 端口、连接拒绝和 TLS/SNI；504 重点查上游响应时间和长连接超时。

连接成功后立即断开时检查超时和路径重写

检查 transport 超时、上游主动关闭、路径重写和客户端关闭码，不要仅凭代理 IP 可连就判断 WebSocket 配置正确。

返回 WebSocket 通用排障流程

如需先确认通用握手、长连接和代理链路，可返回 WebSocket 代理父页；Caddy 具体配置再按本文的 upstream、TLS 和 transport 顺序复核。

版本、验证命令与官方来源

适用环境：Caddy 2.7+、Linux systemd。先执行 caddy validate --config /etc/caddy/Caddyfile，再 sudo systemctl reload caddy，最后用 wscat 复测并保存脱敏 access/error log。官方依据：reverse_proxy、TLS、日志。

FAQ

1. Caddy 是否需要手动配置 WebSocket Upgrade 头？

通常不需要单独手动添加，但 reverse_proxy、upstream 和路径必须配置正确。

2. Caddyfile 修改后如何确认配置有效？

先执行配置校验或 reload，再用普通 HTTP 和 WebSocket 请求分别验证。

3. Caddy 与 Nginx 的 WebSocket 排查重点一样吗？

底层排查逻辑相近，但配置入口、日志格式和 upstream/transport 写法不同。

4. Caddy 能解决上游服务主动断开吗？

不能。应结合 Caddy 和上游日志检查超时、路径和服务关闭策略。