模块 ngx_http_fastcgi_module

示例配置
指令
     fastcgi_bind
     fastcgi_buffer_size
     fastcgi_buffering
     fastcgi_buffers
     fastcgi_busy_buffers_size
     fastcgi_cache
     fastcgi_cache_background_update
     fastcgi_cache_bypass
     fastcgi_cache_key
     fastcgi_cache_lock
     fastcgi_cache_lock_age
     fastcgi_cache_lock_timeout
     fastcgi_cache_max_range_offset
     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
     fastcgi_force_ranges
     fastcgi_hide_header
     fastcgi_ignore_client_abort
     fastcgi_ignore_headers
     fastcgi_index
     fastcgi_intercept_errors
     fastcgi_keep_conn
     fastcgi_limit_rate
     fastcgi_max_temp_file_size
     fastcgi_next_upstream
     fastcgi_next_upstream_timeout
     fastcgi_next_upstream_tries
     fastcgi_no_cache
     fastcgi_param
     fastcgi_pass
     fastcgi_pass_header
     fastcgi_pass_request_body
     fastcgi_pass_request_headers
     fastcgi_read_timeout
     fastcgi_request_buffering
     fastcgi_send_lowat
     fastcgi_send_timeout
     fastcgi_socket_keepalive
     fastcgi_split_path_info
     fastcgi_store
     fastcgi_store_access
     fastcgi_temp_file_write_size
     fastcgi_temp_path
传递给 FastCGI 服务器的参数
嵌入变量

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

示例配置

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 address [transparent] | off;
默认值
上下文 httpserverlocation

此指令出现在 0.8.22 版本中。

使到 FastCGI 服务器的传出连接源自指定的本地 IP 地址(可选端口)(1.11.2)。参数值可以包含变量(1.3.12)。特殊值 off(1.3.12)取消从先前配置级别继承的 fastcgi_bind 指令的效果,允许系统自动分配本地 IP 地址和端口。

transparent 参数 (1.11.0) 允许到 FastCGI 服务器的传出连接源自非本地 IP 地址,例如,来自客户端的真实 IP 地址

fastcgi_bind $remote_addr transparent;

为了使此参数生效,通常需要使用 超级用户 权限运行 nginx 工作进程。在 Linux 上不需要这样做 (1.13.8),因为如果指定了 transparent 参数,工作进程会从主进程继承 CAP_NET_RAW 功能。还需要配置内核路由表以拦截来自 FastCGI 服务器的网络流量。

语法 fastcgi_buffer_size size;
默认值
fastcgi_buffer_size 4k|8k;
上下文 httpserverlocation

设置用于读取从 FastCGI 服务器收到的响应的第一部分的缓冲区的 size。此部分通常包含一个小的响应头。默认情况下,缓冲区大小等于一个内存页。根据平台的不同,它可能是 4K 或 8K。但是,可以将其设得更小。

语法 fastcgi_buffering on | off;
默认值
fastcgi_buffering on;
上下文 httpserverlocation

此指令出现在 1.5.6 版中。

启用或禁用来自 FastCGI 服务器的响应的缓冲。

启用缓冲后,nginx 会尽快从 FastCGI 服务器接收响应,并将其保存到由 fastcgi_buffer_sizefastcgi_buffers 指令设置的缓冲区中。如果整个响应不适合内存,则可以将一部分响应保存到磁盘上的 临时文件 中。写入临时文件由 fastcgi_max_temp_file_sizefastcgi_temp_file_write_size 指令控制。

禁用缓冲后,响应会立即在收到时同步传递给客户端。nginx 不会尝试从 FastCGI 服务器读取整个响应。nginx 一次可以从服务器接收的最大数据大小由 fastcgi_buffer_size 指令设置。

还可以通过在“X-Accel-Buffering”响应头字段中传递“yes”或“no”来启用或禁用缓冲。可以使用 fastcgi_ignore_headers 指令禁用此功能。

