Apache 模块 mod_http2

H2CopyFiles 指令

此指令影响响应中文件内容的处理方式。当设置为 off（默认值）时，文件句柄将从请求处理传递到主连接，使用 Apache 通常的预留处理来管理文件的生命周期。

当设置为 on 时，文件内容将在请求仍在处理时被复制，缓冲的数据将传递到主连接。如果第三方模块将具有不同生命周期的文件注入响应，这将更好。

mod_wsgi 是一个这样的模块示例，它可能会将 Python 文件句柄放入响应中。当 Python 认为处理已完成时，这些文件将关闭。这可能早于 mod_http2 完成对它们的处理。

H2Direct 指令

此指令切换 HTTP/2 直接模式的使用。这应该在 <VirtualHost> 部分内使用，以启用该虚拟主机的直接 HTTP/2 通信。

直接通信意味着，如果服务器在连接上接收到的第一个字节与 HTTP/2 前导匹配，则 HTTP/2 协议将立即切换到该协议，而无需进一步协商。此模式在 RFC 7540 中针对明文 (h2c) 案例进行了定义。它在 TLS 连接上的使用并非标准所强制要求。

当服务器/虚拟主机没有通过 Protocols 启用 h2 或 h2c 时，连接永远不会检查 HTTP/2 前导。此时，H2Direct 无关紧要。这对于使用协议的连接很重要，在这些协议中，初始读取可能会无限期地挂起，例如 NNTP。

对于拥有关于服务器支持 h2c 的带外知识的客户端，直接 HTTP/2 使客户端无需执行 HTTP/1.1 升级，从而提高性能并避免升级对请求正文的限制。

这使得直接 h2c 对服务器到服务器通信也很有吸引力，因为连接可以被信任或通过其他方式进行保护。

H2Direct on

H2EarlyHint 指令

H2EarlyHint 允许在实际请求处理开始之前添加响应头。这些头将在“103 Early Hints”中间响应中获取。主要目的是向客户端浏览器发送“预加载”信息。

name 和 value 必须是有效的 HTTP 头字段，否则会导致响应失败。为了允许发送 103 中间响应，H2EarlyHints 必须仍然启用。此指令可以重复多次，并且相同名称的头字段将被添加。

H2EarlyHint Link "</my.css>;rel=preload;as=style"

H2EarlyHints 指令

此设置控制是否将 HTTP 状态 103 中间响应转发到客户端。默认情况下，目前并非如此，因为许多客户端仍然难以处理意外的中间响应。

当设置为 on 时，使用 H2PushResource 公告的 PUSH 资源将在最终响应之前触发一个中间 103 响应。103 响应将携带 Link 标头，这些标头建议预加载此类资源。

H2MaxDataFrameLen 指令

H2MaxDataFrameLen 限制放置在单个 HTTP/2 DATA 帧中的响应主体字节的最大数量。将其设置为 0 不会设置限制（但会遵守协议允许的最大大小）。

默认情况下，模块尝试使用可能的最大大小，大约为 16KB。这设置了最大值。当可用响应数据较少时，将发送较小的帧。

H2MaxSessionStreams 指令

此指令设置服务器允许的每个 HTTP/2 会话（例如连接）的最大活动流数。如果流不是 idle 或 closed（根据 RFC 7540），则该流处于活动状态。

H2MaxSessionStreams 20

H2MaxWorkerIdleSeconds 指令

此指令设置 h2 工作线程在关闭之前可能空闲的最大秒数。这仅在 h2 工作线程数量超过 H2MinWorkers 时发生。

H2MaxWorkerIdleSeconds 20

H2MaxWorkers 指令

此指令设置每个子进程为 HTTP/2 处理而生成的 worker 线程的最大数量。如果未使用此指令，mod_http2 将选择适合已加载的 mpm 模块的值。

H2MaxWorkers 20

H2MinWorkers 指令

此指令设置每个子进程为 HTTP/2 处理而生成的 worker 线程的最小数量。如果未使用此指令，mod_http2 将选择适合已加载的 mpm 模块的值。

H2MinWorkers 10

H2ModernTLSOnly 指令

此指令切换 TLS 模式（https:）下 HTTP/2 连接的安全检查。这可以在服务器范围内使用，也可以在特定 <VirtualHost> 中使用。

安全检查要求 TSL 协议至少为 TLSv1.2，并且不使用 RFC 7540 附录 A 中列出的任何密码。一旦新的安全要求出现，这些检查将扩展。

