ngx_http_fastcgi_module模块.md

ngx_http_fastcgi_module

ngx_http_fastcgi_module模块允许将请求传递到FastCGI服务器。

fastcgi_bind

Syntax: fastcgi_bind address [transparent] | off;
Default:    —
Context:    http, server, location
This directive appeared in version 0.8.22.

使与FastCGI服务器的传出连接源自具有可选端口（1.11.2）的指定本地IP地址。参数值可以包含变量（1.3.12）。特殊值off（1.3.12）取消了从之前配置级别继承的fastcgi_bind指令的影响，这允许系统自动分配本地IP地址和端口。

fastcgi_buffer_size

Syntax: fastcgi_buffer_size size;
Default:    fastcgi_buffer_size 4k|8k;
Context:    http, server, location

设置用于读取从FastCGI服务器接收的响应的第一部分的缓冲区大小。这部分通常包含一个小的响应报文header。默认情况下，缓冲区大小等于一个内存页。是4K或8K，取决于平台。然而，它可以做得更小。

fastcgi_buffering

Syntax: fastcgi_buffering on | off;
Default:    fastcgi_buffering on;
Context:    http, server, location
This directive appeared in version 1.5.6.

启用或禁用来自FastCGI服务器的响应报文缓冲。
当启用缓冲时，nginx会尽快从FastCGI服务器接收响应，将其保存到由fastcgi_buffer_size和fastcgi_buffers指令设置的缓冲区中。如果整个响应不适合内存，它的一部分可以保存到磁盘上的临时文件。写入临时文件由fastcgi_max_temp_file_size和fastcgi_temp_file_write_size指令控制。
当禁用缓冲时，响应在接收到时立即同步传递给客户端。 nginx不会尝试从FastCGI服务器读取整个响应。 nginx一次可以从服务器接收的数据的最大大小由fastcgi_buffer_size指令设置。
通过在“X-Accel-Buffering”响应头字段中传递“yes”或“no”，也可以启用或禁用缓冲。此功能可以使用fastcgi_ignore_headers指令禁用。

fastcgi_buffers

Syntax: fastcgi_buffers number size;
Default:    fastcgi_buffers 8 4k|8k;
Context:    http, server, location

设置用于从FastCGI服务器读取单个连接的响应的缓冲区的数量和大小。默认情况下，缓冲区大小等于一个内存页。是4K或8K，取决于平台。

fastcgi_busy_buffers_size

Syntax: fastcgi_busy_buffers_size size;
Default:    fastcgi_busy_buffers_size 8k|16k;
Context:    http, server, location

当启用来自FastCGI服务器的响应缓冲时，限制可能响应报文尚未完全读取而忙于向客户端发送响应的缓冲区的总大小。同时，其余缓冲区可用于读取响应，并且如果需要，缓冲对临时文件的响应的一部分。默认情况下，大小受限于由fastcgi_buffer_size和fastcgi_buffers指令设置的两个缓冲区的大小。

fastcgi_cache

Syntax: fastcgi_cache zone | off;
Default:    fastcgi_cache off;
Context:    http, server, location

定义用于缓存的共享内存区域。同一区域可以在几个地方使用。参数值可以包含变量（1.7.9）。 off参数禁用从先前配置级别继承的缓存。

fastcgi_cache_bypass

Syntax: fastcgi_cache_bypass string ...;
Default:    —
Context:    http, server, location

定义不会从缓存获取响应的条件。如果字符串参数的至少一个值不为空，并且不等于“0”，则不会从缓存获取响应:

fastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
fastcgi_cache_bypass $http_pragma    $http_authorization;

可以与fastcgi_no_cache指令一起使用。

fastcgi_cache_key

Syntax: fastcgi_cache_key string;
Default:    —
Context:    http, server, location

定义用于缓存的键。

fastcgi_cache_key localhost:9000$request_uri;

fastcgi_cache_lock