语法 fastcgi_buffers number size;
默认值
fastcgi_buffers 8 4k|8k;
上下文 httpserverlocation

设置用于读取来自 FastCGI 服务器的响应的缓冲区的 numbersize,针对单个连接。默认情况下,缓冲区大小等于一个内存页。根据平台的不同,它可能是 4K 或 8K。

语法 fastcgi_busy_buffers_size size;
默认值
fastcgi_busy_buffers_size 8k|16k;
上下文 httpserverlocation

当启用 FastCGI 服务器的响应缓冲时,限制在响应尚未完全读取时可以忙于向客户端发送响应的缓冲区的总大小。同时,其余缓冲区可用于读取响应,并在需要时将部分响应缓冲到临时文件中。默认情况下,大小受由 fastcgi_buffer_sizefastcgi_buffers 指令设置的两个缓冲区的大小限制。

语法 fastcgi_cache 区域 | 关闭;
默认值
fastcgi_cache off;
上下文 httpserverlocation

定义用于缓存的共享内存区域。同一个区域可以在多个地方使用。参数值可以包含变量 (1.7.9)。关闭参数禁用从上一个配置级别继承的缓存。

语法 fastcgi_cache_background_update 开启 | 关闭;
默认值
fastcgi_cache_background_update off;
上下文 httpserverlocation

此指令出现在 1.11.10 版本中。

允许启动后台子请求来更新过期的缓存项,同时向客户端返回陈旧的缓存响应。请注意,在更新陈旧的缓存响应时有必要允许使用它。

语法 fastcgi_cache_bypass 字符串 ...;
默认值
上下文 httpserverlocation

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

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

可以与 fastcgi_no_cache 指令一起使用。

语法 fastcgi_cache_key 字符串;
默认值
上下文 httpserverlocation

定义缓存的键,例如

fastcgi_cache_key localhost:9000$request_uri;

语法 fastcgi_cache_lock 开启 | 关闭;
默认值
fastcgi_cache_lock off;
上下文 httpserverlocation

此指令出现在 1.1.12 版本中。

启用后,一次只允许一个请求通过向 FastCGI 服务器传递请求来填充根据 fastcgi_cache_key 指令识别的新的缓存元素。相同缓存元素的其他请求将等待响应出现在缓存中或此元素的缓存锁被释放,最长等待时间由 fastcgi_cache_lock_timeout 指令设置。

语法 fastcgi_cache_lock_age time;
默认值
fastcgi_cache_lock_age 5s;
上下文 httpserverlocation

此指令出现在 1.7.8 版本中。

如果传递给 FastCGI 服务器用于填充新缓存元素的最后一个请求在指定的 time 内未完成,则可以将另一个请求传递给 FastCGI 服务器。

语法 fastcgi_cache_lock_timeout time;
默认值
fastcgi_cache_lock_timeout 5s;
上下文 httpserverlocation

此指令出现在 1.1.12 版本中。

fastcgi_cache_lock 设置超时。当 time 过期时,请求将传递给 FastCGI 服务器,但不会缓存响应。

在 1.7.8 之前,可以缓存响应。

语法 fastcgi_cache_max_range_offset number;
默认值
上下文 httpserverlocation

此指令出现在 1.11.6 版本中。

为字节范围请求设置字节偏移。如果范围超出了偏移,则范围请求将传递给 FastCGI 服务器,并且不会缓存响应。

语法 fastcgi_cache_methods GET | HEAD | POST ...;
默认值
fastcgi_cache_methods GET HEAD;
上下文 httpserverlocation

此指令出现在 0.7.59 版本中。

如果客户端请求方法在此指令中列出,则将缓存响应。“GET”和“HEAD”方法始终添加到列表中,尽管建议明确指定它们。另请参见 fastcgi_no_cache 指令。

语法 fastcgi_cache_min_uses number;
默认值
fastcgi_cache_min_uses 1;
上下文 httpserverlocation

