模块 ngx_http_scgi_module

ngx_http_scgi_module 模块允许将请求传递到 SCGI 服务器。

location / {
    include   scgi_params;
    scgi_pass localhost:9000;
}

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

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

scgi_bind $remote_addr transparent;

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

scgi_buffer_size 4k|8k;

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

scgi_buffering on;

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

启用缓冲时，Nginx 会尽快从 SCGI 服务器接收响应，并将其保存到由 scgi_buffer_size 和 scgi_buffers 指令设置的缓冲区中。如果整个响应不适合内存，则其一部分可以保存到磁盘上的 临时文件 中。写入临时文件由 scgi_max_temp_file_size 和 scgi_temp_file_write_size 指令控制。

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

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

scgi_buffers 8 4k|8k;

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

scgi_busy_buffers_size 8k|16k;

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

scgi_cache off;

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

scgi_cache_background_update off;

允许启动一个后台子请求来更新过期的缓存项，同时将陈旧的缓存响应返回给客户端。请注意，在更新缓存响应时，需要 允许 使用陈旧的缓存响应。

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

scgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
scgi_cache_bypass $http_pragma    $http_authorization;

可与 scgi_no_cache 指令一起使用。

定义缓存的键，例如

scgi_cache_key localhost:9000$request_uri;

scgi_cache_lock off;

启用后，一次仅允许一个请求填充根据 scgi_cache_key 指令通过将请求传递到 SCGI 服务器来标识的新缓存元素。同一缓存元素的其他请求将等待响应出现在缓存中或等待此元素的缓存锁释放，直到 scgi_cache_lock_timeout 指令设置的时间为止。

scgi_cache_lock_age 5s;

如果填充新缓存元素的最后一个传递到 SCGI 服务器的请求在指定 时间 内未完成，则可以将另一个请求传递到 SCGI 服务器。

scgi_cache_lock_timeout 5s;

设置 scgi_cache_lock 的超时。当 时间 到期时，请求将传递到 SCGI 服务器，但是响应将不会被缓存。

在 1.7.8 之前，响应可能会被缓存。

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

scgi_cache_methods GET HEAD;

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

scgi_cache_min_uses 1;

设置响应将被缓存的请求 数量。

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

scgi_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 值，则将使用为给定位置由 scgi_temp_path 指令设置的目录。如果该值设置为 off，则临时文件将直接放在缓存目录中。

此外，所有活动键和有关数据的信息都存储在共享内存区域中，其 名称 和 大小 由 keys_zone 参数配置。一个兆字节的区域可以存储大约 8000 个键。

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

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

特殊的“缓存管理器”进程监视由 max_size 参数设置的最大缓存大小以及由 min_free (1.19.1) 参数设置的文件系统上的最小可用空间量。当大小超过或没有足够可用空间时，它会删除最近最少使用的数据。数据以 manager_files、manager_threshold 和 manager_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 版本后，先前缓存的响应将被视为无效。

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

如果清除请求的 缓存键以星号（“*”）结尾，则将删除与通配符键匹配的所有缓存条目。但是，这些条目将保留在磁盘上，直到它们因 空闲而被删除，或由 缓存清除器（1.7.12）处理，或客户端尝试访问它们。

示例配置

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

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

server {
    ...
    location / {
        scgi_pass        backend;
        scgi_cache       cache_zone;
        scgi_cache_key   $uri;
        scgi_cache_purge $purge_method;
    }
}

此功能作为我们 商业订阅的一部分提供。

scgi_cache_revalidate off;

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

scgi_cache_use_stale off;

确定在与 SCGI 服务器通信时发生错误的情况下何时可以使用陈旧的缓存响应。指令的参数与 scgi_next_upstream指令的参数匹配。

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

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

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

• “Cache-Control”头字段的“stale-while-revalidate”扩展允许在当前正在更新缓存响应时使用陈旧的缓存响应。
• “Cache-Control”头字段的“stale-if-error”扩展允许在发生错误时使用陈旧的缓存响应。

为了在填充新的缓存元素时最大程度地减少对 SCGI 服务器的访问次数，可以使用 scgi_cache_lock指令。

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

scgi_cache_valid 200 302 10m;
scgi_cache_valid 404      1m;

为代码为 200 和 302 的响应设置 10 分钟的缓存时间，为代码为 404 的响应设置 1 分钟的缓存时间。

如果只指定缓存 time

scgi_cache_valid 5m;

则仅缓存 200、301 和 302 响应。

此外，可以指定any参数以缓存任何响应。

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

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

• “X-Accel-Expires”头字段以秒为单位设置响应的缓存时间。零值禁用响应的缓存。如果值以@前缀开头，则设置自纪元以来的绝对时间（以秒为单位），在此时间之前可以缓存响应。
• 如果头不包含“X-Accel-Expires”字段，则可以在“Expires”或“Cache-Control”头字段中设置缓存参数。
• 如果头包含“Set-Cookie”字段，则不会缓存此类响应。
• 如果头包含具有特殊值“*”的“Vary”字段，则不会缓存此类响应（1.7.7）。如果头包含具有其他值的“Vary”字段，则将缓存此类响应，同时考虑相应的请求头字段（1.7.7）。

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

scgi_connect_timeout 60s;

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

scgi_force_ranges off;

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

默认情况下，nginx 不会将“Status”和“X-Accel-...”头字段从 SCGI 服务器的响应传递到客户端。scgi_hide_header指令设置不会传递的其他字段。相反，如果需要允许字段的传递，则可以使用 scgi_pass_header指令。