Syntax: fastcgi_cache_lock on | off;
Default:    fastcgi_cache_lock off;
Context:    http, server, location
This directive appeared in version 1.1.12.

当启用时，每次只有一个请求将允许根据fastcgi_cache_key指令通过向FastCGI服务器传递请求来填充标识的新缓存元素。相同高速缓存元素的其他请求将等待响应出现在高速缓存中或高速缓存锁中以释放此元素，直到由fastcgi_cache_lock_timeout指令设置的时间。

fastcgi_cache_lock_age

Syntax: fastcgi_cache_lock_age time;
Default:    fastcgi_cache_lock_age 5s;
Context:    http, server, location
This directive appeared in version 1.7.8.

如果传递到FastCGI服务器用于填充新的高速缓存元素的最后一个请求在指定时间内没有完成，则可以将另一个请求传递给FastCGI服务器。

fastcgi_cache_lock_timeout

Syntax: fastcgi_cache_lock_timeout time;
Default:    fastcgi_cache_lock_timeout 5s;
Context:    http, server, location
This directive appeared in version 1.1.12.

设置fastcgi_cache_lock的超时。当时间到期时，请求将传递到FastCGI服务器，但是响应报文不会被缓存。
Notes:在1.7.8之前，响应报文可以被缓存。

fastcgi_cache_max_range_offset

Syntax: fastcgi_cache_max_range_offset number;
Default:    —
Context:    http, server, location
This directive appeared in version 1.11.6.

设置字节范围请求的偏移量（以字节为单位）。如果范围超出偏移量，范围请求将传递到FastCGI服务器，并且响应不会被缓存。

fastcgi_cache_methods

Syntax: fastcgi_cache_methods GET | HEAD | POST ...;
Default:    fastcgi_cache_methods GET HEAD;
Context:    http, server, location
This directive appeared in version 0.7.59.

如果客户端请求方法列在此指令中，那么响应将被缓存。 “GET”和“HEAD”方法总是添加到列表中，但建议明确指定它们。另请参见fastcgi_no_cache指令。

fastcgi_cache_min_uses

Syntax: fastcgi_cache_min_uses number;
Default:    fastcgi_cache_min_uses 1;
Context:    http, server, location

设置在其后响应将被缓存的请求数。

fastcgi_cache_path

Syntax: fastcgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [manager_files=number] [manager_sleep=time] [manager_threshold=time] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time];
Default:    —
Context:    http

设置缓存的路径和其他参数。缓存数据存储在文件中。高速缓存中的密钥和文件名都是将MD5函数应用于代理URL的结果。 levels参数定义缓存的层次结构级别：从1到3，每个级别接受值1或2.例如，在以下配置中:

fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;

缓存中的文件名将如下所示：

/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c

详细参考

fastcgi_cache_purge

Syntax: fastcgi_cache_purge string ...;
Default:    —
Context:    http, server, location
This directive appeared in version 1.5.7.

定义请求将被视为缓存清除请求的条件。
详细参考

fastcgi_cache_revalidate

Syntax: fastcgi_cache_revalidate on | off;
Default:    fastcgi_cache_revalidate off;
Context:    http, server, location
This directive appeared in version 1.5.7.

允许使用具有“If-Modified-Since”和“If-None-Match”头字段的条件请求重新验证过期缓存项。

fastcgi_cache_use_stale

Syntax: fastcgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | off ...;
Default:    
fastcgi_cache_use_stale off;
Context:    http, server, location

确定在与FastCGI服务器通信期间发生错误时，可以使用过时缓存响应的情况。指令的参数与fastcgi_next_upstream指令的参数匹配。
如果无法选择处理请求的FastCGI服务器，则错误参数还允许使用陈旧的缓存响应。
此外，如果更新参数当前正在被更新，则允许使用陈旧的缓存响应。这允许在更新缓存数据时最大限度地减少对FastCGI服务器的访问次数。
要在填充新缓存元素时最大限度地减少对FastCGI服务器的访问次数，可以使用fastcgi_cache_lock指令。