设置在响应将被缓存之后的请求的 number

语法 fastcgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [min_free=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];
默认值
上下文 http

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

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,则临时文件将直接放在缓存目录中。

此外,所有活动密钥和有关数据的信息都存储在共享内存区域中,其 namesizekeys_zone 参数配置。一个兆字节的区域可以存储大约 8 千个密钥。

作为 商业订阅 的一部分,共享内存区域还存储扩展缓存 信息,因此,需要为相同数量的密钥指定更大的区域大小。例如,一个兆字节的区域可以存储大约 4 千个密钥。

inactive 参数指定的时间内未访问的缓存数据将从缓存中删除,而不管其新鲜度如何。默认情况下,inactive 设置为 10 分钟。

特殊的“缓存管理器”进程监视 max_size 参数设置的最大缓存大小,以及 min_free (1.19.1) 参数设置的缓存文件系统上的最小可用空间量。当大小超出或可用空间不足时,它会删除最近最少使用的的数据。数据删除的迭代次数由 manager_filesmanager_thresholdmanager_sleep 参数配置 (1.11.5)。在一次迭代中,最多删除 manager_files 项(默认值为 100)。一次迭代的持续时间受 manager_threshold 参数的限制(默认值为 200 毫秒)。在迭代之间,暂停时间由 manager_sleep 参数配置(默认值为 50 毫秒)。

启动后一分钟,特殊的“缓存加载器”进程被激活。它将存储在文件系统上的先前缓存数据的信息加载到缓存区域中。加载也是按迭代进行的。在一次迭代中,最多加载 loader_files 项(默认值为 100)。此外,一次迭代的持续时间受 loader_threshold 参数的限制(默认值为 200 毫秒)。在迭代之间,暂停时间由 loader_sleep 参数配置(默认值为 50 毫秒)。

此外,以下参数可作为我们 商业订阅 的一部分提供

purger=on|off
指示与 通配符键 匹配的缓存条目是否将由缓存清除程序从磁盘中删除(1.7.12)。将参数设置为 on(默认值为 off)将激活“缓存清除程序”进程,该进程将永久迭代所有缓存条目并删除与通配符键匹配的条目。
purger_files=number
设置在一次迭代期间将扫描的项目数(1.7.12)。默认情况下,purger_files 设置为 10。
purger_threshold=number
设置一次迭代的持续时间(1.7.12)。默认情况下,purger_threshold 设置为 50 毫秒。
purger_sleep=number
设置迭代之间的暂停时间(1.7.12)。默认情况下,purger_sleep 设置为 50 毫秒。

在版本 1.7.3、1.7.7 和 1.11.10 中,缓存头格式已更改。升级到较新的 nginx 版本后,以前缓存的响应将被视为无效。

语法 fastcgi_cache_purge string ...;
默认值
上下文 httpserverlocation

此指令出现在版本 1.5.7 中。

定义请求将被视为缓存清除请求的条件。如果字符串参数的至少一个值不为空且不等于“0”,则将删除具有相应 缓存键 的缓存条目。通过返回 204(无内容)响应来指示操作成功的结果。

