FastCGI#
该模块允许将请求传递给 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#
使与 FastCGI 服务器的出站连接从指定的本地 IP 地址（可选端口）发起。参数值可以包含变量。特殊值 off 取消从先前配置级别继承的 fastcgi_bind 指令的效果，这允许系统自动分配本地 IP 地址和端口。
transparent 参数允许出站连接从非本地 IP 地址发起，例如，从客户端的真实 IP 地址：
fastcgi_bind $remote_addr transparent;
为了使该参数生效，
Angie 工作进程通常需要以 超级用户 权限运行。
在 Linux 上，这不是必需的：
如果指定了 transparent 参数，
工作进程将继承主进程的 CAP_NET_RAW 能力。
重要
还应该配置内核路由表以拦截来自 FastCGI 服务器的网络流量。
fastcgi_buffer_size#
设置用于读取从 FastCGI 服务器接收的响应的第一部分的缓冲区大小。此部分通常包含一个小的响应头。默认情况下，缓冲区大小等于一个内存页。这是 4K 或 8K，具体取决于平台。它可以变得更小。
fastcgi_buffering#
启用或禁用从 FastCGI 服务器的响应的缓冲。
|
Angie 尽可能快地从 FastCGI 服务器接收响应，并将其保存到由 fastcgi_buffer_size 和 fastcgi_buffers 指令设置的缓冲区中。如果整个响应无法容纳在内存中，其一部分可以保存到磁盘上的 临时文件 中。写入临时文件由 fastcgi_max_temp_file_size 和 fastcgi_temp_file_write_size 指令控制。 |
|
响应在接收到时立即同步传递给客户端。Angie 不会尝试从 FastCGI 服务器读取整个响应。Angie 一次可以从服务器接收的数据的最大大小由 fastcgi_buffer_size 指令设置。 |
可以通过在 "X-Accel-Buffering" 响应头字段中传递 "yes" 或 "no" 来启用或禁用缓冲。此功能可以使用 fastcgi_ignore_headers 指令禁用。
fastcgi_buffers#
设置用于读取从 FastCGI 服务器接收的响应的缓冲区的数量和大小，对于单个连接。
默认情况下，缓冲区大小等于一个内存页。这是 4K 或 8K，具体取决于平台。
fastcgi_busy_buffers_size#
|
|
默认值 |
|
http, server, location |
当启用了从 FastCGI 服务器的响应的 buffering 时，限制可以繁忙地向客户端发送响应的缓冲区总大小，而响应尚未完全读取。同时，其余的缓冲区可以用于读取响应，并在需要时将响应的一部分缓冲到临时文件中。默认情况下，大小受 fastcgi_buffer_size 和 fastcgi_buffers 指令设置的两个缓冲区的大小限制。
fastcgi_cache#
定义用于缓存的共享内存区域。同一区域可以在多个地方使用。参数值可以包含变量。off 参数禁用从先前配置级别继承的缓存。
fastcgi_cache_background_update#
|
|
默认值 |
|
http, server, location |
允许启动后台子请求以更新过期的缓存项，同时将陈旧的缓存响应返回给客户端。请注意，有必要 允许 在更新时使用陈旧的缓存响应。
fastcgi_cache_bypass#
定义在什么条件下响应将不从缓存中获取。如果字符串参数的至少一个值不为空且不等于 "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 localhost:9000$request_uri;
fastcgi_cache_lock#
启用时，只允许一次请求通过向 FastCGI 服务器传递请求来填充根据 fastcgi_cache_key 指令标识的新缓存元素。其他相同缓存元素的请求将等待响应出现在缓存中或该元素的缓存锁释放，最长时间由 fastcgi_cache_lock_timeout 指令设置。
fastcgi_cache_lock_age#
如果发送到 FastCGI 服务器以填充新缓存条目的最后一个请求在指定时间内未完成，则可以向 FastCGI 服务器发送另一个请求。
fastcgi_cache_lock_timeout#
为 fastcgi_cache_lock 设置超时时间。当时间到期时，请求将被传递到 FastCGI 服务器，但是，响应将不会被缓存。
fastcgi_cache_max_range_offset#
为字节范围请求设置偏移量（以字节为单位）。如果范围超出偏移量，范围请求将被传递到 FastCGI 服务器，响应将不会被缓存。
fastcgi_cache_methods#
|
|
默认值 |
|
http, server, location |
如果客户端请求方法在此指令中列出，则响应将被缓存。"GET" 和 "HEAD" 方法总是被添加到列表中，虽然建议显式指定它们。另请参阅 fastcgi_no_cache 指令。
fastcgi_cache_min_uses#
设置请求次数，在此之后响应将被缓存。
fastcgi_cache_path#
|
|
默认 |
— |
http, server, location |
设置缓存的路径和其他参数。缓存数据存储在文件中。缓存中的键和文件名均是通过对代理的 URL 应用 MD5 函数得到的结果。
levels 参数定义了缓存的层次结构：从1到3，每个级别接受值 1 或 2。例如，在以下配置中
fastcgi_cache_path /data/angie/cache levels=1:2 keys_zone=one:10m;
缓存中文件名将如下所示：
/data/angie/cache/c/29/b7f54b2df7773722d382f4809d65029c
缓存的响应首先被写入临时文件，然后将其重命名。临时文件和缓存可以放在不同的文件系统上。但是，要注意在这种情况下，文件是在两个文件系统之间复制，而不是进行廉价的重命名操作。因此，建议在任何给定位置，缓存和临时文件目录都放在同一个文件系统上。
临时文件的目录是根据 use_temp_path 参数设置的。
|
如果省略此参数或将其设置为“on”，则会使用由 fastcgi_temp_path 指令为给定 location 设置的目录。 |
|
临时文件将直接放入缓存目录中。 |
此外，所有活动键和数据信息均存储在共享内存区域中，该区域的名称和大小由 keys_zone 参数配置。一个兆字节的区域可以存储约 8 千个键。
在 inactive 参数指定的时间内未访问的缓存数据将被移除，无论其新鲜度如何。
默认情况下，inactive 设置为 10 分钟。
一个特殊的 缓存管理器 进程监控缓存的最大大小和文件系统上的最小可用空间。当大小超过限制或空间不足时，它会移除最近最少使用的数据。数据是通过迭代方式移除的。
|
最大缓存大小 |
|
文件系统中缓存的最小可用空间 |
|
限制一次迭代中要删除的项目数量 默认情况下， |
|
限制一次迭代的持续时间 默认情况下， |
|
配置交互之间的暂停时间 默认情况下， |
Angie 启动一分钟后，特殊的 缓存加载器 进程被激活。它将文件系统上存储的先前缓存数据的信息加载到缓存区中。加载也是通过迭代方式进行的。
|
限制一次迭代中要加载的项目数量 默认情况下， |
|
限制一次迭代的持续时间 默认情况下， |
|
配置交互之间的暂停时间 默认情况下， |
fastcgi_cache_revalidate#
启用使用 "If-Modified-Since" 和 "If-None-Match" 头字段的条件请求来重新验证过期的缓存项。
fastcgi_cache_use_stale#
|
|
默认值 |
|
http, server, location |
确定在与 FastCGI 服务器通信时出现错误的情况下，何时可以使用陈旧的缓存响应。此指令的参数与 fastcgi_next_upstream 指令的参数匹配。
|
允许在无法选择 FastCGI 服务器来处理请求时使用陈旧的缓存响应。 |
|
额外参数，允许在缓存数据正在更新时使用陈旧的缓存响应。这可以在更新缓存数据时最小化对 FastCGI 服务器的访问次数。 |
使用陈旧的缓存响应也可以直接在响应头中启用，指定响应变陈旧后的秒数。
stale-while-revalidate 扩展了“Cache-Control”头字段，允许在响应正在更新时使用陈旧的缓存响应。
stale-if-error 扩展了“Cache-Control”头字段，允许在出现错误时使用陈旧的缓存响应。
备注
此优先级低于使用指令参数。
为了在填充新缓存元素时最小化对 FastCGI 服务器的访问次数，可以使用 fastcgi_cache_lock 指令。
fastcgi_cache_valid#
设置不同响应代码的缓存时间。例如，以下指令
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" 头字段设置响应的缓存时间（以秒为单位）。零值禁用响应的缓存。如果值以 @ 前缀开头，则设置从纪元时间开始的绝对时间（以秒为单位），直到响应可能被缓存。
如果头部不包括 "X-Accel-Expires" 字段，则缓存参数可以在 "Expires" 或 "Cache-Control" 头字段中设置。
如果头部包括 "Set-Cookie" 字段，则此类响应将不被缓存。
如果头部包括特殊值 “*” 的 "Vary" 字段，则此类响应将不被缓存。如果头部包括 "Vary" 字段的其他值，则此类响应将根据相应的请求头字段进行缓存。
可以使用 fastcgi_ignore_headers 指令禁用对一个或多个这些响应头字段的处理。
fastcgi_catch_stderr#
设置在从 FastCGI 服务器接收到的响应的错误流中搜索的字符串。如果找到该字符串，则认为 FastCGI 服务器返回了 无效响应。这允许在 Angie 中处理应用程序错误，例如：
location /php/ {
fastcgi_pass backend:9000;
...
fastcgi_catch_stderr "PHP Fatal error";
fastcgi_next_upstream error timeout invalid_header;
}
fastcgi_connect_timeout#
定义与 FastCGI 服务器建立连接的超时时间。需要注意的是，此超时时间通常不能超过 75 秒。
fastcgi_connection_drop#
|
|
默认 |
|
http, server, location |
启用在代理服务器从组中移除或被 reresolve 进程或 API命令 DELETE 标记为永久不可用后终止与其的所有连接。
当为客户端或代理服务器处理下一次读写事件时，连接将终止。
设置 time 启用连接终止 超时；设置 on 时，连接会立即断开。
fastcgi_force_ranges#
无论这些响应中的 "Accept-Ranges" 字段如何，均启用来自 FastCGI 服务器的缓存和非缓存响应的字节范围支持。
fastcgi_hide_header#
默认情况下，Angie 不会将 FastCGI 服务器响应中的 “Status” 和 “X-Accel-...” 头字段传递给客户端。fastcgi_hide_header 指令设置不传递的其他字段。如果需要允许字段传递，可以使用 fastcgi_pass_header 指令。
fastcgi_ignore_client_abort#
|
|
默认值 |
|
http, server, location |
决定当客户端在未等待响应时关闭连接时，是否应关闭与 FastCGI 服务器的连接。
fastcgi_ignore_headers#
禁用来自 FastCGI 服务器的某些响应头字段的处理。以下字段可以被忽略：“X-Accel-Redirect”、“X-Accel-Expires”、“X-Accel-Limit-Rate”、“X-Accel-Buffering”、“X-Accel-Charset”、“Expires”、“Cache-Control”、“Set-Cookie”和 “Vary”。
如果未禁用，这些头字段的处理将产生以下效果：
fastcgi_index#
设置将在 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#
决定是否应该将代码大于或等于 300 的 FastCGI 服务器响应传递给客户端，或者拦截并重定向到 Angie 以使用 error_page 指令进行处理。
fastcgi_keep_conn#
默认情况下，FastCGI 服务器会在发送响应后立即关闭连接。然而，当该指令设置为 on 时，Angie 将指示 FastCGI 服务器保持连接打开。这对于使 FastCGI 服务器上的 保持活动连接 功能正常工作是必要的。
fastcgi_limit_rate#
限制从 FastCGI 服务器读取响应的速度。rate 以每秒字节数指定，并可以包含变量。
|
禁用速率限制 |
备注
限制是针对每个请求设置的，因此如果 Angie 同时打开两个到 FastCGI 服务器的连接，整体速率将是指定限制的两倍。此限制仅在启用 FastCGI 服务器响应的 缓冲 时生效。
fastcgi_max_temp_file_size#
|
|
默认值 |
|
http, server, location |
当启用了来自 FastCGI 服务器的响应的 缓冲，并且整个响应不适合由 fastcgi_buffer_size 和 fastcgi_buffers 指令设置的缓冲区时，可以将部分响应保存到临时文件。此指令设置临时文件的最大大小。一次写入临时文件的数据大小由 fastcgi_temp_file_write_size 指令设置。
|
禁用对临时文件的响应缓冲 |
fastcgi_next_upstream#
|
|
默认值 |
|
http, server, location |
指定在何种情况下请求应传递到下一个服务器：
|
在与服务器建立连接、传递请求或读取响应头时发生错误； |
|
在与服务器建立连接、传递请求或读取响应头时发生超时； |
|
服务器返回空的或无效的响应； |
|
服务器返回代码为 500 的响应； |
|
服务器返回代码为 503 的响应； |
|
服务器返回代码为 403 的响应； |
|
服务器返回代码为 404 的响应； |
|
服务器返回代码为 429 的响应； |
|
通常，具有 非幂等 方法 ( |
|
禁止将请求传递到下一个服务器。 |
备注
应注意，将请求传递到下一个服务器仅在尚未向客户端发送任何内容时才可能。也就是说，如果在响应传输的中间发生错误或超时，修复这是不可能的。
该指令还定义了与服务器通信时被认为是 不成功尝试 的情况。
|
|
总是被认为是不成功的尝试，即使它们未在指令中指定 |
|
|
仅在指令中指定时才被认为是不成功的尝试 |
|
|
从不被认为是不成功的尝试 |
fastcgi_next_upstream_timeout#
|
|
默认值 |
|
http, server, location |
限制请求可以传递到 下一个服务器 的时间。
|
关闭此限制 |
fastcgi_next_upstream_tries#
|
|
默认值 |
|
http, server, location |
限制将请求传递到 下一个服务器 的可能尝试次数。
|
关闭此限制 |
fastcgi_no_cache#
定义在何种条件下响应将不会被保存到缓存中。如果字符串参数的至少一个值不为空且不等于 “0”，则响应不会被保存：
fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
fastcgi_no_cache $http_pragma $http_authorization;
可以与 fastcgi_cache_bypass 指令一起使用。
fastcgi_param#
设置应传递给 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，那么这样的参数将仅在其值不为空时传递给服务器：
fastcgi_param HTTPS $https if_not_empty;
fastcgi_pass#
设置 FastCGI 服务器的地址。地址可以指定为域名或 IP 地址，以及端口：
fastcgi_pass localhost:9000;
或者作为 UNIX 域套接字路径：
fastcgi_pass unix:/tmp/fastcgi.socket;
如果域名解析为多个地址，则所有地址将以轮询方式使用。此外，地址可以指定为 服务器组。如果使用了一个组，则不能为其指定端口；相反，应为组中的每个服务器单独指定端口。
参数值可以包含变量。在这种情况下，如果地址指定为域名，则在描述的 服务器组 中查找该名称，如果未找到，则使用 解析器 确定。
fastcgi_pass_header#
允许从 FastCGI 服务器向客户端传递 otherwise disabled 头字段。
fastcgi_pass_request_body#
指示是否将原始请求体传递给 FastCGI 服务器。另请参见 fastcgi_pass_request_headers 指令。
fastcgi_pass_request_headers#
指示是否将原始请求的头字段传递给 FastCGI 服务器。另请参见 fastcgi_pass_request_body 指令。
fastcgi_read_timeout#
定义从 FastCGI 服务器读取响应的超时时间。超时仅在两次连续读取操作之间设置，而不是用于整个响应的传输。如果 FastCGI 服务器在此时间内未传输任何内容，则连接将关闭。
fastcgi_request_buffering#
启用或禁用客户端请求体的缓冲。
fastcgi_send_lowat#
如果将指令设置为非零值，Nginx 将尝试通过使用 kqueue 方法的 NOTE_LOWAT 标志或 SO_SNDLOWAT 套接字选项，以指定的大小，最小化对 FastCGI 服务器的传出连接上的发送操作次数。
备注
在 Linux、Solaris 和 Windows 上忽略此指令。
fastcgi_send_timeout#
设置将请求传输到 FastCGI 服务器的超时时间。超时仅在两次连续写操作之间设置，而不是用于整个请求的传输。如果 FastCGI 服务器在此时间内未接收到任何内容，则连接将关闭。
fastcgi_socket_keepalive#
配置与 FastCGI 服务器的传出连接的 "TCP 保持活动" 行为。
|
默认情况下，操作系统的设置对套接字生效。 |
|
为套接字启用 SO_KEEPALIVE 套接字选项。 |
fastcgi_split_path_info#
定义一个正则表达式，用于捕获 $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#
启用将文件保存到磁盘。
此外，文件名可以使用带有变量的字符串显式设置：
fastcgi_store /data/www$original_uri;
文件的修改时间根据接收到的 "Last-Modified" 响应头字段设置。响应首先写入临时文件，然后文件被重命名。临时文件和持久存储可以放在不同的文件系统上。然而，请注意，在这种情况下，文件是在两个文件系统之间复制的，而不是廉价的重命名操作。因此，建议为任何给定的 location，保存的文件和由 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#
|
|
默认值 |
|
http, server, location |
设置新创建文件和目录的访问权限，例如：
fastcgi_store_access user:rw group:rw all:r;
如果指定了任何组或所有访问权限，则用户权限可以省略：
fastcgi_store_access group:rw all:r;
fastcgi_temp_file_write_size#
|
|
默认值 |
|
http, server, location |
限制在启用从 FastCGI 服务器缓冲响应到临时文件时，一次写入临时文件的数据大小。默认情况下，大小由 fastcgi_buffer_size 和 fastcgi_buffers 指令设置的两个缓冲区限制。临时文件的最大大小由 fastcgi_max_temp_file_size 指令设置。
fastcgi_temp_path#
|
|
默认值 |
|
http, server, location |
定义存储从 FastCGI 服务器接收到的数据的临时文件的目录。可以在指定目录下使用最多三层子目录层次结构。例如，在以下配置中
fastcgi_temp_path /spool/angie/fastcgi_temp 1 2;
临时文件可能如下所示：
/spool/angie/fastcgi_temp/7/45/00000123457
另请参见 fastcgi_cache_path 指令的 use_temp_path 参数。
传递给 FastCGI 服务器的参数#
HTTP 请求头字段作为参数传递给 FastCGI 服务器。在作为 FastCGI 服务器运行的应用程序和脚本中，这些参数通常作为环境变量提供。例如，"User-Agent" 请求头字段作为 HTTP_USER_AGENT 参数传递。除了 HTTP 请求头字段，还可以使用 fastcgi_param 指令传递任意参数。
内置变量#
http_fastcgi 模块支持内置变量，可以使用 fastcgi_param 指令来设置参数：
$fastcgi_script_name#
请求 URI 或者，如果 URI 以斜杠结尾，则为附加了由 fastcgi_index 指令配置的索引文件名的请求 URI。此变量可以用于设置 PHP 中确定脚本名称的 SCRIPT_FILENAME 和 PATH_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 参数。