fastcgi_cache_valid

Syntax: fastcgi_cache_valid [code ...] time;
Default:    —
Context:    http, server, location

设置不同响应代码的缓存时间。例如，以下指令:

fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 404      1m;

对代码200和302的响应设置10分钟的缓存，对代码404的响应设置为1分钟。
如果仅指定高速缓存时间:

fastcgi_cache_valid 5m;

那么只缓存200,301和302响应。
此外，可以指定any参数来缓存任何响应：

fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 301      1h;
fastcgi_cache_valid any      1m;

缓存的参数也可以直接在响应头中设置。这比使用指令设置缓存时间具有更高的优先级。

“X-Accel-Expires”标头字段设置响应的缓存时间（以秒为单位）。零值禁用缓存用于响应。如果值以@前缀开头，则它设置自Epoch开始的绝对时间（以秒为单位），直到响应可以被缓存。
如果报头不包括“X-Accel-Expires”字段，则可以在报头字段“Expires”或“Cache-Control”中设置高速缓存的参数。
如果头包括“Set-Cookie”字段，则这样的响应将不被缓存。
如果头包括具有特殊值“*”的“Vary”字段，则这样的响应将不被缓存（1.7.7）。如果头部包括具有另一个值的“Vary”字段，则这样的响应将被缓存，考虑相应的请求头字段（1.7.7）。

可以使用fastcgi_ignore_headers指令禁用对这些响应头字段中的一个或多个的处理。

fastcgi_catch_stderr

Syntax: fastcgi_catch_stderr string;
Default:    —
Context:    http, server, location

设置要从FastCGI服务器接收到的响应的错误流中搜索的字符串。如果找到该字符串，则认为FastCGI服务器已返回无效响应。这允许处理nginx中的应用程序错误，例如：

location /php {
    fastcgi_pass backend:9000;
    ...
    fastcgi_catch_stderr "PHP Fatal error";
    fastcgi_next_upstream error timeout invalid_header;
}

fastcgi_connect_timeout

Syntax: fastcgi_connect_timeout time;
Default:    fastcgi_connect_timeout 60s;
Context:    http, server, location

定义与FastCGI服务器建立连接的超时。应该注意，该超时通常不能超过75秒。

fastcgi_force_ranges

Syntax: fastcgi_force_ranges on | off;
Default:    fastcgi_force_ranges off;
Context:    http, server, location
This directive appeared in version 1.7.7.

无论这些响应中的“Accept-Ranges”字段如何，对FastCGI服务器的缓存和非缓存响应都启用字节范围支持。

fastcgi_hide_header

Syntax: fastcgi_hide_header field;
Default:    —
Context:    http, server, location

默认情况下，nginx不会将FastCGI服务器响应中的头部字段“Status”和“X-Accel -...”传递给客户端。 fastcgi_hide_header指令设置不会传递的附加字段。如果相反，需要允许字段的传递，则可以使用fastcgi_pass_header伪指令。

fastcgi_ignore_client_abort

Syntax: fastcgi_ignore_client_abort on | off;
Default:    fastcgi_ignore_client_abort off;
Context:    http, server, location

确定当客户端在不等待响应的情况下关闭连接时是否应关闭与FastCGI服务器的连接。

fastcgi_ignore_headers

Syntax: fastcgi_ignore_headers field ...;
Default:    —
Context:    http, server, location

禁用来自FastCGI服务器的某些响应头字段的处理。可以忽略以下字段：“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), and “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”设置响应的所需字符集。

fastcgi_index

Syntax: fastcgi_index name;
Default:    —
Context:    http, server, location

在$ fastcgi_script_name变量的值中设置将附加在以斜杠结尾的URI后面的文件名。例如，使用这些设置和“/page.php”请求，SCRIPT_FILENAME参数将等于“/home/www/scripts/php/page.php”，对于“/”请求，它将等于“/ home / www / scripts / php / index.php“。

fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;

fastcgi_intercept_errors

Syntax: fastcgi_intercept_errors on | off;
Default:    fastcgi_intercept_errors off;
Context:    http, server, location

确定是否应将代码大于或等于300的FastCGI服务器响应传递给客户端，或者拦截并重定向到nginx以便使用error_page指令进行处理。

fastcgi_keep_conn

Syntax: fastcgi_keep_conn on | off;
Default:    fastcgi_keep_conn off;
Context:    http, server, location
This directive appeared in version 1.1.4.

默认情况下，FastCGI服务器将在发送响应后立即关闭连接。但是，当此指令设置为on时，nginx将指示FastCGI服务器保持连接打开。这是必要的，特别是对于与FastCGI服务器的保持连接功能。

fastcgi_limit_rate

Syntax: fastcgi_limit_rate rate;
Default:    fastcgi_limit_rate 0;
Context:    http, server, location
This directive appeared in version 1.7.7.

限制从FastCGI服务器读取响应的速度。速率以字节/秒指定。零值禁用速率限制。每个请求设置限制，因此如果nginx同时打开与FastCFI服务器的两个连接，则总速率将是指定限制的两倍。仅当启用了来自FastCGI服务器的响应缓冲时，该限制才起作用

fastcgi_max_temp_file_size

Syntax: fastcgi_max_temp_file_size size;
Default:    fastcgi_max_temp_file_size 1024m;
Context:    http, server, location

当启用来自FastCGI服务器的响应缓冲，并且整个响应不适合由fastcgi_buffer_size和fastcgi_buffers指令设置的缓冲区时，响应的一部分可以保存到临时文件。此伪指令设置临时文件的最大大小。一次写入临时文件的数据大小由fastcgi_temp_file_write_size指令设置。
零值禁用对临时文件的响应缓冲。
Notes:此限制不适用于将缓存或存储在磁盘上的响应。

fastcgi_next_upstream

Syntax: fastcgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | non_idempotent | off ...;
Default:    
fastcgi_next_upstream error timeout;
Context:    http, server, location

指定请求应传递到下一个服务器的情况：

error:在与服务器建立连接，向其传递请求或读取响应报文header时发生错误;
timeout:在与服务器建立连接，向其传递请求或读取响应报文header时发生超时;
invalid_header:服务器返回空响应或无效响应;
http_500:服务器返回了带有代码500的响应;
http_503:服务器返回具有代码503的响应;
http_403:服务器返回带有代码403的响应;
http_404:服务器返回具有代码404的响应;
non_idempotent:通常，如果请求已经被发送到上游服务器（1.9.13），则具有非幂等方法的请求（POST，LOCK，PATCH）不被传递到下一个服务器;启用此选项明确允许重试此类请求;
off:禁用将请求传递到下一个服务器。

应该记住，将请求传递到下一个服务器是可能的，如果还没有发送到客户端。也就是说，如果在传送响应的中间发生错误或超时，则固定不可能。
该指令还定义了与服务器通信的失败尝试。错误，超时和invalid_header的情况始终被认为是不成功的尝试，即使它们没有在指令中指定。仅当在指令中指定http_500和http_503的情况时，才会将其视为不成功尝试。 http_403和http_404的情况绝不会被认为是失败的尝试。
向下一个服务器传递请求可以受尝试次数和时间限制。

fastcgi_next_upstream_timeout

Syntax: fastcgi_next_upstream_timeout time;
Default:    fastcgi_next_upstream_timeout 0;
Context:    http, server, location
This directive appeared in version 1.7.5.

限制请求可以传递到下一个服务器的时间。 0值关闭此限制。

fastcgi_next_upstream_tries