如果清除请求的 缓存键 以星号(“*”)结尾,则所有与通配符键匹配的缓存条目都将从缓存中删除。但是,这些条目将保留在磁盘上,直到因 不活动 而被删除,或由 缓存清除程序(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 on | off;
默认值
fastcgi_cache_revalidate off;
上下文 httpserverlocation

此指令出现在版本 1.5.7 中。

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

语法 fastcgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | http_429 | off ...;
默认值
fastcgi_cache_use_stale off;
上下文 httpserverlocation

当与 FastCGI 服务器通信时发生错误时,确定在哪些情况下可以使用陈旧的缓存响应。该指令的参数与 fastcgi_next_upstream 指令的参数匹配。

error 参数还允许在无法选择 FastCGI 服务器来处理请求时使用陈旧的缓存响应。

此外,updating 参数允许在当前更新陈旧的缓存响应时使用该响应。这允许在更新缓存数据时最大程度地减少对 FastCGI 服务器的访问次数。

还可以在响应变为陈旧后指定秒数,直接在响应头中启用使用陈旧的缓存响应(1.11.10)。这比使用指令参数的优先级低。

可以使用 fastcgi_cache_lock 指令,最大程度地减少填充新缓存元素时对 FastCGI 服务器的访问次数。

语法 fastcgi_cache_valid [code ...] time;
默认值
上下文 httpserverlocation

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

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;

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

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

语法 fastcgi_catch_stderr string;
默认值
上下文 httpserverlocation

设置一个字符串,用于在从 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 time;
默认值
fastcgi_connect_timeout 60s;
上下文 httpserverlocation

定义与 FastCGI 服务器建立连接的超时时间。需要注意的是,此超时时间通常不能超过 75 秒。

语法 fastcgi_force_ranges on | off;
默认值
fastcgi_force_ranges off;
上下文 httpserverlocation

此指令出现在 1.7.7 版本中。

启用对 FastCGI 服务器的缓存和未缓存响应的字节范围支持,而不管这些响应中的“Accept-Ranges”字段如何。

语法 fastcgi_hide_header field;
默认值
上下文 httpserverlocation

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

语法 fastcgi_ignore_client_abort on | off;
默认值
fastcgi_ignore_client_abort off;
上下文 httpserverlocation

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

语法 fastcgi_ignore_headers field ...;
默认值
上下文 httpserverlocation

禁用对 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)和“Vary”(1.7.7)。

如果没有禁用,则处理这些头部字段会产生以下效果

语法 fastcgi_index name
默认值
上下文 httpserverlocation

设置一个文件名,它将附加在以斜杠结尾的 URI 后面,在 $fastcgi_script_name 变量的值中。例如,使用以下设置

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

以及“/page.php”请求,SCRIPT_FILENAME 参数将等于“/home/www/scripts/php/page.php”,而使用“/”请求,它将等于“/home/www/scripts/php/index.php”。

语法 fastcgi_intercept_errors on | off
默认值
fastcgi_intercept_errors off;
上下文 httpserverlocation

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

语法 fastcgi_keep_conn on | off
默认值
fastcgi_keep_conn off;
上下文 httpserverlocation

此指令出现在 1.1.4 版本中。

默认情况下,FastCGI 服务器会在发送响应后立即关闭连接。但是,当此指令设置为值 on 时,nginx 将指示 FastCGI 服务器保持连接处于打开状态。这尤其对于 FastCGI 服务器的保持活动连接才能正常工作是必需的。

语法 fastcgi_limit_rate rate
默认值
fastcgi_limit_rate 0;
上下文 httpserverlocation

此指令出现在 1.7.7 版本中。

限制从 FastCGI 服务器读取响应的速度。rate 以每秒字节数指定。零值禁用速率限制。限制是针对每个请求设置的,因此,如果 nginx 同时向 FastCFI 服务器打开两个连接,则总体速率将是指定限制的两倍。仅当启用 FastCGI 服务器响应的缓冲时,此限制才有效。

语法 fastcgi_max_temp_file_size size
默认值
fastcgi_max_temp_file_size 1024m;
上下文 httpserverlocation

当启用 FastCGI 服务器响应的缓冲时,并且整个响应不适合由fastcgi_buffer_sizefastcgi_buffers指令设置的缓冲区,则可以将响应的一部分保存到临时文件中。此指令设置临时文件的最大size。一次写入临时文件的数据大小由fastcgi_temp_file_write_size指令设置。

零值禁用对临时文件的响应缓冲。

此限制不适用于将被 缓存存储 在磁盘上的响应。

语法 fastcgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | http_429 | non_idempotent | off ...;
默认值
fastcgi_next_upstream error timeout;
上下文 httpserverlocation

