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