Go ReverseProxy 为什么转发后 Host 头发生变化

我第一次用 Go 的 httputil.ReverseProxy 接入内部服务时，最容易误判的现象就是：客户端访问的是 api.example.com，后端日志里却看到 Host: user-service.internal。这通常不是请求被“改坏了”，而是代理在构造出站请求时把 URL 和 Host 的职责分开处理了。

本文只解决一个问题：为什么 Go ReverseProxy 转发后 Host 头发生变化，以及怎样根据后端路由需求明确选择 Host。官方文档入口：https://pkg.go.dev/net/http/httputil#ReverseProxy。

如果使用 Rewrite 调用 ProxyRequest.SetURL，出站 Host 默认会跟随目标 URL 的主机；需要保留客户端入站 Host 时，应该设置 r.Out.Host = r.In.Host，而不是向 r.Out.Header 写一个名为 Host 的普通字段。

先把三个“主机”字段分开

排查这类问题时，我会先把请求画成三个彼此相关但不等价的节点：入站请求的 Request.Host、目标 URL 的 URL.Host，以及代理链路里的 X-Forwarded-Host。它们分别回答“客户端请求了谁”“代理要连谁”“原始请求声称请求了谁”。

在 Go 的 http.Request 中，Host 通常通过专门的 Request.Host 字段表达。它不等同于 Request.Header.Get("Host")，所以这样的写法并不能可靠地改变出站 Host：

// 不要把 Host 当成普通 Header 处理；后端路由看的通常是 Request.Host。
req.Header.Set("Host", "api.example.com")

真正需要改变代理出站请求 Host 时，应当操作出站请求的 Host 字段；如果要改变请求要连接的主机，则操作 URL 的 Host。两者可以相同，也可以有意不同。

SetURL 为什么会让 Host 跟着目标地址走

ReverseProxy 的 Rewrite 接收一个 ProxyRequest。其中 In 是代理收到的请求，Out 是即将交给 Transport 的出站请求。官方文档明确说明，SetURL 会把出站请求路由到目标的 scheme、host 和基础路径，并把出站 Host 改写成目标主机。

因此，下面的代码中，即使客户端的 Host 是 api.example.com，后端看到的 Host 也会变成 user-service.internal:8080。这是 SetURL 的预期行为，不是 Transport 随机丢失了 Header。

package main

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

func newProxy(target *url.URL) *httputil.ReverseProxy {
	return &httputil.ReverseProxy{
		Rewrite: func(pr *httputil.ProxyRequest) {
			// SetURL 同时确定出站请求的目标 URL 和默认 Host。
			pr.SetURL(target)
			// 让标准库补齐受控的 X-Forwarded-* 链路信息。
			pr.SetXForwarded()
		},
		Transport: http.DefaultTransport,
	}
}

这里的关键不是 Transport，而是 Rewrite 对 Out 的改写。图2把目标 URL、出站 Host 和后端路由这几个静态关系放在一起，便于对照代码。

需要保留客户端 Host 时，显式设置 Out.Host

有些后端按公网域名做租户路由、回调域名判断或虚拟主机匹配。这时“连接到哪个后端地址”和“后端按哪个 Host 路由”是两个不同决定。调用 SetURL 后，再把入站 Host 复制到出站请求即可：

func newTenantProxy(target *url.URL) *httputil.ReverseProxy {
	return &httputil.ReverseProxy{
		Rewrite: func(pr *httputil.ProxyRequest) {
			// 先把请求发送到内部服务地址。
			pr.SetURL(target)
			// 再保留客户端请求的 Host，交给后端做虚拟主机路由。
			pr.Out.Host = pr.In.Host
			// 将原始主机和客户端地址放入受控的转发头。
			pr.SetXForwarded()
		},
		Transport: http.DefaultTransport,
	}
}

这段代码表达的是“连接地址”和“业务 Host”分离：TCP/HTTP 连接仍然发往 target，而后端请求的 Host 由入站请求决定。生产环境中，如果入站 Host 会参与租户、权限或签名判断，还应先做允许列表匹配，不能无条件信任任意外部 Host。

X-Forwarded-Host 不是 Host 的替代品

当后端只需要知道原始访问域名，而不需要用它做 HTTP 虚拟主机匹配时，可以保持出站 Host 为目标主机，同时使用 X-Forwarded-Host 传递原始主机。SetXForwarded 会设置 X-Forwarded-For、X-Forwarded-Host 和 X-Forwarded-Proto。

这两种策略不能混写成“都一样”：保留 Out.Host 会影响后端的 Host 路由；设置 X-Forwarded-Host 只是提供代理链路元数据。后端框架是否读取转发头，还取决于它的信任代理配置。

Rewrite: func(pr *httputil.ProxyRequest) {
	// 目标 Host 用于连接和默认路由，适合后端按内部域名识别服务。
	pr.SetURL(target)
	// 原始域名进入 X-Forwarded-Host，应用层按信任代理策略读取。
	pr.SetXForwarded()
}

从 Director 迁移时不要只改函数名

较早的代码常用 Director。当前文档将它标记为 deprecated，推荐用 Rewrite。迁移时最容易漏掉的是语义差异：Rewrite 运行前，代理会移除 hop-by-hop 头，并清理部分转发头；ProxyRequest.In 不应被修改，真正要改的是 ProxyRequest.Out。

Rewrite: func(pr *httputil.ProxyRequest) {
	// In 只读，用它提供原始请求信息；不要直接改 In。
	pr.SetURL(target)
	// 如果业务需要原始 Host，显式复制到 Out。
	if allowedHost(pr.In.Host) {
		pr.Out.Host = pr.In.Host
	}
	// 只有在明确的代理信任边界内才补充转发头。
	pr.SetXForwarded()
}

示例中的 allowedHost 代表你自己的域名白名单或租户映射，不是标准库提供的函数。它的作用是把“保留 Host”从一个无条件复制动作变成一个受控策略。

上线前按后端需求做三项检查

我现在会把排查顺序固定成：先确认后端到底读取 Host 还是 X-Forwarded-Host，再检查是否调用了 SetURL，最后检查 Out.Host 是否被显式覆盖。这样通常能在代理代码和后端路由配置之间快速定位，而不会把问题误判成连接或 DNS 故障。

相关问题

为什么设置 Header 中的 Host 不生效？

因为 Go 请求的 Host 有专门字段，应该根据出站请求语义设置 Request.Host，不要把它当普通 Header 使用。

保留 Host 后还需要 X-Forwarded-Host 吗？

不一定。前者影响后端看到的 HTTP Host，后者表达代理链路中的原始主机；只有后端明确需要并信任该转发头时才设置或读取。

Director 还能继续使用吗？

已有代码可以按兼容计划维护，但新代码优先使用 Rewrite 和 ProxyRequest，并明确区分 In 与 Out。