nginx中文文档-ngx_http_scgi_module(I-T)

本文档包含以下指令:scgi_ignore_client_abort、scgi_ignore_headers、scgi_intercept_errors、scgi_limit_rate、scgi_max_temp_file_size、scgi_next_upstream、scgi_next_upstream_timeout、scgi_next_upstream_tries、scgi_no_cache、scgi_param、scgi_pass、scgi_pass_header、scgi_pass_request_body、scgi_pass_request_headers、scgi_read_timeout、scgi_request_buffering、scgi_send_timeout、scgi_store、scgi_store_access、scgi_temp_file_write_size、scgi_temp_path

scgi_ignore_client_abort

语法:scgi_ignore_client_abort on | off
默认:scgi_ignore_client_abort off
上下文:http, server, location

决定当客户端没有等待响应关闭了连接时,是否与SCGI服务器关闭连接。

scgi_ignore_headers

语法:scgi_ignore_headers field
默认:—
上下文:http, server, location

禁用处理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

语法:scgi_intercept_errors on | off
默认:scgi_intercept_errors off
上下文:http, server, location

决定当SCGI服务器响应的返回码大于等于300是,应该传给客户端,还是重定向到nginx通过error_page指令进行处理。

scgi_limit_rate

语法:scgi_limit_rate rate
默认:scgi_limit_rate 0
上下文:http, server, location
版本:1.7.7+

限制从SCGI服务器读取响应的速度。rate定义为字节每秒。零值禁用限速。限制针对每一个请求,如果nginx同时打开两个请求,总速率为两倍的指定值。限制只有在SCGI服务器响应缓冲区启用时有效。

scgi_max_temp_file_size

语法:scgi_max_temp_file_size size
默认:scgi_max_temp_file_size 1024m
上下文:http, server, location

当启用了SCGI服务器响应缓冲区,整个请求不能放到由scgi_buffer_size和scgi_buffers指令设置的缓冲区中时,一部分响应会保存到临时文件中。这个指令设置了临时文件的最大大小。一次写入到临时文件的数据量由scgi_temp_file_write_size指令设置。
零值禁用响应缓冲区写入临时文件功能。
这个限制不会对请求会缓存或保存到磁盘的响应生效。

scgi_next_upstream

语法:scgi_next_upstream error | timeout | invalid_header | http_500 | http_503 | http_403 | http_404 | non_idempotent | off …
默认:scgi_next_upstream error timeout
上下文:http, server, location

指定哪些情况下请求会传给下一个服务器:
error
当与服务器建立连接、传递请求或读取响应头时发生了错误

timeout
当与服务器建立连接、传递请求或读取响应头时发生了超时

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

http_500
服务器返回500错误码

http_503
服务器返回503错误码

http_403
服务器返回403错误码

http_404
服务器返回404错误码

non_idempotent
一般地,非幂等方法(POST、LOCK、PATCH)不会传给下一个服务器,如果请求已经发给了一个上游服务器(1.9.13+)。启用这个选项允许重试这些请求。

off
禁用将请求发送给下一个服务器的功能。

需要了解的是,传给下一个服务器只有在没返回客户端任何数据时可用。也就是说,如果错误或超时发生在传输响应中间,不能修复这个问题。
该指令同时定义了与服务器通信的不成功尝试。error、timeout和invalid_header总会被认为是不成功的尝试,即使它们没有在指令中定义。http_500和http_503只有在指令中定义时才会认为是不成功的尝试。http_403和http_404从不会认为是不成功的尝试。

scgi_next_upstream_timeout

语法:scgi_next_upstream_timeout time
默认:scgi_next_upstream_timeout 0
上下文:http, server, location
版本:1.7.5+

限制一个时间,在此期间请求可以传给下一个服务器。0值关闭这个限制。

scgi_next_upstream_tries

语法:scgi_next_upstream_tries number
默认:scgi_next_upstream_tries 0
上下文:http, server, location
版本:1.7.5+

限制尝试传递请求到下一个服务器的次数。0值关闭这个限制。

scgi_no_cache

语法:scgi_no_cache string
默认:—
上下文:http, server, location

定义哪些条件下响应不会被缓存。如果string参数至少有一个非空且不等于“0”的值,则响应不会缓存:

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

可以与scgi_cache_bypass指令一同使用。

scgi_param

语法:scgi_param parameter value [if_not_empty]
默认:—
上下文:http, server, location

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

语法:scgi_pass address
默认:—
上下文:location, if in location

