Nginx官方文档(四十一)【ngx_http_v2_module|ngx_http_xslt_module】

刺骨的言语ヽ痛彻心扉 2021-07-04 12:17 739阅读 0赞

# ngx\_http\_v2\_module #

*  已知问题
 *  示例配置
 *  指令
    
     *  http2\_body\_preread\_size
     *  http2\_chunk\_size
     *  http2\_idle\_timeout
     *  http2\_max\_concurrent\_pushes
     *  http2\_max\_concurrent\_streams
     *  http2\_max\_field\_size
     *  http2\_max\_header\_size
     *  http2\_max\_requests
     *  http2\_push
     *  http2\_push\_preload
     *  http2\_recv\_buffer\_size
     *  http2\_recv\_timeout
 *  内嵌变量

`ngx_http_v2_module` 模块（1.9.5）提供对 [HTTP/2][HTTP_2] 的支持并取代了 ngx\_http\_spdy\_module 模块。

默认不构建此模块，可使用 `--with-http_v2_module` 配置参数启用。

## 已知问题 ##

在 1.9.14 版本之前，无论 proxy\_request\_buffering、fastcgi\_request\_buffering、uwsgi\_request\_buffering 和 scgi\_request\_buffering 指令值如何设置，都无法禁用客户端请求体缓冲。

## 示例配置 ##

server {
        listen 443 ssl http2;
    
        ssl_certificate server.crt;
        ssl_certificate_key server.key;
    }

请注意，通过 TLS 接受 HTTP/2 连接需要「应用层协议协商」（Application-Layer Protocol Negotiation，ALPN）TLS 扩展支持，该支持仅在 [OpenSSL][] 1.0.2 版本之后可用。使用「次协议协商」（Next Protocol Negotiation，NPN）TLS 扩展（自 OpenSSL 1.0.1 版本起可用）不能保证生效。

另外，如果 ssl\_prefer\_server\_ciphers 指令设置为 `on` 值，则应将密码配置为符合 [RFC 7540 中的附录 A 黑名单][RFC 7540 _ A] 并由客户端支持。

## 指令 ##

### http2\_body\_preread\_size ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_body_preread_size</strong> <code>size</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_body_preread_size 64k;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>提示</strong></td> 
   <td align="left">该指令在 1.11.0 版本中出现</td> 
  </tr> 
 </tbody> 
</table>

设置在开始处理之前可能被保存的请求体中的每个请求的缓冲区大小（`size`）。

### http2\_chunk\_size ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_chunk_size</strong> <code>size</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_chunk_size 8k;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server、location</td> 
  </tr> 
 </tbody> 
</table>

设置响应体切片的最大大小（`size`）。值太低会导致更高的开销。由于 [HOL 阻塞][HOL]，过高的值会破坏优先级。

### http2\_idle\_timeout ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_idle_timeout</strong> <code>time</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_idle_timeout 3m;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server</td> 
  </tr> 
 </tbody> 
</table>

设置连接关闭后的不活动超时时间。

### http2\_max\_concurrent\_pushes ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_max_concurrent_pushes</strong> <code>number</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_max_concurrent_pushes 10;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>提示</strong></td> 
   <td align="left">该指令在 1.13.9 版本中出现</td> 
  </tr> 
 </tbody> 
</table>

限制一个连接的最大并发推送请求数。

### http2\_max\_concurrent\_streams ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_max_concurrent_streams</strong> <code>number</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_max_concurrent_streams 128;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server</td> 
  </tr> 
 </tbody> 
</table>

设置一个连接的最大并发 HTTP/2 流数量。

### http2\_max\_field\_size ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_max_field_size</strong> <code>size</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_max_field_size 4k;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server</td> 
  </tr> 
 </tbody> 
</table>

限制 [HPACK][] 压缩的请求头字段的最大大小（`size`）。该限制同样适用于字段名和值。请注意，如果使用了霍夫曼编码，则解压缩后的字段名和值字符串的实际大小可能会更大。对于大多数请求，默认限制应该足够。

### http2\_max\_header\_size ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_max_header_size</strong> <code>size</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_max_header_size 16k;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server</td> 
  </tr> 
 </tbody> 
</table>