Syntax: fastcgi_next_upstream_tries number;
Default:    fastcgi_next_upstream_tries 0;
Context:    http, server, location
This directive appeared in version 1.7.5.

限制将请求传递到下一个服务器的可能尝试次数。 0值关闭此限制。

fastcgi_no_cache

Syntax: fastcgi_no_cache string ...;
Default:    —
Context:    http, server, location

定义响应不会保存到缓存的条件。如果字符串参数的至少一个值不为空，并且不等于“0”，则不会保存响应：

fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
fastcgi_no_cache $http_pragma    $http_authorization;

可以与fastcgi_cache_bypass指令一起使用。

fastcgi_param

Syntax: fastcgi_param parameter value [if_not_empty];
Default:    —
Context:    http, server, location

设置应传递到FastCGI服务器的参数。该值可以包含文本，变量及其组合。当且仅当没有在当前级别上定义fastcgi_param伪指令时，这些伪指令才继承自上一级。
以下示例显示了PHP的最低要求设置：

fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
fastcgi_param QUERY_STRING    $query_string;

SCRIPT_FILENAME参数在PHP中用于确定脚本名称，并且QUERY_STRING参数用于传递请求参数。
对于处理POST请求的脚本，还需要以下三个参数：

fastcgi_param REQUEST_METHOD  $request_method;
fastcgi_param CONTENT_TYPE    $content_type;
fastcgi_param CONTENT_LENGTH  $content_length;

如果PHP是使用--enable-force-cgi-redirect配置参数构建的，那么REDIRECT_STATUS参数也应该使用值“200”传递：

fastcgi_param REDIRECT_STATUS 200;

如果指令使用if_not_empty（1.1.11）指定，那么这样的参数不会传递到服务器，直到它的值不为空：

fastcgi_param HTTPS           $https if_not_empty;

fastcgi_pass

Syntax: fastcgi_pass address;
Default:    —
Context:    location, if in location

设置FastCGI服务器的地址。地址可以指定为域名或IP地址和端口：

fastcgi_pass localhost:9000;

如果域名解析为多个地址，则所有这些地址都将以循环方式使用。此外，可以将地址指定为服务器组。

fastcgi_pass_header

Syntax: fastcgi_pass_header field;
Default:    —
Context:    http, server, location

允许从FastCGI服务器向客户端传递禁用的标头字段。

fastcgi_pass_request_body

Syntax: fastcgi_pass_request_body on | off;
Default:    fastcgi_pass_request_body on;
Context:    http, server, location

指示是否将原始请求正文传递到FastCGI服务器。另请参见fastcgi_pass_request_headers指令。

fastcgi_pass_request_headers

Syntax: fastcgi_pass_request_headers on | off;
Default:    fastcgi_pass_request_headers on;
Context:    http, server, location

指示原始请求的标头字段是否传递到FastCGI服务器。另请参见fastcgi_pass_request_body指令。

fastcgi_read_timeout

Syntax: fastcgi_read_timeout time;
Default:    fastcgi_read_timeout 60s;
Context:    http, server, location

定义从FastCGI服务器读取响应的超时。超时仅在两个连续读取操作之间设置，而不是用于传输整个响应。如果FastCGI服务器在此时间内未传输任何内容，则连接将关闭。

fastcgi_request_buffering

Syntax: fastcgi_request_buffering on | off;
Default:    fastcgi_request_buffering on;
Context:    http, server, location
This directive appeared in version 1.7.11.

启用或禁用客户端请求正文的缓冲。
当启用缓冲时，在将请求发送到FastCGI服务器之前，从客户端读取整个请求主体。
当禁用缓冲时，请求主体在接收到时立即发送到FastCGI服务器。在这种情况下，如果nginx已经开始发送请求主体，则请求无法传递到下一个服务器。

fastcgi_send_lowat

Syntax: fastcgi_send_lowat size;
Default:    fastcgi_send_lowat 0;
Context:    http, server, location

