反向代理基础

reverse_proxy 是 Caddy 转发请求到 upstream 的核心指令。对照 ngx-proxy 的 proxy_pass，Caddy 默认设置较完整的转发头，配置更短。

学习目标

• 正确使用 reverse_proxy 与 URI 前缀处理
• 传递 Host、客户端 IP 与 X-Forwarded-*
• 支持 WebSocket / Next.js HMR 的 Upgrade

核心内容

基本反代

www.coderoadmap.cn {
    handle /api/* {
        uri strip_prefix /api
        reverse_proxy 127.0.0.1:8080
    }
    handle {
        reverse_proxy 127.0.0.1:3000
    }
}

• uri strip_prefix /api：去掉 /api 再转发，等价 Nginx location /api/ + proxy_pass http://backend/
• 无 strip 时 URI 原样转发，类似 proxy_pass 末尾无 /

转发头（默认行为）

Caddy 自动设置：

Host              → 原 Host
X-Forwarded-For   → 客户端链
X-Forwarded-Proto → https
X-Real-IP         → 客户端 IP

Spring Boot 需信任 X-Forwarded-* 才能生成正确 URL 与 Sa-Token cookie（sb-security）。如需覆盖：

reverse_proxy 127.0.0.1:8080 {
    header_up Host {host}
    header_up X-Forwarded-Proto {scheme}
}

WebSocket / HMR

handle {
    reverse_proxy 127.0.0.1:3000 {
        header_up Connection {>Connection}
        header_up Upgrade {>Upgrade}
    }
}

Caddy 2 对 Upgrade 多数场景已自动处理；经 Caddy 反代 npm run dev 时若 HMR 失败，检查此项。

超时与 body 大小

reverse_proxy 127.0.0.1:8080 {
    transport http {
        read_timeout 60s
        write_timeout 60s
    }
}

request_body {
    max_size 20MB
}

与 Nginx client_max_body_size 20m 及 Spring multipart 限制对齐。

练习

• 用 curl 经 Caddy 访问 /api/tracks，对比直连 :8080 路径
• 解释 strip_prefix /api 与 Nginx proxy_pass 末尾 的对应关系