设置SCGI服务器的地址。地址可以定义为域名或IP地址和端口号:
scgi_pass localhost:9000;
或是一个UNIX-domain socket路径:
scgi_pass unix:/tmp/scgi.socket;
如果域名解析成多个地址,所有的地址会通过轮询的方式使用。地址可以定义为服务器组。

scgi_pass_header

语法:scgi_pass_header field
默认:—
上下文:http, server, location

允许传递被禁用的头域到客户端。

scgi_pass_request_body

语法:scgi_pass_request_body on | off
默认:scgi_pass_request_body on
上下文:http, server, location

指示原始请求体是否会传给SCGI服务器。参见scgi_pass_request_headers指令。

scgi_pass_request_headers

语法:scgi_pass_request_headers on | off
默认:scgi_pass_request_headers on
上下文:http, server, location

指示原始请求头是否传给SCGI服务器。参见scgi_pass_request_body指令。

scgi_read_timeout

语法:scgi_read_timeout time
默认:scgi_read_timeout 60s
上下文:http, server, location

定义从SCGI服务器读取响应的超时时间。超时时间为两次成功的读操作的时间,而不是整个响应的传输。如果在这期间SCGI服务器没有发送任何数据,连接将被关闭。

scgi_request_buffering

语法:scgi_request_buffering on | off
默认:scgi_request_buffering on
上下文:http, server, location
版本:1.7.11+

启用或禁用客户端请求体缓冲区。
当缓冲区启用时,整个请求体会先读取到缓冲区中,然后发送给SCGI服务器。
当缓冲区禁用时,请求体达到后会立即传给SCGI服务器。这种情况下,如果nginx已经发送请求体,请求就不能传给下一个服务器。
当HTTP1.1 chunked传输用来传输原始请求体,请求体会被缓冲不管指令的值。

scgi_send_timeout

语法:scgi_send_timeout time
默认:scgi_send_timeout 60s
上下文:http, server, location

设置传输请求到SCGI服务器的超时时间。超时时间为两次成功的写操作之间,不是整个请求传输。如果在此期间SCGI服务器没有收到任何数据,连接将被关闭。

scgi_store

语法:scgi_store on | off | string
默认:scgi_store off
上下文:http, server, location

开启将文件保存到磁盘功能。on参数保存文件到alias或root指令对应的路径下。off参数禁用保存文件。文件名可以使用string带变量:
scgi_store /data/www$original_uri;
修改时间是根据响应头中“Last-Modified”字段设置。响应首先写入到临时文件,然后重命名。从0.8.9版本开始临时文件和持久化文件可以放在不同的文件系统上。但是,需要知道的是,这种情况下文件会在两个文件系统中复制,而不是代价低的重命名操作。因此建议同时给出保存文件的位置和存放临时文件的目录位置,并放在同一个文件系统上。
这个指令可以用于创建静态不变的文件副本,例如:

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

语法:scgi_store_access users:permissions
默认:scgi_store_access user:rw
上下文:http, server, location

设置新创建的文件和目录的访问权限,例如:
scgi_store_access user:rw group:rw all:r;
如果group或all的访问权限指定了,那么user的权限可以忽略:
scgi_store_access group:rw all:r;

scgi_temp_file_write_size

语法:scgi_temp_file_write_size size
默认:scgi_temp_file_write_size 8k|16k
上下文:http, server, location

当SCGI服务器响应缓冲区到临时文件功能启用时,限制每次写入临时文件的数据大小。默认情况下,大小由scgi_buffer_size和scgi_buffers指令设置的两个缓冲区限制。最大的临时文件大小由scgi_max_temp_file_size指令设置。

scgi_temp_path

语法:scgi_temp_path path [level1 [level2 [level3]]]
默认:scgi_temp_path scgi_temp
上下文:http, server, location

定义一个保存从SCGI服务器收到的数据的临时文件的目录。最多可以使用三层子目录层级指定目录。例如下面的配置
scgi_temp_path /spool/nginx/scgi_temp 1 2;
临时文件类似于:
/spool/nginx/scgi_temp/7/45/00000123457
参见scgi_cache_path指令的use_temp_path参数。

nginx中文文档-ngx_http_scgi_module(B-H)

本文档包含以下指令:scgi_bind、scgi_buffer_size、scgi_buffering、scgi_buffers、scgi_busy_buffers_size、scgi_cache、scgi_cache_bypass、scgi_cache_key、scgi_cache_lock、scgi_cache_lock_age、scgi_cache_lock_timeout、scgi_cache_methods、scgi_cache_min_uses、scgi_cache_path、scgi_cache_purge、scgi_cache_revalidate、scgi_cache_use_stale、scgi_cache_valid、scgi_connect_timeout、scgi_force_ranges、scgi_hide_header

