分类： nginx

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指令。

ngx_http_rewrite_module模块的指令按以下顺序处理：

• server级别中定义的指令的顺序
• 基于请求URI查询的location
• 找到的location中指令按顺序执行
• 如果请求URI重写了，则按指定顺序进行循环，但最多10次

break

语法：break
默认：—
上下文：server, location, if

停止当前ngx_http_rewrite_module的指令处理。
如果指令定义在location中，请求的后续处理继续在当前location中。
例子：

if ($slow) {
    limit_rate 10k;
    break;
}

if

语法：if (condition) { … }
默认：—
上下文：server, location

指定的condition会被解析，如果结果是真值，该模块会被执行，请求会分配到if指令的配置中。if指令中的配置继承自上级配置。
条件可以是下面的值：

• 变量名，如果变量值为“0”或空字符串，则结果为false。1.0.1版本之前，以“0”开头的字符串被认为是false。
• 使用“=”或“!=”操作符进行比较
• 匹配以“~”（大小写敏感）及“~*”（大小写不敏感）开头的正则表达式。正则表达式可以包含捕获，可以在后面用$1~$9使用。“!~”和“!~*”操作符也是可以用的。如果正则表达式包含“}”或“;”字符，整个正则表达式需要用单引号或双引号包裹。
• 通过“-f”或“!-f”操作符检测文件存在性。
• 通过“-d”或“!-d”操作符检测目录存在性。
• 通过“-e”或“!-e”操作符检测文件、目录或符号链接存在性。
• 通过“-x”或“!-x”操作符检测可执行文件的存在性。

例子：

if ($http_user_agent ~ MSIE) {
    rewrite ^(.*)$ /msie/$1 break;
}

if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
    set $id $1;
}

if ($request_method = POST) {
    return 405;
}

if ($slow) {
    limit_rate 10k;
}

if ($invalid_referer) {
    return 403;
}

$invalid_referer内嵌变量由valid_referers指令设置。

return

语法：return code [text]
return code URL
return URL
默认：—
上下文：server, location, if

停止处理，并返回指定的code给客户端。非标准错误码444关闭连接并不返回响应头。
从0.8.42版本起，可以定义重定向URL（为301、302、303或307错误码），或响应体文本（其他错误码）。响应体文本及重定向URL可以包含变量。特殊的情况下，重定向URL可以定义为当前服务器的本地URI，这种情况下，完整的URL由请求的模式（$scheme）和server_name_in_redirect及port_in_redirect指令决定。
302的临时重定向URL定义为唯一的参数。该参数应该由“http://”、“https://”或“$scheme”字符串。URL可以包含变量。
0.7.51版本前，只有下面的返回码可以返回：204, 400, 402 — 406, 408, 410, 411, 413, 416, 500 — 504。
307错误码在1.1.16 和 1.0.13版本前不会当做重定向。

rewrite

语法：rewrite regex replacement [flag]
默认：—
上下文：server, location, if

如果指定的正则表达式匹配请求URI，URI会按照replacement字符串进行改变。rewrite指令按照它们出现在配置文件中的顺序执行。可以使用标识对后续处理进行终结。如果替换字符串以“http://”或“https://”开始，处理停止并返回重定向到客户端。
可选flag参数可以是下面值之一：
last
停止处理当前ngx_http_rewrite_module的指令，并开始寻找匹配URI的新location。

break
停止处理ngx_http_rewrite_module的指令，同break指令。

redirect
如果替换字符串不以“http://”和“https://”开头，返回临时响应码302。

permanent
返回永久重定向返回码301。

完整的重定向URL根据请求模式（$scheme）和server_name_in_redirect 和 port_in_redirect指令构成。
例子：

server {
    ...
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  last;
    return  403;
    ...
}

但是如果这些指令放在“/download/”location中，last标识应该替换为break，否则nginx会进行10次循环，并返回500错误码：

location /download/ {
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  break;
    return  403;
}

如果replacement字符串包含新的请求参数，之前的请求参数会追加到后面。如果不希望这样，在替换字符串后面加一个问号，避免追加参数，例如：
rewrite ^/users/(.*)$ /show?user=$1? last;
如果正则表达式包含“}”或“;”，整个正则表达式需要用单引号或双引号包裹。

rewrite_log

语法：rewrite_log on | off
默认：rewrite_log off
上下文：http, server, location, if

启用或禁用将ngx_http_rewrite_module模块指令的处理结果记录到error_log的notice级别中。

set

语法：set $variable value
默认：—
上下文：server, location, if

为指定变量设置值，值可以包含文本、变量及它们的混合。

uninitialized_variable_warn

语法：uninitialized_variable_warn on | off
默认：uninitialized_variable_warn on
上下文：http, server, location, if

控制是否警告未初始化的变量被记录。

内部实现

ngx_http_rewrite_module模块的指令在配置期间编译成处理请求时理解的内部指令。解释器是一个简单的虚拟堆栈。例如，指令

location /download/ {
    if ($forbidden) {
        return 403;
    }

    if ($slow) {
        limit_rate 10k;
    }

    rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
}

将会翻译成

variable $forbidden
check against zero
    return 403
    end of code
variable $slow
check against zero
match of regular expression
copy "/"
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code

注意上面的指令中没有limit_rate，因为它与ngx_http_rewrite_module模块无关。单独的配置会为if块创建。如果条件为true，请求会分配到该配置上，限速10k。
指令
rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
可以变得更短，如果正则表达式中第一个“/”在括号里：
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
对应的指令为：

match of regular expression
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code