明文 HTTP/2 服务怎样通过 Protocols 显式开启

Go 1.24 及以上版本可以直接通过 http.Server.Protocols 开启明文 HTTP/2：为字段分配一个 http.Protocols，调用 SetUnencryptedHTTP2(true)，然后用 ListenAndServe 监听明文端口。如果还要兼容普通 HTTP/1 客户端，再额外调用 SetHTTP1(true)；如果只允许 prior-knowledge h2c，就不要打开 HTTP/1。

Go 官方文档：https://pkg.go.dev/net/http#Protocols

HTTP/2 标准：https://www.rfc-editor.org/info/rfc9113/

先决定这条明文链路要保护什么

开启 h2c 之前，先列出服务承载的资产：请求正文里是否有账号、令牌或个人信息，响应里是否有内部业务数据，监听地址是否可能被非预期网络访问，代理是否会把内部端口暴露出去。HTTP/2 改变的是应用层的分帧和多路复用方式，并不会让明文 TCP 自动获得 TLS 的机密性、完整性和服务器身份认证。

RFC 9113 还提醒，明文 HTTP/2 对跨协议攻击的保护有限。连接前言能帮助 HTTP/1.1 服务拒绝误投的数据，但不能代替 TLS 的协议确认与加密。因此，我会把 h2c 的适用范围收窄到本机进程、受控内网，或一个可信 TLS 入口之后的内部链路；公网入口仍然优先使用 HTTPS 上的 HTTP/2。

Protocols 决定监听器接受什么

Server.Protocols 是一个协议集合。集合为空并不等于“全部启用”，所以显式配置时必须把真正需要的协议逐项加入。对明文监听器，最重要的是区分 HTTP1 与 UnencryptedHTTP2：前者表示 HTTP/1.0 和 HTTP/1.1，后者表示不安全 TCP 上的 HTTP/2。

业务 Handler 不需要为 h2c 重写一套。协议识别发生在服务器连接层，请求进入 ServeMux 后仍然使用熟悉的 http.Request 与 http.ResponseWriter。需要核对实际协议时，读取 r.Proto 即可。

同端口兼容 HTTP/1 与明文 HTTP/2

下面是一个完整的最小服务。它在 :8080 同时接受 HTTP/1 和 prior-knowledge h2c，并设置了读请求头超时、写超时、空闲超时与头部大小上限。代码不依赖 golang.org/x/net/http2/h2c；该包当前已被官方标记为弃用，新代码直接使用标准库即可。

package main

import (
    "fmt"
    "log"
    "net/http"
    "time"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        // 只返回必要的协议字段，避免把请求头或凭据写入响应
        w.Header().Set("Content-Type", "text/plain; charset=utf-8")
        fmt.Fprintf(w, "ok protocol=%s\n", r.Proto)
    })

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadHeaderTimeout: 5 * time.Second,
        WriteTimeout:      15 * time.Second,
        IdleTimeout:       60 * time.Second,
        MaxHeaderBytes:    1 

如果服务只应该接受 h2c，删除 SetHTTP1(true) 即可。这个选择要与客户端和入口网关一起确定：兼容模式适合迁移期或同端口混合访问，h2c-only 模式则能更早暴露发错协议的客户端，但不能自动让链路更安全。

把 h2c 放进可信边界

更稳妥的部署形态是：公网客户端先连接支持 TLS 与 ALPN 的入口，入口完成身份与加密边界控制；只有入口到 Go 服务之间的受控网络段使用 h2c。这个结构并非要求所有系统都在内部改用明文，而是明确标记“哪一段允许明文、谁能访问、谁负责 TLS”。

如果入口只是把 TLS 去掉，却没有网络访问控制，那么内部 h2c 端口仍可能被旁路访问。防护措施应落到具体对象：监听私有地址或回环地址、限制安全组和防火墙来源、禁止外部路由直达、让入口与后端都明确上游协议，并避免在普通访问日志中记录 Authorization、Cookie 或完整请求正文。

四类风险对应四组控制

这里没有一个“h2c 安全模式”开关。Protocols 只选择协议，超时、访问控制、鉴权和日志策略仍要分别配置。把这些职责分开，反而能避免把 HTTP/2 的多路复用能力误解成传输安全能力。