如果指令设置为非零值，则nginx将尝试通过使用kqueue方法的NOTE_LOWAT标志或具有指定大小的SO_SNDLOWAT套接字选项，最小化对到FastCGI服务器的传出连接的发送操作数。
在Linux，Solaris和Windows上将忽略此指令。

fastcgi_send_timeout

Syntax: fastcgi_send_timeout time;
Default:    fastcgi_send_timeout 60s;
Context:    http, server, location

设置将请求发送到FastCGI服务器的超时。超时仅在两个连续的写操作之间设置，而不是用于传输整个请求。如果FastCGI服务器在此时间内未收到任何内容，则连接将关闭。

fastcgi_split_path_info

Syntax: fastcgi_split_path_info regex;
Default:    —
Context:    location

定义捕获$ fastcgi_path_info变量值的正则表达式。正则表达式应该有两个捕获：第一个变为$ fastcgi_script_name变量的值，第二个变为$ fastcgi_path_info变量的值。例如，使用这些设置和“/show.php/article/0001”请求，SCRIPT_FILENAME参数将等于“/path/to/php/show.php”，并且PATH_INFO参数将等于“/article/0001 “。

location ~ ^(.+.php)(.*)$ {
    fastcgi_split_path_info       ^(.+.php)(.*)$;
    fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name;
    fastcgi_param PATH_INFO       $fastcgi_path_info;

fastcgi_store

Syntax: fastcgi_store on | off | string;
Default:    fastcgi_store off;
Context:    http, server, location

启用将文件保存到磁盘。 on参数使用与指令别名或根对应的路径保存文件。 off参数禁用文件保存。此外，文件名可以使用带有变量的字符串显式设置：

fastcgi_store /data/www$original_uri;

文件的修改时间根据接收到的“Last-Modified”响应头字段设置。响应首先写入临时文件，然后重命名该文件。从版本0.8.9开始，临时文件和持久存储可以放在不同的文件系统上。但是，请注意，在这种情况下，文件跨两个文件系统复制，而不是廉价的重命名操作。因此，建议对于任何给定位置，保存的文件和保存临时文件的目录（由fastcgi_temp_path指令设置）放在同一文件系统上。
此伪指令可用于创建静态不可更改文件的本地副本，例如：

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

location /fetch/ {
    internal;

    fastcgi_pass         backend:9000;
    ...

    fastcgi_store        on;
    fastcgi_store_access user:rw group:rw all:r;
    fastcgi_temp_path    /data/temp;

    alias                /data/www/;
}

fastcgi_store_access

Syntax: fastcgi_store_access users:permissions ...;
Default:    fastcgi_store_access user:rw;
Context:    http, server, location

设置新创建的文件和目录的访问权限，例如：

fastcgi_store_access user:rw group:rw all:r;

如果指定了任何组或所有访问权限，则可以省略用户权限：

fastcgi_store_access group:rw all:r;

fastcgi_temp_file_write_size

Syntax: fastcgi_temp_file_write_size size;
Default:    fastcgi_temp_file_write_size 8k|16k;
Context:    http, server, location

当启用从FastCGI服务器到临时文件的响应缓冲时，限制写入临时文件的数据大小。默认情况下，大小受限于由fastcgi_buffer_size和fastcgi_buffers指令设置的两个缓冲区。临时文件的最大大小由fastcgi_max_temp_file_size指令设置。

fastcgi_temp_path

Syntax: fastcgi_temp_path path [level1 [level2 [level3]]];
Default:    fastcgi_temp_path fastcgi_temp;
Context:    http, server, location

定义用于存储具有从FastCGI服务器接收的数据的临时文件的目录。最多可以在指定目录下使用三级子目录层次结构。例如，在以下配置中

fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2;

一个临时文件可能如下所示：

/spool/nginx/fastcgi_temp/7/45/00000123457

另请参见fastcgi_cache_path指令的use_temp_path参数。