指定在哪些情况下应将请求传递到下一台服务器

error
在建立与服务器的连接、向其传递请求或读取响应头时发生错误;
timeout
在建立与服务器的连接、向其传递请求或读取响应头时发生超时;
invalid_header
服务器返回空或无效响应;
http_500
服务器返回代码为 500 的响应;
http_503
服务器返回代码为 503 的响应;
http_403
服务器返回代码为 403 的响应;
http_404
服务器返回代码为 404 的响应;
http_429
服务器返回代码为 429 的响应 (1.11.13);
non_idempotent
通常,如果已向上一游服务器发送请求,则不会将具有 非幂等 方法 (POSTLOCKPATCH) 的请求传递到下一台服务器 (1.9.13);启用此选项明确允许重试此类请求;
off
禁用将请求传递到下一台服务器。

应记住,只有在尚未向客户端发送任何内容时才有可能将请求传递到下一台服务器。也就是说,如果在传输响应过程中发生错误或超时,则无法修复此问题。

该指令还定义了哪些情况被视为与服务器通信的 失败尝试。即使未在指令中指定,errortimeoutinvalid_header 的情况始终被视为失败尝试。只有在指令中指定了 http_500http_503http_429 的情况才被视为失败尝试。http_403http_404 的情况永远不被视为失败尝试。

将请求传递到下一台服务器可以通过 尝试次数时间 进行限制。

语法 fastcgi_next_upstream_timeout 时间;
默认值
fastcgi_next_upstream_timeout 0;
上下文 httpserverlocation

此指令出现在 1.7.5 版本中。

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

语法 fastcgi_next_upstream_tries 数字;
默认值
fastcgi_next_upstream_tries 0;
上下文 httpserverlocation

此指令出现在 1.7.5 版本中。

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

语法 fastcgi_no_cache 字符串 ...;
默认值
上下文 httpserverlocation

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

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

可与fastcgi_cache_bypass指令一起使用。

语法 fastcgi_param 参数 [if_not_empty];
默认值
上下文 httpserverlocation

设置应传递给 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配置参数构建的,则还应传递值为“200”的REDIRECT_STATUS参数

fastcgi_param REDIRECT_STATUS 200;

如果使用if_not_empty(1.1.11)指定指令,则仅当其值不为空时,才会将此类参数传递给服务器

fastcgi_param HTTPS           $https if_not_empty;

语法 fastcgi_pass 地址;
默认值
上下文 locationif in location

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

fastcgi_pass localhost:9000;

或作为 UNIX 域套接字路径

fastcgi_pass unix:/tmp/fastcgi.socket;

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

参数值可以包含变量。在这种情况下,如果地址指定为域名,则在所述服务器组中搜索该名称,如果未找到,则使用解析器确定该名称。

语法 fastcgi_pass_header 字段;
默认值
上下文 httpserverlocation

允许将否则禁用的头字段从 FastCGI 服务器传递到客户端。

语法 fastcgi_pass_request_body on | off;
默认值
fastcgi_pass_request_body on;
上下文 httpserverlocation

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

语法 fastcgi_pass_request_headers on | off;
默认值
fastcgi_pass_request_headers on;
上下文 httpserverlocation

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

语法 fastcgi_read_timeout time;
默认值
fastcgi_read_timeout 60s;
上下文 httpserverlocation

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

语法 fastcgi_request_buffering on | off;
默认值
fastcgi_request_buffering on;
上下文 httpserverlocation

此指令出现在 1.7.11 版中。

启用或禁用客户端请求正文的缓冲。

启用缓冲后,在向 FastCGI 服务器发送请求之前,将从客户端读取整个请求正文。

禁用缓冲后,请求正文将在收到后立即发送到 FastCGI 服务器。在这种情况下,如果 nginx 已开始发送请求正文,则无法将请求传递给下一个服务器

语法 fastcgi_send_lowat size;
默认值
fastcgi_send_lowat 0;
上下文 httpserverlocation

