Mercurial > hg > nginx-site
changeset 792:ceb8a4e374b7
Updated the Chinese documentation.
line wrap: on
line diff
--- a/xml/cn/GNUmakefile +++ b/xml/cn/GNUmakefile @@ -19,6 +19,18 @@ REFS = \ http/ngx_http_auth_basic_module \ http/ngx_http_autoindex_module \ http/ngx_http_browser_module \ + http/ngx_http_core_module \ + http/ngx_http_empty_gif_module \ + http/ngx_http_geo_module \ + http/ngx_http_geoip_module \ http/ngx_http_gzip_static_module \ + http/ngx_http_image_filter_module \ http/ngx_http_index_module \ http/ngx_http_limit_conn_module \ + http/ngx_http_limit_req_module \ + http/ngx_http_log_module \ + http/ngx_http_map_module \ + http/ngx_http_proxy_module \ + http/ngx_http_referer_module \ + http/ngx_http_rewrite_module \ + http/ngx_http_upstream_module \
--- a/xml/cn/docs/http/ngx_http_addition_module.xml +++ b/xml/cn/docs/http/ngx_http_addition_module.xml @@ -23,7 +23,7 @@ </section> -<section id="example" name="Example Configuration"> +<section id="example" name="配置示例"> <para> <example> @@ -37,7 +37,7 @@ location / { </section> -<section id="directives" name="Directives"> +<section id="directives" name="指令"> <directive name="add_before_body"> <syntax><value>uri</value></syntax>
--- a/xml/cn/docs/http/ngx_http_autoindex_module.xml +++ b/xml/cn/docs/http/ngx_http_autoindex_module.xml @@ -7,7 +7,7 @@ <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> -<module name="Module ngx_http_autoindex_module" +<module name="ngx_http_autoindex_module模块" link="/cn/docs/http/ngx_http_autoindex_module.html" lang="cn" translator="Weibin Yao" @@ -23,7 +23,7 @@ </section> -<section id="example" name="Example Configuration"> +<section id="example" name="配置示例"> <para> <example> @@ -36,7 +36,7 @@ location / { </section> -<section id="directives" name="Directives"> +<section id="directives" name="指令"> <directive name="autoindex"> <syntax><literal>on</literal> | <literal>off</literal></syntax>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_core_module.xml @@ -0,0 +1,2543 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_core_module 模块" + link="/cn/docs/http/ngx_http_core_module.html" + lang="cn" + translator="cfsego" + rev="13"> + +<section id="directives" name="指令"> + +<directive name="aio"> +<syntax> + <literal>on</literal> | + <literal>off</literal> | + <literal>sendfile</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.8.11</appeared-in> + +<para> +在FreeBSD和Linux操作系统上启用或者禁用异步文件I/O(AIO)。 +</para> + +<para> +从FreeBSD 4.3版本开始，可以使用AIO。AIO既可以静态链接到内核中： +<example> +options VFS_AIO +</example> +又可以作为内核模块动态加载： +<example> +kldload aio +</example> +</para> + +<para> +在FreeBSD第5版和第6版，静态启动AIO，或者在系统启动时动态加载AIO，都会触发网络子系统使用一把大锁，进而对整个系统的性能造成负面影响。 +这个限制在2009年发布的FreeBSD 6.4稳定版和FreeBSD 7中被消除。 +虽然如此，仍有方法在5.3及以上版本的FreeBSD中开启AIO而不触发网络子系统的大锁，那就是在内核启动以后加载AIO模块。 +使用这种时，<path>/var/log/messages</path>中会出现下面信息， +<example> +WARNING: Network stack Giant-free, but aio requires Giant. +Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0 +</example> +但可以安全的忽略它。 +<note> +使用AIO大锁的是FreeBSD套接字上的<c-func>aio_read</c-func>和<c-func>aio_write</c-func>异步操作。但是nginx仅仅在磁盘I/O使用AIO，所以不会出现问题。 +</note> +</para> + +<para> +为了让AIO工作，需要关闭<link id="sendfile"/>： +<example> +location /video/ { + sendfile off; + aio on; + output_buffers 1 64k; +} +</example> +</para> + +<para> +不过，从FreeBSD 5.2.1版和nginx 0.8.12版开始，AIO也可以为<c-func>sendfile</c-func>预读数据： +<example> +location /video/ { + sendfile on; + tcp_nopush on; + aio sendfile; +} +</example> + +这个配置使nginx在调用<c-func>sendfile</c-func>时带<c-def>SF_NODISKIO</c-def>参数， +那么<c-func>sendfile</c-func>在数据没有读入内存的时候，就不会阻塞在磁盘I/O上，而是直接返回报告；接着nginx就读这个一字节报告，然后初始化异步数据。 +FreeBSD内核接着会读取文件的开始128K字节到内存，而后续的读取只会以16K的单位来进行。 +这个性质可以使用<link id="read_ahead"/>指令来调节。 +</para> + +<para> +从Linux内核2.6.22版开始，也可以使用AIO。但必须同时开启<link id="directio"/>，否则读取将是阻塞的： +<example> +location /video/ { + aio on; + directio 512; + output_buffers 1 128k; +} +</example> +</para> + +<para> +在Linux上，<link id="directio"/>只在读取的块的边界对齐512字节（在XFS上是4K字节）时才有用。在读取文件尾部时， +如果没有对齐，AIO读取还是阻塞的。同样的情况(如果数据的开始或者结尾未对齐时，读取也是阻塞的) +也发生在含有<header>byte range</header>头的请求中，或者发生在不是从头开始的FLV请求中。 +没有必要手动关闭<link id="sendfile"/>，因为如果使用了<link id="directio"/>，它就会自动关闭。 +</para> + +</directive> + + +<directive name="alias"> +<syntax><value>path</value></syntax> +<default/> +<context>location</context> + +<para> +定义指定路径的替换路径。比如下面配置 +<example> +location /i/ { + alias /data/w3/images/; +} +</example> +“<literal>/i/top.gif</literal>”将由<path>/data/w3/images/top.gif</path>文件来响应。 +</para> + +<para> +<value>path</value>的值可以包含变量，但不能使用<var>$document_root</var>和<var>$realpath_root</var>这两个变量。 +</para> + +<para> +如果在定义了正则表达式的路径中使用了<literal>alias</literal>，那么正则表达式中应该含有匹配组， +并且<literal>alias</literal>应该引用这些匹配组(0.7.40版)来组成一个完整的文件路径，比如： +<example> +location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { + alias /data/w3/images/$1; +} +</example> +</para> + +<para> +如果路径对应指令<value>path</value>值的最后一部分： +<example> +location /images/ { + alias /data/w3/images/; +} +</example> +最好换用<link id="root"/>指令： +<example> +location /images/ { + root /data/w3; +} +</example> +</para> + +</directive> + + +<directive name="chunked_transfer_encoding"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +允许关闭HTTP/1.1中的分块传输编码。在客户端软件不支持分块传输编码的时候，这条指令才有用。 +</para> + +</directive> + + +<directive name="client_body_buffer_size"> + +<syntax><value>size</value></syntax> +<default>8k|16k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置读取客户端请求正文的缓冲容量。如果请求正文大于缓冲容量，整个正文或者正文的一部分将写入<link id="client_body_temp_path">临时文件</link>。 +缓冲大小默认等于两块内存页的大小，在x86平台、其他32位平台和x86-64平台，这个值是8K。在其他64位平台，这个值一般是16K。 +</para> + +</directive> + + +<directive name="client_body_in_file_only"> +<syntax> + <literal>on</literal> | + <literal>clean</literal> | + <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +决定nginx是否将客户端请求正文整个写入文件。这条指令在调试时，或者使用<var>$request_body_file</var>变量时， +或者使用<link doc="ngx_http_perl_module.xml">ngx_http_perl_module</link>模块的 +<link doc="ngx_http_perl_module.xml" id="methods">$r->request_body_file</link>方法时都可以使用。 +</para> + +<para> +当指令值设置为<literal>on</literal>时，请求处理结束后不会删除临时文件。 +</para> + +<para> +当指令值设置为<literal>clean</literal>时，请求处理结束后会删除临时文件。 +</para> + +</directive> + + +<directive name="client_body_in_single_buffer"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +决定nginx将整个客户端请求正文保存在一块缓冲中。 +这条指令推荐在使用<var>$request_body</var>变量时使用，可以节省引入的拷贝操作。 +</para> + +</directive> + + +<directive name="client_body_temp_path"> +<syntax> + <value>path</value> + [<value>level1</value> + [<value>level2</value> + [<value>level3</value>]]]</syntax> +<default>client_body_temp</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +定义存储客户端请求正文的临时文件的目录。 +支持在指定目录下多达3层的子目录结构。比如下面配置 +<example> +client_body_temp_path /spool/nginx/client_temp 1 2; +</example> +存储临时文件的路径是 +<example> +/spool/nginx/client_temp/7/45/00000123457 +</example> +</para> + +</directive> + + +<directive name="client_body_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +定义读取客户端请求正文的超时。超时是指相邻两次读操作之间的最大时间间隔，而不是整个请求正文完成传输的最大时间。 +如果客户端在这段时间内没有传输任何数据，nginx将返回<http-status code="408" text="Request Time-out"/>错误到客户端。 +</para> + +</directive> + + +<directive name="client_header_buffer_size"> +<syntax><value>size</value></syntax> +<default>1k</default> +<context>http</context> +<context>server</context> + +<para> +设置读取客户端请求头部的缓冲容量。 +对于大多数请求，1K的缓冲足矣。 +但如果请求中含有的cookie很长，或者请求来自WAP的客户端，可能请求头不能放在1K的缓冲中。 +如果从请求行，或者某个请求头开始不能完整的放在这块空间中，那么nginx将按照 +<link id="large_client_header_buffers"/>指令的配置分配更多更大的缓冲来存放。 +directive. +</para> + +</directive> + + +<directive name="client_header_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> + +<para> +定义读取客户端请求头部的超时。如果客户端在这段时间内没有传送完整的头部到nginx， +nginx将返回错误<http-status code="408" text="Request Time-out"/>到客户端。 +</para> + +</directive> + + +<directive name="client_max_body_size"> +<syntax><value>size</value></syntax> +<default>1m</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置允许客户端请求正文的最大长度。请求的长度由<header>Content-Length</header>请求头指定。 +如果请求的长度超过设定值，nginx将返回错误<http-status code="413" text="Request Entity Too Large"/>到客户端。 +请注意<!--link doc="/web/upload.xml"-->浏览器不能正确显示这个错误<!--/link-->。 +将<value>size</value>设置成0可以使nginx不检查客户端请求正文的长度。 +</para> + +</directive> + + +<directive name="connection_pool_size"> +<syntax><value>size</value></syntax> +<default>256</default> +<context>http</context> +<context>server</context> + +<para> +允许微调为每个连接分配的内存。这条指令对nginx的性能影响非常小，一般不应该使用。 +</para> + +</directive> + + +<directive name="default_type"> +<syntax><value>mime-type</value></syntax> +<default>text/plain</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +定义响应的默认MIME类型。设置文件扩展名和响应的MIME类型的映射表则使用<link id="types"/>指令。 +</para> + +</directive> + + +<directive name="directio"> +<syntax><value>size</value> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.7.7</appeared-in> + +<para> +当读入长度大于等于指定<value>size</value>的文件时，开启DirectIO功能。 +具体的做法是， +在FreeBSD或Linux系统开启使用<c-def>O_DIRECT</c-def>标志， +在Mac OS X系统开启使用<c-def>F_NOCACHE</c-def>标志， +在Solaris系统开启使用<c-func>directio</c-func>功能。 +这条指令自动关闭<link id="sendfile"/>(0.7.15版)。 +它在处理大文件时 +<example> +directio 4m; +</example> +或者在Linux系统使用<link id="aio"/>时比较有用。 +</para> + +</directive> + + +<directive name="directio_alignment"> +<syntax><value>size</value></syntax> +<default>512</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.8.11</appeared-in> + +<para> +为<link id="directio"/>设置文件偏移量对齐。大多数情况下，按512字节对齐足矣， +但在Linux系统下使用XFS，需要将值扩大到4K。 +</para> + +</directive> + + +<directive name="disable_symlinks"> +<syntax><literal>off</literal></syntax> +<syntax> + <literal>on</literal> | + <literal>if_not_owner</literal> + [<literal>from</literal>=<value>part</value>]</syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.15</appeared-in> + +<para> +决定nginx打开文件时如何处理符号链接： +<list type="tag"> + +<tag-name><literal>off</literal></tag-name> +<tag-desc> +默认行为，允许路径中出现符号链接，不做检查。 +</tag-desc> + +<tag-name><literal>on</literal></tag-name> +<tag-desc> +如果文件路径中任何组成部分中含有符号链接，拒绝访问该文件。 +</tag-desc> + +<tag-name><literal>if_not_owner</literal></tag-name> +<tag-desc> +如果文件路径中任何组成部分中含有符号链接，且符号链接和链接目标的所有者不同，拒绝访问该文件。 +</tag-desc> + +<tag-name><literal>from</literal>=<value>part</value></tag-name> +<tag-desc> +当nginx进行符号链接检查时(参数<literal>on</literal>和参数<literal>if_not_owner</literal>)，路径中所有部分默认都会被检查。 +而使用<literal>from</literal>=<value>part</value>参数可以避免对路径开始部分进行符号链接检查，而只检查后面的部分路径。 +如果某路径不是以指定值开始，整个路径将被检查，就如同没有指定这个参数一样。 +如果某路径与指定值完全匹配，将不做检查。 +这个参数的值可以包含变量。 +</tag-desc> + +</list> +</para> + +<para> +比如： +<example> +disable_symlinks on from=$document_root; +</example> +</para> + +<para> +这条指令只在有<c-func>openat</c-func>和<c-func>fstatat</c-func>接口的系统上可用。 +当然，现在的FreeBSD、Linux和Solaris都支持这些接口。 +</para> + +<para> +参数<literal>on</literal>和<literal>if_not_owner</literal>会带来处理开销。 +<note> +只在那些不支持打开目录查找文件的系统中，使用这些参数需要工作进程有这些被检查目录的读权限。 +</note> +</para> + +<para> +<note> +<link doc="ngx_http_autoindex_module.xml">ngx_http_autoindex_module</link>模块， +<link doc="ngx_http_random_index_module.xml">ngx_http_random_index_module</link>模块 +和<link doc="ngx_http_dav_module.xml">ngx_http_dav_module</link>模块目前忽略这条指令。 +</note> +</para> + +</directive> + + +<directive name="error_page"> +<syntax> + <value>code</value> ... + [<literal>=</literal>[<value>response</value>]] + <value>uri</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if in location</context> + +<para> +为指令错误定义显示的URI。当前配置级别没有<literal>error_page</literal>指令时，将从上层配置继承。 +<literal>uri</literal>可以包含变量。 +</para> + +<para> +比如： +<example> +error_page 404 /404.html; +error_page 500 502 503 504 /50x.html; +</example> +</para> + +<para> +而且，可以使用“<literal>=</literal><value>response</value>语法改变响应状态码。比如： +<example> +error_page 404 =200 /empty.gif; +</example> +</para> + +<para> +如果URI将被发送到一个被代理的服务器处理，或者发送到一个FastCGI服务器处理， +这些后端服务器又返回了不同的响应状态码（比如200、302、401或404），那么这些返回的状态码也可以由本指令处理： +<example> +error_page 404 = /404.php; +</example> +</para> + +<para> +当然，也可以使用本指令对错误处理进行重定向： +<example> +error_page 403 http://example.com/forbidden.html; +error_page 404 =301 http://example.com/notfound.html; +</example> +对于例子中的第一行，nginx将向客户端发送302响应状态码。这种用法能使用的状态码只有301、302、303和307。 +</para> + +<para> +如果内部跳转时无需改变URI，可以将错误处理转到一个命名路径： +<example> +location / { + error_page 404 = @fallback; +} + +location @fallback { + proxy_pass http://backend; +} +</example> +</para> + +<para> +<note> +如果处理<literal>uri</literal>产生了错误，那么nginx将最后一次出错的HTTP响应状态码返回给客户端。 +</note> +</para> + +</directive> + + +<directive name="etag"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.3.3</appeared-in> + +<para> +开启或关闭为静态文件自动计算<header>ETag</header>响应头。 +</para> + +</directive> + + +<directive name="http"> +<syntax block="yes"/> +<default/> +<context>main</context> +<para> +为HTTP服务器提供配置上下文。 +</para> +</directive> + + +<directive name="if_modified_since"> +<syntax> + <literal>off</literal> | + <literal>exact</literal> | + <literal>before</literal></syntax> +<default>exact</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.7.24</appeared-in> + +<para> +指定响应的修改时间和<header>If-Modified-Since</header>请求头的比较方法： + +<list type="tag"> + +<tag-name><literal>off</literal></tag-name> +<tag-desc> +忽略<header>If-Modified-Since</header>请求头(0.7.34)； +</tag-desc> + +<tag-name><literal>exact</literal></tag-name> +<tag-desc> +精确匹配； +</tag-desc> + +<tag-name><literal>before</literal></tag-name> +<tag-desc> +响应的修改时间小于等于<header>If-Modified-Since</header>请求头指定的时间。 +</tag-desc> + +</list> +</para> + +</directive> + + +<directive name="ignore_invalid_headers"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> + +<para> +控制是否忽略非法的请求头字段名。 +合法的名字是由英文字母、数字和连字符组成，当然也可以包含下划线(由<link id="underscores_in_headers"/>指令控制)。 +</para> + +<para> +本指令可以在默认虚拟主机的<link id="server"/>配置层级中定义一次，那么这个值在监听在相同地址和端口的所有虚拟主机上都生效。 +</para> + +</directive> + + +<directive name="internal"> +<syntax/> +<default/> +<context>location</context> + +<para> +指定一个路径是否只能用于内部访问。如果是外部访问，客户端将收到<http-status code="404" text="Not Found"/>错误。 +下列请求是内部请求： + +<list type="bullet"> + +<listitem> +由<link id="error_page"/>指令、<link doc="ngx_http_index_module.xml" id="index"/>指令、 +<link doc="ngx_http_random_index_module.xml" id="random_index"/>指令 +和<link id="try_files"/>指令引起的重定向请求； +</listitem> + +<listitem> +由后端服务器返回的<header>X-Accel-Redirect</header>响应头引起的重定向请求； +</listitem> + +<listitem> +由<link doc="ngx_http_ssi_module.xml">ngx_http_ssi_module</link>模块 +和<link doc="ngx_http_addition_module.xml">ngx_http_addition_module</link>模块 +的“<command>include virtual</command>”指令产生的子请求； +</listitem> + +<listitem> +用<link doc="ngx_http_rewrite_module.xml" id="rewrite"/>指令对请求进行修改。 +</listitem> + +</list> +</para> + +<para> +举例： +<example> +error_page 404 /404.html; + +location /404.html { + internal; +} +</example> +<note> +nginx限制每个请求只能最多进行10次内部重定向，以防配置错误引起请求处理出现问题。 +如果内部重定向次数已达到10次，nginx将返回<http-status code="500" text="Internal Server Error"/>错误。 +同时，错误日志中将有“rewrite or internal redirection cycle”的信息。 +</note> +</para> + +</directive> + + +<directive name="keepalive_disable"> +<syntax><literal>none</literal> | <value>browser</value> ...</syntax> +<default>msie6</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +针对行为异常的浏览器关闭长连接功能。 +<value>browser</value>参数指定那些浏览器会受到影响。 +值为<literal>msie6</literal>表示在遇到POST请求时，关闭与老版MSIE浏览器建立长连接。 +值为<literal>safari</literal>表示在遇到Mac OS X和类Mac OS X操作系统下的Safari浏览器和类Safari浏览器时，不与浏览器建立长连接。 +值为<literal>none</literal>表示为所有浏览器开启长连接功能。 +<note> +在nginx 1.1.18版本及以前，<literal>safari</literal>将匹配所有操作系统上的Safari和类Safari浏览器，并默认不与这些浏览器建立长连接。 +</note> +</para> + +</directive> + + +<directive name="keepalive_requests"> +<syntax><value>number</value></syntax> +<default>100</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.8.0</appeared-in> + +<para> +设置通过一个长连接可以处理的最大请求数。 +请求数超过此值，长连接将关闭。 +</para> + +</directive> + + +<directive name="keepalive_timeout"> +<syntax> + <value>timeout</value> + [<value>header_timeout</value>]</syntax> +<default>75s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +第一个参数设置客户端的长连接在服务器端保持的最长时间（在此时间客户端未发起新请求，则长连接关闭）。 +第二个参数为可选项，设置<header>Keep-Alive: timeout=<value>time</value></header>响应头的值。 +可以为这两个参数设置不同的值。 +</para> + +<para> +<header>Keep-Alive: timeout=<value>time</value></header>响应头可以被Mozilla和Konqueror浏览器识别和处理。 +MSIE浏览器在大约60秒后会关闭长连接。 +</para> + +</directive> + + +<directive name="large_client_header_buffers"> +<syntax><value>number</value> <value>size</value></syntax> +<default>4 8k</default> +<context>http</context> +<context>server</context> + +<para> +设置读取客户端请求超大请求的缓冲最大<value>number(数量)</value>和每块缓冲的<value>size(容量)</value>。 +HTTP请求行的长度不能超过一块缓冲的容量，否则nginx返回错误<http-status code="414" text="Request-URI Too Large"/>到客户端。 +每个请求头的长度也不能超过一块缓冲的容量，否则nginx返回错误<http-status code="400" text="Bad Request"/>到客户端。 +缓冲仅在必需是才分配，默认每块的容量是8K字节。 +即使nginx处理完请求后与客户端保持入长连接，nginx也会释放这些缓冲。 +</para> + +</directive> + + +<directive name="limit_except"> +<syntax block="yes"><value>method</value> ...</syntax> +<default/> +<context>location</context> + +<para> +允许按请求的HTTP方法限制对某路径的请求。<value>method</value>用于指定不由这些限制条件进行过滤的HTTP方法，可选值有 +<literal>GET</literal>、 +<literal>HEAD</literal>、 +<literal>POST</literal>、 +<literal>PUT</literal>、 +<literal>DELETE</literal>、 +<literal>MKCOL</literal>、 +<literal>COPY</literal>、 +<literal>MOVE</literal>、 +<literal>OPTIONS</literal>、 +<literal>PROPFIND</literal>、 +<literal>PROPPATCH</literal>、 +<literal>LOCK</literal>、 +<literal>UNLOCK</literal> +或者 +<literal>PATCH</literal>。 +指定<value>method</value>为<literal>GET</literal>方法的同时，nginx会自动添加<literal>HEAD</literal>方法。 +那么其他HTTP方法的请求就会由指令引导的配置块中的<link doc="ngx_http_access_module.xml">ngx_http_access_module</link> +模块和<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>模块的指令来限制访问。如： +<example> +limit_except GET { + allow 192.168.1.0/32; + deny all; +} +</example> +请留意上面的例子将对<emphasis>除</emphasis>GET和HEAD方法以外的所有HTTP方法的请求进行访问限制。 +</para> + +</directive> + + +<directive name="limit_rate"> +<syntax><value>rate</value></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if in location</context> + +<para> +限制向客户端传送响应的速率限制。参数<value>rate</value>的单位是字节/秒，设置为0将关闭限速。 +<!-- +速率越小，限速越精确。 +--> +nginx按连接限速，所以如果某个客户端同时开启了两个连接，那么客户端的整体速率是这条指令设置值的2倍。 +</para> + +<para> +也可以利用<var>$limit_rate</var>变量设置流量限制。如果想在特定条件下限制响应传输速率，可以使用这个功能： +<example> +server { + + if ($slow) { + set $limit_rate 4k; + } + + ... +} +</example> +</para> + +<para> +此外，也可以通过<header>X-Accel-Limit-Rate</header>响应头来完成速率限制。 +这种机制可以用<link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/>指令和 +<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_ignore_headers"/>指令关闭。 +</para> + +</directive> + + +<directive name="limit_rate_after"> +<syntax><value>size</value></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if in location</context> +<appeared-in>0.8.0</appeared-in> + +<para> +设置不限速传输的响应大小。当传输量大于此值时，超出部分将限速传送。 +</para> + +<para> +比如: +<example> +location /flv/ { + flv; + limit_rate_after 500k; + limit_rate 50k; +} +</example> +</para> + +</directive> + + +<directive name="lingering_close"> +<syntax> + <literal>off</literal> | + <literal>on</literal> | + <literal>always</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.0</appeared-in> +<appeared-in>1.0.6</appeared-in> + +<para> +控制nginx如何关闭客户端连接。 +</para> + +<para> +默认值“<literal>on</literal>”指示nginx在完成关闭连接前<link id="lingering_timeout">等待</link>和 +<link id="lingering_time">处理</link>客户端发来的额外数据。但只有在预测客户端可能发送更多数据的情况才会做此处理。 +</para> + +<para> +“<literal>always</literal>”指示nginx无条件等待和处理客户端的额外数据。 +</para> + +<para> +“<literal>off</literal>”指示nginx立即关闭连接，而绝不等待客户端传送额外数据。 +这样做破坏了协议，所以正常条件下不应使用。 +</para> + +</directive> + + +<directive name="lingering_time"> +<syntax><value>time</value></syntax> +<default>30s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +<link id="lingering_close"/>生效时，这条指令定义nginx处理(读取但忽略)客户端额外数据的最长时间。 +超过这段时间后，nginx将关闭连接，不论是否还有更多数据待处理。 +</para> + +</directive> + + +<directive name="lingering_timeout"> +<syntax><value>time</value></syntax> +<default>5s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +<link id="lingering_close"/>生效时，这条指令定义nginx等待客户端更多数据到来的最长时间。 +如果在这段时间内，nginx没有接收到数据，nginx将关闭连接。否则，nginx将接收数据，忽略它，然后再等待更多数据。 +这个“等待——接收——忽略”的循环一直重复，但总时间不会超过<link id="lingering_time"/>指令定义的时间。 +</para> + +</directive> + + +<directive name="listen"> +<syntax> + <value>address</value>[:<value>port</value>] + [<literal>default_server</literal>] + [<literal>setfib</literal>=<value>number</value>] + [<literal>backlog</literal>=<value>number</value>] + [<literal>rcvbuf</literal>=<value>size</value>] + [<literal>sndbuf</literal>=<value>size</value>] + [<literal>accept_filter</literal>=<value>filter</value>] + [<literal>deferred</literal>] + [<literal>bind</literal>] + [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>ssl</literal>] + [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax> +<syntax> + <value>port</value> + [<literal>default_server</literal>] + [<literal>setfib</literal>=<value>number</value>] + [<literal>backlog</literal>=<value>number</value>] + [<literal>rcvbuf</literal>=<value>size</value>] + [<literal>sndbuf</literal>=<value>size</value>] + [<literal>accept_filter</literal>=<value>filter</value>] + [<literal>deferred</literal>] + [<literal>bind</literal>] + [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>] + [<literal>ssl</literal>] + [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax> +<syntax> + <literal>unix:</literal><value>path</value> + [<literal>default_server</literal>] + [<literal>backlog</literal>=<value>number</value>] + [<literal>rcvbuf</literal>=<value>size</value>] + [<literal>sndbuf</literal>=<value>size</value>] + [<literal>accept_filter</literal>=<value>filter</value>] + [<literal>deferred</literal>] + [<literal>bind</literal>] + [<literal>ssl</literal>] + [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax> +<default>*:80 | *:8000</default> +<context>server</context> + +<para> +设置nginx监听地址，nginx从这里接受请求。对于IP协议，这个地址就是<value>address</value>和<value>port</value>；对于UNIX域套接字协议，这个地址就是<value>path</value>。 +一条listen指令只能指定一个<value>address</value>或者<value>port</value>。 +<value>address</value>也可以是主机名。 +比如： +<example> +listen 127.0.0.1:8000; +listen 127.0.0.1; +listen 8000; +listen *:8000; +listen localhost:8000; +</example> +IPv6地址(0.7.36版)用方括号来表示： +<example> +listen [::]:8000; +listen [fe80::1]; +</example> +UNIX域套接字(0.8.21版)则使用“<literal>unix:</literal>”前缀： +<example> +listen unix:/var/run/nginx.sock; +</example> +</para> + +<para> +如果只定义了<value>address</value>，nginx将使用80端口。 +</para> + +<para> +在没有定义listen指令的情况下，如果以超级用户权限运行nginx，它将监听<literal>*:80</literal>，否则他将监听<literal>*:8000</literal>。 +</para> + +<para> +如果listen指令携带<literal>default_server</literal>参数，当前虚拟主机将成为指定<value>address</value>:<value>port</value>的默认虚拟主机。 +如果任何listen指令都没有携带<literal>default_server</literal>参数，那么第一个监听<value>address</value>:<value>port</value>的虚拟主机将被作为这个地址的默认虚拟主机。 +<note> +0.8.21版以前，这个参数的名称是<literal>default</literal>。 +</note> +</para> + +<para> +可以为<literal>listen</literal>指令定义若干额外的参数，这些参数用于套接字相关的系统调用。 +这些参数可以在任何<literal>listen</literal>指令中指定，但是对于每个<value>address</value>:<value>port</value>，只能定义一次。 +<note> +0.8.21版以前，只有为<literal>listen</literal>指令定义了<literal>default</literal>参数，才能定义这些额外的参数。 +</note> +<list type="tag"> + +<tag-name> +<literal>setfib</literal>=<value>number</value> +</tag-name> +<tag-desc> +这个参数(0.8.44)为监听套接字设置关联路由表FIB(<c-def>SO_SETFIB</c-def>选项)。 +当前这个参数仅工作在FreeBSD上。 +</tag-desc> + +<tag-name> +<literal>backlog</literal>=<value>number</value> +</tag-name> +<tag-desc> +为系统调用<c-func>listen</c-func>设置<literal>backlog</literal>参数，用以限制未接受(Accept)连接的队列的最大长度。 +FreeBSD和Mac OS X下，<literal>backlog</literal>的默认值是-1，在其他系统中，默认值是511。 +</tag-desc> + + +<tag-name> +<literal>rcvbuf</literal>=<value>size</value> +</tag-name> +<tag-desc> +为监听套接字设置接收缓冲区大小(<c-def>SO_RCVBUF</c-def>参数)。 +</tag-desc> + +<tag-name> +<literal>sndbuf</literal>=<value>size</value> +</tag-name> +<tag-desc> +为监听套接字设置发送缓冲区大小(<c-def>SO_SNDBUF</c-def>参数)。 +</tag-desc> + +<tag-name> +<literal>accept_filter</literal>=<value>filter</value> +</tag-name> +<tag-desc> +为监听套接字设置接受过滤器的名称(<c-def>SO_ACCEPTFILTER</c-def>选项)。 +对每个到来的连接，接受过滤器先进行过滤，然后才将它们呈现给<c-func>accept</c-func>。 +本特性仅工作在FreeBSD系统和NetBSD 5.0+系统下。 +可接受的值是 +<link url="http://man.freebsd.org/accf_data">dataready</link> +和 +<link url="http://man.freebsd.org/accf_http">httpready</link>。 +</tag-desc> + +<tag-name> +<literal>deferred</literal> +</tag-name> +<tag-desc> +指示在Linux系统使用延迟的<c-func>accept</c-func>(<c-def>TCP_DEFER_ACCEPT</c-def>选项)。 +</tag-desc> + +<tag-name> +<literal>bind</literal> +</tag-name> +<tag-desc> +指示nginx为设置的<value>address</value>:<value>port</value>单独调用一次<c-func>bind</c-func>。 +这是因为当有多条<literal>listen</literal>指令监听不同地址下的相同端口， +而其中一条<literal>listen</literal>指令监听了这个端口的所有地址(<literal>*:</literal><value>port</value>)时， +nginx只会为<literal>*:</literal><value>port</value>调用一次<c-func>bind</c-func>绑定套接字。 +需要留意的是，这种情况下，nginx会调用<c-func>getsockname</c-func>系统调用来确定接受请求的套接字地址。 +如果为某个<value>address</value>:<value>port</value>定义了参数<literal>backlog</literal>、<literal>rcvbuf</literal>、 +<literal>sndbuf</literal>、<literal>accept_filter</literal>、<literal>deferred</literal>或者<literal>so_keepalive</literal>， +nginx总会为这个地址单独调用一次<c-func>bind</c-func>绑定套接字。 +</tag-desc> + +<tag-name> +<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal> +</tag-name> +<tag-desc> +这个参数(0.7.42)(通过<c-def>IPV6_V6ONLY</c-def>选项)决定监听在通配地址<literal>[::]</literal>上的IPv6套接字是只支持IPv6连接，还是同时支持IPv6和IPv4连接。 +这个参数默认打开，并且只能在nginx启动时设置。 +<note> +在1.3.4版以前，如果省略此参数，那么操作系统的套接字设置将生效。 +</note> +</tag-desc> + +<tag-name> +<literal>ssl</literal> +</tag-name> +<tag-desc> +本参数(0.7.14)与套接字相关的系统调用无关，但是它可以指定从这个端口接受的连接应该以SSL模式工作。 +本参数在某服务器同时处理HTTP和HTTPS请求时，可以使<link doc="configuring_https_servers.xml" id="single_http_https_server">配置</link>更为紧凑。 +<example> +listen 80; +listen 443 ssl; +</example> +</tag-desc> + +<tag-name> +<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>] +</tag-name> +<tag-desc> +这个参数(1.1.11)为监听套接字配置“TCP keepalive”行为。 +如果省略此参数，操作系统默认的设置将对此端口生效。 +如果参数值设置为“<literal>on</literal>”，监听套接字的<c-def>SO_KEEPALIVE</c-def>属性将被开启。 +如果参数值设置为“<literal>off</literal>”，监听套接字的<c-def>SO_KEEPALIVE</c-def>属性将被关闭。 +有些操作系统支持为每个连接调整TCP长连接的参数。调整参数可以使用套接字选项<c-def>TCP_KEEPIDLE</c-def>，<c-def>TCP_KEEPINTVL</c-def>和<c-def>TCP_KEEPCNT</c-def>。 +在这些操作系统上(当前就是Linux 2.4+，嬀NetBSD 5+FreeBSD 9.0-STABLE)，可以使用<value>keepidle</value>，<value>keepintvl</value>和<value>keepcnt</value>参数来配置。 +省略一到两个参数的话，对应套接字属性的系统默认设置将生效。 +比如， +<example>so_keepalive=30m::10</example>将 +设置空闲超时(<c-def>TCP_KEEPIDLE</c-def>)为30分钟， +设置探测次数(<c-def>TCP_KEEPCNT</c-def>)为10次， +保留探测时间间隔(<c-def>TCP_KEEPINTVL</c-def>)为系统默认值。 +</tag-desc> + +</list> +</para> + +<para> +举例： +<example> +listen 127.0.0.1 default_server accept_filter=dataready backlog=1024; +</example> +</para> + +</directive> + + +<directive name="location"> +<syntax block="yes">[ + <literal>=</literal> | + <literal>~</literal> | + <literal>~*</literal> | + <literal>^~</literal> + ] <value>uri</value></syntax> +<syntax block="yes"><literal>@</literal><value>name</value></syntax> +<default/> +<context>server</context> +<context>location</context> + +<para> +为某个请求URI（路径）建立配置。 +</para> + +<para> +路径匹配在URI规范化以后进行。所谓规范化，就是先将URI中形如“<literal>%XX</literal>”的编码字符进行解码， +再解析URI中的相对路径“<literal>.</literal>”和“<literal>..</literal>”部分， +另外还可能会<link id="merge_slashes">压缩</link>相邻的两个或多个斜线成为一个斜线。 +</para> + +<para> +可以使用前缀字符串或者正则表达式定义路径。使用正则表达式需要在路径开始添加“<literal>~*</literal>”前缀 +(不区分大小写)，或者“<literal>~</literal>”前缀(区分大小写)。为了根据请求URI查找路径，nginx先检查前缀字符串定义的路径 +(前缀路径)，在这些路径中找到能最精确匹配请求URI的路径。然后nginx按在配置文件中的出现顺序检查正则表达式路径， +匹配上某个路径后即停止匹配并使用该路径的配置，否则使用最大前缀匹配的路径的配置。 +</para> + +<para> +路径可以嵌套，但有例外，后面将提到。 +</para> + +<para> +在不区分大小写的操作系统（诸如Mac OS X和Cygwin）上，前缀匹配忽略大小写(0.7.7)。但是，比较仅限于单字节的编码区域(one-byte locale)。 +</para> + +<para> +正则表达式中可以包含匹配组(0.7.40)，结果可以被后面的其他指令使用。 +</para> + +<para> +如果最大前缀匹配的路径以“<literal>^~</literal>”开始，那么nginx不再检查正则表达式。 +</para> + +<para> +而且，使用“<literal>=</literal>”前缀可以定义URI和路径的精确匹配。如果发现匹配，则终止路径查找。 +比如，如果请求“<literal>/</literal>”出现频繁，定义“<literal>location = /</literal>”可以提高这些请求的处理速度， +因为查找过程在第一次比较以后即结束。这样的路径明显不可能包含嵌套路径。 +</para> + +<para> +<note> +在0.7.1到0.8.41的所有nginx中，如果请求匹配的前缀字符串路径并没有“<literal>=</literal>”或“<literal>^~</literal>”前缀， +路径查找过程仍然会停止，而不进行正则表达式匹配。 +</note> +</para> + +<para> +让我们用一个例子解释上面的说法： +<example> +location = / { + [ configuration A ] +} + +location / { + [ configuration B ] +} + +location /documents/ { + [ configuration C ] +} + +location ^~ /images/ { + [ configuration D ] +} + +location ~* \.(gif|jpg|jpeg)$ { + [ configuration E ] +} +</example> +请求“<literal>/</literal>”匹配配置A， +请求“<literal>/index.html</literal>”匹配配置B， +请求“<literal>/documents/document.html</literal>”匹配配置C， +请求“<literal>/images/1.gif</literal>”匹配配置D， +请求“<literal>/documents/1.jpg</literal>”匹配配置E。 +</para> + +<para> +前缀“<literal>@</literal>”定义了命名路径。这种路径不在一般的请求处理中使用， +而是用在请求重定向中。这些路径不能嵌套，也不能包含嵌套路径。 +</para> + +<!-- +<migration from="Apache" directive="Location" /> +--> + +</directive> + + +<directive name="log_not_found"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +开启或者关闭在<link doc="../ngx_core_module.xml" id="error_log"/>中记录文件不存在的错误。 +</para> + +</directive> + + +<directive name="log_subrequest"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +开启或者关闭在<link doc="ngx_http_log_module.xml" id="access_log"/>中记录子请求的访问日志。 +</para> + +</directive> + + +<directive name="max_ranges"> +<syntax><value>number</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.2</appeared-in> + +<para> +如果请求中含有字节范围的请求头，这条指令可以限制此范围允许的最大值。如果请求头的值超过此限制，将按请求未携带此请求头的情况处理。 +默认nginx对此不做限制。设置为0将使nginx完全不支持HTTP字节范围特性。 +</para> + +</directive> + + +<directive name="merge_slashes"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> + +<para> +开启或者关闭将请求URI中相邻两个或更多斜线合并成一个的功能。 +</para> + +<para> +注意压缩URI对于前缀匹配和正则匹配的正确性是很重要的。没有开启这个功能时，请求“<literal>//scripts/one.php</literal>”将不能匹配 +<example> +location /scripts/ { + ... +} +</example> +而被按静态文件的流程处理，所以将它变换成“<literal>/scripts/one.php</literal>”。 +</para> + +<para> +如果URI中包含base64编码的内容，必须将斜线压缩调整成<literal>off</literal>，因为base64编码本身会使用“<literal>/</literal>”字符。 +然而。出于安全方面的考虑，最好还是不要关闭压缩。 +</para> + +<para> +这条指令可以指定在默认虚拟主机的<link id="server"/>配置级别。这样的话，这个配置可以覆盖监听同一地址和端口的所有虚拟主机。 +</para> + +</directive> + + +<directive name="msie_padding"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +在响应状态码大于等于400时，在响应正文中添加一段注释，使响应正文达到512字节。 +本指令可以为MSIE客户端开启或关闭这个功能。 +</para> + +</directive> + + +<directive name="msie_refresh"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +为MSIE客户端开启或者关闭用页面刷新取代页面重定向的功能。 +</para> + +</directive> + + +<directive name="open_file_cache"> +<syntax><literal>off</literal></syntax> +<syntax> +<literal>max</literal>=<value>N</value> +[<literal>inactive</literal>=<value>time</value>]</syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +用于配置文件缓存，可缓存： +<list type="bullet"> + +<listitem> +打开文件的描述符，大小和修改时间； +</listitem> + +<listitem> +目录查找结果； +</listitem> + +<listitem> +文件查找时的错误结果，诸如“file not found”(文件不存在)、“no read permission”(无读权限)等等。 +<note> +应单独使用<link id="open_file_cache_errors"/>指令开启缓存错误结果的功能。 +</note> +</listitem> + +</list> +</para> + +<para> +指令有下列参数： +<list type="tag"> + +<tag-name> +<literal>max</literal> +</tag-name> +<tag-desc> +设置缓存中元素的最大数量，当缓存溢出时，使用LRU(最近最少使用)算法删除缓存中的元素； +</tag-desc> + +<tag-name> +<literal>inactive</literal> +</tag-name> +<tag-desc> +设置超时，在这段时间内缓存元素如果没有被访问，将从缓存中删除。 +默认超时是60秒； +</tag-desc> + +<tag-name> +<literal>off</literal> +</tag-name> +<tag-desc> +关闭缓存。 +</tag-desc> + +</list> +</para> + +<para> +举例： +<example> +open_file_cache max=1000 inactive=20s; +open_file_cache_valid 30s; +open_file_cache_min_uses 2; +open_file_cache_errors on;<!-- +open_file_cache_events on; +--> +</example> +</para> + +</directive> + + +<directive name="open_file_cache_errors"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +开启或者关闭<link id="open_file_cache">缓存文件</link>查找的错误结果。 +</para> + +</directive> + + +<!-- + +<directive name="open_file_cache_events"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Enables to use kernel events to validate +<link id="open_file_cache"/> +elements. +This directive works with the +<link doc="../events.xml" id="kqueue"/> +method only. +Note that only NetBSD 2.0+ and FreeBSD 6.0+ +support events for arbitrary file system types. +Other operating systems support events only for essential +file systems such as UFS or FFS. +</para> + +</directive> + +--> + + +<directive name="open_file_cache_min_uses"> +<syntax><value>number</value></syntax> +<default>1</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置在由<link id="open_file_cache"/>指令的<literal>inactive</literal>参数配置的超时时间内， +文件应该被访问的最小<value>number(次数)</value>。如果访问次数大于等于此值，文件描述符会保留在缓存中，否则从缓存中删除。 +</para> + +</directive> + + +<directive name="open_file_cache_valid"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置检查<link id="open_file_cache"/>缓存的元素的时间间隔。 +<!-- +When +<link id="open_file_cache_events"/> +is enabled, open file descriptors +are checked only once, and then updated right after they get changed. +--> +</para> + +</directive> + + +<directive name="optimize_server_names"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> + +<para> +这条指令已经被废弃，请使用<link id="server_name_in_redirect"/>指令。 +</para> + +<!-- +<para> +Enables or disables optimization of hostname checking in name-based +virtual servers. +In particular, the checking affects hostnames used in redirects. +If optimization is enabled, and all name-based servers listening on +the same address:port pair have identical configuration, then +names are not checked during request processing, and the first +server name is used in redirects. +In case redirects should use hostnames sent by clients, +optimization needs to be disabled. +</para> +--> + +</directive> + + +<directive name="port_in_redirect"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +开启或关闭nginx发起重定向时指定端口。 +</para> + +<para> +重定向中首要主机名的使用由<link id="server_name_in_redirect"/>指令控制。 +</para> + +</directive> + + +<directive name="postpone_output"> +<syntax><value>size</value></syntax> +<default>1460</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +如果可能，到客户端的数据将被推迟发送，直到nginx需要发送的数据至少有<value>size</value>字节。 +设置为0将关闭推迟发送的功能。 +</para> + +</directive> + + +<directive name="read_ahead"> +<syntax><value>size</value></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置内核参数，控制文件预读的数量。 +</para> + +<para> +在Linux上，因为使用的是<literal>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</literal>系统调用，所以<value>size</value>无用。 +</para> + +<para> +在FreeBSD上，访问的是<literal>fcntl(O_READAHEAD,</literal><value>size</value><literal>)</literal>系统调用。 +该系统调用在FreeBSD 9.0-CURRENT才被支持，在FreeBSD 7上则需要<link url="http://sysoev.ru/freebsd/patch.readahead.txt">打补丁</link>。 +</para> + +</directive> + + +<directive name="recursive_error_pages"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +允许或禁止<link id="error_page"/>指令进行多次重定向。 +允许的话，重定向次数也有<link id="internal">限制</link>。 +而禁止此功能时，当访问<link id="error_page"/>指令重定向的错误页面出现任何问题时，nginx将直接输出默认错误页面。 +</para> + +</directive> + + +<directive name="request_pool_size"> +<syntax><value>size</value></syntax> +<default>4k</default> +<context>http</context> +<context>server</context> + +<para> +允许对每个请求的内存分配进行细调。这条指令对性能影响很小，通常情况下不应使用。 +</para> + +</directive> + + +<directive name="reset_timedout_connection"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +开启或关闭重置超时连接的功能。重置连接是这样执行的：关闭套接字以前，设置<c-def>SO_LINGER</c-def>选项的超时值为0， +那么当关闭套接字时，nginx向客户端发送TCP RST，并且释放此套接字占用的所有内存。 +这样可以避免某个已关闭的套接字长时间处于FIN_WAIT1状态，并占用内存缓冲区。 +</para> + +<para> +应该注意的事，超时的长连接仍然是正常关闭。 +</para> + +</directive> + + +<directive name="resolver"> +<syntax> +<value>address</value> ... +[<literal>valid</literal>=<value>time</value>]</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +配置将后端服务器的名字解析成ip地址的名字服务器，比如： +<example> +resolver 127.0.0.1 [::1]:5353; +</example> +这里地址可以指定域名或者ip地址，可以带端口号(1.3.1，1.2.2)。如果未指定端口，nginx使用53端口。 +以轮询方式发送请求到多台名字服务器。 +<note> +在1.1.7版以前，只允许配置一个名字服务器。而支持使用IPv6地址定义名字服务器则是从1.3.1和1.2.2版本开始。 +</note> +nginx会缓存名字解析的结果。默认情况下，缓存时间是名字解析响应中的TTL字段的值。也允许通过<literal>valid</literal>参数覆盖它： +<example> +resolver 127.0.0.1 [::1]:5353 valid=30s; +</example> +<note> +在1.1.9版以前，不可能调节缓存时间，nginx总会将响应缓存5分钟。 +</note> +</para> + +</directive> + + +<directive name="resolver_timeout"> +<syntax><value>time</value></syntax> +<default>30s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +为名字解析设置超时，比如： +<example> +resolver_timeout 5s; +</example> +</para> + +</directive> + + +<directive name="root"> +<syntax><value>path</value></syntax> +<default>html</default> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if in location</context> + +<para> +为请求设置根目录。比如，如果配置如下 +<example> +location /i/ { + root /data/w3; +} +</example> +那么nginx将使用文件<path>/data/w3/i/top.gif</path>响应请求“<literal>/i/top.gif</literal>”。 +</para> + +<para> +<value>path</value>的值中可以包含除<var>$document_root</var>和<var>$realpath_root</var>以外的变量。 +</para> + +<para> +文件路径的构造仅仅是将URI拼在<literal>root</literal>指令的值后面。如果需要修改URI，应该使用<link id="alias"/>指令。 +</para> + +</directive> + + +<directive name="satisfy"> +<syntax><literal>all</literal> | <literal>any</literal></syntax> +<default>all</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +nginx进行访问限制的有<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>模块和 +<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>模块。 +本指令设置成<literal>all</literal>时，表示只有当两个模块的所有限制条件(写入配置的)都授权访问时，允许请求访问； +设置成<literal>any</literal>时，表示如果当任意模块的任意限制条件授权访问时，允许请求访问。 +</para> + +<para> +举例： +<example> +location / { + satisfy any; + + allow 192.168.1.0/32; + deny all; + + auth_basic "closed site"; + auth_basic_user_file conf/htpasswd; +} +</example> +</para> + +</directive> + + +<directive name="satisfy_any"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +这条指令已被<link id="satisfy"/>指令的<literal>any</literal>参数取代。 +</para> + +</directive> + + +<directive name="send_lowat"> +<syntax><value>size</value></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +如果设置成非0值，nginx将尝试最小化向客户端发送数据的次数。 +这是通过将<link doc="../events.xml" id="kqueue"/>方法的<c-def>NOTE_LOWAT</c-def>标志， +或者将套接字的<c-def>SO_SNDLOWAT</c-def>属性设置成指定的<value>size</value>实现的。 +</para> + +<para> +这条指令在Linux、Solaris和Windows操作系统无效。 +</para> + +</directive> + + +<directive name="send_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置向客户端传输响应的超时。超时仅指两次相邻写操作之间的时间间隔，而非整个响应的传输时间。 +如果客户端在这段时间中没有收到任何数据，连接将关闭。 +</para> + +</directive> + + +<directive name="sendfile"> + +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if in location</context> + +<para> +开启或关闭使用<c-func>sendfile</c-func>调用。 +</para> + +</directive> + + +<directive name="sendfile_max_chunk"> + +<syntax><value>size</value></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置为非0值时，可以限制在一次<c-func>sendfile</c-func>调用时传输的数据量。 +如果不进行限制，一个快速的连接可能会霸占整个worker进程的所有资源。 +</para> + +</directive> + + +<directive name="server"> +<syntax block="yes"/> +<default/> +<context>http</context> + +<para> +表示开始设置虚拟主机的配置。 +nginx没有明显分隔IP-based(基于IP地址)和name-based(基于<header>Host</header>请求头)这两种类型的虚拟主机， +而是用<link id="listen"/>指令描述虚拟主机接受连接的地址和端口，用<link id="server_name"/>指令列出虚拟主机的所有主机名。 +在文档“<link doc="request_processing.xml">Nginx如何处理一个请求</link>”中提供了示例配置。 +</para> + +</directive> + + +<directive name="server_name"> +<syntax><value>name</value> ...</syntax> +<default>""</default> +<context>server</context> + +<para> +设置虚拟主机名，比如： +<example> +server { + server_name example.com www.example.com; +} +</example> +</para> + +<para> +第一个名字成为虚拟主机的首要主机名。 +</para> + +<para> +主机名中可以含有星号(“<literal>*</literal>”)，以替代名字的开始部分或结尾部分： +<example> +server { + server_name example.com *.example.com www.example.*; +} +</example> +上面这些名字称为通配符主机名。 +</para> + +<para> +上面例子中的前两个名字可以组合成一个： +<example> +server { + server_name .example.com; +} +</example> +</para> + +<para> +也可以在主机名中使用正则表达式，就是在名字前面补一个波浪线(“<literal>~</literal>”)： +<example> +server { + server_name www.example.com ~^www\d+\.example\.com$; +} +</example> +</para> + +<para> +可以在正则表达式中包含匹配组(0.7.40)，后续被其他指令使用： +<example> +server { + server_name ~^(www\.)?(.+)$; + + location / { + root /sites/$2; + } +} + +server { + server_name _; + + location / { + root /sites/default; + } +} +</example> +</para> + +<para> + +正则表达式中的命名匹配组可以创建变量(0.8.25)，后续被其他指令使用： +<example> +server { + server_name ~^(www\.)?(?<domain>.+)$; + + location / { + root /sites/$domain; + } +} + +server { + server_name _; + + location / { + root /sites/default; + } +} +</example> +</para> + +<para> +如果参数值等于“<var>$hostname</var>”(0.9.4)，将使用机器的hostname来替换。 +</para> + +<para> +nginx也允许定义空主机名(0.7.11)： +<example> +server { + server_name www.example.com ""; +} +</example> +这种主机名可以让虚拟主机处理没有<header>Host</header>请求头的请求，而不是让指定“地址:端口”的默认虚拟主机来处理。 +这是本指令的默认设置。 +<note> +在0.8.48版以前，机器的hostname被用作默认设置。 +</note> +</para> + +<para> +通过名字查找虚拟主机时，如果一个名字可以匹配多个指定的配置，比如同时匹配上通配符和正则表达式， +按下面优先级，使用先匹配上的虚拟主机： +<list type="enum"> + +<listitem> +确切的名字； +</listitem> + +<listitem> +最长的以星号起始的通配符名字，比如“<literal>*.example.com</literal>”； +</listitem> + +<listitem> +最长的以星号结束的通配符名字，比如“<literal>mail.*</literal>”； +</listitem> + +<listitem> +第一个匹配的正则表达式名字（按在配置文件中出现的顺序）。 +</listitem> + +</list> +</para> + +<para> +另一篇文档“<link doc="server_names.xml">虚拟主机名</link>”对虚拟主机名的有详细的描述。 +</para> + +</directive> + + +<directive name="server_name_in_redirect"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +开启或关闭nginx将<link id="server_name"/>指令指定的首要虚拟主机名用于发起的重定向的功能。 +关闭此功能时，nginx将使用<header>Host</header>请求头的中的名字，如果没有此请求头，nginx将使用虚拟主机所在的IP地址。 +</para> + +<para> +重定向中端口的使用由<link id="port_in_redirect"/>指令控制。 +</para> + +</directive> + + +<directive name="server_names_hash_bucket_size"> +<syntax><value>size</value></syntax> +<default>32|64|128</default> +<context>http</context> + +<para> +设置主机名哈希表的表项长度，其默认值取决于处理器的缓存线长度。 +另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。 +</para> + +</directive> + + +<directive name="server_names_hash_max_size"> +<syntax><value>size</value></syntax> +<default>512</default> +<context>http</context> + +<para> +设置主机名哈希表的最大<value>size</value>(桶容量)。 +另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。 +</para> + +</directive> + + +<directive name="server_tokens"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +开启或关闭在错误信息的<header>Server</header>响应头中输出nginx版本号。 +</para> + +</directive> + + +<directive name="tcp_nodelay"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +开启或关闭nginx使用<c-def>TCP_NODELAY</c-def>选项的功能。 +这个选项仅在将连接转变为长连接的时候才被启用。（译者注，在upstream发送响应到客户端时也会启用）。 +</para> + +</directive> + + +<directive name="tcp_nopush"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +开启或者关闭nginx在FreeBSD上使用<c-def>TCP_NOPUSH</c-def>套接字选项， +在Linux上使用<c-def>TCP_CORK</c-def>套接字选项。 +选项仅在使用<link id="sendfile"/>的时候才开启。 +开启此选项允许 +<list type="bullet"> + +<listitem> +在Linux和FreeBSD 4.*上将响应头和正文的开始部分一起发送； +</listitem> + +<listitem> +一次性发送整个文件。 +</listitem> + +</list> +</para> + +</directive> + + +<directive name="try_files"> +<syntax><value>file</value> ... <value>uri</value></syntax> +<syntax><value>file</value> ... =<value>code</value></syntax> +<default/> +<context>server</context> +<context>location</context> + +<para> +按指定顺序检查文件是否存在，并且使用第一个找到的文件来处理请求，那么处理过程就是在当前上下文环境中进行的。 +文件路径是根据<link id="root"/>指令和<link id="alias"/>指令，将<value>file</value>参数拼接而成。 +可以在名字尾部添加斜线以检查目录是否存在，比如“<literal>$uri/</literal>”。 +如果找不到任何文件，将按最后一个参数指定的<value>uri</value>进行内部跳转。 +比如： +<example> +location /images/ { + try_files $uri /images/default.gif; +} + +location = /images/default.gif { + expires 30s; +} +</example> +最后一个参数也可以指向一个命名路径，如下面的例子所示。 +从0.7.51版开始，最后一个参数也可以是<value>code</value>： +<example> +location / { + try_files $uri $uri/index.html $uri.html =404; +} +</example> +</para> + +<para> +下面是代理Mongrel的例子： +<example> +location / { + try_files /system/maintenance.html + $uri $uri/index.html $uri.html + @mongrel; +} + +location @mongrel { + proxy_pass http://mongrel; +} +</example> +</para> + +<para> +下面是Drupal用FastCGI的例子： +<example> +location / { + try_files $uri $uri/ @drupal; +} + +location ~ \.php$ { + try_files $uri @drupal; + + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + fastcgi_param SCRIPT_NAME $fastcgi_script_name; + fastcgi_param QUERY_STRING $args; + + ... other fastcgi_param's +} + +location @drupal { + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to/index.php; + fastcgi_param SCRIPT_NAME /index.php; + fastcgi_param QUERY_STRING q=$uri&$args; + + ... other fastcgi_param's +} +</example> +而下面的例子中 +<example> +location / { + try_files $uri $uri/ @drupal; +} +</example> +<literal>try_files</literal>指令等价于 +<example> +location / { + error_page 404 = @drupal; + log_not_found off; +} +</example> +然后是这里， +<example> +location ~ \.php$ { + try_files $uri @drupal; + + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + + ... +} +</example> +<literal>try_files</literal>在将请求发送到FastCGI服务器以前检查PHP文件是否存在。 +</para> + +<para> +下面是Wordpress和Joomla的例子： +<example> +location / { + try_files $uri $uri/ @wordpress; +} + +location ~ \.php$ { + try_files $uri @wordpress; + + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + ... other fastcgi_param's +} + +location @wordpress { + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to/index.php; + ... other fastcgi_param's +} +</example> +</para> + +</directive> + + +<directive name="types"> +<syntax block="yes"/> +<default> + text/html html; + image/gif gif; + image/jpeg jpg; +</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置文件扩展名和响应的MIME类型的映射表。 +可以将多个扩展名映射到同一种类型，比如： +<example> +types { + application/octet-stream bin exe dll; + application/octet-stream deb; + application/octet-stream dmg; +} +</example> +</para> + +<para> +随nginx发行的<path>conf/mime.types</path>文件中包含了足够全面的映射表。 +</para> + +<para> +为了是为某个路径的所有请求生成MIME类型“<literal>application/octet-stream</literal>”， +可以使用下面配置： +<example> +location /download/ { + types { } + default_type application/octet-stream; +} +</example> +</para> + +</directive> + + +<directive name="types_hash_bucket_size"> +<syntax><value>size</value></syntax> +<default>32|64|128</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置MIME类型哈希表的表项长度，其默认值取决于处理器的缓存线长度。 +另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。 +</para> + +</directive> + + +<directive name="types_hash_max_size"> +<syntax><value>size</value></syntax> +<default>1024</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置MIME类型哈希表的最大<value>size</value>(桶容量)。 +另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。 +</para> + +</directive> + + +<directive name="underscores_in_headers"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> + +<para> +允许或禁止在客户端请求头中使用下划线。 +如果禁止，含有下划线的请求头将被标志为非法请求头并接受<link id="ignore_invalid_headers"/>指令的处理。 +</para> + +<para> +可以在默认主机的<link id="server"/>配置级别定义此命令。这样，指令设置将覆盖监听同一地址和端口的所有虚拟主机。 +</para> + +</directive> + + +<directive name="variables_hash_bucket_size"> +<syntax><value>size</value></syntax> +<default>64</default> +<context>http</context> + +<para> +设置变量哈希表的表项长度，其默认值取决于处理器的缓存线长度。 +另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。 +</para> + +</directive> + + +<directive name="variables_hash_max_size"> +<syntax><value>size</value></syntax> +<default>512</default> +<context>http</context> + +<para> +设置变量哈希表的最大<value>size</value>(桶容量)。 +另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。 +</para> + +</directive> + +</section> + + +<section id="variables" name="内嵌变量"> + +<para> +<literal>ngx_http_core_module</literal>模块支持内嵌变量，变量名与Apache服务器对应。 +首先，这些变量可以表示客户端的请求头字段，诸如<var>$http_user_agent</var>、<var>$http_cookie</var>等等。 +nginx也支持其他变量： +<list type="tag"> + +<tag-name id="var_arg_"><var>$arg_</var><value>name</value></tag-name> +<tag-desc> +请求行中的<value>name</value>参数。 +</tag-desc> + +<tag-name id="var_args"><var>$args</var></tag-name> +<tag-desc> +请求行中参数字符串。 +</tag-desc> + +<tag-name id="var_binary_remote_addr"><var>$binary_remote_addr</var></tag-name> +<tag-desc> +客户端IP地址的二进制形式，值的长度总是4字节。 +</tag-desc> + +<tag-name id="var_body_bytes_sent"><var>$body_bytes_sent</var></tag-name> +<tag-desc> +nginx返回给客户端的字节数，不含响应头。 +</tag-desc> + +<tag-name id="var_bytes_sent"><var>$bytes_sent</var></tag-name> +<tag-desc> +nginx返回给客户端的字节数(1.3.8, 1.2.5)。 +</tag-desc> + +<tag-name id="var_connection"><var>$connection</var></tag-name> +<tag-desc> +连接的序列号(1.3.8, 1.2.5)。 +</tag-desc> + +<tag-name id="var_content_length"><var>$content_length</var></tag-name> +<tag-desc> +<header>Content-Length</header>请求头的值。 +</tag-desc> + +<tag-name id="var_content_type"><var>$content_type</var></tag-name> +<tag-desc> +<header>Content-Type</header>请求头的值。 +</tag-desc> + +<tag-name id="var_cookie_"><var>$cookie_</var><value>name</value></tag-name> +<tag-desc> +名为<value>name</value>的cookie。 +</tag-desc> + +<tag-name id="var_document_root"><var>$document_root</var></tag-name> +<tag-desc> +当前请求的<link id="root"/>指令或<link id="alias"/>指令的配置值。 +</tag-desc> + +<tag-name id="var_document_uri"><var>$document_uri</var></tag-name> +<tag-desc> +与<var>$uri</var>相同。 +</tag-desc> + +<tag-name id="var_host"><var>$host</var></tag-name> +<tag-desc> +<header>Host</header>请求头的值，如果没有该请求头，则为与请求对应的虚拟主机的首要主机名。 +</tag-desc> + +<tag-name id="var_hostname"><var>$hostname</var></tag-name> +<tag-desc> +机器名称。 +</tag-desc> + +<tag-name id="var_http_"><var>$http_</var><value>name</value></tag-name> +<tag-desc> +任意请求头的值；变量名的后半部为转化为小写并且用下划线替代横线后的请求头名称。 +</tag-desc> + +<tag-name id="var_https"><var>$https</var></tag-name> +<tag-desc> +如果连接是SSL模块，返回“<literal>on</literal>”，否则返回空字符串。 +</tag-desc> + +<tag-name id="var_is_args"><var>$is_args</var></tag-name> +<tag-desc> +如果请求行带有参数，返回“<literal>?</literal>”，否则返回空字符串。 +</tag-desc> + +<tag-name id="var_limit_rate"><var>$limit_rate</var></tag-name> +<tag-desc> +允许设置此值来限制连接的传输速率。 +</tag-desc> + +<tag-name id="var_msec"><var>$msec</var></tag-name> +<tag-desc> +当前时间，单位是秒，精度是毫秒。(1.3.9, 1.2.6) +</tag-desc> + +<tag-name id="var_nginx_version"><var>$nginx_version</var></tag-name> +<tag-desc> +nginx版本号。 +</tag-desc> + +<tag-name id="var_pid"><var>$pid</var></tag-name> +<tag-desc> +worker进程的PID。 +</tag-desc> + +<tag-name id="var_query_string"><var>$query_string</var></tag-name> +<tag-desc> +与<var>$args</var>相同。 +</tag-desc> + +<tag-name id="var_realpath_root"><var>$realpath_root</var></tag-name> +<tag-desc> +按<link id="root"/>指令或<link id="alias"/>指令算出的当前请求的绝对路径。其中的符号链接都会解析成真是文件路径。 +</tag-desc> + +<tag-name id="var_remote_addr"><var>$remote_addr</var></tag-name> +<tag-desc> +客户端IP地址。 +</tag-desc> + +<tag-name id="var_remote_port"><var>$remote_port</var></tag-name> +<tag-desc> +客户端端口。 +</tag-desc> + +<tag-name id="var_remote_user"><var>$remote_user</var></tag-name> +<tag-desc> +为基本用户认证提供的用户名。 +</tag-desc> + +<tag-name id="var_request"><var>$request</var></tag-name> +<tag-desc> +完整的原始请求行。 +</tag-desc> + +<tag-name id="var_request_body"><var>$request_body</var></tag-name> +<tag-desc> +请求正文。 +<para> +在由<link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>指令和 +<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>指令处理的路径中， +这个变量值可用。 +</para> +</tag-desc> + +<tag-name id="var_reuqest_body_file"><var>$request_body_file</var></tag-name> +<tag-desc> +请求正文的临时文件名。 +<para> +处理完成时，临时文件将被删除。 +如果希望总是将请求正文写入文件，需要开启<link id="client_body_in_file_only"/>。 +如果在被代理的请求或FastCGI请求中传递临时文件名，就应该禁止传递请求正文本身。 +使用<link doc="ngx_http_proxy_module.xml" id="proxy_pass_request_body">proxy_pass_request_body off</link>指令 +和<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass_request_body">fastcgi_pass_request_body off</link>指令 +分别禁止在代理和FastCGI中传递请求正文。 +</para> +</tag-desc> + +<tag-name id="var_request_complete"><var>$request_completion</var></tag-name> +<tag-desc> +请求完成时返回“<literal>OK</literal>”，否则返回空字符串。 +</tag-desc> + +<tag-name id="var_request_filename"><var>$request_filename</var></tag-name> +<tag-desc> +基于<link id="root"/>指令或<link id="alias"/>指令，以及请求URI，得到的当前请求的文件路径。 +</tag-desc> + +<tag-name id="var_request_method"><var>$request_method</var></tag-name> +<tag-desc> +HTTP方法，通常为“<literal>GET</literal>”或者“<literal>POST</literal>”。 +</tag-desc> + +<tag-name id="var_request_time"><var>$request_time</var></tag-name> +<tag-desc> +请求处理的时间，单位为秒，精度是毫秒(1.3.9, 1.2.6)；请求处理时间从由客户端接收到第一个字节开始计算。 +</tag-desc> + +<tag-name id="var_request_uri"><var>$request_uri</var></tag-name> +<tag-desc> +完整的原始请求行（带参数）。 +</tag-desc> + +<tag-name id="var_scheme"><var>$scheme</var></tag-name> +<tag-desc> +请求协议类型，为“<literal>http</literal>”或“<literal>https</literal>”。 +</tag-desc> + +<tag-name id="var_sent_http_"><var>$sent_http_</var><value>name</value></tag-name> +<tag-desc> +任意的响应头字段的值。 +变量名的后半部为转化为小写并且用下划线替代横线后的响应头名称。 +</tag-desc> + +<tag-name id="var_server_addr"><var>$server_addr</var></tag-name> +<tag-desc> +接受请求的服务器地址。 +<para> +为计算这个值，通常需要进行一次系统调用。为了避免系统调用，必须指定<link id="listen"/>指令 +的地址，并且使用<literal>bind</literal>参数。 +</para> +</tag-desc> + +<tag-name id="var_server_name"><var>$server_name</var></tag-name> +<tag-desc> +接受请求的虚拟主机的首要主机名。 +</tag-desc> + +<tag-name id="var_server_port"><var>$server_port</var></tag-name> +<tag-desc> +接受请求的虚拟主机的端口。 +</tag-desc> + +<tag-name id="var_server_protocol"><var>$server_protocol</var></tag-name> +<tag-desc> +请求协议，通常为“<literal>HTTP/1.0</literal>”或“<literal>HTTP/1.1</literal>”。 +</tag-desc> + +<tag-name id="var_status"><var>$status</var></tag-name> +<tag-desc> +响应状态码。 +</tag-desc> + +<tag-name id="var_tcpinfo_"> +<var>$tcpinfo_rtt</var>, +<var>$tcpinfo_rttvar</var>, +<var>$tcpinfo_snd_cwnd</var>, +<var>$tcpinfo_rcv_space</var> +</tag-name> +<tag-desc> +客户端TCP连接的信息，在支持套接字选项<c-def>TCP_INFO</c-def>的系统中可用。 +</tag-desc> + +<tag-name id="var_uri"><var>$uri</var></tag-name> +<tag-desc> +当前请求<link id="location">规范化</link>以后的URI。 +<para> +变量<var>$uri</var>的值可能随请求的处理过程而改变。 +比如，当进行内部跳转时，或者使用默认页文件。 +</para> +</tag-desc> + +</list> +</para> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_empty_gif_module.xml @@ -0,0 +1,54 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_empty_gif_module 模块" + link="/cn/docs/http/ngx_http_empty_gif_module.html" + lang="cn" + translator="yzprofile" + rev="1"> + + +<section id="summary"> + +<para> +模块 <literal>ngx_http_empty_gif_module</literal> 只返回一个透明像素的GIF图片。 +</para> + +</section> + + +<section id="example" name="配置范例"> + +<para> +<example> +location = /_.gif { + empty_gif; +} +</example> +</para> + +</section> + + +<section id="directives" name="指令"> + +<directive name="empty_gif"> +<syntax/> +<default/> +<context>location</context> + +<para> +在当前location里使用这个模块处理请求。 +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_flv_module.xml @@ -0,0 +1,65 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_flv_module 模块" + link="/en/docs/http/ngx_http_flv_module.html" + lang="cn" + translator="litianqing" + rev="1"> + +<section id="summary"> + +<para> +模块<literal>ngx_http_flv_module </literal> 为Flash Video(FLV)文件 +提供服务端伪流媒体支持 +</para> + +<para> +通过返回以请求偏移位置开始的文件内容，该模块专门处理 +在查询串中有<literal>start</literal>参数的请求, +和有预先设置到FLV头部的请求。 +</para> + +<para> +这个模块并不是默认构建的，必须通过配置参数 +<literal>--with-http_flv_module</literal> +来启用。 +</para> + +</section> + + +<section id="example" name="配置范例"> + +<para> +<example> +location ~ \.flv$ { + flv; +} +</example> +</para> + +</section> + + +<section id="directives" name="指令"> +<directive name="flv"> +<syntax/> +<default/> +<context>location</context> + +<para> +在当前location里使用这个模块处理请求。 +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_geo_module.xml @@ -0,0 +1,152 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_geo_module 模块" + link="/cn/docs/http/ngx_http_geo_module.html" + lang="cn" + translator="cfsego" + rev="1"> + +<section id="summary"> + +<para> +<literal>ngx_http_geo_module</literal> 模块创建变量，并根据客户端IP地址对变量赋值。 +</para> + +</section> + + +<section id="example" name="配置示例"> + +<para> +<example> +geo $geo { + default 0; + 127.0.0.1/32 2; + 192.168.1.0/24 1; + 10.1.0.0/16 1; +} +</example> +</para> + +</section> + + +<section id="directives" name="指令"> + +<directive name="geo"> +<syntax block="yes">[<value>$address</value>] <value>$variable</value></syntax> +<default/> +<context>http</context> + +<para> +定义从指定的变量获取客户端的IP地址。默认情况下，nginx从<var>$remote_addr</var>变量取得客户端IP地址，但也可以从其他变量获得（0.7.27版），比如： +<example> +geo $arg_remote_addr $geo { + ...; +} +</example> +如果该变量的值不能代表一个合法的IP地址，那么nginx将使用地址“<literal>255.255.255.255</literal>”。 +</para> + +<para> +nginx通过CIDR或者地址段（0.7.23版）来描述地址，同时支持下面的特殊参数： +<list type="tag"> + +<tag-name><literal>delete</literal></tag-name> +<tag-desc> +删除指定网络（0.7.23版）。 +</tag-desc> + +<tag-name><literal>default</literal></tag-name> +<tag-desc> +如果客户端地址不能匹配任意一个定义的地址，nginx将使用此值。 +如果使用CIDR，可以用“<literal>0.0.0.0/0</literal>”代替<literal>default</literal>。 +</tag-desc> + +<tag-name><literal>include</literal></tag-name> +<tag-desc> +包含一个定义地址和值的文件。可以多次包含。 +</tag-desc> + +<tag-name><literal>proxy</literal></tag-name> +<tag-desc> +定义可信地址（0.8.7，0.7.63版）。 +如果请求来自可信地址，nginx将使用其<header>X-Forwarded-For</header>头来获得地址。 +相对于普通地址，可信地址是顺序检测的。 +<note> +从1.3.0和1.2.1版本起，nginx开始支持IPv6地址。 +</note> +</tag-desc> + +<tag-name><literal>proxy_recursive</literal></tag-name> +<tag-desc> +开启递归查找地址（1.3.0，1.2.1版）。 +如果关闭递归查找，在客户端地址与某个可信地址匹配时，nginx将使用<header>X-Forwarded-For</header>中的最后一个地址来代替原始客户端地址。 +如果开启递归查找，在客户端地址与某个可信地址匹配时，nginx将使用<header>X-Forwarded-For</header>中最后一个与所有可信地址都不匹配的地址来代替原始客户端地址。 +</tag-desc> + +<tag-name><literal>ranges</literal></tag-name> +<tag-desc> +指示地址将定义为地址段的形式（0.7.23版）。这个参数应该第一个被定义。为了加速装载地址库，地址应按升序定义。 +</tag-desc> + +</list> +</para> + +<para> +举例： +<example> +geo $country { + default ZZ; + include conf/geo.conf; + delete 127.0.0.0/16; + proxy 192.168.100.0/24; + proxy 2001:0db8::/32; + + 127.0.0.0/24 US; + 127.0.0.1/32 RU; + 10.1.0.0/16 RU; + 192.168.1.0/24 UK; +} +</example> +</para> + +<para> +<path>conf/geo.conf</path>文件中可能包含下列文本行： +<example> +10.2.0.0/16 RU; +192.168.2.0/24 RU; +</example> +</para> + +<para> +nginx将使用能最精确匹配客户端地址的配置中定义的值。比如，对于地址127.0.0.1，nginx会选取“<literal>RU</literal>”而非“<literal>US</literal>”，作为变量值。 +</para> + +<para> +地址段的例子： +<example> +geo $country { + ranges; + default ZZ; + 127.0.0.0-127.0.0.0 US; + 127.0.0.1-127.0.0.1 RU; + 127.0.0.1-127.0.0.255 US; + 10.1.0.0-10.1.255.255 RU; + 192.168.1.0-192.168.1.255 UK; +} +</example> +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_geoip_module.xml @@ -0,0 +1,167 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_geoip_module 模块" + link="/cn/docs/http/ngx_http_geoip_module.html" + lang="cn" + translator="cfsego" + rev="1"> + +<section id="summary"> + +<para> +<literal>ngx_http_geoip_module</literal> 模块（0.8.6+）创建变量，使用预编译的<link url="http://www.maxmind.com">MaxMind</link>数据库解析客户端IP地址，得到变量值。 +</para> + +<para> +nginx默认不编译这个模块，需要开启<literal>--with-http_geoip_module</literal>编译选项。 +<note> +模块依赖<link url="http://www.maxmind.com/app/c">MaxMind GeoIP</link>库。 +</note> +</para> + +</section> + + +<section id="example" name="配置示例"> + +<para> +<example> +http { + geoip_country GeoIP.dat; + geoip_city GeoLiteCity.dat; + geoip_proxy 192.168.100.0/24; + geoip_proxy 2001:0db8::/32; + geoip_proxy_recursive on; + ... +</example> +</para> + +</section> + + +<section id="directives" name="指令"> + +<directive name="geoip_country"> +<syntax><value>database</value></syntax> +<default/> +<context>http</context> + +<para> +指定数据库，用于根据客户端IP地址得到其所在国家。 +使用这个数据库时，配置中可用下列变量： +<list type="tag"> + +<tag-name><var>$geoip_country_code</var></tag-name> +<tag-desc> +双字符国家代码，比如 +“<literal>RU</literal>”，“<literal>US</literal>”。 +</tag-desc> + +<tag-name><var>$geoip_country_code3</var></tag-name> +<tag-desc> +三字符国家代码，比如 +“<literal>RUS</literal>”，“<literal>USA</literal>”。 +</tag-desc> + +<tag-name><var>$geoip_country_name</var></tag-name> +<tag-desc> +国家名称，比如 +“<literal>Russian Federation</literal>”，“<literal>United States</literal>”。 +</tag-desc> + +</list> +</para> + +</directive> + + +<directive name="geoip_city"> +<syntax><value>database</value></syntax> +<default/> +<context>http</context> + +<para> +指定数据库，用于根据客户端IP地址得到其所在的国家、行政区和城市。 +使用这个数据库时，配置中可用下列变量： +<list type="tag"> + +<tag-name><var>$geoip_city_country_code</var></tag-name> +<tag-desc> +双字符国家代码，比如 +“<literal>RU</literal>”，“<literal>US</literal>”。 +</tag-desc> + +<tag-name><var>$geoip_city_country_code3</var></tag-name> +<tag-desc> +三字符国家代码，比如 +“<literal>RUS</literal>”，“<literal>USA</literal>”。 +</tag-desc> + +<tag-name><var>$geoip_city_country_name</var></tag-name> +<tag-desc> +国家名称，比如 +“<literal>Russian Federation</literal>”，“<literal>United States</literal>”。 +</tag-desc> + +<tag-name><var>$geoip_region</var></tag-name> +<tag-desc> +国家行政区名（行政区、直辖区、州、省、联邦管辖区，诸如此类），比如 +“<literal>Moscow City</literal>”，“<literal>DC</literal>”。 +</tag-desc> + +<tag-name><var>$geoip_city</var></tag-name> +<tag-desc> +城市名称，比如 +“<literal>Moscow</literal>”，“<literal>Washington</literal>”。 +</tag-desc> + +<tag-name><var>$geoip_postal_code</var></tag-name> +<tag-desc> +邮编。 +</tag-desc> + +</list> +</para> + +</directive> + + +<directive name="geoip_proxy"> +<syntax><value>address</value> | <value>CIDR</value></syntax> +<default/> +<context>http</context> +<appeared-in>1.3.0</appeared-in> +<appeared-in>1.2.1</appeared-in> + +<para> +定义可信地址。 +如果请求来自可信地址，nginx将使用其<header>X-Forwarded-For</header>头来获得地址。 +</para> + +</directive> + + +<directive name="geoip_proxy_recursive"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<appeared-in>1.3.0</appeared-in> +<appeared-in>1.2.1</appeared-in> + +<para> +如果关闭递归查找，在客户端地址与某个可信地址匹配时，nginx将使用<header>X-Forwarded-For</header>中的最后一个地址来代替原始客户端地址。 +如果开启递归查找，在客户端地址与某个可信地址匹配时，nginx将使用<header>X-Forwarded-For</header>中最后一个与所有可信地址都不匹配的地址来代替原始客户端地址。 +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_image_filter_module.xml @@ -0,0 +1,219 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_image_filter_module模块" + link="/cn/docs/http/ngx_http_image_filter_module.html" + lang="cn" + translator="Cen Zheng" + rev="1"> + +<section id="summary"> + +<para> +<literal>ngx_http_image_filter_module</literal> 模块（0.7.54+）是一个 +过滤器，它可以对JPEG,GIF和PNG等图像进行变换。 +</para> + +<para> +这个模块并不是默认编译的，需要通过 +<literal>--with-http_image_filter_module</literal>编译选项来启用。 +<note> +这个模块使用了 +<link url="http://libgd.org">libgd</link> 库。 +推荐使用这个库可用的最新版本；在写这个文档时它的最新版本是2.0.35。 +</note> +</para> + +</section> + + +<section id="example" name="配置例子"> + +<para> +<example> +location /img/ { + proxy_pass http://backend; + image_filter resize 150 100; + image_filter rotate 90; + error_page 415 = /empty; +} + +location = /empty { + empty_gif; +} +</example> +</para> + +</section> + + +<section id="directives" name="指令"> + +<directive name="image_filter"> +<syntax><literal>off</literal></syntax> +<syntax><literal>test</literal></syntax> +<syntax><literal>size</literal></syntax> +<syntax> + <literal>rotate</literal> + <literal>90</literal> | <literal>180</literal> | + <literal>270</literal></syntax> +<syntax> + <literal>resize</literal> + <value>width</value> + <value>height</value></syntax> +<syntax> + <literal>crop</literal> + <value>width</value> + <value>height</value></syntax> +<default/> +<context>location</context> + +<para> +设置图像变换的操作： +<list type="tag"> + +<tag-name><literal>off</literal></tag-name> +<tag-desc> +在所在location关闭模块处理。 +</tag-desc> + +<tag-name><literal>test</literal></tag-name> +<tag-desc> +确保应答是JPEG，GIF或PNG格式的图像。否则错误 +<http-status code="415" text="Unsupported Media Type"/> +将被返回。 +</tag-desc> + +<tag-name><literal>size</literal></tag-name> +<tag-desc> +以JSON格式返回图像信息。例如： +<example> +{ "img" : { "width": 100, "height": 100, "type": "gif" } } +</example> +如果有错误发生，将会返回如下： +<example> +{} +</example> +</tag-desc> + +<tag-name><literal>rotate</literal> +<literal>90</literal>|<literal>180</literal>|<literal>270</literal> +</tag-name> +<tag-desc> +将图像逆时针旋转指定角度。 +参数的值可以包含变量。 +可以单独使用，或与 +<literal>resize</literal> 和 <literal>crop</literal> 变换同时使用. +</tag-desc> + +<tag-name><literal>resize</literal> +<value>width</value> +<value>height</value> +</tag-name> +<tag-desc> +按比例缩小图像至指定大小。 +如果想只指定其中一维，另一维可以指定为： +“<literal>-</literal>”。 +如果有错误发生，服务器会返回 +<http-status code="415" text="Unsupported Media Type"/>. +参数的值可以包含变量。 +当与 <literal>rotate</literal> 参数同时使用时, +旋转发生在缩放 <emphasis>之后</emphasis>。 +</tag-desc> + +<tag-name><literal>crop</literal> +<value>width</value> +<value>height</value> +</tag-name> +<tag-desc> +按比例以图像的最短边为准对图像大小进行缩小，然后裁剪另一边多出来的部分。 +如果想只指定其中一维，另一维可以指定为： +“<literal>-</literal>”。 +如果有错误发生，服务器会返回 +<http-status code="415" text="Unsupported Media Type"/>. +参数的值可以包含变量。 +当与 <literal>rotate</literal> 参数同时使用时, +旋转发生在裁剪 <emphasis>之前</emphasis>。 +</tag-desc> + +</list> +</para> + +</directive> + + +<directive name="image_filter_buffer"> +<syntax><value>size</value></syntax> +<default>1M</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置用来读图像的缓冲区的最大值。 +若图像超过这个大小，服务器会返回 +<http-status code="415" text="Unsupported Media Type"/>. +</para> + +</directive> + + +<directive name="image_filter_jpeg_quality"> +<syntax><value>quality</value></syntax> +<default>75</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置变换后的JPEG图像的 <value>质量</value> 。 +可配置值： 1 ~ 100 。 +更小的值意味着更差的图像质量以及更少需要传输的数据。 +推荐的最大值是95. +参数的值可以包含变量。 +</para> + +</directive> + + +<directive name="image_filter_sharpen"> +<syntax><value>percent</value></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +增加最终图像的锐度。 +锐度百分比可以超过100. +0为关闭锐化。 +参数的值可以包含变量。 +</para> + +</directive> + + +<directive name="image_filter_transparency"> +<syntax><literal>on</literal>|<literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +定义当对PNG，或者GIF图像进行颜色变换时是否需要保留透明度。 +损失透明度有可能可以获得更高的图像质量。 +PNG图像中的alpha通道的透明度默认会一直被保留。 +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_limit_req_module.xml @@ -0,0 +1,153 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_limit_req_module 模块" + link="/cn/docs/http/ngx_http_limit_req_module.html" + lang="cn" + translator="Weibin Yao" + rev="1"> + +<section id="summary"> + +<para> +<literal>ngx_http_limit_req_module</literal>模块(0.7.21)可以通过定义的 +键值来限制请求处理的频率。特别的，它可以限制来自单个IP地址的请求处理频率。 +限制的方法是通过一种“漏桶”的方法——固定每秒处理的请求数，推迟过多的请求处理。 +</para> + + +</section> + + +<section id="example" name="配置示例"> + +<para> +<example> +http { + limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; + + ... + + server { + + ... + + location /search/ { + limit_req zone=one burst=5; + } +</example> +</para> + +</section> + + +<section id="directives" name="指令"> + +<directive name="limit_req"> +<syntax> + <literal>zone</literal>=<value>name</value> + [<literal>burst</literal>=<value>number</value>] + [<literal>nodelay</literal>]</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置对应的共享内存限制域和允许被处理的最大请求数阈值。 +如果请求的频率超过了限制域配置的值，请求处理会被延迟，所以 +所有的请求都是以定义的频率被处理的。 +超过频率限制的请求会被延迟，直到被延迟的请求数超过了定义的阈值 +这时，这个请求会被终止，并返回<http-status code="503" text="Service Temporarily Unavailable"/> +错误。这个阈值的默认值等于0。 +比如这些指令： +<example> +limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; + +server { + location /search/ { + limit_req zone=one burst=5; + } +</example> +限制平均每秒不超过一个请求，同时允许超过频率限制的请求数不多于5个。 +</para> + +<para> +如果不希望超过的请求被延迟，可以用<literal>nodelay</literal>参数： +<example> +limit_req zone=one burst=5 nodelay; +</example> +</para> + +</directive> + + +<directive name="limit_req_log_level"> +<syntax> +<literal>info</literal> | +<literal>notice</literal> | +<literal>warn</literal> | +<literal>error</literal></syntax> +<default>error</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>0.8.18</appeared-in> + +<para> +设置你所希望的日志级别，当服务器因为频率过高拒绝或者延迟处理请求时可以记下相应级别的日志。 +延迟记录的日志级别比拒绝的低一个级别；比如， +如果设置“<literal>limit_req_log_level notice</literal>”， +延迟的日志就是<literal>info</literal>级别。 +</para> + +</directive> + + +<directive name="limit_req_zone"> +<syntax> + <value>$variable</value> + <literal>zone</literal>=<value>name</value>:<value>size</value> + <literal>rate</literal>=<value>rate</value></syntax> +<default/> +<context>http</context> + +<para> +设置一块共享内存限制域的参数，它可以用来保存键值的状态。 +它特别保存了当前超出请求的数量。 +键的值就是指定的变量（空值不会被计算）。 +示例用法： +<example> +limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; +</example> +</para> + +<para> +这里，状态被存在名为“one”，最大10M字节的共享内存里面。对于这个限制域来说 +平均处理的请求频率不能超过每秒一次。 +</para> + +<para> +键值是客户端的IP地址。 +如果不使用<var>$remote_addr</var>变量，而用<var>$binary_remote_addr</var>变量， +可以将每条状态记录的大小减少到64个字节，这样1M的内存可以保存大约1万6千个64字节的记录。 +如果限制域的存储空间耗尽了，对于后续所有请求，服务器都会返回 +<http-status code="503" text="Service Temporarily Unavailable"/>错误。 +</para> + +<para> +请求频率可以设置为每秒几次（r/s）。如果请求的频率不到每秒一次， +你可以设置每分钟几次(r/m)。比如每秒半次就是30r/m。 +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_log_module.xml @@ -0,0 +1,266 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_log_module模块" + link="/cn/docs/http/ngx_http_log_module.html" + lang="cn" + translator="nigelzeng" + rev="3"> + +<section id="summary"> + +<para> +<literal>ngx_http_log_module</literal>模块按指定的格式写访问日志。 +</para> + +<para> +请求在处理结束时，会按请求路径的配置上下文记访问日志。 +如果在请求处理期间产生了<link doc="ngx_http_core_module.xml" id="internal">内部跳转</link>， +请求结束时的路径可能不同于原始的请求路径。 +</para> + +</section> + + +<section id="example" name="配置实例"> + +<para> +<example> +log_format gzip '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $bytes_sent ' + '"$http_referer" "$http_user_agent" "$gzip_ratio"'; + +access_log /spool/logs/nginx-access.log gzip buffer=32k; +</example> +</para> + +</section> + + +<section id="directives" name="指令"> + +<directive name="access_log"> +<syntax> + <value>path</value> + [<value>format</value> + [<literal>buffer</literal>=<value>size</value>]]</syntax> +<syntax><literal>off</literal></syntax> +<default>logs/access.log combined</default> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if in location</context> +<context>limit_except</context> + +<para> +为访问日志设置路径，格式和缓冲区大小（nginx访问日志支持缓存）。 +在同一个配置层级里可以指定多个日志。 +特定值<literal>off</literal>会取消当前配置层级里的所有<literal>access_log</literal>指令。 +如果没有指定日志格式则会使用预定义的“<literal>combined</literal>”格式。 +</para> + +<para> +缓冲区的大小不能超过磁盘文件原子性写入的大小。 +对于FreeBSD来说缓冲区大小是无限制的。 +</para> + +<para> +日志文件的路径可以包含变量（0.7.6+）， +但此类日志存在一些限制： +<list type="bullet"> + +<listitem> +工作进程使用的<link doc="../ngx_core_module.xml" id="user"/> +应拥有在目录里创建文件的权限； +</listitem> + +<listitem> +写缓冲无效； +</listitem> + +<listitem> +每条日志写入都会打开和关闭文件。然而，频繁使用的文件描述符可以存储在 +<link id="open_log_file_cache">缓存</link>中， +在<link id="open_log_file_cache"/>指令的<literal>valid</literal>参数指定的时间里， +写操作能持续写到旧文件。 +</listitem> + +<listitem> +每次日志写入的操作都会检查请求的 +<link doc="ngx_http_core_module.xml" id="root">根目录</link>是否存在， +如果不存在则日志不会被创建。 +因此在一个层级里同时指定<link doc="ngx_http_core_module.xml" id="root"/> +和<literal>access_log</literal>是一个不错的想法： +<example> +server { + root /spool/vhost/data/$host; + access_log /spool/vhost/logs/$host; + ... +</example> +</listitem> + +</list> +</para> + +</directive> + + +<directive name="log_format"> +<syntax> + <value>name</value> + <value>string</value> ...</syntax> +<default>combined "..."</default> +<context>http</context> + +<para> +指定日志的格式。 +</para> + +<para> +日志格式允许包含普通变量和只在日志写入时存在的变量： +<list type="tag"> + +<tag-name><var>$body_bytes_sent</var></tag-name> +<tag-desc> +发送给客户端的字节数，不包括响应头的大小； +该变量与Apache模块<literal>mod_log_config</literal>里的“<literal>%B</literal>”参数兼容。 +</tag-desc> + +<tag-name><var>$bytes_sent</var></tag-name> +<tag-desc> +发送给客户端的总字节数。 +</tag-desc> + +<tag-name><var>$connection</var></tag-name> +<tag-desc> +连接的序列号。 +</tag-desc> + +<tag-name><var>$connection_requests</var></tag-name> +<tag-desc> +当前通过一个连接获得的请求数量。 +</tag-desc> + +<tag-name><var>$msec</var></tag-name> +<tag-desc> +日志写入时间。单位为秒，精度是毫秒。 +</tag-desc> + +<tag-name><var>$pipe</var></tag-name> +<tag-desc> +如果请求是通过HTTP流水线(pipelined)发送，pipe值为“<literal>p</literal>”，否则为“<literal>.</literal>”。 +</tag-desc> + +<tag-name><var>$request_length</var></tag-name> +<tag-desc> +请求的长度（包括请求行，请求头和请求正文）。 +</tag-desc> + +<tag-name><var>$request_time</var></tag-name> +<tag-desc> +请求处理时间，单位为秒，精度毫秒； +从读入客户端的第一个字节开始，直到把最后一个字符发送给客户端后进行日志写入为止。 +</tag-desc> + +<tag-name><var>$status</var></tag-name> +<tag-desc> +响应状态。 +</tag-desc> + +<tag-name><var>$time_iso8601</var></tag-name> +<tag-desc> +ISO8601标准格式下的本地时间。 +</tag-desc> + +<tag-name><var>$time_local</var></tag-name> +<tag-desc> +通用日志格式下的本地时间。 +</tag-desc> + +</list> +</para> + +<para> +发送给客户端的响应头拥有“<literal>sent_http_</literal>”前缀。 +比如<var>$sent_http_content_range</var>。 +</para> + +<para> +配置始终包含预先定义的“<literal>combined</literal>”日志格式： +<example> +log_format combined '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $body_bytes_sent ' + '"$http_referer" "$http_user_agent"'; +</example> +</para> + +</directive> + + +<directive name="open_log_file_cache"> + +<syntax> +<literal>max</literal>=<value>N</value> +[<literal>inactive</literal>=<value>time</value>] +[<literal>min_uses</literal>=<value>N</value>] +[<literal>valid</literal>=<value>time</value>]</syntax> +<syntax><literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +定义一个缓存，用来存储频繁使用的文件名中包含变量的日志文件描述符。 +该指令包含以下参数： +<list type="tag"> + +<tag-name><literal>max</literal></tag-name> +<tag-desc> +设置缓存中描述符的最大数量；如果缓存被占满，最近最少使用（LRU）的描述符将被关闭。 +</tag-desc> + +<tag-name><literal>inactive</literal></tag-name> +<tag-desc> +设置缓存文件描述符在多长时间内没有被访问就关闭； +默认为10秒。 +</tag-desc> + +<tag-name><literal>min_uses</literal></tag-name> +<tag-desc> +设置在<literal>inactive</literal>参数指定的时间里， +最少访问多少次才能使文件描述符保留在缓存中；默认为1。 +</tag-desc> + +<tag-name><literal>valid</literal></tag-name> +<tag-desc> +设置一段用于检查超时后文件是否仍以同样名字存在的时间； +默认为60秒。 +</tag-desc> + +<tag-name><literal>off</literal></tag-name> +<tag-desc> +禁用缓存。 +</tag-desc> + +</list> +</para> + +<para> +使用实例： +<example> +open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2; +</example> +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_map_module.xml @@ -0,0 +1,186 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_map_module" + link="/cn/docs/http/ngx_http_map_module.html" + lang="cn" + translator="yzprofile" + rev="1"> + +<section id="summary"> + +<para> +模块 <literal>ngx_http_map_module</literal> 可以创建一些和另外变量相关联的变量。 +</para> + +</section> + + +<section id="example" name="配置范例"> + +<para> +<example> +map $http_host $name { + hostnames; + + default 0; + + example.com 1; + *.example.com 1; + example.org 2; + *.example.org 2; + .example.net 3; + wap.* 4; +} + +map $http_user_agent $mobile { + default 0; + "~Opera Mini" 1; +} +</example> +</para> + +</section> + + +<section id="directives" name="指令"> + +<directive name="map"> +<syntax block="yes"> + <value>string</value> + <value>$variable</value></syntax> +<default/> +<context>http</context> + +<para> +在配置的参数中，第一个是要创建新的变量，它的值取决于后面一个或多个源变量。 +<note> +在0.9.0版本之前，这里只支持一个变量。 +</note> +</para> + +<para> +在 <literal>map</literal> 块里的参数指定了源变量值和结果值的对应关系。 +</para> + +<para> +源变量值可以使用字符串或者正则表达式 (0.9.6)。 +</para> + +<para> +一个正则表达式如果以 “<literal>~</literal>” 开头，这个正则表达式对大小写敏感； +若以 “<literal>~*</literal>”开头 (1.0.4)，这个正则表达式对大小写不敏感。 +且正则表达式里可以包含命名捕获和位置捕获，这些变量可以跟结果变量一起被其它指令使用。 +</para> + +<para> +如果源变量的值正好跟特殊参数同名（看下面），它要以 “<literal>\</literal>” 字符作为前缀。 +</para> + +<para> +结果变量可以是一个字符串也可以是另外一个变量 (0.9.0)。 +</para> + +<para> +这个指令也支持三个特殊参数。 +<list type="tag"> +<tag-name><literal>default</literal> <value>value</value></tag-name> +<tag-desc> +如果源变量值没有匹配到任何变量，则设置一个默认值作为结果。 +当没有设置 <literal>default</literal>，将会用一个空的字符串作为默认的结果。 +</tag-desc> + +<tag-name><literal>hostnames</literal></tag-name> +<tag-desc> +允许用前缀或者后缀掩码指定域名作为源变量值，举个例子， +<example> +*.example.com 1; +example.* 1; +</example> +这两条记录 +<example> +example.com 1; +*.example.com 1; +</example> +可以被合并为： +<example> +.example.com 1; +</example> +这个参数必须写在值映射列表的最前面。 +</tag-desc> + +<tag-name><literal>include</literal> <value>file</value></tag-name> +<tag-desc> +包含一个或者多个存有映射值的文件。 +</tag-desc> + +</list> +</para> + +<para> +如果源值匹配了多余一个的指定变量，例如掩码和正则同时匹配，那么将会按照下面的顺序进行优先选择： +<list type="enum"> + +<listitem> +没有掩码的字符串 +</listitem> + +<listitem> +最长的带前缀的字符串，例如: “<literal>*.example.com</literal>” +</listitem> + +<listitem> +最长的带后缀的字符串，例如：“<literal>mail.*</literal>” +</listitem> + +<listitem> +按顺序第一个先匹配的正则表达式 （在配置文件中体现的顺序） +</listitem> + +<listitem> +默认值 +</listitem> + +</list> +</para> + +</directive> + + +<directive name="map_hash_bucket_size"> +<syntax><value>size</value></syntax> +<default>32|64|128</default> +<context>http</context> + +<para> +为 <link id="map"/> 的变量哈稀表设置桶大小。 +默认值取决于处理器cache line的大小。 +可以从这里获取到更多参考信息： +<link doc="../hash.xml">设置哈稀表</link>. +</para> + +</directive> + + +<directive name="map_hash_max_size"> +<syntax><value>size</value></syntax> +<default>2048</default> +<context>http</context> + +<para> +设置 <link id="map"/> 变量哈稀表<value>大小</value>的上限。 +可以从这里获取到更多参考信息： +<link doc="../hash.xml">设置哈稀表</link>. +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_proxy_module.xml @@ -0,0 +1,1103 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_proxy_module 模块" + link="/cn/docs/http/ngx_http_proxy_module.html" + lang="cn" + translator="cfsego" + rev="1"> + +<section id="summary"> + +<para> +<literal>ngx_http_proxy_module</literal> 模块允许传送请求到其它服务器。 +</para> + +</section> + + +<section id="example" name="配置示例"> + +<para> +<example> +location / { + proxy_pass http://localhost:8000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; +} +</example> +</para> + +</section> + + +<section id="directives" name="指令"> + +<directive name="proxy_buffer_size"> +<syntax><value>size</value></syntax> +<default>4k|8k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置缓冲区的大小为<value>size</value>。nginx从被代理的服务器读取响应时，使用该缓冲区保存响应的开始部分。这部分通常包含着一个小小的响应头。该缓冲区大小默认等于<link id="proxy_buffers"/>指令设置的一块缓冲区的大小，但它也可以被设置得更小。 +</para> + +</directive> + + +<directive name="proxy_buffering"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +代理的时候，开启或关闭缓冲后端服务器的响应。 +</para> + +<para> +当开启缓冲时，nginx尽可能快地从被代理的服务器接收响应，再将它存入<link id="proxy_buffer_size"/>和<link id="proxy_buffers"/>指令设置的缓冲区中。如果响应无法整个纳入内存，那么其中一部分将存入磁盘上的<link id="proxy_temp_path">临时文件</link>。<link id="proxy_max_temp_file_size"/>和<link id="proxy_temp_file_write_size"/>指令可以控制临时文件的写入。 +</para> + +<para> +当关闭缓冲时，收到响应后，nginx立即将其同步传给客户端。nginx不会尝试从被代理的服务器读取整个请求，而是将<link id="proxy_buffer_size"/>指令设定的大小作为一次读取的最大长度。 +</para> + +<para> +响应头<header>X-Accel-Buffering</header>传递“<literal>yes</literal>”或“<literal>no</literal>”可以动态地开启或关闭代理的缓冲功能。 +这个能力可以通过<link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/>指令关闭。 +</para> + +</directive> + + +<directive name="proxy_buffers"> +<syntax><value>number</value> <value>size</value></syntax> +<default>8 4k|8k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +为每个连接设置缓冲区的数量为<value>number</value>，每块缓冲区的大小为<value>size</value>。这些缓冲区用于保存从被代理的服务器读取的响应。每块缓冲区默认等于一个内存页的大小。这个值是4K还是8K，取决于平台。 +</para> + +</directive> + + +<directive name="proxy_busy_buffers_size"> +<syntax><value>size</value></syntax> +<default>8k|16k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +当开启<link id="proxy_buffering">缓冲</link>响应的功能以后，在没有读到全部响应的情况下，写缓冲到达一定<value>大小</value>时，nginx一定会向客户端发送响应，直到缓冲小于此值。这条指令用来设置此值。 +同时，剩余的缓冲区可以用于接收响应，如果需要，一部分内容将缓冲到临时文件。该<value>大小</value>默认是<link id="proxy_buffer_size"/>和<link id="proxy_buffers"/>指令设置单块缓冲大小的两倍。 +</para> + +</directive> + + +<directive name="proxy_cache"> +<syntax><value>zone</value> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +指定用于页面缓存的共享内存。同一块共享内存可以在多个地方使用。<literal>off</literal>参数可以屏蔽从上层配置继承的缓存功能。 +</para> + +</directive> + + +<directive name="proxy_cache_bypass"> +<syntax><value>string</value> ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +定义nginx不从缓存取响应的条件。如果至少一个字符串条件非空而且非“0”，nginx就不会从缓存中去取响应： +<example> +proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment; +proxy_cache_bypass $http_pragma $http_authorization; +</example> +本指令可和与<link id="proxy_no_cache"/>一起使用。 +</para> + +</directive> + + +<directive name="proxy_cache_key"> +<syntax><value>string</value></syntax> +<default>$scheme$proxy_host$request_uri</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +定义如何生成缓存的键，比如 +<example> +proxy_cache_key "$host$request_uri $cookie_user"; +</example> +这条指令的默认值类似于下面字符串 +<example> +proxy_cache_key $scheme$proxy_host$uri$is_args$args; +</example> +</para> + +</directive> + + +<directive name="proxy_cache_lock"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.12</appeared-in> + +<para> +开启此功能时，对于相同的请求，同时只允许一个请求发往后端，并根据<link id="proxy_cache_key"/>指令的设置在缓存中植入一个新条目。 +其他请求相同条目的请求将一直等待，直到缓存中出现相应的内容，或者锁在<link id="proxy_cache_lock_timeout"/>指令设置的超时后被释放。 +</para> + +</directive> + + +<directive name="proxy_cache_lock_timeout"> +<syntax><value>time</value></syntax> +<default>5s</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.12</appeared-in> + +<para> +为<link id="proxy_cache_lock"/>指令设置锁的超时。 +</para> + +</directive> + + +<directive name="proxy_cache_min_uses"> +<syntax><value>number</value></syntax> +<default>1</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置响应被缓存的最小请求<value>次数</value>。 +</para> + +</directive> + + +<directive name="proxy_cache_path"> +<syntax> + <value>path</value> + [<literal>levels</literal>=<value>levels</value>] + <literal>keys_zone</literal>=<value>name</value>:<value>size</value> + [<literal>inactive</literal>=<value>time</value>] + [<literal>max_size</literal>=<value>size</value>] + [<literal>loader_files</literal>=<value>number</value>] + [<literal>loader_sleep</literal>=<value>time</value>] + [<literal>loader_threshold</literal>=<value>time</value>]</syntax> +<default/> +<context>http</context> + +<para> +设置缓存的路径和其他参数。缓存数据是保存在文件中的，缓存的键和文件名都是在代理URL上执行MD5的结果。 + +<literal>levels</literal>参数定义了缓存的层次结构。比如，下面配置 +<example> +proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; +</example> +缓存中文件名看起来是这样的： +<example> +/data/nginx/cache/<emphasis>c</emphasis>/<emphasis>29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis> +</example> +</para> + +<para> +被缓存的响应首先写入一个临时文件，然后进行重命名。从0.8.9版本开始，临时文件和缓存可以放在不同的文件系统。但请注意，这将导致文件在这两个文件系统中进行拷贝，而不是廉价的重命名操作。因此，针对任何路径，都建议将缓存和<link id="proxy_temp_path"/>指令设置的临时文件目录放在同一文件系统。 +</para> + +<para> +此外，所有活动的键和缓存数据相关的信息都被存放在共享内存中。共享内存通过<literal>keys_zone</literal>参数的<value>name</value>和<value>size</value>来定义。被缓存的数据如果在<literal>inactive</literal>参数指定的时间内未被访问，就会被从缓存中移除，不论它是否是刚产生的。<literal>inactive</literal>的默认值是10分钟。 +</para> + +<para> +特殊进程“cache manager”监控缓存的条目数量，如果超过<literal>max_size</literal>参数设置的最大值，使用LRU算法移除缓存数据。 +</para> + +<para> +nginx新启动后不就，特殊进程“cache loader”就被启动。该进程将文件系统上保存的过去缓存的数据的相关信息重新加载到共享内存。加载过程分多次迭代完成，每次迭代，进程只加载不多于<literal>loader_files</literal>参数指定的文件数量（默认值为100）。此外，每次迭代过程的持续时间不能超过<literal>loader_threshold</literal>参数的值（默认200毫秒）。每次迭代之间，nginx的暂停时间由<literal>loader_sleep</literal>参数指定（默认50毫秒）。 +</para> + +</directive> + + +<directive name="proxy_cache_use_stale"> +<syntax> + <literal>error</literal> | + <literal>timeout</literal> | + <literal>invalid_header</literal> | + <literal>updating</literal> | + <literal>http_500</literal> | + <literal>http_502</literal> | + <literal>http_503</literal> | + <literal>http_504</literal> | + <literal>http_404</literal> | + <literal>off</literal> + ...</syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +如果后端服务器出现状况，nginx是可以使用过期的响应缓存的。这条指令就是定义何种条件下允许开启此机制。这条指令的参数与<link id="proxy_next_upstream"/>指令的参数相同。 +</para> + +<para> +此外，<literal>updating</literal>参数允许nginx在正在更新缓存的情况下使用过期的缓存作为响应。这样做可以使更新缓存数据时，访问源服务器的次数最少。 +</para> + +<para> +在植入新的缓存条目时，如果想使访问源服务器的次数最少，可以使用<link id="proxy_cache_lock"/>指令。 +</para> + +</directive> + + +<directive name="proxy_cache_valid"> +<syntax>[<value>code</value> ...] <value>time</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +为不同的响应状态码设置不同的缓存时间。比如，下面指令 +<example> +proxy_cache_valid 200 302 10m; +proxy_cache_valid 404 1m; +</example> +设置状态码为200和302的响应的缓存时间为10分钟，状态码为404的响应的缓存时间为1分钟。 +</para> + +<para> +如果仅仅指定了<value>time</value>， +<example> +proxy_cache_valid 5m; +</example> +那么只有状态码为200、300和302的响应会被缓存。 +</para> + +<para> +如果使用了<literal>any</literal>参数，那么就可以缓存任何响应： +<example> +proxy_cache_valid 200 302 10m; +proxy_cache_valid 301 1h; +proxy_cache_valid any 1m; +</example> +</para> + +<para> +缓存参数也可以直接在响应头中设定。这种方式的优先级高于使用这条指令设置缓存时间。 +<header>X-Accel-Expires</header>响应头可以以秒为单位设置响应的缓存时间，如果值为0，表示禁止缓存响应，如果值以<literal>@</literal>开始，表示自1970年1月1日以来的秒数，响应一直会被缓存到这个绝对时间点。 +如果不含<header>X-Accel-Expires</header>响应头，缓存参数仍可能被<header>Expires</header>或者<header>Cache-Control</header>响应头设置。 +如果响应头含有<header>Set-Cookie</header>，响应将不能被缓存。 +这些头的处理过程可以使用指令<link id="proxy_ignore_headers"/>忽略。 +</para> + +</directive> + + +<directive name="proxy_connect_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置与后端服务器建立连接的超时时间。应该注意这个超时一般不可能大于75秒。 +</para> + +</directive> + + +<directive name="proxy_cookie_domain"> +<syntax><literal>off</literal></syntax> +<syntax><value>domain</value> <value>replacement</value></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.15</appeared-in> + +<para> +设置<header>Set-Cookie</header>响应头中的<literal>domain</literal>属性的替换文本。 +假设后端服务器返回的<header>Set-Cookie</header>响应头含有属性“<literal>domain=localhost</literal>”，那么指令 +<example> +proxy_cookie_domain localhost example.org; +</example> +将这个属性改写为“<literal>domain=example.org</literal>”。 +</para> + +<para> +<value>domain</value>和<value>replacement</value>配置字符串，以及<literal>domain</literal>属性中起始的点将被忽略。 +匹配过程大小写不敏感。 +</para> + +<para> +<value>domain</value>和<value>replacement</value>配置字符串中可以包含变量： +<example> +proxy_cookie_domain www.$host $host; +</example> +</para> + +<para> +这条指令同样可以使用正则表达式。这时，<value>domain</value>应以“<literal>~</literal>”标志开始，且可以使用命名匹配组和位置匹配组，而<value>replacement</value>可以引用这些匹配组： +<example> +proxy_cookie_domain ~\.(?P<sl_domain>[-0-9a-z]+\.[a-z]+)$ $sl_domain; +</example> +</para> + +<para> +可以同时定义多条<literal>proxy_cookie_domain</literal>指令： +<example> +proxy_cookie_domain localhost example.org; +proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1; +</example> +</para> + +<para> +<literal>off</literal>参数可以取消当前配置级别的所有<literal>proxy_cookie_domain</literal>指令： +<example> +proxy_cookie_domain off; +proxy_cookie_domain localhost example.org; +proxy_cookie_domain www.example.org example.org; +</example> +</para> + +</directive> + + +<directive name="proxy_cookie_path"> +<syntax><literal>off</literal></syntax> +<syntax><value>path</value> <value>replacement</value></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.15</appeared-in> + +<para> +设置<header>Set-Cookie</header>响应头中的<literal>path</literal>属性的替换文本。 +假设后端服务器返回的<header>Set-Cookie</header>响应头含有属性“<literal>path=/two/some/uri/</literal>”，那么指令 +<example> +proxy_cookie_path /two/ /; +</example> +将这个属性改写为“<literal>path=/some/uri/</literal>”。 +</para> + +<para> +<value>path</value>和<value>replacement</value>配置字符串可以包含变量： +<example> +proxy_cookie_path $uri /some$uri; +</example> +</para> + +<para> +这条指令同样可以使用正则表达式。如果使用大小写敏感的匹配，<value>path</value>应以“<literal>~</literal>”标志开始，如果使用大小写不敏感的匹配，<value>path</value>应以“<literal>~*</literal>”标志开始。<value>path</value>可以使用命名匹配组和位置匹配组，<value>replacement</value>可以引用这些匹配组： +<example> +proxy_cookie_path ~*^/user/([^/]+) /u/$1; +</example> +</para> + +<para> +可以同时定义多条<literal>proxy_cookie_path</literal>指令： +<example> +proxy_cookie_path /one/ /; +proxy_cookie_path / /two/; +</example> +</para> + +<para> +<literal>off</literal>参数可以取消当前配置级别的所有<literal>proxy_cookie_path</literal>指令： +<example> +proxy_cookie_path off; +proxy_cookie_path /two/ /; +proxy_cookie_path ~*^/user/([^/]+) /u/$1; +</example> +</para> + +</directive> + + +<directive name="proxy_hide_header"> +<syntax><value>field</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +nginx默认不会将<header>Date</header>、<header>Server</header>、<header>X-Pad</header>，和<header>X-Accel-...</header>响应头发送给客户端。<literal>proxy_hide_header</literal>指令则可以设置额外的响应头，这些响应头也不会发送给客户端。相反的，如果希望允许传递某些响应头给客户端，可以使用<link id="proxy_pass_header"/>指令。 +</para> + +</directive> + + +<directive name="proxy_http_version"> +<syntax><literal>1.0</literal> | <literal>1.1</literal></syntax> +<default>1.0</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.1.4</appeared-in> + +<para> +设置代理使用的HTTP协议版本。默认使用的版本是1.0，而1.1版本则推荐在使用<link doc="ngx_http_upstream_module.xml" id="keepalive"/>连接时一起使用。 +</para> + +</directive> + + +<directive name="proxy_ignore_client_abort"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +决定当客户端在响应传输完成前就关闭连接时，nginx是否应关闭后端连接。 +</para> + +</directive> + + +<directive name="proxy_ignore_headers"> +<syntax><value>field</value> ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +不处理后端服务器返回的指定响应头。下面的响应头可以被设置： +<header>X-Accel-Redirect</header>，<header>X-Accel-Expires</header>，<header>X-Accel-Limit-Rate</header> (1.1.6)，<header>X-Accel-Buffering</header> (1.1.6)， +<header>X-Accel-Charset</header> (1.1.6)，<header>Expires</header>，<header>Cache-Control</header>，和<header>Set-Cookie</header> (0.8.44)。 +</para> + +<para> +如果不被取消，这些头部的处理可能产生下面结果： +<list type="bullet" compact="no"> + +<listitem> +<header>X-Accel-Expires</header>，<header>Expires</header>，<header>Cache-Control</header>，和<header>Set-Cookie</header> +设置响应<link id="proxy_cache_valid">缓存</link>的参数； +</listitem> + +<listitem> +<header>X-Accel-Redirect</header>执行到指定URI的<link doc="ngx_http_core_module.xml" id="internal">内部跳转</link>； +</listitem> + +<listitem> +<header>X-Accel-Limit-Rate</header>设置响应到客户端的传输<link doc="ngx_http_core_module.xml" id="limit_rate">速率限制</link>； +</listitem> + +<listitem> +<header>X-Accel-Buffering</header>启动或者关闭响应<link id="proxy_buffering">缓冲</link>； +</listitem> + +<listitem> +<header>X-Accel-Charset</header>设置响应所需的<link doc="ngx_http_charset_module.xml" id="charset">字符集</link>。 +</listitem> + +</list> +</para> + +</directive> + + +<directive name="proxy_intercept_errors"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +当后端服务器的响应状态码大于等于400时，决定是否直接将响应发送给客户端，亦或将响应转发给nginx由<link doc="ngx_http_core_module.xml" id="error_page"/>指令来处理。 +</para> + +</directive> + + +<directive name="proxy_max_temp_file_size"> +<syntax><value>size</value></syntax> +<default>1024m</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +打开响应<link id="proxy_buffering">缓冲</link>以后，如果整个响应不能存放在<link id="proxy_buffer_size"/>和<link id="proxy_buffers"/>指令设置的缓冲区内，部分响应可以存放在临时文件中。 +这条指令可以设置临时文件的最大<value>容量</value>。而每次写入临时文件的数据量则由<link id="proxy_temp_file_write_size"/>指令定义。 +</para> + +<para> +将此值设置为0将禁止响应写入临时文件。 +</para> + +</directive> + + +<directive name="proxy_next_upstream"> +<syntax> + <literal>error</literal> | + <literal>timeout</literal> | + <literal>invalid_header</literal> | + <literal>http_500</literal> | + <literal>http_502</literal> | + <literal>http_503</literal> | + <literal>http_504</literal> | + <literal>http_404</literal> | + <literal>off</literal> + ...</syntax> +<default>error timeout</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +指定在何种情况下一个失败的请求应该被发送到下一台后端服务器： +<list type="tag"> + +<tag-name><literal>error</literal></tag-name> +<tag-desc>和后端服务器建立连接时，或者向后端服务器发送请求时，或者从后端服务器接收响应头时，出现错误；</tag-desc> + +<tag-name><literal>timeout</literal></tag-name> +<tag-desc>和后端服务器建立连接时，或者向后端服务器发送请求时，或者从后端服务器接收响应头时，出现超时；</tag-desc> + +<tag-name><literal>invalid_header</literal></tag-name> +<tag-desc>后端服务器返回空响应或者非法响应头；</tag-desc> + +<tag-name><literal>http_500</literal></tag-name> +<tag-desc>后端服务器返回的响应状态码为500；</tag-desc> + +<tag-name><literal>http_502</literal></tag-name> +<tag-desc>后端服务器返回的响应状态码为502；</tag-desc> + +<tag-name><literal>http_503</literal></tag-name> +<tag-desc>后端服务器返回的响应状态码为503；</tag-desc> + +<tag-name><literal>http_504</literal></tag-name> +<tag-desc>后端服务器返回的响应状态码为504；</tag-desc> + +<tag-name><literal>http_404</literal></tag-name> +<tag-desc>后端服务器返回的响应状态码为404；</tag-desc> + +<tag-name><literal>off</literal></tag-name> +<tag-desc>停止将请求发送给下一台后端服务器。</tag-desc> + +</list> +</para> + +<para> +需要理解一点的是，只有在没有向客户端发送任何数据以前，将请求转给下一台后端服务器才是可行的。也就是说，如果在传输响应到客户端时出现错误或者超时，这类错误是不可能恢复的。 +</para> + +</directive> + + +<directive name="proxy_no_cache"> +<syntax><value>string</value> ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +定义nginx不将响应写入缓存的条件。如果至少一个字符串条件非空而且非“0”，nginx就不将响应存入缓存： +<example> +proxy_no_cache $cookie_nocache $arg_nocache$arg_comment; +proxy_no_cache $http_pragma $http_authorization; +</example> +这条指令可以和<link id="proxy_cache_bypass"/>指令一起使用。 +</para> + +</directive> + + +<directive name="proxy_pass"> +<syntax><value>URL</value></syntax> +<default/> +<context>location</context> +<context>if in location</context> +<context>limit_except</context> + +<para> +设置后端服务器的协议和地址，还可以设置可选的URI以定义本地路径和后端服务器的映射关系。 +这条指令可以设置的协议是“<literal>http</literal>”或者“<literal>https</literal>”，而地址既可以使用域名或者IP地址加端口（可选）的形式来定义： +<example> +proxy_pass http://localhost:8000/uri/; +</example> +又可以使用UNIX域套接字路径来定义。该路径接在“<literal>unix</literal>”字符串后面，两端由冒号所包围，比如： +<example> +proxy_pass http://unix:/tmp/backend.socket:/uri/; +</example> +</para> + +<para> +如果解析一个域名得到多个地址，所有的地址都会以轮转的方式被使用。当然，也可以使用<link doc="ngx_http_upstream_module.xml">服务器组</link>来定义地址。 +</para> + +<para> +请求URI按下面规则传送给后端服务器： +<list type="bullet" compact="no"> + +<listitem> +如果<literal>proxy_pass</literal>使用了URI，当传送请求到后端服务器时，<link doc="ngx_http_core_module.xml" id="location">规范化</link>以后的请求路径与配置中的路径的匹配部分将被替换为指令中定义的URI： +<example> +location /name/ { + proxy_pass http://127.0.0.1/remote/; +} +</example> +</listitem> + +<listitem> +如果<literal>proxy_pass</literal>没有使用URI，传送到后端服务器的请求URI一般客户端发起的原始URI，如果nginx改变了请求URI，则传送的URI是nginx改变以后完整的规范化URI： +<example> +location /some/path/ { + proxy_pass http://127.0.0.1; +} +</example> +<note> +在1.1.12版以前，如果<literal>proxy_pass</literal>没有使用URI，某些情况下，nginx改变URI以后，会错误地将原始URI而不是改变以后的URI发送到后端服务器。 +</note> +</listitem> +</list> +</para> + +<para> +某些情况下，无法确定请求URI中应该被替换的部分： +<list type="bullet" compact="no"> + +<listitem> +使用正则表达式定义路径。 +<para> +这种情况下，指令不应该使用URI。 +</para> +</listitem> + +<listitem> +在需要代理的路径中，使用<link doc="ngx_http_rewrite_module.xml" id="rewrite"/>指令改变了URI，但仍使用相同配置处理请求(<literal>break</literal>)： +<example> +location /name/ { + rewrite /name/([^/]+) /users?name=$1 break; + proxy_pass http://127.0.0.1; +} +</example> +<para> +这种情况下，本指令设置的URI会被忽略，改变后的URI将被发送给后端服务器。 +</para> +</listitem> +</list> +</para> + +<para> +后端服务器的地址，端口和URI中都可以使用变量： +<example> +proxy_pass http://$host$uri; +</example> +甚至像这样： +<example> +proxy_pass $request; +</example> +</para> + +<para> +这种情况下，后端服务器的地址将会在定义的<link doc="ngx_http_upstream_module.xml">服务器组</link>中查找。如果查找不到，nginx使用<link doc="ngx_http_core_module.xml" id="resolver"/>来查找该地址。 +</para> + +</directive> + + +<directive name="proxy_pass_header"> +<syntax><value>field</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +允许传送<link id="proxy_hide_header">被屏蔽</link>的后端服务器响应头到客户端。 +</para> + +</directive> + + +<directive name="proxy_read_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +定义从后端服务器读取响应的超时。此超时是指相邻两次读操作之间的最长时间间隔，而不是整个响应传输完成的最长时间。如果后端服务器在超时时间段内没有传输任何数据，连接将被关闭。 +</para> + +</directive> + + +<directive name="proxy_redirect"> +<syntax><literal>default</literal></syntax> +<syntax><literal>off</literal></syntax> +<syntax><value>redirect</value> <value>replacement</value></syntax> +<default>default</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置后端服务器<header>Location</header>响应头和<header>Refresh</header>响应头的替换文本。 +假设后端服务器返回的响应头是 +“<literal>Location: http://localhost:8000/two/some/uri/</literal>”，那么指令 +<example> +proxy_redirect http://localhost:8000/two/ http://frontend/one/; +</example> +将把字符串改写为 +“<literal>Location: http://frontend/one/some/uri/</literal>”。 +</para> + +<para> +<value>replacement</value>字符串可以省略服务器名： +<example> +proxy_redirect http://localhost:8000/two/ /; +</example> +此时将使用代理服务器的主域名和端口号来替换。如果端口是80，可以不加。 +</para> + +<para> +用<literal>default</literal>参数指定的默认替换使用了<link doc="ngx_http_core_module.xml" id="location"/>和<link id="proxy_pass"/>指令的参数。因此，下面两例配置等价： +<example> +location /one/ { + proxy_pass http://upstream:port/two/; + proxy_redirect default; +</example> + +<example> +location /one/ { + proxy_pass http://upstream:port/two/; + proxy_redirect http://upstream:port/two/ /one/; +</example> +而且因为同样的原因，<link id="proxy_pass"/>指令使用变量时，不允许本指令使用<literal>default</literal>参数。 +</para> + +<para> +<value>replacement</value>字符串可以包含变量： +<example> +proxy_redirect http://localhost:8000/ http://$host:$server_port/; +</example> +</para> + +<para> +而<value>redirect</value>字符串从1.1.11版本开始也可以包含变量： +<example> +proxy_redirect http://$proxy_host:8000/ /; +</example> +</para> + +<para> +同时，从1.1.11版本开始，指令支持正则表达式。使用正则表达式的话，如果是大小写敏感的匹配，<value>redirect</value>以“<literal>~</literal>”作为开始，如果是大小写不敏感的匹配，<value>redirect</value>以“<literal>~*</literal>”作为开始。而且<value>redirect</value>的正则表达式中可以包含命名匹配组和位置匹配组，而在<value>replacement</value>中可以引用这些匹配组的值： +<example> +proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2; +proxy_redirect ~*/user/([^/]+)/(.+)$ http://$1.example.com/$2; +</example> +</para> + +<para> +除此以外，可以同时定义多个<literal>proxy_redirect</literal>指令： +<example> +proxy_redirect default; +proxy_redirect http://localhost:8000/ /; +proxy_redirect http://www.example.com/ /; +</example> +</para> + +<para> +另外，<literal>off</literal>参数可以使所有相同配置级别的<literal>proxy_redirect</literal>指令无效： +<example> +proxy_redirect off; +proxy_redirect default; +proxy_redirect http://localhost:8000/ /; +proxy_redirect http://www.example.com/ /; +</example> +</para> + +<para> +最后，使用这条指令也可以为地址为相对地址的重定向添加域名： +<example> +proxy_redirect / /; +</example> +</para> + +</directive> + + +<directive name="proxy_send_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +定义向后端服务器传输请求的超时。此超时是指相邻两次写操作之间的最长时间间隔，而不是整个请求传输完成的最长时间。如果后端服务器在超时时间段内没有接收到任何数据，连接将被关闭。 +</para> + +</directive> + + +<directive name="proxy_set_header"> +<syntax><value>field</value> <value>value</value></syntax> +<default>Host $proxy_host</default> +<default>Connection close</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +允许重新定义或者添加发往后端服务器的请求头。<value>value</value>可以包含文本、变量或者它们的组合。 +当且仅当当前配置级别中没有定义<literal>proxy_set_header</literal>指令时，会从上面的级别继承配置。 +默认情况下，只有两个请求头会被重新定义： +<example> +proxy_set_header Host $proxy_host; +proxy_set_header Connection close; +</example> +</para> + +<para> +如果不想改变请求头<header>Host</header>的值，可以这样来设置： +<example> +proxy_set_header Host $http_host; +</example> +</para> + +<para> +但是，如果客户端请求头中没有携带这个头部，那么传递到后端服务器的请求也不含这个头部。 +这种情况下，更好的方式是使用<var>$host</var>变量——它的值在请求包含<header>Host</header>请求头时为<header>Host</header>字段的值，在请求未携带<header>Host</header>请求头时为虚拟主机的主域名： +<example> +proxy_set_header Host $host; +</example> +</para> + +<para> +此外，服务器名可以和后端服务器的端口一起传送： +<example> +proxy_set_header Host $host:$proxy_port; +</example> +</para> + +<para> +如果某个请求头的值为空，那么这个请求头将不会传送给后端服务器： +<example> +proxy_set_header Accept-Encoding ""; +</example> +</para> + +</directive> + + +<directive name="proxy_ssl_session_reuse"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +决定是否重用与后端服务器的SSL会话。如果日志中出现“<literal>SSL3_GET_FINISHED:digest check failed</literal>”错误，请尝试关闭会话重用。 +</para> + +</directive> + + +<directive name="proxy_store"> +<syntax> + <literal>on</literal> | + <literal>off</literal> | + <value>string</value></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +开启将文件保存到磁盘上的功能。如果设置为<literal>on</literal>，nginx将文件保存在<link doc="ngx_http_core_module.xml" id="alias"/>指令或<link doc="ngx_http_core_module.xml" id="root"/>指令设置的路径中。如果设置为<literal>off</literal>，nginx将关闭文件保存的功能。此外，保存的文件名也可以使用含变量的<value>string</value>参数来指定： +<example> +proxy_store /data/www$original_uri; +</example> +</para> + +<para> +保存文件的修改时间根据接收到的<header>Last-Modified</header>响应头来设置。响应都是先写到临时文件，然后进行重命名来生成的。从0.8.9版本开始，临时文件和持久化存储可以放在不同的文件系统，但是需要注意这时文件执行的是在两个文件系统间拷贝操作，而不是廉价的重命名操作。因此建议保存文件的路径和<link id="proxy_temp_path"/>指令设置的临时文件的路径在同一个文件系统中。 +</para> + +<para> +这条指令可以用于创建静态无更改文件的本地拷贝，比如： +<example> +location /images/ { + root /data/www; + open_file_cache_errors off; + error_page 404 = /fetch$uri; +} + +location /fetch/ { + internal; + + proxy_pass http://backend/; + proxy_store on; + proxy_store_access user:rw group:rw all:r; + proxy_temp_path /data/temp; + + alias /data/www/; +} +</example> +</para> + +<para> +或者像这样： +<example> +location /images/ { + root /data/www; + error_page 404 = @fetch; +} + +location @fetch { + internal; + + proxy_pass http://backend; + proxy_store on; + proxy_store_access user:rw group:rw all:r; + proxy_temp_path /data/temp; + + root /data/www; +} +</example> +</para> + +</directive> + + +<directive name="proxy_store_access"> +<syntax><value>users</value>:<value>permissions</value> ...</syntax> +<default>user:rw</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +设置新创建的文件和目录的访问权限，比如： +<example> +proxy_store_access user:rw group:rw all:r; +</example> +</para> + +<para> +如果指定了任何<literal>group</literal>或者<literal>all</literal>的访问权限，那么可以略去<literal>user</literal>的访问权限： +<example> +proxy_store_access group:rw all:r; +</example> +</para> + +</directive> + + +<directive name="proxy_temp_file_write_size"> +<syntax><value>size</value></syntax> +<default>8k|16k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +在开启缓冲后端服务器响应到临时文件的功能后，设置nginx每次写数据到临时文件的<value>size(大小)</value>限制。 +<value>size</value>的默认值是<link id="proxy_buffer_size"/>指令和<link id="proxy_buffers"/>指令定义的每块缓冲区大小的两倍， +而临时文件最大容量由<link id="proxy_max_temp_file_size"/>指令设置。 +</para> + +</directive> + + +<directive name="proxy_temp_path"> +<syntax> + <value>path</value> + [<value>level1</value> + [<value>level2</value> + [<value>level3</value>]]]</syntax> +<default>proxy_temp</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +定义从后端服务器接收的临时文件的存放路径，可以为临时文件路径定义至多三层子目录的目录树。 +比如，下面配置 +<example> +proxy_temp_path /spool/nginx/proxy_temp 1 2; +</example> +那么临时文件的路径看起来会是这样： +<example> +/spool/nginx/proxy_temp/<emphasis>7</emphasis>/<emphasis>45</emphasis>/00000123<emphasis>457</emphasis> +</example> +</para> + +</directive> + +</section> + + +<section id="variables" name="内嵌变量"> + +<para> +<literal>ngx_http_proxy_module</literal>支持内嵌变量，可以用于在<link id="proxy_set_header"/>指令中构造请求头： +<list type="tag"> + +<tag-name><var>$proxy_host</var></tag-name> +<tag-desc>后端服务器的主机名和端口；</tag-desc> + +<tag-name><var>$proxy_port</var></tag-name> +<tag-desc>后端服务器的端口；</tag-desc> + +<tag-name><var>$proxy_add_x_forwarded_for</var></tag-name> +<tag-desc>将<var>$remote_addr</var>变量值添加在客户端<header>X-Forwarded-For</header>请求头的后面，并以逗号分隔。 +如果客户端请求未携带<header>X-Forwarded-For</header>请求头，<var>$proxy_add_x_forwarded_for</var>变量值将与<var>$remote_addr</var>变量相同。</tag-desc> +</list> +</para> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_random_index_module.xml @@ -0,0 +1,62 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_random_index_module" + link="/en/docs/http/ngx_http_random_index_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The module <literal>ngx_http_random_index_module</literal> picks a random +file in a directory as an index file. +It works before the +<link doc="ngx_http_index_module.xml">ngx_http_index_module</link> +module. +</para> + +<para> +This module is not built by default, it should be enabled with the +<literal>--with-http_random_index_module</literal> +configuration parameter. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +location / { + random_index on; +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="random_index"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>location</context> + +<para> +Enables or disables module processing in a surrounding location. +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_realip_module.xml @@ -0,0 +1,112 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_realip_module" + link="/en/docs/http/ngx_http_realip_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_http_realip_module</literal> module allows +to change the client address to the one sent in the specified header field. +</para> + +<para> +This module is not built by default, it should be enabled with the +<literal>--with-http_realip_module</literal> +configuration parameter. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +set_real_ip_from 192.168.1.0/24; +set_real_ip_from 192.168.2.1; +set_real_ip_from 2001:0db8::/32; +real_ip_header X-Forwarded-For; +real_ip_recursive on; +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="set_real_ip_from"> +<syntax> + <value>address</value> | + <value>CIDR</value> | + <literal>unix:</literal></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines trusted addresses that are known to send correct +replacement addresses. +If the special value <literal>unix:</literal> is specified, +all UNIX-domain sockets will be trusted. +<note> +IPv6 addresses are supported starting from versions 1.3.0 and 1.2.1. +</note> +</para> + +</directive> + + +<directive name="real_ip_header"> +<syntax> + <value>field</value> | + <literal>X-Real-IP</literal> | + <literal>X-Forwarded-For</literal></syntax> +<default>X-Real-IP</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines a request header field used to send +the address for a replacement. +</para> + +</directive> + + +<directive name="real_ip_recursive"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<appeared-in>1.3.0</appeared-in> +<appeared-in>1.2.1</appeared-in> + +<para> +If recursive search is disabled, an original client address that +matches one of the trusted addresses is replaced by the last +address sent in the request header field defined by the +<link id="real_ip_header"/> directive. +If recursive search is enabled, an original client address that +matches one of the trusted addresses is replaced by the last +non-trusted address sent in the request header field. +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_referer_module.xml @@ -0,0 +1,141 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_referer_module模块" + link="/cn/docs/http/ngx_http_referer_module.html" + lang="cn" + translator="nigelzeng" + rev="1"> + +<section id="summary"> + +<para> +<literal>ngx_http_referer_module</literal>模块允许拦截<header>Referer</header>请求头中含有非法值的请求，阻止它们访问站点。 +需要注意的是伪造一个有效的<header>Referer</header>请求头是相当容易的， +因此这个模块的预期目的不在于彻底地阻止这些非法请求，而是为了阻止由正常浏览器发出的大规模此类请求。 +还有一点需要注意，即使正常浏览器发送的合法请求，也可能没有<header>Referer</header>请求头。 +</para> + +</section> + + +<section id="example" name="配置实例"> + +<para> +<example> +valid_referers none blocked server_names + *.example.com example.* www.example.org/galleries/ + ~\.google\.; + +if ($invalid_referer) { + return 403; +} +</example> +</para> + +</section> + + +<section id="directives" name="指令"> + +<directive name="referer_hash_bucket_size"> +<syntax><value>size</value></syntax> +<default>64</default> +<context>server</context> +<context>location</context> +<appeared-in>1.0.5</appeared-in> + +<para> +设置用来存储有效referer的哈希表的表项长度。 +详细的情况参见<link doc="../hash.xml">哈希表设置</link>。 +</para> + +</directive> + + +<directive name="referer_hash_max_size"> +<syntax><value>size</value></syntax> +<default>2048</default> +<context>server</context> +<context>location</context> +<appeared-in>1.0.5</appeared-in> + +<para> +设置用来存储有效referer的哈希表最大<value>桶容量</value>。 +详细的情况参见<link doc="../hash.xml">哈希表设置</link>。 +</para> + +</directive> + + +<directive name="valid_referers"> +<syntax> + <literal>none</literal> | + <literal>blocked</literal> | + <literal>server_names</literal> | + <value>string</value> + ...</syntax> +<default/> +<context>server</context> +<context>location</context> + +<para> +<header>Referer</header>请求头为指定值时，内嵌变量<var>$invalid_referer</var>被设置为空字符串， +否则这个变量会被置成“<literal>1</literal>”。查找匹配时不区分大小写。 +</para> + +<para> +该指令的参数可以为下面的内容： +<list type="tag"> + +<tag-name><literal>none</literal></tag-name> +<tag-desc> +缺少<header>Referer</header>请求头； +</tag-desc> + +<tag-name><literal>blocked</literal></tag-name> +<tag-desc> +<header>Referer</header> 请求头存在，但是它的值被防火墙或者代理服务器删除； +这些值都不以“<literal>http://</literal>” 或者 “<literal>https://</literal>”字符串作为开头； +</tag-desc> + +<tag-name><literal>server_names</literal></tag-name> +<tag-desc> +<header>Referer</header> 请求头包含某个虚拟主机名； +</tag-desc> + +<tag-name>任意字符串</tag-name> +<tag-desc> +定义一个服务器名和可选的URI前缀。服务器名允许在开头或结尾使用“<literal>*</literal>”符号。 +当nginx检查时，<header>Referer</header>请求头里的服务器端口将被忽略。 +</tag-desc> + +<tag-name>正则表达式</tag-name> +<tag-desc> +必须以“<literal>~</literal>”符号作为开头。 +需要注意的是表达式会从“<literal>http://</literal>”或者“<literal>https://</literal>”之后的文本开始匹配。 +</tag-desc> + +</list> +</para> + +<para> +实例: +<example> +valid_referers none blocked server_names + *.example.com example.* www.example.org/galleries/ + ~\.google\.; +</example> +</para> + +</directive> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_rewrite_module.xml @@ -0,0 +1,374 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_rewrite_module模块" + link="/cn/docs/http/ngx_http_rewrite_module.html" + lang="cn" + translator="cfsego" + rev="2"> + +<section id="summary"> + +<para> +<literal>ngx_http_rewrite_module</literal>模块允许正则替换URI，返回页面重定向，和按条件选择配置。 +</para> + +<para> +<literal>ngx_http_rewrite_module</literal>模块指令按以下顺序处理： +<list type="bullet"> + +<listitem> +处理在<link doc="ngx_http_core_module.xml" id="server"/>级别中定义的模块指令； +</listitem> + +<listitem> +为请求查找location； +</listitem> + +<listitem> +处理在选中的<link doc="ngx_http_core_module.xml" id="location"/>中定义的模块指令。如果指令改变了URI，按新的URI查找location。这个循环至多重复<link doc="ngx_http_core_module.xml" id="internal">10次</link>，之后nginx返回错误<http-status code="500" text="Internal Server Error"/>。 +</listitem> + +</list> +</para> + +</section> + + +<section id="directives" name="指令"> + +<directive name="break"> +<syntax/> +<default/> +<context>server</context> +<context>location</context> +<context>if</context> + +<para> +停止处理当前这一轮的<literal>ngx_http_rewrite_module</literal>指令集。 +</para> + +<para> +举例： +<example> +if ($slow) { + limit_rate 10k; + break; +} +</example> +</para> + +</directive> + + +<directive name="if"> +<syntax block="yes">(<value>condition</value>)</syntax> +<default/> +<context>server</context> +<context>location</context> + +<para> +计算指定的<value>condition</value>的值。如果为真，执行定义在大括号中的rewrite模块指令，并将<literal>if</literal>指令中的配置指定给请求。<literal>if</literal>指令会从上一层配置中继承配置。 +</para> + +<para> +条件可以是下列任意一种： +<list type="bullet"> + +<listitem> +变量名；如果变量值为空或者是以“<literal>0</literal>”开始的字符串，则条件为假； +</listitem> + +<listitem> +使用“<literal>=</literal>”和“<literal>!=</literal>”运算符比较变量和字符串； +</listitem> + +<listitem> +使用“<literal>~</literal>”（大小写敏感）和“<literal>~*</literal>”（大小写不敏感）运算符匹配变量和正则表达式。正则表达式可以包含匹配组，匹配结果后续可以使用变量<var>$1</var>..<var>$9</var>引用。如果正则表达式中包含字符“<literal>}</literal>”或者“<literal>;</literal>”，整个表达式应该被包含在单引号或双引号的引用中。 +</listitem> + +<listitem> +使用“<literal>-f</literal>”和“<literal>!-f</literal>”运算符检查文件是否存在； +</listitem> + +<listitem> +使用“<literal>-d</literal>”和“<literal>!-d</literal>”运算符检查目录是否存在； +</listitem> + +<listitem> +使用“<literal>-e</literal>”和“<literal>!-e</literal>”运算符检查文件、目录或符号链接是否存在； +</listitem> + +<listitem> +使用“<literal>-x</literal>”和“<literal>!-x</literal>”运算符检查可执行文件； +</listitem> + +</list> +</para> + +<para> +举例： +<example> +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; +} +</example> +<note> +内嵌变量<var>$invalid_referer</var>的值是通过<link doc="ngx_http_referer_module.xml" id="valid_referers"/>指令设置的。 +</note> +</para> + +</directive> + + +<directive name="return"> +<syntax><value>code</value> [<value>text</value>]</syntax> +<syntax><value>code</value> <value>URL</value></syntax> +<syntax><value>URL</value></syntax> +<default/> +<context>server</context> +<context>location</context> +<context>if</context> + +<para> +停止处理并返回指定<value>code</value>给客户端。返回非标准的状态码444可以直接关闭连接而不返回响应头。 +</para> + +<para> +从0.8.42版开始，可以在指令中指定重定向的URL（状态码为301、302、303和307），或者指定响应体<value>文本</value>（状态码为其它值）。响应体文本或重定向URL中可以包含变量。作为一种特殊情况，重定向URL可以简化为当前server的本地URI，那么完整的重定向URL将按照请求协议（<var>$scheme</var>）、<link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/>指令和<link doc="ngx_http_core_module.xml" id="port_in_redirect"/>指令的配置进行补全。 +</para> + +<para> +另外，状态码为302的临时重定向使用的<value>URL</value>可以作为指令的唯一参数。该参数应该以“<literal>http://</literal>”、“<literal>https://</literal>”或者“<literal>https://</literal>”开始。<value>URL</value>中可以包含变量。 +</para> + +<para> +<note> +0.7.51版本以前只能返回下面状态码： +204、400、402 — 406、408、410、411、413、416 和 500 — 504。 +</note> + +<note> +直到1.1.16和1.0.13版，状态码307才被认为是一种重定向。 +</note> +</para> + +</directive> + + +<directive name="rewrite"> +<syntax> + <value>regex</value> + <value>replacement</value> + [<value>flag</value>]</syntax> +<default/> +<context>server</context> +<context>location</context> +<context>if</context> + +<para> +如果指定的正则表达式能匹配URI，此URI将被<value>replacement</value>参数定义的字符串改写。<literal>rewrite</literal>指令按其在配置文件中出现的顺序执行。flag可以终止后续指令的执行。如果replacement的字符串以“<literal>http://</literal>”或“<literal>https://</literal>”开头，nginx将结束执行过程，并返回给客户端一个重定向。 +</para> + +<para> +可选的<value>flag</value>参数可以是其中之一： +<list type="tag"> + +<tag-name><literal>last</literal></tag-name> +<tag-desc> +停止执行当前这一轮的<literal>ngx_http_rewrite_module</literal>指令集，然后查找匹配改变后URI的新location； +</tag-desc> + +<tag-name><literal>break</literal></tag-name> +<tag-desc> +停止执行当前这一轮的<literal>ngx_http_rewrite_module</literal>指令集； +</tag-desc> + +<tag-name><literal>redirect</literal></tag-name> +<tag-desc> +在replacement字符串未以“<literal>http://</literal>”或“<literal>https://</literal>”开头时，使用返回状态码为302的临时重定向； +</tag-desc> + +<tag-name><literal>permanent</literal></tag-name> +<tag-desc> +返回状态码为301的永久重定向。 +</tag-desc> + +</list> +完整的重定向URL将按照请求协议（<var>$scheme</var>）、<link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/>指令和<link doc="ngx_http_core_module.xml" id="port_in_redirect"/>指令的配置进行补全。 +</para> + +<para> +举例： +<example> +server { + ... + rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; + rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last; + return 403; + ... +} +</example> +</para> + +<para> +但是当上述指令写在“<literal>/download/</literal>”的location中时，应使用标志<literal>break</literal>代替<literal>last</literal>，否则nginx会重复10轮循环，然后返回错误500： +<example> +location /download/ { + rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; + rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break; + return 403; +} +</example> +</para> + +<para> +如果<value>replacement</value>字符串包括新的请求参数，以往的请求参数会添加到新参数后面。如果不希望这样，在replacement字符串末尾加一个问号“？”，就可以避免，比如： +<example> +rewrite ^/users/(.*)$ /show?user=$1? last; +</example> +</para> + +<para> +如果正则表达式中包含字符“<literal>}</literal>”或者“<literal>;</literal>”，整个表达式应该被包含在单引号或双引号的引用中。 +</para> + +</directive> + + +<directive name="rewrite_log"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>off</default> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if</context> + +<para> +开启或者关闭将<literal>ngx_http_rewrite_module</literal>模块指令的处理日志以<literal>notice</literal>级别记录到错误日志中。 +</para> + +</directive> + + +<directive name="set"> +<syntax><value>variable</value> <value>value</value></syntax> +<default/> +<context>server</context> +<context>location</context> +<context>if</context> + +<para> +为指定变量<value>variable</value>设置变量值<value>value</value>。<value>value</value>可以包含文本、变量或者它们的组合。 +</para> + +</directive> + + +<directive name="uninitialized_variable_warn"> +<syntax><literal>on</literal> | <literal>off</literal></syntax> +<default>on</default> +<context>http</context> +<context>server</context> +<context>location</context> +<context>if</context> + +<para> +控制是否记录变量未初始化的警告到日志。 +</para> + +</directive> + +</section> + + +<section id="internals" name="内部实现"> + +<para> +<literal>ngx_http_rewrite_module</literal>模块的指令在解析配置阶段被编译成nginx内部指令。这些内部指令在处理请求时被解释执行。而解释器是一个简单的堆栈机器。 +</para> + +<para> +比如，下面指令 +<example> +location /download/ { + if ($forbidden) { + return 403; + } + + if ($slow) { + limit_rate 10k; + } + + rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; +} +</example> +将被翻译成下面这些指令： +<example> +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 +</example> +</para> + +<para> +请注意没有对应上面的<link doc="ngx_http_core_module.xml" id="limit_rate"/>指令的内部指令，因为这个指令与<literal>ngx_http_rewrite_module</literal>模块无关。nginx会为这个<link id="if"/>块单独创建一个配置，包含<literal>limit_rate</literal>等于10k。如果条件为真，nginx将把这个配置指派给请求。 +</para> + +<para> +指令 +<example> +rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; +</example> +可以通过将正则表达式中的第一个斜线“/”放入圆括号，来实现节约一个内部指令： +<example> +rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; +</example> +对应的内部指令将会是这样： +<example> +match of regular expression +copy $1 +copy "/mp3/" +copy $2 +copy ".mp3" +end of regular expression +end of code +</example> +</para> + +</section> + +</module>
new file mode 100644 --- /dev/null +++ b/xml/cn/docs/http/ngx_http_upstream_module.xml @@ -0,0 +1,366 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="ngx_http_upstream_module模块" + link="/cn/docs/http/ngx_http_upstream_module.html" + lang="cn" + translator="Weibin Yao" + rev="1"> + +<section id="summary"> + +<para> +<literal>ngx_http_upstream_module</literal>模块 +允许定义一组服务器。它们可以在指令<link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>、 +<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>和 +<link doc="ngx_http_memcached_module.xml" id="memcached_pass"/>中被引用到。 +</para> + +</section> + + +<section id="example" name="配置例子"> + +<para> +<example> +upstream <emphasis>backend</emphasis> { + server backend1.example.com weight=5; + server backend2.example.com:8080; + server unix:/tmp/backend3; + + server backup1.example.com:8080 backup; + server backup2.example.com:8080 backup; +} + +server { + location / { + proxy_pass http://<emphasis>backend</emphasis>; + } +} +</example> +</para> + +</section> + + +<section id="directives" name="指令"> + +<directive name="upstream"> +<syntax block="yes"><value>name</value></syntax> +<default/> +<context>http</context> + +<para> +定义一组服务器。 +这些服务器可以监听不同的端口。 +而且，监听在TCP和UNIX域套接字的服务器可以混用。 +</para> + +<para> +例子： +<example> +upstream backend { + server backend1.example.com weight=5; + server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; + server unix:/tmp/backend3; +} +</example> +</para> + +<para> +默认情况下，nginx按加权轮转的方式将请求分发到各服务器。 +在上面的例子中，每7个请求会通过以下方式分发： +5个请求分到<literal>backend1.example.com</literal>， +一个请求分到第二个服务器，一个请求分到第三个服务器。 +与服务器通信的时候，如果出现错误，请求会被传给下一个服务器，直到所有可用的服务器都被尝试过。 +如果所有服务器都返回失败，客户端将会得到最后通信的那个服务器的（失败）响应结果。 +</para> + +</directive> + + +<directive name="server"> +<syntax><value>address</value> [<value>parameters</value>]</syntax> +<default/> +<context>upstream</context> + +<para> +定义服务器的地址<value>address</value>和其他参数<value>parameters</value>。 +地址可以是域名或者IP地址，端口是可选的，或者是指定“<literal>unix:</literal>”前缀的UNIX域套接字的路径。如果没有指定端口，就使用80端口。 +如果一个域名解析到多个IP，本质上是定义了多个server。 +</para> + +<para> +你可以定义下面的参数： +<list type="tag"> + +<tag-name><literal>weight</literal>=<value>number</value></tag-name> +<tag-desc> +设定服务器的权重，默认是1。 +</tag-desc> + +<tag-name><literal>max_fails</literal>=<value>number</value></tag-name> +<tag-desc> +设定Nginx与服务器通信的尝试失败的次数。在<literal>fail_timeout</literal>参数定义的时间段内，如果失败的次数达到此值，Nginx就认为服务器不可用。在下一个<literal>fail_timeout</literal>时间段，服务器不会再被尝试。 +失败的尝试次数默认是1。设为0就会停止统计尝试次数，认为服务器是一直可用的。 +你可以通过指令<link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>、 +<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>和 +<link doc="ngx_http_memcached_module.xml" id="memcached_next_upstream"/>来配置什么是失败的尝试。 +默认配置时，<literal>http_404</literal>状态不被认为是失败的尝试。 +</tag-desc> + +<tag-name><literal>fail_timeout</literal>=<value>time</value></tag-name> +<tag-desc> +设定 +<list type="bullet"> + +<listitem> +统计失败尝试次数的时间段。在这段时间中，服务器失败次数达到指定的尝试次数，服务器就被认为不可用。 +</listitem> + +<listitem> +服务器被认为不可用的时间段。 +</listitem> + +</list> +默认情况下，该超时时间是10秒。 +</tag-desc> + +<tag-name><literal>backup</literal></tag-name> +<tag-desc> +标记为备用服务器。当主服务器不可用以后，请求会被传给这些服务器。 +</tag-desc> + +<tag-name><literal>down</literal></tag-name> +<tag-desc> +标记服务器永久不可用，可以跟<link id="ip_hash"/>指令一起使用。 +</tag-desc> + +</list> +</para> + +<para> +Example: +<example> +upstream backend { + server backend1.example.com weight=5; + server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; + server unix:/tmp/backend3; + + server backup1.example.com:8080 backup; +} +</example> +</para> + +</directive> + + +<directive name="ip_hash"> +<syntax/> +<default/> +<context>upstream</context> + +<para> +指定服务器组的负载均衡方法，请求基于客户端的IP地址在服务器间进行分发。 +IPv4地址的前三个字节或者IPv6的整个地址，会被用来作为一个散列key。 +这种方法可以确保从同一个客户端过来的请求，会被传给同一台服务器。除了当服务器被认为不可用的时候，这些客户端的请求会被传给其他服务器，而且很有可能也是同一台服务器。 +<note> +从1.3.2和1.2.2版本开始支持IPv6地址。 +</note> +</para> + +<para> +如果其中一个服务器想暂时移除，应该加上<literal>down</literal>参数。这样可以保留当前客户端IP地址散列分布。 +</para> + +<para> +例子： +<example> +upstream backend { + ip_hash; + + server backend1.example.com; + server backend2.example.com; + server backend3.example.com <emphasis>down</emphasis>; + server backend4.example.com; +} +</example> +</para> + +<para> +<note> +从1.3.1和1.2.2版本开始，<literal>ip_hash</literal>的负载均衡方法才支持设置服务器权重值。 +</note> +</para> + +</directive> + + +<directive name="keepalive"> +<syntax><value>connections</value></syntax> +<default/> +<context>upstream</context> +<appeared-in>1.1.4</appeared-in> + +<para> +激活对上游服务器的连接进行缓存。 +</para> + +<para> +<value>connections</value>参数设置每个worker进程与后端服务器保持连接的最大数量。这些保持的连接会被放入缓存。 +如果连接数大于这个值时，最久未使用的连接会被关闭。 +<note> +需要注意的是，<literal>keepalive</literal>指令不会限制Nginx进程与上游服务器的连接总数。 +新的连接总会按需被创建。 +<value>connections</value>参数应该稍微设低一点，以便上游服务器也能处理额外新进来的连接。 +</note> +</para> + +<para> +配置memcached上游服务器连接keepalive的例子： +<example> +upstream memcached_backend { + server 127.0.0.1:11211; + server 10.0.0.2:11211; + + keepalive 32; +} + +server { + ... + + location /memcached/ { + set $memcached_key $uri; + memcached_pass memcached_backend; + } + +} +</example> +</para> + +<para> +对于HTTP代理，<link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/>指令应该设置为“<literal>1.1</literal>”，同时<header>Connection</header>头的值也应被清空。 +<example> +upstream http_backend { + server 127.0.0.1:8080; + + keepalive 16; +} + +server { + ... + + location /http/ { + proxy_pass http://http_backend; + proxy_http_version 1.1; + proxy_set_header Connection ""; + ... + } +} +</example> +</para> + +<para> +<note> +另外一种选择是，HTTP/1.0协议的持久连接也可以通过发送<header>Connection: Keep-Alive</header>头来实现。不过不建议这样用。 +</note> +</para> + +<para> +对于FastCGI的服务器，需要设置 +<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_keep_conn"/> +指令来让连接keepalive工作： +<example> +upstream fastcgi_backend { + server 127.0.0.1:9000; + + keepalive 8; +} + +server { + ... + + location /fastcgi/ { + fastcgi_pass fastcgi_backend; + fastcgi_keep_conn on; + ... + } +} +</example> +</para> + +<para> +<note> +当使用的负载均衡方法不是默认的轮转法时，必须在<literal>keepalive</literal> 指令之前配置。 +</note> + +<note> +针对SCGI和uwsgi协议，还没有实现其keepalive连接的打算。 +</note> +</para> + +</directive> + + +<directive name="least_conn"> +<syntax/> +<default/> +<context>upstream</context> +<appeared-in>1.3.1</appeared-in> +<appeared-in>1.2.2</appeared-in> + +<para> +指定服务器组的负载均衡方法，根据其权重值，将请求发送到活跃连接数最少的那台服务器。 +如果这样的服务器有多台，那就采取有权重的轮转法进行尝试。 +</para> + +</directive> + +</section> + + +<section id="variables" name="嵌入的变量"> + +<para> +<literal>ngx_http_upstream_module</literal>模块支持以下嵌入变量： + +<list type="tag"> + +<tag-name><var>$upstream_addr</var></tag-name> +<tag-desc> +保存服务器的IP地址和端口或者是UNIX域套接字的路径。 +在请求处理过程中，如果有多台服务器被尝试了，它们的地址会被拼接起来，以逗号隔开，比如： +“<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”。 +如果在服务器之间通过<header>X-Accel-Redirect</header>头或者<link doc="ngx_http_core_module.xml" id="error_page"/>有内部跳转，那么这些服务器组之间会以冒号隔开，比如：“<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80</literal>”。 +</tag-desc> + +<tag-name><var>$upstream_response_time</var></tag-name> +<tag-desc> +以毫秒的精度保留服务器的响应时间，（输出）单位是秒。 +出现多个响应时，也是以逗号和冒号隔开。 +</tag-desc> + +<tag-name><var>$upstream_status</var></tag-name> +<tag-desc> +保存服务器的响应代码。 +出现多个响应时，也是以逗号和冒号隔开。 +</tag-desc> + +<tag-name><var>$upstream_http_...</var></tag-name> +<tag-desc> +保存服务器的响应头的值。比如<header>Server</header>响应头的值可以通过<var>$upstream_http_server</var>变量来获取。 +需要注意的是只有最后一个响应的头会被保留下来。 +</tag-desc> + +</list> +</para> + +</section> + +</module>
--- a/xml/cn/docs/index.xml +++ b/xml/cn/docs/index.xml @@ -8,7 +8,7 @@ <article name="Nginx文档" link="/cn/docs/" lang="cn" - rev="3" + rev="4" toc="no"> @@ -93,11 +93,36 @@ ngx_http_browser_module</link> </listitem> <listitem> +<link doc="http/ngx_http_core_module.xml"> +ngx_http_core_module</link> +</listitem> + +<listitem> +<link doc="http/ngx_http_empty_gif_module.xml"> +ngx_http_empty_gif_module</link> +</listitem> + +<listitem> +<link doc="http/ngx_http_geo_module.xml"> +ngx_http_geo_module</link> +</listitem> + +<listitem> +<link doc="http/ngx_http_geoip_module.xml"> +ngx_http_geoip_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_gzip_static_module.xml"> ngx_http_gzip_static_module</link> </listitem> <listitem> +<link doc="http/ngx_http_image_filter_module.xml"> +ngx_http_image_filter_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_index_module.xml"> ngx_http_index_module</link> </listitem> @@ -107,6 +132,41 @@ ngx_http_index_module</link> ngx_http_limit_conn_module</link> </listitem> +<listitem> +<link doc="http/ngx_http_limit_req_module.xml"> +ngx_http_limit_req_module</link> +</listitem> + +<listitem> +<link doc="http/ngx_http_log_module.xml"> +ngx_http_log_module</link> +</listitem> + +<listitem> +<link doc="http/ngx_http_map_module.xml"> +ngx_http_map_module</link> +</listitem> + +<listitem> +<link doc="http/ngx_http_proxy_module.xml"> +ngx_http_proxy_module</link> +</listitem> + +<listitem> +<link doc="http/ngx_http_referer_module.xml"> +ngx_http_referer_module</link> +</listitem> + +<listitem> +<link doc="http/ngx_http_rewrite_module.xml"> +ngx_http_rewrite_module</link> +</listitem> + +<listitem> +<link doc="http/ngx_http_upstream_module.xml"> +ngx_http_upstream_module</link> +</listitem> + </list> </para>