限制 [HPACK][] 解压缩后整个请求头列表的最大大小（`size`）。对于大多数请求，默认限制应该足够。

### http2\_max\_requests ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_max_requests</strong> <code>number</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_max_requests 1000;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>提示</strong></td> 
   <td align="left">该指令在 1.11.6 版本中出现</td> 
  </tr> 
 </tbody> 
</table>

设置可以通过一个 HTTP/2 连接提供服务的最大请求数量（`number`）（包括推送请求），之后下一个客户端请求将导致连接关闭以及需要建立新连接。

要释放每个连接的内存分配，必须定期关闭连接。因此，设置过多的最大请求数可能会导致内存使用过多，因此不建议这样做。

### http2\_push ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_push</strong> <code>uri</code> | <code>off</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_push off;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server、location</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>提示</strong></td> 
   <td align="left">该指令在 1.13.9 版本中出现</td> 
  </tr> 
 </tbody> 
</table>

抢先向指定的 `uri` 发送（[推送][Link 1]）请求以及对原始请求响应。仅处理有绝对路径的相对 URI，例如：

http2_push /static/css/main.css;

`uri` 值可以包含变量。

可以在同一配置级别上指定几个 `http2_push` 指令。`off` 参数取消从其他配置级别继承的 `http2_push` 指令的作用。

### http2\_push\_preload ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_push_preload</strong> <code>on</code> | <code>off</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_push_preload off;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server、location</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>提示</strong></td> 
   <td align="left">该指令在 1.13.9 版本中出现</td> 
  </tr> 
 </tbody> 
</table>

启用将 **Link** 响应头字段中指定的[预加载链接][Link 2]自动转换为[推送][Link 1]请求的功能。

### http2\_recv\_buffer\_size ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_recv_buffer_size</strong> <code>size</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_recv_buffer_size 256k;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http</td> 
  </tr> 
 </tbody> 
</table>

设置每个工作进程输入缓冲区的大小（`size`）。

### http2\_recv\_timeout ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>http2_recv_timeout</strong> <code>time</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">http2_recv_timeout 30s;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server</td> 
  </tr> 
 </tbody> 
</table>

设置超时时间以从客户端获得更多数据，然后关闭连接。

## 内嵌变量 ##

`ngx_http_userid_module` 模块支持以下内嵌变量：

*  `$http2`
    
    协商的协议标识符：`h2` 用于 TLS HTTP/2，`h2c` 用于在明文 TCP HTTP/2，否则为空字符串。

## 原文档 ##

