nginx中文文档-ngx_http_v2_module

此页面版本:2016-06-08
ngx_http_v2_module模块(1.9.5+)提供了HTTP2协议的支持,并取代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上的HTTP2连接需要“Application-Layer Protocol Negotiation”(ALPN)TLS扩展支持,仅从OpenSSL1.0.2版本开始可用。使用“Next Protocol Negotiation”(NPN)TLS扩展(从OpenSSL1.0.1版本可用)的不能保证。
还要注意,如果ssl_prefer_server_ciphers指令设置的值为“on”,加密算法需要遵从RFC7540 附录A黑名单,并受客户端支持。

http2_chunk_size

语法:http2_chunk_size size
默认:http2_chunk_size 8k
上下文:http, server, location

设置响应体被分割的最大块大小。过小的值会导致更高的负荷。太高的值由于排头阻塞对优化有害。

http2_body_preread_size

语法:http2_body_preread_size size
默认:http2_body_preread_size 64k;
上下文:http, server
版本:1.11.0+

设置每一个请求的缓冲区大小,请求体在开始处理前可以保存到缓冲区中

http2_idle_timeout

语法:http2_idle_timeout time
默认:http2_idle_timeout 3m
上下文:http, server

设置非活跃的超时时间,过了这个时间后连接将被关闭。

http2_max_concurrent_streams

语法:http2_max_concurrent_streams number
默认:http2_max_concurrent_streams 128
上下文:http, server

设置一个连接中同时传输HTTP2流的最大数。

http2_max_field_size

语法:http2_max_field_size size
默认:http2_max_field_size 4k
上下文:http, server

限制HPACK压缩请求头域的最大大小。限制应用于名字和值。注意如果使用哈夫曼编码,实际的解压的名字和值的字符串大小可能更大。对于大多数请求,默认的限制是足够的。

http2_max_header_size

语法:http2_max_header_size size
默认:http2_max_header_size 16k
上下文:http, server

限制在HPACK解压后完整的请求头列表的最大大小。对于大多数请求来说,默认的限制是足够的。

http2_recv_buffer_size

语法:http2_recv_buffer_size size
默认:http2_recv_buffer_size 256k
上下文:http

设置接收缓冲区的大小。

http2_recv_timeout

语法:http2_recv_timeout time
默认:http2_recv_timeout 30s
上下文:http, server

为希望从客户端收到更多数据设置超时时间,超过这个时间之后连接将关闭。

内嵌变量
ngx_http_v2_module模块支持以下内嵌变量:

$http2
协商协议标识符:TLS上的HTTP2为“h2”,明文TCP的HTTP2为“h2c”,其他的为空。

nginx中文文档-ngx_http_uwsgi_module(I-T)

本文档包含以下指令:uwsgi_ignore_client_abort、uwsgi_ignore_headers、uwsgi_intercept_errors、uwsgi_limit_rate、uwsgi_max_temp_file_size、uwsgi_modifier1、uwsgi_modifier2、uwsgi_next_upstream、uwsgi_next_upstream_timeout、uwsgi_next_upstream_tries、uwsgi_no_cache、uwsgi_param、uwsgi_pass、uwsgi_pass_header、uwsgi_pass_request_body、uwsgi_pass_request_headers、uwsgi_read_timeout、uwsgi_request_buffering、uwsgi_send_timeout、uwsgi_ssl_certificate、uwsgi_ssl_certificate_key、uwsgi_ssl_ciphers、uwsgi_ssl_crl、uwsgi_ssl_name、uwsgi_ssl_password_file、uwsgi_ssl_protocols、uwsgi_ssl_server_name、uwsgi_ssl_session_reuse、uwsgi_ssl_trusted_certificate、uwsgi_ssl_verify、uwsgi_ssl_verify_depth、uwsgi_store、uwsgi_store_access、uwsgi_temp_file_write_size、uwsgi_temp_path

uwsgi_ignore_client_abort

语法:uwsgi_ignore_client_abort on | off
默认:uwsgi_ignore_client_abort off
上下文:http, server, location

决定在客户端没有等待响应就关闭连接时,与uwsgi服务器的连接是否需要关闭。

uwsgi_ignore_headers

语法:uwsgi_ignore_headers field
默认:—
上下文:http, server, location

