nginx中文文档-ngx_http_fastcgi_module(B-C)

本文档包含以下指令:fastcgi_bind、fastcgi_buffer_size、fastcgi_buffering、fastcgi_buffers、fastcgi_busy_buffers_size、fastcgi_cache、fastcgi_cache_bypass、fastcgi_cache_key、fastcgi_cache_lock、fastcgi_cache_lock_age、fastcgi_cache_lock_timeout、fastcgi_cache_methods、fastcgi_cache_min_uses、fastcgi_cache_path、fastcgi_cache_purge、fastcgi_cache_revalidate、fastcgi_cache_use_stale、fastcgi_cache_valid、fastcgi_catch_stderr、fastcgi_connect_timeout

示例配置

location / {
    fastcgi_pass  localhost:9000;
    fastcgi_index index.php;

    fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
    fastcgi_param QUERY_STRING    $query_string;
    fastcgi_param REQUEST_METHOD  $request_method;
    fastcgi_param CONTENT_TYPE    $content_type;
    fastcgi_param CONTENT_LENGTH  $content_length;
}

fastcgi_bind

语法:fastcgi_bind address | off
默认:—
上下文:http, server, location
版本:0.8.22+

定义从指定本地IP地址,从该地址输出连接到一个FastCGI服务器上。参数的值可以包含变量(1.3.12版本起)。特殊的值off(1.3.12起)取消了继承与上级fastcgi_bind指令的作用,进而允许系统自动选择本地的IP地址。

fastcgi_buffer_size

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

设置用于读取FastCGI服务器响应起始部分的缓冲区大小,该部分通常包含了一个小的响应头。默认情况下,大小等于一页内存。具体是4k还是8k取决于平台,但可以变得更小。

fastcgi_buffering

语法:fastcgi_buffering on | off
默认:fastcgi_buffering on
上下文:http, server, location
版本: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

语法:fastcgi_buffers number size
默认:fastcgi_buffers 8 4k|8k
上下文:http, server, location

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

fastcgi_busy_buffers_size

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

当FastCGI服务器响应缓冲区功能启用时,缓冲区总大小的限制会在响应没有完全读取的情况下向客户端发送响应。与此同时,剩下的缓冲区可以用来读取响应,如果需要还会降响应的部分保存在临时文件中。默认情况下,大小受fastcgi_buffer_size和fastcgi_buffers指令设置的两个缓冲区限制。

fastcgi_cache

语法:fastcgi_cache zone | off
默认:fastcgi_cache off
上下文:http, server, location

定义了缓存的共享内存区域。同一个区域可以在不同位置上使用。参数值可以包含变量(1.7.9版本起)。参数off禁用了从上级继承的设置。

fastcgi_cache_bypass

语法:fastcgi_cache_bypass string
默认:—
上下文: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

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

定义一个缓存的关键字,例如:
fastcgi_cache_key localhost:9000$request_uri;

fastcgi_cache_lock

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

当启用时,同一时间只有一个请求可以存在于由fastcgi_cache_key指令定义的新缓存元素中。使用相同缓存元素的其他请求将等待响应出现在缓存中或等待该元素被释放,这取决于fastcgi_cache_lock_timeout指令定义的时间。

fastcgi_cache_lock_age

语法:fastcgi_cache_lock_age time
默认:fastcgi_cache_lock_age 5s
上下文:http, server, location
版本:1.7.8+

如果最后传递给FastCGI服务器的请求占用了一个新的缓存元素,但在指定的时间没有完成,其他的请求也可以发送到FastCGI服务器上。

fastcgi_cache_lock_timeout

语法:fastcgi_cache_lock_timeout time
默认:fastcgi_cache_lock_timeout 5s
上下文:http, server, location
版本:1.1.12+

为fastcgi_cache_lock指令设置超时时间。当时间过期,请求将发送到FastCGI服务器上,但是响应不会被缓存。
在1.7.8版本之前,响应会被缓存。

fastcgi_cache_methods

语法:fastcgi_cache_methods GET | HEAD | POST …
默认:fastcgi_cache_methods GET HEAD
上下文:http, server, location
版本:0.7.59+

如果客户端请求方法在该指令指定的列表中,响应会被缓存。“GET”和“HEAD”方法总会被添加到列表中,尽管建议显式的指定它们。

fastcgi_cache_min_uses

语法:fastcgi_cache_min_uses number
默认:fastcgi_cache_min_uses 1
上下文:http, server, location

定义了请求多少次后,响应会被缓存。

fastcgi_cache_path

语法:path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time]
默认:—
上下文:http