ngx_http_scgi_module模块允许将请求传递给SCGI服务器。
示例配置

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

scgi_bind

语法:scgi_bind address [transparent] | off
默认:—
上下文:http, server, location

从指定的本地IP地址建立外部连接到SCGI服务器。参数可以包含变量(1.3.12+)。特殊值off(1.3.12+)取消继承自上一级别配置中scgi_bind指令的影响,让系统自动分配本地IP地址。
transparent参数(1.11.0)允许从非本地IP地址建立到SCGI服务器的连接,例如从一个客户端真实的IP地址:
scgi_bind $remote_addr transparent;
为使这个参数工作,需要以超级用户权限运行nginx的工作进程,并且配置核心路由表以拦截从SCGI服务器的网络流量。

scgi_buffer_size

语法:scgi_buffer_size size
默认:scgi_buffer_size 4k|8k
上下文:http, server, location

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

scgi_buffering

语法:scgi_buffering on | off
默认:scgi_buffering on
上下文:http, server, location

启用或禁用SCGI服务器响应缓冲区。
当缓冲区启用,nginx收到SCGI服务器的请求后尽快的将其保存到由scgi_buffer_size和scgi_buffers 指令设置的缓冲区中。如果整个响应不能放到内存,部分会被放到磁盘上的临时文件中。写入临时文件由scgi_max_temp_file_size和scgi_temp_file_write_size指令控制。
当缓冲区禁用,响应会在收到后立即同步的传给客户端。nginx不会尝试从SCGI服务器读取完整的响应。从服务器一次可以接受数据的最大大小由scgi_buffer_size指令设置。
缓冲区也可以通过“X-Accel-Buffering”响应头域的“yes”和“no”值启用及禁用。这个功能可以通过scig_ignore_headers指令禁用。

scgi_buffers

语法:scgi_buffers number size
默认:scgi_buffers 8 4k|8k
上下文:http, server, location

设置用于读取从SCGI服务器响应的缓冲区数量和大小,针对一个连接。默认,缓冲区大小为一页内存。这个是4k或8k取决于平台。

scgi_busy_buffers_size

语法:scgi_busy_buffers_size size
默认:scgi_busy_buffers_size 8k|16k
上下文:http, server, location

当启用SCGI服务器响应缓冲区,限制当响应没有完全读取时可以发送给客户端的缓冲区总大小。与此同时,剩下的缓冲区可以用于读取响应,如果需要,一部分响应写入临时文件。默认情况下,size由scig_buffer_size和scgi_buffers指令设置的两个缓冲区大小限制。

scgi_cache

语法:scgi_cache zone | off
默认:scgi_cache off
上下文:http, server, location

为缓存定义一个共享内存区域。相同的区域可以用在多处。参数值可以包含变量(1.7.9+)。参数off禁用从上级配置中继承的缓存。

scgi_cache_bypass

语法:scgi_cache_bypass string
默认:—
上下文:http, server, location

定义哪些情况下响应不会从缓存中取。如果字符串参数至少有一个不是空,并且不等于“0”,响应不会从缓存中取:

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

可以与scgi_no_cache指令一同使用。

scgi_cache_key

语法:scgi_cache_key string
默认:—
上下文:http, server, location

为缓存定义一个关键字,例如
scgi_cache_key localhost:9000$request_uri;

scgi_cache_lock

语法:scgi_cache_lock on | off
默认:scgi_cache_lock off
上下文:http, server, location
版本:1.1.12+

当启用时,同一时间只有一个请求可以占用新的缓存元素。其他用相同缓存元素的请求要么等待缓存中响应出现,要么等待scgi_cache_lock_timeout指令设置的时间后该元素缓存锁被释放。

scgi_cache_lock_age

语法:scgi_cache_lock_age time
默认:scgi_cache_lock_age 5s
上下文:http, server, location
版本:1.7.8+

如果最后一个传给SCGI服务器的请求占用了新的缓存元素,在指定的时间内没有完成,更多的请求可以传给SCGI服务器。

scgi_cache_lock_timeout

语法:scgi_cache_lock_timeout time
默认:scgi_cache_lock_timeout 5s
上下文:http, server, location
版本:1.1.12+

设置scgi_cache_lock的超时。当时间过期,请求将被传给SCGI服务器,但是响应不会被缓存。
在1.7.8版本之前,响应会被缓存。

scgi_cache_methods

语法:scgi_cache_methods GET | HEAD | POST …
默认:scgi_cache_methods GET HEAD
上下文:http, server, location

如果客户端请求方法在指令中列出,则响应会被缓存。“GET”和“HEAD”方法总会被添加到列表中,仍然建议显式的定义它们。参见scgi_no_cache指令。