禁用处理从uwsgi服务器响应的头域。以下字段可以被忽略:“X-Accel-Redirect”, “X-Accel-Expires”, “X-Accel-Limit-Rate” (1.1.6+), “X-Accel-Buffering” (1.1.6+), “X-Accel-Charset” (1.1.6+), “Expires”, “Cache-Control”, “Set-Cookie” (0.8.44+) 和 “Vary” (1.7.7+)。
如果不禁用,处理这些头域有以下影响:

  • “X-Accel-Expires”, “Expires”, “Cache-Control”, “Set-Cookie”, 和“Vary” 设置缓存参数
  • “X-Accel-Redirect”执行内部重定向到指定的URI
  • “X-Accel-Limit-Rate”设置传输到客户端的响应的速度限制
  • “X-Accel-Buffering”启用或禁用响应的缓冲区
  • “X-Accel-Charset”设置希望响应的字符编码

uwsgi_intercept_errors

语法:uwsgi_intercept_errors on | off
默认:uwsgi_intercept_errors off
上下文:http, server, location

决定在uwsgi服务器响应的状态码大于等于300时,应该传给客户端还是重定向到nginx使用error_page指令处理。

uwsgi_limit_rate

语法:uwsgi_limit_rate rate
默认:uwsgi_limit_rate 0
上下文:http, server, location
版本:1.7.7+

限制从uwsgi服务器读取响应的速度。限速指定为字节每秒。零值禁用限速。限制针对一个请求,如果nginx同时打开两个连接到uwsgi服务器,整体速率将会使指定限制的两倍。限制只有在启用uwsgi服务器响应缓冲区时可用。

uwsgi_max_temp_file_size

语法:uwsgi_max_temp_file_size size
默认:uwsgi_max_temp_file_size 1024m
上下文:http, server, location

当从uwsgi服务器的响应缓冲区启用并且整体响应不能放到uwsgi_buffer_size和uwsgi_buffers指令设置的缓冲区中时,一部分响应可以保存到临时文件中。指令限制了临时文件的最大大小。一次写入到临时文件的数据大小由uwsgi_temp_file_write_size指令设置。
零值禁用缓冲区到临时文件功能。
这个限制不能应用在将要缓存或保存到磁盘上的响应。

uwsgi_modifier1

语法:uwsgi_modifier1 number
默认:uwsgi_modifier1 0
上下文:http, server, location

设置uwsgi包头中的modifier1字段值。

uwsgi_modifier2

语法:uwsgi_modifier2 number
默认:uwsgi_modifier2 0
上下文:http, server, location

设置uwsgi包头中的uwsgi_modifier2字段值。

uwsgi_next_upstream

语法:uwsgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | non_idempotent | off …
默认:uwsgi_next_upstream error timeout
上下文:http, server, location

指定哪些情况下请求会传递给下一个服务器:
error
当与服务器建立连接、传递请求或读取响应头时发生了一个错误。

timeout
当与服务器建立连接、传递请求或读取响应头时发生了超时。

invalid_header
服务器返回空或无效的请求

http_500
服务器返回500状态码

http_503
服务器返回503状态码

http_403
服务器返回403状态码

http_404
服务器返回404状态码

non_idempotent
一般地,非幂等方法(POST、LOCK、PATCH)的请求如果请求已经发送到上游服务器(1.9.13+),就不会传给下一个服务器,启用这个选项允许重试这样的请求。

off
禁用传递请求到下一个服务器。
需要知道的是传递请求到下一个服务器,是只有在没有任何数据发送到客户端时才可能的。也就是说,如果当传输响应的过程直冲发生了超时或错误,不可能修复。
指令同时定义了什么是与服务器通信的不成功尝试。error、timeout和invalid_header总会被认为是不成功的尝试,即使它们没有指定在指令中。http_500和http_503只有在指定在指令中时才会认为是不成功的尝试。http_403和http_404从不会被视为不成功的尝试。
传递请求到下一个服务器可以由尝试次数和时间限制。

uwsgi_next_upstream_timeout

语法:uwsgi_next_upstream_timeout time
默认:uwsgi_next_upstream_timeout 0
上下文:http, server, location
版本:1.7.5+

限制一个时间,在这个期间请求可以传给下一个服务器。0值关闭这个限制。

uwsgi_next_upstream_tries

语法:uwsgi_next_upstream_tries number
默认:uwsgi_next_upstream_tries 0
上下文:http, server, location
版本:1.7.5+

限制可能尝试传递请求给下一个服务器的次数。0值禁用这个限制。

uwsgi_no_cache

语法:uwsgi_no_cache string
默认:—
上下文:http, server, location

定义哪种情况下响应不会保存到缓存。如果string参数至少有一个是非“0”非空字符串,响应不会缓存:

uwsgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
uwsgi_no_cache $http_pragma    $http_authorization;

可以与uwsgi_cache_bypass指令一同使用。

uwsgi_param

语法:uwsgi_param parameter value [if_not_empty]
默认:—
上下文:http, server, location