设置缓存的路径和其他参数。缓存数据保存在文件中。关键字和文件名在缓存中都是以代理URL的MD5结果保存。levels参数缓存的层次。例如,在下面的配置中:
fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
缓存文件名将类似于:
/data/nginx/cache/c/29/b7f54b2df7773722d382f4809d65029c
缓存的响应首先写入到临时文件中,然后再进行重命名。从0.8.9版本开始,临时文件和缓存可以放在不同的文件系统中。但是,需要明白的是这种情况下,一个文件会在两个文件系统中复制,而不是代价低的重命名操作。建议将缓存和存放临时文件的目录都定位到同一个文件系统中。存放临时文件的目录通过use_temp_path参数设置(1.7.10版本起)。如果该参数忽略或设置为on,将会使用fastcgi_temp_path指令给出的位置。如果值设置为off,临时文件将直接存放在缓存目录中。
另外,所有活动的关键词和数据信息都保存在共享内存区域,其名称和大小由keys_zone参数设置。1M的容量可以存储大约8000个关键词。
缓存数据如果再inactive参数指定的时间内没有被访问过,将会从缓存中移除而不管它们的新鲜度。默认情况下inactive设置为10分钟。
特殊的“缓存管理”进程监控max_size参数设置的最大缓存大小。当超过这个大小后,将会移除最近最少使用的数据。
“缓存加载器”在启动一分钟后开始工作。它加载之前存在文件系统中的缓存信息到缓存区域中。加载在迭代中完成。在一次迭代中不会超过loader_files指定的数目(默认是100)被加载。例外,一次迭代过程中也会被loader_threshold参数限制(默认是200毫秒)。在迭代中间,会根据loader_sleep参数的设置进行暂停(默认是50毫秒)。
下面的参数将在商业版本中使用(译者注:商业版本就不翻译了):

purger=on|off
    Instructs whether cache entries that match a wildcard key will be removed from the disk by the cache purger (1.7.12). Setting the parameter to on (default is off) will activate the “cache purger” process that permanently iterates through all cache entries and deletes the entries that match the wildcard key.

purger_files=number
    Sets the number of items that will be scanned during one iteration (1.7.12). By default, purger_files is set to 10.

purger_threshold=number
    Sets the duration of one iteration (1.7.12). By default, purger_threshold is set to 50 milliseconds.

purger_sleep=number
    Sets a pause between iterations (1.7.12). By default, purger_sleep is set to 50 milliseconds.

fastcgi_cache_purge

语法:fastcgi_cache_purge string
默认:—
上下文:http, server, location
版本:1.5.7+

定义了哪种情况下,请求将被作为缓存清除请求。如果string参数至少有一个非空或不等于0的值,对应的缓存关键词会被移除。操作成功将通过204状态码进行提示。
如果清理请求的缓存关键词以型号(“*”)结尾,所有匹配通配符的关键词将会从缓存中移除。但是所有条目将会在磁盘中保留,直到被不再活动或被cache_purger(1.7.12+)或客户端尝试访问时被删除。
示例配置:

fastcgi_cache_path /data/nginx/cache keys_zone=cache_zone:10m;

map $request_method $purge_method {
    PURGE   1;
    default 0;
}

server {
    ...
    location / {
        fastcgi_pass        backend;
        fastcgi_cache       cache_zone;
        fastcgi_cache_key   $uri;
        fastcgi_cache_purge $purge_method;
    }
}

该函数为商业版本中的功能。

fastcgi_cache_revalidate

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

开启过期缓存重验证功能,使用请求头中的“If-Modified-Since”和“If-None-Match”。

fastcgi_cache_use_stale

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

定义了在何种情况下,与FastCGI服务器通信产生错误后可以使用过时的缓存。该指令的参数匹配fastcgi_next_upstream指令的参数。
error参数允许使用旧缓存如果无法选择一个FastCGI服务器处理请求。
updating参数允许当缓存正在更新时,使用旧缓存。这样会在更新缓存数据时减少访问FastCGI服务器的次数。
为了减少访问FastCGI服务器的次数,可以使用fastcgi_cache_lock指令。

fastcgi_cache_valid

语法:fastcgi_cache_valid [code …] time
默认:—
上下文:http, server, location

为不同的响应码设置缓存时间,例如下面指令:

fastcgi_cache_valid 200 302 10m;
fastcgi_cache_valid 404      1m;

为200和302状态码设置了10分钟的缓存,为404设置了1分钟的缓存。
如果之定义了time参数:
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”头域设置了响应缓存的时间。零值禁用缓存。如果值以@前缀开头,设置一个绝对时间从1970-01-01 00:00:00 UTC开始的秒数,缓存将在这之前一直有效。
  • 如果不包含“X-Accel-Expires”域,缓存参数可以通过“Expires”或“Cache-Control”域设置。
  • 如果头部包含“Set-Cookie”域,则响应不会被缓存。
  • 如果头部包含带“*”的“Vary”域,这种响应不会被缓存(1.7.7+),如果“Vary”值是其他的值,响应将会考虑相应的请求头域进行缓存。(1.7.7+)

处理这几种响应头域的功能可以使用fastcgi_ignore_headers指令进行禁用。

fastcgi_catch_stderr

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

设置一个字符串用于查找从FastCGI接收到的响应的错误流。如果string参数设置的值被找到,FastCGI服务器返回的值被认为是一个无效的响应。这样允许处理nginx中的应用错误,例如:

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

fastcgi_connect_timeout

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

定义同FastCGI服务器建立连接的超时时间。注意超时时间通常不能超过75秒。