*  [http://nginx.org/en/docs/http/ngx\_http\_v2\_module.html][http_nginx.org_en_docs_http_ngx_http_v2_module.html]

--------------------

# ngx\_http\_xslt\_module #

*  示例配置
 *  指令
    
     *  xml\_entities
     *  xslt\_last\_modified
     *  xslt\_param
     *  xslt\_string\_param
     *  xslt\_stylesheet
     *  xslt\_types

`ngx_http_xslt_module`（0.7.8+）是一个过滤器，可使用一个或多个 XSLT 样式表来转换 XML 响应。

默认不构建此模块，可在构建时使用 `--with-http_xslt_module` 配置参数启用。

> 该模块雨来 [libxml2][] 和 [libxslt][] 库。

## 示例配置 ##

location / {
        xml_entities    /site/dtd/entities.dtd;
        xslt_stylesheet /site/xslt/one.xslt param=value;
        xslt_stylesheet /site/xslt/two.xslt;
    }

## 指令 ##

### xml\_entities ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>xml_entities</strong> <code>path</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server、location</td> 
  </tr> 
 </tbody> 
</table>

指定声明字符实体的 DTD 文件。该文件在配置阶段编译。出于技术原因，该模块无法在已处理的 XML 中使用外部子集声明，因此将其忽略，可使用专门定义的文件。该文件不应描述 XML 结构。仅声明所需的字符实体就足够了，例如：

<!ENTITY nbsp " ">

### xslt\_last\_modified ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>xslt_last_modified</strong> <code>on</code> | <code>off</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">xslt_last_modified off;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server、location</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>提示</strong></td> 
   <td align="left">该指令在 1.5.1 版本中出现</td> 
  </tr> 
 </tbody> 
</table>

允许在 XSLT 转换期间保留原始响应中的 `Last-Modified` 头字段，以方便响应缓存。

默认情况下，在转换期间修改响应的内容时，将删除头字段，并且该头字段可能包含动态生成的元素或片段，这些元素或片段独立于原始响应更改。

### xslt\_param ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>xslt_param</strong> <code>parameter value</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server、location</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>提示</strong></td> 
   <td align="left">该指令在 1.1.18 版本中出现</td> 
  </tr> 
 </tbody> 
</table>

定义 XSLT 样式表的参数。该值（`value`）为 XPath 表达式。`value` 可以包含变量。要将字符串值传递给样式表，可使用 xslt\_string\_param 指令。

可以有多个 `xslt_param` 指令。当且仅当当前级别上没有定义 `xslt_param` 和 xslt\_string\_param 指令时，这些指令才从上一级继承。

### xslt\_string\_param ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>xslt_string_param</strong> <code>parameter value</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server、location</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>提示</strong></td> 
   <td align="left">该指令在 1.1.18 版本中出现</td> 
  </tr> 
 </tbody> 
</table>

定义 XSLT 样式表的字符串参数。`value` 中的 XPath 表达式不会被解释。`value` 可以包含变量。

可以有多个 `xslt_string_param` 指令。当且仅当当前级别上没有定义 xslt\_param 和 `xslt_string_param` 指令时，这些指令才从上一级继承。

### xslt\_stylesheet ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>xslt_stylesheet</strong> <code>stylesheet [parameter=value ...]</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">——</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server、location</td> 
  </tr> 
 </tbody> 
</table>

定义 XSLT 样式表及其可选参数。在配置阶段将编译样式表。

可以单独指定参数，也可以使用 `:` 定界符将其分组在一行中。如果参数包含 `:` 字符，则应将其转义为 `％3A`。另外，`libxslt` 要求将包含非字母数字字符的参数括在单引号或双引号中，例如：

param1='http%3A//www.example.com':param2=value2

参数描述可以包含变量，例如，整行参数可以取自单个变量：

location / {
        xslt_stylesheet /site/xslt/one.xslt
                        $arg_xslt_params
                        param1='$value1':param2=value2
                        param3=value3;
    }

可以指定多个样式表。它们将按指定顺序应用。

### xslt\_types ###

<table> 
 <thead> 
  <tr> 
   <th align="left">-</th> 
   <th align="left">说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td align="left"><strong>语法</strong></td> 
   <td align="left"><strong>xslt_types</strong> <code>mime-type ...</code>;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>默认</strong></td> 
   <td align="left">xslt_types text/xml;</td> 
  </tr> 
  <tr> 
   <td align="left"><strong>上下文</strong></td> 
   <td align="left">http、server、location</td> 
  </tr> 
 </tbody> 
</table>

除了 `text/xml` 之外，还启用有指定 MIME 类型的响应的转换。特殊值 `*` 与任何 MIME 类型（0.8.29）匹配。如果转换结果是 HTML 响应，则其 MIME 类型将更改为 `text/html`。

## 原文档 ##

*  [http://nginx.org/en/docs/http/ngx\_http\_xslt\_module.html][http_nginx.org_en_docs_http_ngx_http_xslt_module.html]

[HTTP_2]: https://tools.ietf.org/html/rfc7540
[OpenSSL]: http://www.openssl.org/
[RFC 7540 _ A]: https://tools.ietf.org/html/rfc7540#appendix-A
[HOL]: http://en.wikipedia.org/wiki/Head-of-line_blocking
[HPACK]: https://tools.ietf.org/html/rfc7541
[Link 1]: https://tools.ietf.org/html/rfc7540#section-8.2
[Link 2]: https://www.w3.org/TR/preload/#server-push-http-2
[http_nginx.org_en_docs_http_ngx_http_v2_module.html]: http://nginx.org/en/docs/http/ngx_http_v2_module.html
[libxml2]: http://xmlsoft.org/
[libxslt]: http://xmlsoft.org/XSLT/
[http_nginx.org_en_docs_http_ngx_http_xslt_module.html]: http://nginx.org/en/docs/http/ngx_http_xslt_module.html