该名称源自 Mozilla 的 Security/Server Side TLS 定义，其中定义了“现代兼容性”。Mozilla Firefox 和其他浏览器要求 HTTP/2 连接具有现代兼容性。与 OpSec 中的所有内容一样，这是一个不断变化的目标，预计将来会不断发展。

在 mod_http2 中进行这些检查的目的是，对所有连接（不仅是来自浏览器的连接）强制执行此安全级别。另一个目的是，如果未满足要求，则防止协商 HTTP/2 作为协议。

最终，TLS 连接的安全性由 mod_ssl 的服务器配置指令决定。

H2ModernTLSOnly off

H2OutputBuffering 指令

指令 H2OutputBuffering 控制流输出的缓冲。默认值为 on，这是先前版本的行为。当关闭时，所有字节都将立即提供给主连接，以便将其发送到客户端。这修复了某些 gRPC 版本的互操作性问题。

H2Padding 指令

使用默认值 0，不会将任何填充字节添加到任何有效负载帧，例如 HEADERS、DATA 和 PUSH_PROMISE。这是先前版本的行为。这意味着在某些情况下，网络流量的观察者可以在 TLS 流中看到这些帧的长度。

当配置 1-8 的 numbits 时，将在每个帧中添加 [0, 2^numbits[ 范围内的随机数。模块发送回客户端的每个帧都会独立选择随机值。

虽然更多的填充字节可以更好地混淆消息长度，但它们也是额外的流量。因此，最佳数量取决于服务器承载的网络流量类型。

默认值 0（即无填充）是为了最大限度地向后兼容而选择的。可能存在填充字节不受欢迎或有害的部署。最可能的原因是客户端的实现存在故障。

H2ProxyRequests 指令

使用 H2ProxyRequests 在转发代理配置中启用或禁用处理 HTTP/2 请求。

与 ProxyRequests 类似，当在转发代理配置中启用 HTTP/2 时，这将触发对请求所需的处理。这两个指令都应启用。

H2Push 指令

此指令切换 HTTP/2 服务器推送协议功能的使用。

HTTP/2 协议允许服务器在客户端请求特定资源时将其他资源推送到客户端。如果这些资源以某种方式连接，并且可以预期客户端会请求这些资源，这将很有帮助。推送可以节省客户端自行请求资源所需的时间。另一方面，推送客户端不需要或已经拥有的资源会浪费带宽。

通过检查响应的 Link 标头来检测服务器推送（有关规范，请参阅 https://tools.ietf.org/html/rfc5988）。当这样指定的链接具有 rel=preload 属性时，它将被视为要推送的资源。

响应中的链接标头要么由应用程序设置，要么可以通过 H2PushResource 或使用 mod_headers 进行配置，如下所示：

<Location /index.html>
    Header add Link "</css/site.css>;rel=preload"
    Header add Link "</images/logo.jpg>;rel=preload"
</Location>

如示例所示，可以将多个链接标头添加到响应中，从而触发多个推送。模块中没有检查以避免将相同资源两次或多次推送到一个客户端。谨慎使用。

默认情况下启用 HTTP/2 服务器推送。在服务器或虚拟主机上，您可以为与主机的任何连接启用/禁用此功能。此外，您可以在目录/位置中为一组资源禁用 PUSH。这控制哪些资源可能导致 PUSH，而不是哪些资源可能通过 PUSH 发送。

H2Push off

最后但并非最不重要的一点是，推送仅在客户端表示愿意接受这些推送时才会发生。大多数浏览器都这样做，但有些浏览器（如 Safari 9）则不这样做。此外，推送也仅针对与原始响应相同的授权的资源发生。

H2PushDiarySize 指令

此指令切换每个 HTTP/2 连接记住的 HTTP/2 服务器推送的最大数量。这可以在 <VirtualHost> 部分内使用，以影响对该虚拟主机的所有连接的数量。

推送日记记录推送资源（其 URL）的摘要，以避免在同一连接上进行重复推送。这些值不会持久化，因此打开新连接的客户端将再次体验已知的推送。

如果达到最大大小，较新的条目将替换最旧的条目。一个日记条目使用 8 个字节，让默认的日记包含 256 个条目，消耗大约 2 KB 的内存。

大小为 0 将有效地禁用推送日记。

H2PushPriority 指令

此指令根据响应的 content-type 定义推送响应的优先级处理。这通常在每个服务器配置中定义，但也可以出现在虚拟主机中。

HTTP/2 服务器推送始终与客户端请求相关。每个这样的请求/响应对或流都有一个依赖项和一个权重，共同定义流的优先级。

当一个流依赖于另一个流时，例如 X 依赖于 Y，那么 Y 会先获得所有带宽，然后 X 才能获得任何带宽。请注意，这并不意味着 Y 会阻塞 X。如果 Y 没有数据要发送，则分配给 Y 的所有带宽都可以由 X 使用。

当一个流具有多个依赖项时，例如 X1 和 X2 都依赖于 Y，则权重决定带宽分配。如果 X1 和 X2 的权重相同，则它们都获得可用带宽的一半。如果 X1 的权重是 X2 的两倍，则 X1 获得 X2 的两倍带宽。

最终，每个流都依赖于根流，该流获得所有可用带宽，但从不发送任何内容。因此，其所有带宽都根据权重分配给其子级。这些子级要么有数据要发送，要么将带宽分配给它们自己的子级。依此类推。如果所有子级都没有数据要发送，则该带宽将根据相同的规则分配到其他地方。

此优先级系统的目的是始终利用可用带宽，同时允许对特定流进行优先级排序和加权。由于通常所有流都是由客户端启动的，因此它也是设置这些优先级的客户端。

只有当这样的流导致 PUSH 时，服务器才会决定此类推送流的初始优先级。在下面的示例中，X 是客户端流。它依赖于 Y，服务器决定将流 P1 和 P2 推送到 X 上。

默认优先级规则是

H2PushPriority * After 16

它表示“发送任何 content-type 的推送流，该流依赖于客户端流，权重为 16”。因此，P1 和 P2 将在 X 之后发送，并且由于它们具有相同的权重，因此它们在彼此之间平等地共享带宽。

H2PushPriority text/css Interleaved 256

这表示“发送与客户端流具有相同依赖关系和权重的任何 CSS 资源”。如果 P1 的内容类型为“text/css”，它将依赖于 Y（就像 X 一样），并且它的有效权重将计算为 P1ew = Xw * (P1w / 256)。如果 P1w 为 256，这将使有效权重与 X 的权重相同。如果 X 和 P1 都有数据要发送，带宽将平均分配给两者。

如果 Pw 指定为 512，则推送的交错流将获得 X 两倍的权重。如果为 128，则只有 X 一半的权重。请注意，有效权重始终限制在 256。

H2PushPriority application/json Before

这表示任何推送的“application/json”内容类型流都应该在 X 之前发送。这使得 P1 依赖于 Y，而 X 依赖于 P1。因此，只要 P1 有数据要发送，X 就会被阻塞。有效权重从客户端流继承。不允许指定权重。

请注意，优先级规范的效果受可用服务器资源的限制。如果服务器没有可用于推送流的 worker，则流的数据可能只能在其他流完成时到达。

最后但并非最不重要的是，此指令中使用的语法有一些细节。

1. “*”是唯一匹配所有其他内容类型的特殊内容类型。“image/*”将不起作用。
2. 默认依赖关系为“After”。
3. 还有一些默认权重：“After”为 16，“interleaved”为 256。

H2PushPriority application/json 32         # an After rule
H2PushPriority image/jpeg before           # weight inherited
H2PushPriority text/css   interleaved      # weight 256 default

H2PushResource 指令

当添加到目录/位置时，将尝试对通过此指令添加的所有路径进行 HTTP/2 PUSH。此指令可以多次用于同一个位置。

此指令比通过 mod_headers 添加 Link 标头更早地推送资源。 mod_http2 在对客户端的 103 Early Hints 中间响应中宣布这些资源。这意味着不支持 PUSH 的客户端仍然会收到提前预加载提示。

与通过 mod_headers 设置 Link 响应标头相比，此指令仅对 HTTP/2 连接生效。

通过向此类资源添加 critical，服务器将优先处理它，并在数据可用后，在主请求数据之前发送其数据。

H2SerializeHeaders 指令

此指令切换是否应将 HTTP/2 请求序列化为 HTTP/1.1 格式，以便由 httpd 核心进行处理，或者是否应将接收到的二进制数据直接传递到 request_rec 中。

序列化会降低性能，但在自定义过滤器/钩子需要它时，会提供更多向后兼容性。

H2SerializeHeaders on

H2StreamMaxMemSize 指令

此指令设置活动流在内存中缓冲的最大输出数据字节数。此内存不是按流分配的。当要进行分配时，分配将针对此限制进行计数。当达到限制时，流处理会冻结，并且只有在将缓冲数据发送到客户端后才会继续。

H2StreamMaxMemSize 128000

H2StreamTimeout 指令

H2StreamTimeout 指定正在处理的流等待其数据发送/接收的最大时间。

H2TLSCoolDownSecs 指令

此指令设置 TLS 连接空闲时间，在该时间段后，TLS 写入大小将回退到较小的 (~1300 字节) 长度。这可以在服务器范围内使用，也可以用于特定的 <VirtualHost>。

有关 TLS 预热的信息，请参阅 H2TLSWarmUpSize。 H2TLSCoolDownSecs 反映了连接可能会随着时间的推移而恶化（并且 TCP 流量会调整）的事实，因为空闲连接也会出现这种情况。在一段时间内没有发送数据后，回退到预热阶段有利于整体性能。

在连接可以被认为是可靠的部署中，可以通过将其设置为 0 来禁用此计时器。

以下示例将秒数设置为零，有效地禁用了任何冷却。预热的 TLS 连接保持最大记录大小。

H2TLSCoolDownSecs 0

H2TLSWarmUpSize 指令

此指令设置在 https: HTTP/2 连接上进行最大大小写入 (16k) 之前，以小 TLS 记录 (~1300 字节) 发送的字节数。这可以在服务器范围内使用，也可以用于特定的 <VirtualHost>。

由 google performance labs 进行的测量表明，如果初始记录大小保持在 MTU 级别以下，以允许完整记录适合 IP 数据包，则可以在 TLS 连接上获得最佳性能。

虽然 TCP 会调整其流量控制和窗口大小，但较长的 TLS 记录可能会卡在队列中或丢失并需要重新传输。当然，这对所有数据包都是正确的。但是，TLS 需要完整的记录才能对其进行解密。任何末尾缺少的字节都会阻止使用接收到的字节。

在成功发送了足够数量的字节后，连接的 TCP 状态将稳定，并且可以使用最大 TLS 记录大小 (16 KB) 来获得最佳性能。

在服务器仅在本地或通过可靠连接访问的部署中，可以将值降低，其中 0 表示完全禁用任何预热阶段。

以下示例将大小设置为零，有效地禁用了任何预热阶段。

H2TLSWarmUpSize 0

H2Upgrade 指令

此指令切换是否使用 HTTP/1.1 升级方法切换到 HTTP/2。这应该在 <VirtualHost> 部分内使用，以启用对该虚拟主机的 HTTP/2 升级。

这种协议切换方法在 HTTP/1.1 中定义，并使用“Upgrade”标头（因此得名）来宣布愿意使用其他协议。这可能发生在 HTTP/1.1 连接的任何请求上。

这种协议切换方法在明文（潜在的 h2c）连接上默认启用，在 TLS（潜在的 h2）上禁用，如 RFC 7540 所规定。

请注意，升级仅适用于不包含正文的请求。带有内容的 POST 和 PUT 永远不会触发升级到 HTTP/2。有关升级的替代方法，请参阅 H2Direct。

此模式仅在通过 Protocols 启用 h2 或 h2c 时有效。

H2Upgrade on

H2WebSockets 指令

使用 H2WebSockets 来启用或禁用通过 HTTP/2 协议引导 WebSockets。此协议扩展在 RFC 8441 中定义。

此类请求作为带有额外“:protocol”标头的 CONNECT 出现。此类请求在模块内部转换为其 HTTP/1.1 等效项，然后再传递到内部处理。

这意味着 HTTP/2 WebSockets 可用于带有“upgrade=websocket”参数的 ProxyPass，无需进一步更改。

对于直接在服务器中处理 WebSockets 的（第三方）模块，协议引导本身也将起作用。但是，数据传输在 HTTP/2 的情况下需要额外的支持。协商的 WebSocket 将无法使用客户端连接套接字来轮询与 IO 相关的事件。

由于启用此功能可能会破坏此类第三方模块的向后兼容性，因此它默认情况下未启用。

H2WindowSize 指令

此指令设置用于从客户端到服务器的流量控制的窗口大小，并限制服务器必须缓冲的数据量。一旦达到限制，客户端将停止在流上发送，直到服务器宣布更多可用空间（因为它已处理了一些数据）。

此限制仅影响请求正文，不影响其元数据（如标头）。此外，它对响应正文没有影响，因为这些正文的窗口大小由客户端管理。

H2WindowSize 128000