用匹配的客户端核对服务端协议

服务端开启后，核对客户端也必须使用 prior knowledge。Go 客户端要为 http:// 请求只启用 UnencryptedHTTP2；如果同时启用 HTTP1，Transport 会选择 HTTP/1。下面的探针只读取状态码与 resp.Proto，用于确认服务端配置关系。

package main

import (
    "fmt"
    "log"
    "net/http"
    "time"
)

func main() {
    tr := &http.Transport{
        // 直连核对时不读取环境代理，避免中间层改变协议
        Proxy:     nil,
        Protocols: new(http.Protocols),
    }
    // 客户端只启用明文 HTTP/2，确保目标协议唯一
    tr.Protocols.SetUnencryptedHTTP2(true)

    client := &http.Client{
        Transport: tr,
        Timeout:   5 * time.Second,
    }
    resp, err := client.Get("http://127.0.0.1:8080/healthz")
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()

    // HTTP/2.0 说明请求以明文 HTTP/2 到达兼容服务端
    fmt.Printf("status=%s protocol=%s\n", resp.Status, resp.Proto)
}

如果代码在编译阶段提示 Protocols 或 SetUnencryptedHTTP2 不存在，先确认构建工具链是否至少为 Go 1.24。如果建立连接后失败，再核对服务端是否真的部署了新二进制、入口是否转成 HTTP/1、客户端是否访问了正确端口。标准库不支持已弃用的 Upgrade: h2c 路径，因此不要用一个只会 HTTP/1 升级的客户端验证这里的配置。

协议审计应记录什么

最小审计信息通常包括时间、服务实例、远端网络标识、请求方法、规范化路径、状态码、耗时和 r.Proto。记录协议字段能发现本应 h2c-only 的链路突然出现 HTTP/1，也能判断网关升级后是否改变了上游协议。不要为了排查方便记录 Authorization、Cookie、完整查询参数或请求正文。

如果服务同时兼容两种协议，可以按 r.ProtoMajor 做计数指标；当 HTTP/1 客户端数量降到预期范围后，再评估是否移除 SetHTTP1(true)。这种做法把兼容策略变成可观察的迁移过程，而不是永久保留一个无人确认的旧入口。

上线前检查清单

• 构建与运行环境均为 Go 1.24 或更高版本。
• Server.Protocols 显式包含 UnencryptedHTTP2。
• 是否保留 HTTP1 已由兼容需求决定，而不是无意中默认打开。
• 服务使用 ListenAndServe 监听明文端口；TLS 服务则走 ListenAndServeTLS 与 HTTP2 配置。
• 客户端和中间代理都支持 prior knowledge，而不是只支持 Upgrade: h2c。
• h2c 端口不能从不可信网络直达，并已配置防火墙、安全组或服务网格策略。
• 已设置请求头超时、写超时、空闲超时和头部大小限制。
• 审计与指标能区分 HTTP/1 和 HTTP/2，但不保存敏感头部与正文。

常见问题

SetHTTP2(true) 能开启明文 HTTP/2 服务吗？

不能。HTTP2 表示 TLS 上的 HTTP/2；明文 TCP 上的 HTTP/2 要使用 SetUnencryptedHTTP2(true)。

一个端口可以同时接受 HTTP/1 和 h2c 吗？

可以。把 HTTP1 和 UnencryptedHTTP2 都加入 Server.Protocols 即可。是否这样做取决于兼容目标。

为什么不再推荐 golang.org/x/net/http2/h2c？

当前官方包文档已经将它标记为弃用，因为明文 HTTP/2 已可直接通过标准库 net/http 的 Protocols 配置。

h2c 是否会自动回退到 HTTP/1？

prior-knowledge h2c 客户端会直接发送 HTTP/2 连接前言，不应把自动回退当作保障。需要兼容 HTTP/1 时，应在客户端和服务端明确设计各自的协议集合。

通过 Server.Protocols 开启明文 HTTP/2 的代码并不复杂，真正需要认真决定的是边界：服务是否只接受 h2c、是否还保留 HTTP/1、谁负责 TLS、谁能访问内部端口，以及怎样确认请求实际使用了哪种协议。把这些问题逐项写进配置和审计，h2c 才是一项可控的工程选择，而不是一个隐含的明文入口。