模块 ngx_http_scgi_module

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

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

定义允许或拒绝访问 SCGI 服务器的条件。如果所有字符串参数均不为空且不等于“0”，则允许访问。每次在与 SCGI 服务器建立连接之前都会对这些条件进行评估。参数值可以包含变量。

geo $upstream_last_addr $allow {
    volatile;
    10.10.0.0/24        1;
}

server {
    listen 127.0.0.1:8080;

    location / {
        scgi_pass           localhost:9000;
        scgi_allow_upstream $allow;
        ...
    }
}

该指令是我们的商业订阅的一部分。

使传向 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_bind_dynamic off;

启用后，将在每次连接尝试时执行绑定操作。

该指令是我们的商业订阅的一部分。

scgi_buffer_size 4k|8k;

设置用于读取从 SCGI 服务器接收到的响应第一部分的缓冲区 size。这部分通常包含较小的响应头部；如果头部超过了缓冲区大小，则该响应被视为无效。默认情况下，缓冲区大小等于一个内存页。根据平台不同，该大小为 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 服务器来填充由 scgi_cache_key 指令标识的新缓存元素。同一缓存元素的其他请求将等待响应出现在缓存中，或者等待该元素的缓存锁释放，等待时间不超过 scgi_cache_lock_timeout 指令设置的时间。

scgi_cache_lock_age 5s;

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

scgi_cache_lock_timeout 5s;

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

在 1.7.8 之前，响应是可以被缓存的。

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

scgi_cache_methods GET HEAD;

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

scgi_cache_min_uses 1;

设置请求的 number，达到该次数后响应将被缓存。

设置缓存的路径和其他参数。缓存数据存储在文件中。缓存中的文件名是将 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 参数配置。一个兆字节的区域可以存储大约 8 千个键。

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

在 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 指令的参数相匹配。

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

此外，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;

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

默认情况下，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”和“Vary”设置响应缓存参数；
• “X-Accel-Redirect”执行到指定 URI 的内部重定向；
• “X-Accel-Limit-Rate”设置向客户端传输响应的速率限制；
• “X-Accel-Buffering”启用或禁用响应的缓冲；
• “X-Accel-Charset”设置响应的期望字符集。

scgi_intercept_errors off;

确定 SCGI 服务器返回大于或等于 300 的代码的响应是否应传递给客户端，还是被拦截并重定向到 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

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

denied

服务器拒绝了连接（自 1.29.3 起）；

此参数是我们商业订阅的一部分。

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、denied 和 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_param HTTP_HOST $host$is_request_port$request_port;

设置应传给 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;

如果域名解析为多个地址，它们都将以循环（round-robin）方式使用。此外，地址可以指定为服务器组。

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

允许将否则被禁用的头部字段从 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_request_dynamic off;

启用或禁用为每个 SCGI 服务器创建单独的请求实例。默认情况下，所有 SCGI 服务器使用单个请求。如果启用，则会创建一个单独的请求实例，从而允许进行服务器特定的请求自定义。

该指令是我们的商业订阅的一部分。

scgi_send_timeout 60s;

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

scgi_socket_keepalive off;

配置传向 SCGI 服务器的传出连接的“TCP 保活”行为。默认情况下，套接字采用操作系统的设置。如果指令设置为“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 参数。