设置需要传给uwsgi服务器的参数。值可以包含文本、变量以及它们的混合。这些指令当且仅当当前等级中没有uwsgi_param指令定义时才会继承自上次指令。
标准CGI环境变量应该作为uwsgi头提供,查阅uwsgi_params文件:

location / {
    include uwsgi_params;
    ...
}

如果指令指定了if_not_empty(1.1.11+)参数,那么这个参数将在值不空的时候传递给服务器:
uwsgi_param HTTPS $https if_not_empty;

uwsgi_pass

语法:uwsgi_pass [protocol://]address
默认:—
上下文:location, if in location

设置uwsgi服务器的协议和地址。“uwsgi”或“suwsgi”(安全的uwsgi,在SSL层上的uwsgi)可以作为协议指定。地址可以指定为域名或IP地址与端口号:

uwsgi_pass localhost:9000;
uwsgi_pass uwsgi://localhost:9000;
uwsgi_pass suwsgi://[2001:db8::1]:9090;

或者是一个UNIX-domain socket路径:
uwsgi_pass unix:/tmp/uwsgi.socket;
如果域名解析成多个地址,它们会通过轮询的方法使用。另外服务器可以指定为服务器组。
安全uwsgi协议从1.5.8版本开始支持。

uwsgi_pass_header

语法:uwsgi_pass_header field
默认:—
上下文:http, server, location

允许传递从uwsgi服务器被禁用的头域到客户端。

uwsgi_pass_request_body

语法:uwsgi_pass_request_body on | off
默认:uwsgi_pass_request_body on
上下文:http, server, location

指明原始请求体是否传给uwsgi服务器。参见uwsgi_pass_request_headers指令。

uwsgi_pass_request_headers

语法:uwsgi_pass_request_headers on | off
默认:uwsgi_pass_request_headers on
上下文:http, server, location

指明原始请求头域是否传给uwsgi服务器。参见uwsgi_pass_request_body指令。

uwsgi_read_timeout

语法:uwsgi_read_timeout time
默认:uwsgi_read_timeout 60s
上下文:http, server, location

定义一个超时时间,用于读取来自于uwsgi服务器的响应。超时是设置在两次成功的读操作之间,不是整个响应的传输。如果uwsgi服务器在这个时间内没有传递任何数据,连接将关闭。

uwsgi_request_buffering

语法:uwsgi_request_buffering on | off
默认:uwsgi_request_buffering on
上下文:http, server, location
版本:1.7.11+

启用或禁用客户端请求体缓冲区。
当缓冲区启用,在发送请求到uwsgi服务器之前会从客户端读取完整的请求体。
当缓冲区关闭,请求体会在收到时立即发送uwsgi服务器。这种情况下,如果nginx已经开始发送请求体,请求不能传递给下一个服务器。
当使用HTTP1.1 chunked传输编码发送原始请求体时,请求体将会被缓冲不管指令的值。

uwsgi_send_timeout

语法:uwsgi_send_timeout time
默认:uwsgi_send_timeout 60s
上下文:http, server, location

设置传递请求到uwsgi服务器的超时时间。超时时间只是两次成功的写请求之间,不是完整请求的传输。如果uwsgi服务器在这个时间没有收到任何数据,连接将关闭。

uwsgi_ssl_certificate

语法:uwsgi_ssl_certificate file
默认:—
上下文:http, server, location
版本:1.7.8+

指定一个PEM格式的证书文件用于安全uwsgi服务器的验证。

uwsgi_ssl_certificate_key

语法:uwsgi_ssl_certificate_key file
默认:—
上下文:http, server, location
版本:1.7.8+

指定一个PEM格式的密钥文件用于安全uwsgi服务器的验证。
可以指定engine:name:id值代替文件(1.7.9+),将从OpenSSL引擎name中加载一个指定id的密钥。

uwsgi_ssl_ciphers

语法:uwsgi_ssl_ciphers ciphers
默认:uwsgi_ssl_ciphers DEFAULT
上下文:http, server, location
版本:1.5.8+

指定安全uwsgi服务器请求可以使用的加密算法。加密算法指定为OpenSSL库可以识别的格式。
完整的列表可以使用“openssl ciphers”命令查看。

uwsgi_ssl_crl

语法:uwsgi_ssl_crl file
默认:—
上下文:http, server, location
版本:1.7.0+

指定一个PEM格式的吊销证书列表文件,用于验证安全uwsgi服务器的证书。

uwsgi_ssl_name

语法:uwsgi_ssl_name name
默认:uwsgi_ssl_name host from uwsgi_pass
上下文:http, server, location
版本:1.7.0+

允许覆盖服务器名称用于验证安全uwsgi服务器的证书,并当与安全uwsgi服务器建立连接时通过SNI传递。
默认情况下,会使用uwsgi_pass中的host部分。

uwsgi_ssl_password_file

语法:uwsgi_ssl_password_file file
默认:—
上下文:http, server, location
版本:1.7.8+

指定一个文件,用于保存密钥的密码,密码指定在分开的行中。密码会在加载密钥时轮流尝试。

uwsgi_ssl_protocols

语法:uwsgi_ssl_protocols [SSLv2] [SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2]
默认:uwsgi_ssl_protocols TLSv1 TLSv1.1 TLSv1.2
上下文:http, server, location
版本:1.5.8+

为安全uwsgi服务器请求启用指定协议。

uwsgi_ssl_server_name

语法:uwsgi_ssl_server_name on | off
默认:uwsgi_ssl_server_name off
上下文:http, server, location
版本:1.7.0+

启用或禁用当与安全uwsgi服务器建立连接时,通过TLS Server Name Indication扩展(SNI,RFC 6066)传递服务器名称。

uwsgi_ssl_session_reuse

语法:uwsgi_ssl_session_reuse on | off
默认:uwsgi_ssl_session_reuse on
上下文:http, server, location
版本:1.5.8+

决定当使用安全uwsgi服务器时,SSL会话是否可以重用。如果错误“SSL3_GET_FINISHED:digest check failed”出现在日志中,尝试禁用会话重用。

uwsgi_ssl_trusted_certificate

语法:uwsgi_ssl_trusted_certificate file
默认:—
上下文:http, server, location
版本:1.7.0+

指定一个PEM格式的可信CA证书文件,用于验证安全uwsgi服务器的证书。

uwsgi_ssl_verify

语法:uwsgi_ssl_verify on | off
默认:uwsgi_ssl_verify off
上下文:http, server, location
版本:1.7.0+

启用或禁用验证安全uwsgi服务器证书。

uwsgi_ssl_verify_depth

语法:uwsgi_ssl_verify_depth number
默认:uwsgi_ssl_verify_depth 1
上下文:http, server, location
版本:1.7.0+

设置验证安全uwsgi服务器证书链的深度。

uwsgi_store

语法:uwsgi_store on | off | string
默认:uwsgi_store off
上下文:http, server, location

启用保存文件到磁盘。on参数保存文件到alias或root指令对应的路径。off参数禁用保存文件。文件名可以用带变量的字符串:
uwsgi_store /data/www$original_uri;
文件的修改时间根据收到的响应头“Last-Modified”字段设置。响应首先写到临时文件中,然后重命名。从0.8.9版本开始,临时文件和持久化存储可以放到不同的文件系统中。但是,要知道的是,这种情况下,文件会在两个文件系统中复制,而不是更廉价的重命名操作。因此建议通过uwsgi_temp_path指令同时给出临时文件和保存文件的位置,并放到同一个文件系统上。
指令可以用于创建不更改的静态文件副本,例如:

location /images/ {
    root               /data/www;
    error_page         404 = /fetch$uri;
}

location /fetch/ {
    internal;

    uwsgi_pass         backend:9000;
    ...

    uwsgi_store        on;
    uwsgi_store_access user:rw group:rw all:r;
    uwsgi_temp_path    /data/temp;

    alias              /data/www/;
}

uwsgi_store_access

语法:uwsgi_store_access users:permissions
默认:uwsgi_store_access user:rw
上下文:http, server, location

设置新创建的文件和目录的权限,例如:
uwsgi_store_access user:rw group:rw all:r;
如果group或all的权限指定了,可以不指定user的权限:
uwsgi_store_access group:rw all:r;

uwsgi_temp_file_write_size

语法:uwsgi_temp_file_write_size size
默认:uwsgi_temp_file_write_size 8k|16k
上下文:http, server, location

当从uwsgi服务器的缓冲区吸入到临时文件功能启用时,限制一次写人到临时文件的数据大小。默认情况下,大小受uwsgi_buffer_size和uwsgi_buffers指令设置的两个缓冲区大小限制。临时文件的最大大小由uwsgi_max_temp_file_size指令设置。

uwsgi_temp_path

语法:uwsgi_temp_path path [level1 [level2 [level3]]]
默认:uwsgi_temp_path uwsgi_temp
上下文:http, server, location

定义一个目录用于保存从uwsgi服务器收到数据的临时文件。最多可以使用三级子目录。例如下面的配置
uwsgi_temp_path /spool/nginx/uwsgi_temp 1 2;
一个临时文件类似于:
/spool/nginx/uwsgi_temp/7/45/00000123457
参见uwsgi_cache_path指令的use_temp_path参数。