如果将指令设置为非零值,nginx 将尝试通过使用 kqueue 方法的 NOTE_LOWAT 标志或 SO_SNDLOWAT 套接字选项(使用指定的 size)来最小化到 FastCGI 服务器的传出连接上的发送操作次数。

此指令在 Linux、Solaris 和 Windows 上被忽略。

语法 fastcgi_send_timeout time;
默认值
fastcgi_send_timeout 60s;
上下文 httpserverlocation

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

语法 fastcgi_socket_keepalive on | off;
默认值
fastcgi_socket_keepalive off;
上下文 httpserverlocation

此指令出现在 1.15.6 版中。

为到 FastCGI 服务器的传出连接配置“TCP 保活”行为。默认情况下,操作系统的设置对套接字有效。如果将指令设置为值“on”,则为套接字打开 SO_KEEPALIVE 套接字选项。

语法 fastcgi_split_path_info regex;
默认值
上下文 location

定义一个正则表达式,用于捕获 $fastcgi_path_info 变量的值。正则表达式应有两个捕获:第一个成为 $fastcgi_script_name 变量的值,第二个成为 $fastcgi_path_info 变量的值。例如,使用以下设置

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

对于“/show.php/article/0001”请求,SCRIPT_FILENAME 参数将等于“/path/to/php/show.php”,而 PATH_INFO 参数将等于“/article/0001”。

语法 fastcgi_store on | off | string;
默认值
fastcgi_store off;
上下文 httpserverlocation

启用将文件保存到磁盘。on 参数使用与指令 aliasroot 相对应的路径保存文件。off 参数禁用文件保存。此外,可以使用包含变量的 string 显式设置文件名

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 users:permissions ...;
默认值
fastcgi_store_access user:rw;
上下文 httpserverlocation

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

fastcgi_store_access user:rw group:rw all:r;

如果指定了任何 groupall 访问权限,则可以省略 user 权限

fastcgi_store_access group:rw all:r;

语法 fastcgi_temp_file_write_size size;
默认值
fastcgi_temp_file_write_size 8k|16k;
上下文 httpserverlocation

限制每次写入临时文件的数据 size,当启用将来自 FastCGI 服务器的响应缓冲到临时文件时。默认情况下,sizefastcgi_buffer_sizefastcgi_buffers 指令设置的两个缓冲区限制。临时文件的最大大小由 fastcgi_max_temp_file_size 指令设置。

语法 fastcgi_temp_path path [level1 [level2 [level3]]];
默认值
fastcgi_temp_path fastcgi_temp;
上下文 httpserverlocation

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

fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2;

临时文件可能如下所示

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

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

传递给 FastCGI 服务器的参数

HTTP 请求头字段作为参数传递给 FastCGI 服务器。在作为 FastCGI 服务器运行的应用程序和脚本中,这些参数通常作为环境变量提供。例如,“User-Agent”头字段作为 HTTP_USER_AGENT 参数传递。除了 HTTP 请求头字段外,还可以使用 fastcgi_param 指令传递任意参数。

嵌入式变量

ngx_http_fastcgi_module 模块支持嵌入式变量,可以使用 fastcgi_param 指令使用该变量设置参数

$fastcgi_script_name
请求 URI,或者如果 URI 以斜杠结尾,则为请求 URI,其中附加了 fastcgi_index 指令配置的索引文件名。此变量可用于设置确定 PHP 中脚本名称的 SCRIPT_FILENAMEPATH_TRANSLATED 参数。例如,对于具有以下指令的“/info/”请求
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name;
SCRIPT_FILENAME 参数将等于“/home/www/scripts/php/info/index.php”。

使用 fastcgi_split_path_info 指令时,$fastcgi_script_name 变量等于指令设置的第一个捕获的值。

$fastcgi_path_info
fastcgi_split_path_info 指令设置的第二个捕获的值。此变量可用于设置 PATH_INFO 参数。