httputil.ReverseProxy 转发原始 Host 与请求头的配置方法

在 Go 的反向代理中，原始域名并不存放在一个普通的 Header 里。入站请求的 Host 位于 Request.Host，而 httputil.ProxyRequest.SetURL 会把出站请求路由到目标地址，并默认让出站 Host 跟随目标主机。要把客户端原始 Host 继续交给后端，应在 Rewrite 中显式执行 r.Out.Host = r.In.Host；普通业务头则通过 r.Out.Header 按白名单复制。

官方文档：https://pkg.go.dev/net/http/httputil

最小可靠配置是：用 Rewrite 调用 SetURL，需要保留原始域名时再赋值 Out.Host，不要试图用 Header.Set("Host", ...) 代替；自定义头只复制明确允许的字段，并用 SetXForwarded 生成代理链信息。

先分清三个“Host”位置

r.In.Host 是客户端发给代理的原始 Host；r.Out.URL.Host 是代理实际要连接的后端主机；r.Out.Host 是发给后端的 Host 值。Host 不在 Header map 中，所以 r.Out.Header.Set("Host", ...) 不会完成这项控制。

这也是 SetURL 后经常出现“后端虚拟主机匹配错”的原因：路由地址已经正确，但后端看到的 Host 默认变成了目标地址。只有后端确实依赖原始域名做租户、站点或路由判断时，才恢复 Out.Host；如果后端只认内部域名，则应保留目标 Host。

用 Rewrite 同时控制目标地址和原始 Host

下面的配置适合单个后端目标。SetURL 负责改写协议、主机和基础路径，然后用 Out.Host 恢复入站 Host。代码中的请求头只挑选业务上确实需要的字段，避免把客户端随意传入的连接级头或身份头直接带到后端。

package main

import (
    "net/http/httputil"
    "net/url"
)

func newProxy(target *url.URL) *httputil.ReverseProxy {
    return &httputil.ReverseProxy{
        Rewrite: func(r *httputil.ProxyRequest) {
            // SetURL 负责后端连接地址，并默认把 Out.Host 指向目标主机。
            r.SetURL(target)

            // 后端按租户域名路由时，显式保留客户端原始 Host。
            r.Out.Host = r.In.Host

            // 只复制明确需要的业务头；Host 不属于 Header map。
            if value := r.In.Header.Get("X-Tenant-ID"); value != "" {
                r.Out.Header.Set("X-Tenant-ID", value)
            }

            // 由库统一生成代理链信息，不手写客户端可伪造的转发值。
            r.SetXForwarded()
        },
    }
}

如果路径也需要完全自定义，可以在 SetURL 后直接调整 r.Out.URL.Path；如果只是把原始请求路径拼到目标基础路径，保留 SetURL 的默认合并规则即可。

请求头复制要有边界

Rewrite 调用前，代理会移除一批 hop-by-hop 头以及已有的 Forwarded、X-Forwarded-* 头，再让代码决定是否重新添加。对于业务头，建议维护一个小型白名单，而不是遍历 r.In.Header 全量复制。

Director 还能用吗，哪些坑要避开

Director 仍为兼容旧代码保留，但官方文档已标记为弃用，新的配置优先使用 Rewrite。Director 返回后还会继续清理 hop-by-hop 头，可能删掉刚写入的字段；同时客户端传入的部分 X-Forwarded 头可能被保留，若没有主动清理就会带来错误的代理链信息。

另外，NewSingleHostReverseProxy 默认不会改写 Host，并且内部使用兼容性的 Director。想同时控制 Host、转发头和安全边界时，直接构造 ReverseProxy 并设置 Rewrite 更清晰。一个实用判断是：后端需要外部租户域名就恢复 Out.Host，后端需要内部虚拟主机就不要恢复；两者不要混用成“始终转发原始 Host”。

常见问题

为什么 Header.Get("Host") 读不到原始域名？因为 Host 使用 http.Request.Host 字段表示，不是普通 Header map 项。读取入站域名用 r.In.Host，写出站域名用 r.Out.Host。

SetURL 后还要手动设置 URL.Host 吗？通常不需要。SetURL 已经完成目标协议、主机和基础路径的改写；只有路径拼接规则与默认行为不同，才直接调整 r.Out.URL。

归纳起来，Host 是请求对象的独立字段，业务头是 Header map，代理链头由 SetXForwarded 负责。把三类数据分开配置，ReverseProxy 的行为就能在路由、租户识别和请求头安全之间保持可解释。