模块 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服务器读取响应的缓冲区的number和size，对于单个连接。默认情况下，缓冲区大小等于一个内存页面。这通常是4K或8K，具体取决于平台。

scgi_busy_buffers_size 8k|16k;

当启用来自SCGI服务器的响应的缓冲时，限制可以在尚未完全读取响应的情况下忙于向客户端发送响应的总size的缓冲区。同时，其余的缓冲区可以用于读取响应，并且如果需要，可以将响应的部分缓冲到临时文件中。默认情况下，size受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，则临时文件将直接放在缓存目录中。

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

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

未在指定的时间内被访问的缓存数据，无论其新鲜度如何，都将从缓存中移除。默认情况下，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指令的参数匹配。

如果无法选择用于处理请求的 SCGI 服务器，则error参数还允许使用旧的缓存响应。

此外，updating参数允许在当前正在更新时使用旧的缓存响应。这允许在更新缓存数据时最小化对 SCGI 服务器的访问次数。

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

• The “stale-while-revalidate” extension of the “Cache-Control” header field permits using a stale cached response if it is currently being updated.
• The “stale-if-error” extension of the “Cache-Control” header field permits using a stale cached response in case of an error.

为了在填充新的缓存元素时最小化对 SCGI 服务器的访问次数，可以使用scgi_cache_lock指令。

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

scgi_cache_valid 200 302 10m;
scgi_cache_valid 404      1m;

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

如果只指定了缓存时间

scgi_cache_valid 5m;

则只缓存代码为 200、301 和 302 的响应。

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

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

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

• The “X-Accel-Expires” header field sets caching time of a response in seconds. The zero value disables caching for a response. If the value starts with the @ prefix, it sets an absolute time in seconds since Epoch, up to which the response may be cached.
• If the header does not include the “X-Accel-Expires” field, parameters of caching may be set in the header fields “Expires” or “Cache-Control”.
• If the header includes the “Set-Cookie” field, such a response will not be cached.
• If the header includes the “Vary” field with the special value “*”, such a response will not be cached (1.7.7). If the header includes the “Vary” field with another value, such a response will be cached taking into account the corresponding request header fields (1.7.7).

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

scgi_connect_timeout 60s;

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

scgi_force_ranges off;

无论这些响应是否被缓存，都会为来自SCGI服务器的响应启用字节范围支持，而不管这些响应中的“Accept-Ranges”字段是什么。

默认情况下，nginx不会将来自SCGI服务器响应的“Status”和“X-Accel-…”字段传递给客户端。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”, and “Vary” set the parameters of response caching;
• “X-Accel-Redirect” performs an internal redirect to the specified URI;
• “X-Accel-Limit-Rate” sets the rate limit for transmission of a response to a client;
• “X-Accel-Buffering” enables or disables buffering of a response;
• “X-Accel-Charset” sets the desired charset of a response.

scgi_intercept_errors off;

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

scgi_limit_rate 0;

限制从 SCGI 服务器读取响应的速度。速率以每秒字节为单位指定。零值禁用速率限制。限制是针对每个请求设置的，因此如果 nginx 同时向 SCGI 服务器打开两个连接，则整体速率将是指定限制的两倍。只有在启用了从 SCGI 服务器的响应的缓冲时，限制才有效。

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 服务器的 parameter。该 value 可包含文本、变量及其组合。如果当前级别上没有定义 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 参数禁用文件保存。此外，还可以使用带有变量的 string 明确设置文件名：

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;

如果指定了任何 group 或 all 访问权限，则可以省略 user 权限：

scgi_store_access group:rw all:r;

scgi_temp_file_write_size 8k|16k;

当启用来自SCGI服务器的响应的缓冲时，限制一次写入临时文件的数据的 size。默认情况下，size 由 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 参数。