scgi_cache_min_uses

语法:scgi_cache_path path [levels=levels] [use_temp_path=on|off] keys_zone=name:size [inactive=time] [max_size=size] [loader_files=number] [loader_sleep=time] [loader_threshold=time] [purger=on|off] [purger_files=number] [purger_sleep=time] [purger_threshold=time]
默认:—
上下文:http

设置缓存的路径和其他参数。缓存数据保存在文件中。文件名在缓存中是一个MD5的缓存关键词。levels参数定义了缓存等级,例如下面的配置
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参数配置。1M的区域可以保存大约8000个关键字。
在inactive参数设置的时间内缓存数据没有被访问的会被移除,不管他们的新鲜度。默认情况下,inactive设置为10分钟。
特殊的“cache manager”进程监控max_size参数设置的最大缓存大小。当大小超额,会移除最近最少使用的数据。
在启动后1分钟,特殊的“cache loader”进程激活。它会加载之前存在文件系统中的缓存数据信息到缓存区域内。加载过程是迭代的。一次迭代过程中,不会超过loader_files的项目被载入(默认是100)。另外一次迭代的时间由loader_threshold参数限制(默认200毫秒)。两次迭代之间,会有一个由loader_sleep参数设置的暂停(默认50毫秒)。
以下参数作为商业版本可用:(商业版本不进行翻译)
purger=on|off
Instructs whether cache entries that match a wildcard key will be removed from the disk by the cache purger (1.7.12). Setting the parameter to on (default is off) will activate the “cache purger” process that permanently iterates through all cache entries and deletes the entries that match the wildcard key.

purger_files=number
Sets the number of items that will be scanned during one iteration (1.7.12). By default, purger_files is set to 10.

purger_threshold=number
Sets the duration of one iteration (1.7.12). By default, purger_threshold is set to 50 milliseconds.

purger_sleep=number
Sets a pause between iterations (1.7.12). By default, purger_sleep is set to 50 milliseconds.

scgi_cache_purge

语法:scgi_cache_purge string …
默认:—
上下文:http, server, location
版本:1.5.7+

商业版本不进行翻译。
Defines conditions under which the request will be considered a cache purge request. If at least one value of the string parameters is not empty and is not equal to “0” then the cache entry with a corresponding cache key is removed. The result of successful operation is indicated by returning the 204 (No Content) response.

If the cache key of a purge request ends with an asterisk (“*”), all cache entries matching the wildcard key will be removed from the cache. However, these entries will remain on the disk until they are deleted for either inactivity, or processed by the cache purger (1.7.12), or a client attempts to access them.

Example configuration:

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

语法:scgi_cache_revalidate on | off
默认:scgi_cache_revalidate off
上下文:http, server, location
版本:1.5.7+

启用重验证缓存过期,通过请求的“If-Modified-Since”和“If-None-Match”头域。

scgi_cache_use_stale

语法:scgi_cache_use_stale error | timeout | invalid_header | updating | http_500 | http_503 | http_403 | http_404 | off …
默认:scgi_cache_use_stale off
上下文:http, server, location

定义哪些情况下当错误发生在与SCGI服务器通信期间,陈旧的缓存响应被使用。指令的参数匹配scgi_next_upstream指令。
error参数语序使用陈旧的缓存响应,如果无法选择SCGI服务器处理请求。
updating参数允许使用陈旧的缓存响应,如果当前正在更新。这使得在更新缓存数据时,最少的与SCGI服务器进行连接。
要减少与SCGI服务器的访问次数,可以使用scgi_cache_lock指令。

scgi_cache_valid

语法:scgi_cache_valid [code …] time
默认:—
上下文:http, server, location

设置不同响应码的缓存时间。例如,下面的指令

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;

缓存参数可以直接由响应头设置。这个比用指令设置的优先级高。

  • “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

语法:scgi_connect_timeout time
默认:scgi_connect_timeout 60s
上下文:http, server, location

定义与SCGI服务器建立连接的超时时间。注意超时时间一般不超过75秒。

scgi_force_ranges

语法:scgi_force_ranges on | off
默认:scgi_force_ranges off
上下文:http, server, location
版本:1.7.7+

为缓存和不缓存的响应启用byte-range支持,不管响应头中的“Accept-Ranges”。

scgi_hide_header

语法:scgi_hide_header field
默认:—
上下文:http, server, location

默认情况下,nginx不会传递头域“Status”和“X-Accel-…”给客户端。scgi_hide_header指令设置其他不会传递的字段。如果相反需要传递某些字段,可以使用scgi_pass_header指令。