在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

caddyserver/caddy

菜单

传输选项

相关源文件

本文档涵盖了 Caddy 反向代理处理程序中的 HTTP 传输配置选项。传输选项控制反向代理如何与上游服务器通信，包括连接管理、超时、TLS 设置和协议版本。

有关负载均衡算法和上游选择的信息，请参阅负载均衡。有关上游健康监测配置，请参阅健康检查。

概述

反向代理传输负责建立和管理与上游服务器的连接。传输配置决定了 HTTP 请求如何发送到后端，包括连接池、超时行为、TLS 设置以及使用的 HTTP 协议版本。

传输架构

来源：modules/caddyhttp/reverseproxy/reverseproxy.go74-78 modules/caddyhttp/reverseproxy/httptransport.go50-164

HTTPTransport 配置

HTTPTransport 结构体为 HTTP 客户端传输行为提供了全面的配置。它封装了 Go 的标准 http.Transport，并增加了 Caddy 特定的功能。

核心传输字段

来源：modules/caddyhttp/reverseproxy/httptransport.go53-164

连接和超时配置

设置默认描述
DialTimeout3秒连接上游的最大等待时间
FallbackDelay300毫秒生成 RFC 6555 快速回退连接前的延迟
ResponseHeaderTimeout无超时等待响应头的时间
ExpectContinueTimeout无超时等待 "100 Continue" 响应的时间
MaxConnsPerHost0 (无限制)每个上游主机的最大连接数

来源：modules/caddyhttp/reverseproxy/httptransport.go97-114

缓冲区和读/写设置

传输支持可配置的缓冲区大小和每连接的读/写超时

设置默认描述
ReadBufferSize4KiB读取缓冲区大小（字节）
WriteBufferSize4KiB写入缓冲区大小（字节）
ReadTimeout无超时读取操作的最大时间
WriteTimeout无超时写入操作的最大时间
MaxResponseHeaderSize10MiB最大响应头大小

当配置时，读/写超时通过使用 tcpRWTimeoutConn 封装 TCP 连接来强制执行。

来源：modules/caddyhttp/reverseproxy/httptransport.go116-126 modules/caddyhttp/reverseproxy/httptransport.go753-785

TLS 配置

TLSConfig 结构体为与上游服务器的安全连接提供了全面的 TLS 客户端配置。

TLS 配置结构

来源：modules/caddyhttp/reverseproxy/httptransport.go554-615

TLS 功能

证书颁发机构配置

  • CARaw: 使用 CA 模块的现代证书池配置
  • RootCAPool / RootCAPEMFiles: 遗留 CA 证书配置 (已弃用)

客户端证书认证

  • ClientCertificateFile / ClientCertificateKeyFile: 静态客户端证书文件
  • ClientCertificateAutomate: 自动客户端证书管理

安全选项

  • InsecureSkipVerify: 禁用证书验证（仅用于测试）
  • ServerName: 覆盖用于证书验证的 SNI 主机名
  • Renegotiation: TLS 重协商策略 (never, once, freely)
  • ExceptPorts: 不应使用 TLS 的端口

来源：modules/caddyhttp/reverseproxy/httptransport.go617-733

Keep-Alive 和连接管理

KeepAlive 结构体控制 HTTP 连接重用和持久化行为。

Keep-Alive 配置

设置默认描述
已启用true是否启用 HTTP Keep-Alive
ProbeInterval30秒探测连接活跃性的频率
MaxIdleConns0 (无限制)最大空闲连接数
MaxIdleConnsPerHost32每个主机之间的最大空闲连接数
IdleConnTimeout2分钟保持空闲连接的时间

来源：modules/caddyhttp/reverseproxy/httptransport.go735-751 modules/caddyhttp/reverseproxy/httptransport.go192-199

协议版本支持

传输通过 Versions 字段支持多种 HTTP 协议版本。

支持的协议版本

默认配置

  • 默认版本：["1.1", "2"]
  • 当版本中包含 "2" 时，HTTP/2 会自动配置
  • 如果指定了 HTTP/3，它必须是唯一的版本
  • H2C 允许在明文 TCP 上启用 HTTP/2

协议选择逻辑

RoundTrip 方法根据请求 URL 方案和配置的版本选择合适的传输

  1. 如果独占配置，使用 HTTP/3 传输
  2. 当 H2C 启用时，对于 HTTP 方案使用 H2C 传输
  3. 否则使用支持 HTTP/2 的标准传输

来源：modules/caddyhttp/reverseproxy/httptransport.go177-179 modules/caddyhttp/reverseproxy/httptransport.go439-484 modules/caddyhttp/reverseproxy/httptransport.go486-505

高级传输功能

PROXY 协议支持

传输可以发送 PROXY 协议头以保留客户端连接信息

  • ProxyProtocol: 要使用的版本 ("v1" 或 "v2")
  • 启用时自动禁用 keep-alive (不兼容)
  • 保留原始客户端 IP 和端口信息

PROXY 协议头在使用请求上下文中的 ProxyProtocolInfo 建立连接后立即发送。

来源：modules/caddyhttp/reverseproxy/httptransport.go76-78 modules/caddyhttp/reverseproxy/httptransport.go279-333 modules/caddyhttp/reverseproxy/httptransport.go430-433

网络代理配置

NetworkProxyRaw 字段配置正向代理支持

  • 支持 HTTP、HTTPS 和 SOCKS 代理
  • 通过 caddy.network_proxy 命名空间使用可插拔代理模块
  • 默认为环境变量 (HTTP_PROXY, HTTPS_PROXY, NO_PROXY)

自定义 DNS 解析

UpstreamResolver 允许自定义 DNS 配置

  • Addresses: 自定义 DNS 服务器地址列表
  • 覆盖上游连接的系统 DNS 解析
  • 在配置的解析器中随机选择

来源：modules/caddyhttp/reverseproxy/httptransport.go58-59 modules/caddyhttp/reverseproxy/httptransport.go237-254

Caddyfile 配置

传输在 Caddyfile 中通过 reverse_proxy 块内的 transport 指令进行配置。

基本传输配置

reverse_proxy upstream1 upstream2 {
    transport http {
        dial_timeout 5s
        response_header_timeout 10s
        read_timeout 30s
        write_timeout 30s
    }
}

TLS 传输配置

reverse_proxy https://backend {
    transport http {
        tls
        tls_trusted_ca_certs /path/to/ca.pem
        tls_client_auth /path/to/cert.pem /path/to/key.pem
        tls_server_name backend.example.com
        tls_insecure_skip_verify
    }
}

高级特性

reverse_proxy backend {
    transport http {
        keepalive 5m
        keepalive_idle_conns 100
        max_conns_per_host 50
        proxy_protocol v2
        versions 1.1 2
        compression off
    }
}

Caddyfile 指令映射

Caddyfile 指令HTTPTransport 字段描述
dial_timeoutDialTimeout连接超时
response_header_timeoutResponseHeaderTimeout响应头超时
read_timeoutReadTimeout每连接读取超时
write_timeoutWriteTimeout每连接写入超时
tlsTLS启用 TLS 配置
keepaliveKeepAlive.IdleConnTimeoutKeep-alive 超时
versions版本HTTP 协议版本
proxy_protocolProxyProtocolPROXY 协议版本

来源：modules/caddyhttp/reverseproxy/caddyfile.go1012-1350