scgi_ignore_client_abort off;

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

禁用处理来自 SCGI 服务器的某些响应头字段。可以忽略以下字段：“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）。

如果未禁用，则处理这些头字段具有以下效果

• “X-Accel-Expires”、“Expires”、“Cache-Control”、“Set-Cookie”和“Vary”设置响应 缓存的参数；
• “X-Accel-Redirect”执行到指定 URI 的 内部重定向；
• “X-Accel-Limit-Rate”设置将响应传输到客户端的 速率限制；
• “X-Accel-Buffering”启用或禁用响应的 缓冲；
• “X-Accel-Charset”设置响应所需的 字符集。

scgi_intercept_errors off;

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

scgi_limit_rate 0;

限制从 SCGI 服务器读取响应的速度。rate以每秒字节数指定。零值禁用速率限制。限制针对每个请求设置，因此如果 nginx 同时打开两个到 SCGI 服务器的连接，则总速率将是指定限制的两倍。仅当启用了来自 SCGI 服务器的响应的 缓冲时，限制才有效。参数值可以包含变量（1.27.0）。

scgi_max_temp_file_size 1024m;

当启用来自 SCGI 服务器的响应的 缓冲，并且整个响应不适合由 scgi_buffer_size和 scgi_buffers指令设置的缓冲区时，响应的一部分可以保存到临时文件。此指令设置临时文件的最大 size。一次写入临时文件的数据大小由 scgi_temp_file_write_size指令设置。

零值禁用将响应缓冲到临时文件。

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

scgi_next_upstream error timeout;

指定在什么情况下应将请求传递到下一个服务器

error

在与服务器建立连接、将请求传递给服务器或读取响应头时发生错误；

timeout

在与服务器建立连接、将请求传递给服务器或读取响应头时发生超时；

invalid_header

服务器返回空或无效的响应；

http_500

服务器返回代码为 500 的响应；

http_503

服务器返回代码为 503 的响应；

http_403

服务器返回代码为 403 的响应；

http_404

服务器返回代码为 404 的响应；

http_429

服务器返回代码为 429 的响应（1.11.13）；

non_idempotent

通常，如果已将请求发送到上游服务器，则不会将使用 非幂等方法（POST、LOCK、PATCH）的请求传递到下一个服务器（1.9.13）；明确启用此选项允许重试此类请求；

off

禁用将请求传递到下一个服务器。

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

该指令还定义了什么是与服务器通信的 不成功尝试。error、timeout和invalid_header的情况始终被视为不成功尝试，即使它们未在指令中指定。http_500、http_503和http_429的情况仅在指令中指定时才被视为不成功尝试。http_403和http_404的情况永远不被视为不成功尝试。

将请求传递到下一个服务器可以受 尝试次数和 时间限制。

scgi_next_upstream_timeout 0;

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

scgi_next_upstream_tries 0;

限制将请求传递给下一个服务器的尝试次数。值为0表示关闭此限制。

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

scgi_no_cache $cookie_nocache $arg_nocache$arg_comment;
scgi_no_cache $http_pragma    $http_authorization;

可以与scgi_cache_bypass指令一起使用。

设置应传递给SCGI服务器的参数。值可以包含文本、变量及其组合。如果当前级别没有定义scgi_param指令，则这些指令将从上一级配置继承。

标准CGI环境变量应作为SCGI头提供，请参阅发行版中提供的scgi_params文件。

location / {
    include scgi_params;
    ...
}

如果指令与if_not_empty (1.1.11)一起指定，则只有当参数值不为空时，才会将该参数传递给服务器。

scgi_param HTTPS $https if_not_empty;

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

scgi_pass localhost:9000;

或UNIX域套接字路径。

scgi_pass unix:/tmp/scgi.socket;

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

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

允许将来自SCGI服务器到客户端的其他禁用的头字段传递。

scgi_pass_request_body on;

指示是否将原始请求正文传递给SCGI服务器。另请参阅scgi_pass_request_headers指令。

scgi_pass_request_headers on;

指示是否将原始请求的头字段传递给SCGI服务器。另请参阅scgi_pass_request_body指令。

scgi_read_timeout 60s;

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

scgi_request_buffering on;

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

启用缓冲时，在将请求发送到SCGI服务器之前，将从客户端读取整个请求正文。

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

当使用HTTP/1.1分块传输编码发送原始请求正文时，无论指令值如何，请求正文都将被缓冲。

scgi_send_timeout 60s;

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

scgi_socket_keepalive off;

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

scgi_store off;

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

scgi_store /data/www$original_uri;

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

此指令可用于创建静态不变文件的本地副本，例如：

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

location /fetch/ {
    internal;

    scgi_pass         backend:9000;
    ...

    scgi_store        on;
    scgi_store_access user:rw group:rw all:r;
    scgi_temp_path    /data/temp;

    alias             /data/www/;
}

scgi_store_access user:rw;

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

scgi_store_access user:rw group:rw all:r;

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

scgi_store_access group:rw all:r;

scgi_temp_file_write_size 8k|16k;

限制在启用将来自SCGI服务器的响应缓冲到临时文件时，一次写入临时文件的数据大小。默认情况下，大小受scgi_buffer_size和scgi_buffers指令设置的两个缓冲区的限制。临时文件的最大大小由scgi_max_temp_file_size指令设置。

scgi_temp_path scgi_temp;

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

scgi_temp_path /spool/nginx/scgi_temp 1 2;

临时文件可能如下所示：

/spool/nginx/scgi_temp/7/45/00000123457

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