Mercurial > hg > nginx-site

comparison xml/cn/docs/http/ngx_http_core_module.xml @ 792:ceb8a4e374b7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated the Chinese documentation.
author Ruslan Ermilov <ru@nginx.com>
date Tue, 25 Dec 2012 06:34:37 +0000
parents
children ff357b676c2e
comparison
equal deleted inserted replaced
791:15f2bab0740d 792:ceb8a4e374b7
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Igor Sysoev
5 Copyright (C) Nginx, Inc.
6 -->
7
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9
10 <module name="ngx_http_core_module 模块"
11 link="/cn/docs/http/ngx_http_core_module.html"
12 lang="cn"
13 translator="cfsego"
14 rev="13">
15
16 <section id="directives" name="指令">
17
18 <directive name="aio">
19 <syntax>
20 <literal>on</literal> |
21 <literal>off</literal> |
22 <literal>sendfile</literal></syntax>
23 <default>off</default>
24 <context>http</context>
25 <context>server</context>
26 <context>location</context>
27 <appeared-in>0.8.11</appeared-in>
28
29 <para>
30 在FreeBSD和Linux操作系统上启用或者禁用异步文件I/O(AIO)。
31 </para>
32
33 <para>
34 从FreeBSD 4.3版本开始，可以使用AIO。AIO既可以静态链接到内核中：
35 <example>
36 options VFS_AIO
37 </example>
38 又可以作为内核模块动态加载：
39 <example>
40 kldload aio
41 </example>
42 </para>
43
44 <para>
45 在FreeBSD第5版和第6版，静态启动AIO，或者在系统启动时动态加载AIO，都会触发网络子系统使用一把大锁，进而对整个系统的性能造成负面影响。
46 这个限制在2009年发布的FreeBSD 6.4稳定版和FreeBSD 7中被消除。
47 虽然如此，仍有方法在5.3及以上版本的FreeBSD中开启AIO而不触发网络子系统的大锁，那就是在内核启动以后加载AIO模块。
48 使用这种时，<path>/var/log/messages</path>中会出现下面信息，
49 <example>
50 WARNING: Network stack Giant-free, but aio requires Giant.
51 Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0
52 </example>
53 但可以安全的忽略它。
54 <note>
55 使用AIO大锁的是FreeBSD套接字上的<c-func>aio_read</c-func>和<c-func>aio_write</c-func>异步操作。但是nginx仅仅在磁盘I/O使用AIO，所以不会出现问题。
56 </note>
57 </para>
58
59 <para>
60 为了让AIO工作，需要关闭<link id="sendfile"/>：
61 <example>
62 location /video/ {
63 sendfile off;
64 aio on;
65 output_buffers 1 64k;
66 }
67 </example>
68 </para>
69
70 <para>
71 不过，从FreeBSD 5.2.1版和nginx 0.8.12版开始，AIO也可以为<c-func>sendfile</c-func>预读数据：
72 <example>
73 location /video/ {
74 sendfile on;
75 tcp_nopush on;
76 aio sendfile;
77 }
78 </example>
79
80 这个配置使nginx在调用<c-func>sendfile</c-func>时带<c-def>SF_NODISKIO</c-def>参数，
81 那么<c-func>sendfile</c-func>在数据没有读入内存的时候，就不会阻塞在磁盘I/O上，而是直接返回报告；接着nginx就读这个一字节报告，然后初始化异步数据。
82 FreeBSD内核接着会读取文件的开始128K字节到内存，而后续的读取只会以16K的单位来进行。
83 这个性质可以使用<link id="read_ahead"/>指令来调节。
84 </para>
85
86 <para>
87 从Linux内核2.6.22版开始，也可以使用AIO。但必须同时开启<link id="directio"/>，否则读取将是阻塞的：
88 <example>
89 location /video/ {
90 aio on;
91 directio 512;
92 output_buffers 1 128k;
93 }
94 </example>
95 </para>
96
97 <para>
98 在Linux上，<link id="directio"/>只在读取的块的边界对齐512字节（在XFS上是4K字节）时才有用。在读取文件尾部时，
99 如果没有对齐，AIO读取还是阻塞的。同样的情况(如果数据的开始或者结尾未对齐时，读取也是阻塞的)
100 也发生在含有<header>byte range</header>头的请求中，或者发生在不是从头开始的FLV请求中。
101 没有必要手动关闭<link id="sendfile"/>，因为如果使用了<link id="directio"/>，它就会自动关闭。
102 </para>
103
104 </directive>
105
106
107 <directive name="alias">
108 <syntax><value>path</value></syntax>
109 <default/>
110 <context>location</context>
111
112 <para>
113 定义指定路径的替换路径。比如下面配置
114 <example>
115 location /i/ {
116 alias /data/w3/images/;
117 }
118 </example>
119 “<literal>/i/top.gif</literal>”将由<path>/data/w3/images/top.gif</path>文件来响应。
120 </para>
121
122 <para>
123 <value>path</value>的值可以包含变量，但不能使用<var>$document_root</var>和<var>$realpath_root</var>这两个变量。
124 </para>
125
126 <para>
127 如果在定义了正则表达式的路径中使用了<literal>alias</literal>，那么正则表达式中应该含有匹配组，
128 并且<literal>alias</literal>应该引用这些匹配组(0.7.40版)来组成一个完整的文件路径，比如：
129 <example>
130 location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
131 alias /data/w3/images/$1;
132 }
133 </example>
134 </para>
135
136 <para>
137 如果路径对应指令<value>path</value>值的最后一部分：
138 <example>
139 location /images/ {
140 alias /data/w3/images/;
141 }
142 </example>
143 最好换用<link id="root"/>指令：
144 <example>
145 location /images/ {
146 root /data/w3;
147 }
148 </example>
149 </para>
150
151 </directive>
152
153
154 <directive name="chunked_transfer_encoding">
155 <syntax><literal>on</literal> | <literal>off</literal></syntax>
156 <default>on</default>
157 <context>http</context>
158 <context>server</context>
159 <context>location</context>
160
161 <para>
162 允许关闭HTTP/1.1中的分块传输编码。在客户端软件不支持分块传输编码的时候，这条指令才有用。
163 </para>
164
165 </directive>
166
167
168 <directive name="client_body_buffer_size">
169
170 <syntax><value>size</value></syntax>
171 <default>8k|16k</default>
172 <context>http</context>
173 <context>server</context>
174 <context>location</context>
175
176 <para>
177 设置读取客户端请求正文的缓冲容量。如果请求正文大于缓冲容量，整个正文或者正文的一部分将写入<link id="client_body_temp_path">临时文件</link>。
178 缓冲大小默认等于两块内存页的大小，在x86平台、其他32位平台和x86-64平台，这个值是8K。在其他64位平台，这个值一般是16K。
179 </para>
180
181 </directive>
182
183
184 <directive name="client_body_in_file_only">
185 <syntax>
186 <literal>on</literal> |
187 <literal>clean</literal> |
188 <literal>off</literal></syntax>
189 <default>off</default>
190 <context>http</context>
191 <context>server</context>
192 <context>location</context>
193
194 <para>
195 决定nginx是否将客户端请求正文整个写入文件。这条指令在调试时，或者使用<var>$request_body_file</var>变量时，
196 或者使用<link doc="ngx_http_perl_module.xml">ngx_http_perl_module</link>模块的
197 <link doc="ngx_http_perl_module.xml" id="methods">$r->request_body_file</link>方法时都可以使用。
198 </para>
199
200 <para>
201 当指令值设置为<literal>on</literal>时，请求处理结束后不会删除临时文件。
202 </para>
203
204 <para>
205 当指令值设置为<literal>clean</literal>时，请求处理结束后会删除临时文件。
206 </para>
207
208 </directive>
209
210
211 <directive name="client_body_in_single_buffer">
212 <syntax><literal>on</literal> | <literal>off</literal></syntax>
213 <default>off</default>
214 <context>http</context>
215 <context>server</context>
216 <context>location</context>
217
218 <para>
219 决定nginx将整个客户端请求正文保存在一块缓冲中。
220 这条指令推荐在使用<var>$request_body</var>变量时使用，可以节省引入的拷贝操作。
221 </para>
222
223 </directive>
224
225
226 <directive name="client_body_temp_path">
227 <syntax>
228 <value>path</value>
229 [<value>level1</value>
230 [<value>level2</value>
231 [<value>level3</value>]]]</syntax>
232 <default>client_body_temp</default>
233 <context>http</context>
234 <context>server</context>
235 <context>location</context>
236
237 <para>
238 定义存储客户端请求正文的临时文件的目录。
239 支持在指定目录下多达3层的子目录结构。比如下面配置
240 <example>
241 client_body_temp_path /spool/nginx/client_temp 1 2;
242 </example>
243 存储临时文件的路径是
244 <example>
245 /spool/nginx/client_temp/7/45/00000123457
246 </example>
247 </para>
248
249 </directive>
250
251
252 <directive name="client_body_timeout">
253 <syntax><value>time</value></syntax>
254 <default>60s</default>
255 <context>http</context>
256 <context>server</context>
257 <context>location</context>
258
259 <para>
260 定义读取客户端请求正文的超时。超时是指相邻两次读操作之间的最大时间间隔，而不是整个请求正文完成传输的最大时间。
261 如果客户端在这段时间内没有传输任何数据，nginx将返回<http-status code="408" text="Request Time-out"/>错误到客户端。
262 </para>
263
264 </directive>
265
266
267 <directive name="client_header_buffer_size">
268 <syntax><value>size</value></syntax>
269 <default>1k</default>
270 <context>http</context>
271 <context>server</context>
272
273 <para>
274 设置读取客户端请求头部的缓冲容量。
275 对于大多数请求，1K的缓冲足矣。
276 但如果请求中含有的cookie很长，或者请求来自WAP的客户端，可能请求头不能放在1K的缓冲中。
277 如果从请求行，或者某个请求头开始不能完整的放在这块空间中，那么nginx将按照
278 <link id="large_client_header_buffers"/>指令的配置分配更多更大的缓冲来存放。
279 directive.
280 </para>
281
282 </directive>
283
284
285 <directive name="client_header_timeout">
286 <syntax><value>time</value></syntax>
287 <default>60s</default>
288 <context>http</context>
289 <context>server</context>
290
291 <para>
292 定义读取客户端请求头部的超时。如果客户端在这段时间内没有传送完整的头部到nginx，
293 nginx将返回错误<http-status code="408" text="Request Time-out"/>到客户端。
294 </para>
295
296 </directive>
297
298
299 <directive name="client_max_body_size">
300 <syntax><value>size</value></syntax>
301 <default>1m</default>
302 <context>http</context>
303 <context>server</context>
304 <context>location</context>
305
306 <para>
307 设置允许客户端请求正文的最大长度。请求的长度由<header>Content-Length</header>请求头指定。
308 如果请求的长度超过设定值，nginx将返回错误<http-status code="413" text="Request Entity Too Large"/>到客户端。
309 请注意<!--link doc="/web/upload.xml"-->浏览器不能正确显示这个错误<!--/link-->。
310 将<value>size</value>设置成0可以使nginx不检查客户端请求正文的长度。
311 </para>
312
313 </directive>
314
315
316 <directive name="connection_pool_size">
317 <syntax><value>size</value></syntax>
318 <default>256</default>
319 <context>http</context>
320 <context>server</context>
321
322 <para>
323 允许微调为每个连接分配的内存。这条指令对nginx的性能影响非常小，一般不应该使用。
324 </para>
325
326 </directive>
327
328
329 <directive name="default_type">
330 <syntax><value>mime-type</value></syntax>
331 <default>text/plain</default>
332 <context>http</context>
333 <context>server</context>
334 <context>location</context>
335
336 <para>
337 定义响应的默认MIME类型。设置文件扩展名和响应的MIME类型的映射表则使用<link id="types"/>指令。
338 </para>
339
340 </directive>
341
342
343 <directive name="directio">
344 <syntax><value>size</value> | <literal>off</literal></syntax>
345 <default>off</default>
346 <context>http</context>
347 <context>server</context>
348 <context>location</context>
349 <appeared-in>0.7.7</appeared-in>
350
351 <para>
352 当读入长度大于等于指定<value>size</value>的文件时，开启DirectIO功能。
353 具体的做法是，
354 在FreeBSD或Linux系统开启使用<c-def>O_DIRECT</c-def>标志，
355 在Mac OS X系统开启使用<c-def>F_NOCACHE</c-def>标志，
356 在Solaris系统开启使用<c-func>directio</c-func>功能。
357 这条指令自动关闭<link id="sendfile"/>(0.7.15版)。
358 它在处理大文件时
359 <example>
360 directio 4m;
361 </example>
362 或者在Linux系统使用<link id="aio"/>时比较有用。
363 </para>
364
365 </directive>
366
367
368 <directive name="directio_alignment">
369 <syntax><value>size</value></syntax>
370 <default>512</default>
371 <context>http</context>
372 <context>server</context>
373 <context>location</context>
374 <appeared-in>0.8.11</appeared-in>
375
376 <para>
377 为<link id="directio"/>设置文件偏移量对齐。大多数情况下，按512字节对齐足矣，
378 但在Linux系统下使用XFS，需要将值扩大到4K。
379 </para>
380
381 </directive>
382
383
384 <directive name="disable_symlinks">
385 <syntax><literal>off</literal></syntax>
386 <syntax>
387 <literal>on</literal> |
388 <literal>if_not_owner</literal>
389 [<literal>from</literal>=<value>part</value>]</syntax>
390 <default>off</default>
391 <context>http</context>
392 <context>server</context>
393 <context>location</context>
394 <appeared-in>1.1.15</appeared-in>
395
396 <para>
397 决定nginx打开文件时如何处理符号链接：
398 <list type="tag">
399
400 <tag-name><literal>off</literal></tag-name>
401 <tag-desc>
402 默认行为，允许路径中出现符号链接，不做检查。
403 </tag-desc>
404
405 <tag-name><literal>on</literal></tag-name>
406 <tag-desc>
407 如果文件路径中任何组成部分中含有符号链接，拒绝访问该文件。
408 </tag-desc>
409
410 <tag-name><literal>if_not_owner</literal></tag-name>
411 <tag-desc>
412 如果文件路径中任何组成部分中含有符号链接，且符号链接和链接目标的所有者不同，拒绝访问该文件。
413 </tag-desc>
414
415 <tag-name><literal>from</literal>=<value>part</value></tag-name>
416 <tag-desc>
417 当nginx进行符号链接检查时(参数<literal>on</literal>和参数<literal>if_not_owner</literal>)，路径中所有部分默认都会被检查。
418 而使用<literal>from</literal>=<value>part</value>参数可以避免对路径开始部分进行符号链接检查，而只检查后面的部分路径。
419 如果某路径不是以指定值开始，整个路径将被检查，就如同没有指定这个参数一样。
420 如果某路径与指定值完全匹配，将不做检查。
421 这个参数的值可以包含变量。
422 </tag-desc>
423
424 </list>
425 </para>
426
427 <para>
428 比如：
429 <example>
430 disable_symlinks on from=$document_root;
431 </example>
432 </para>
433
434 <para>
435 这条指令只在有<c-func>openat</c-func>和<c-func>fstatat</c-func>接口的系统上可用。
436 当然，现在的FreeBSD、Linux和Solaris都支持这些接口。
437 </para>
438
439 <para>
440 参数<literal>on</literal>和<literal>if_not_owner</literal>会带来处理开销。
441 <note>
442 只在那些不支持打开目录查找文件的系统中，使用这些参数需要工作进程有这些被检查目录的读权限。
443 </note>
444 </para>
445
446 <para>
447 <note>
448 <link doc="ngx_http_autoindex_module.xml">ngx_http_autoindex_module</link>模块，
449 <link doc="ngx_http_random_index_module.xml">ngx_http_random_index_module</link>模块
450 和<link doc="ngx_http_dav_module.xml">ngx_http_dav_module</link>模块目前忽略这条指令。
451 </note>
452 </para>
453
454 </directive>
455
456
457 <directive name="error_page">
458 <syntax>
459 <value>code</value> ...
460 [<literal>=</literal>[<value>response</value>]]
461 <value>uri</value></syntax>
462 <default/>
463 <context>http</context>
464 <context>server</context>
465 <context>location</context>
466 <context>if in location</context>
467
468 <para>
469 为指令错误定义显示的URI。当前配置级别没有<literal>error_page</literal>指令时，将从上层配置继承。
470 <literal>uri</literal>可以包含变量。
471 </para>
472
473 <para>
474 比如：
475 <example>
476 error_page 404 /404.html;
477 error_page 500 502 503 504 /50x.html;
478 </example>
479 </para>
480
481 <para>
482 而且，可以使用“<literal>=</literal><value>response</value>语法改变响应状态码。比如：
483 <example>
484 error_page 404 =200 /empty.gif;
485 </example>
486 </para>
487
488 <para>
489 如果URI将被发送到一个被代理的服务器处理，或者发送到一个FastCGI服务器处理，
490 这些后端服务器又返回了不同的响应状态码（比如200、302、401或404），那么这些返回的状态码也可以由本指令处理：
491 <example>
492 error_page 404 = /404.php;
493 </example>
494 </para>
495
496 <para>
497 当然，也可以使用本指令对错误处理进行重定向：
498 <example>
499 error_page 403 http://example.com/forbidden.html;
500 error_page 404 =301 http://example.com/notfound.html;
501 </example>
502 对于例子中的第一行，nginx将向客户端发送302响应状态码。这种用法能使用的状态码只有301、302、303和307。
503 </para>
504
505 <para>
506 如果内部跳转时无需改变URI，可以将错误处理转到一个命名路径：
507 <example>
508 location / {
509 error_page 404 = @fallback;
510 }
511
512 location @fallback {
513 proxy_pass http://backend;
514 }
515 </example>
516 </para>
517
518 <para>
519 <note>
520 如果处理<literal>uri</literal>产生了错误，那么nginx将最后一次出错的HTTP响应状态码返回给客户端。
521 </note>
522 </para>
523
524 </directive>
525
526
527 <directive name="etag">
528 <syntax><literal>on</literal> | <literal>off</literal></syntax>
529 <default>on</default>
530 <context>http</context>
531 <context>server</context>
532 <context>location</context>
533 <appeared-in>1.3.3</appeared-in>
534
535 <para>
536 开启或关闭为静态文件自动计算<header>ETag</header>响应头。
537 </para>
538
539 </directive>
540
541
542 <directive name="http">
543 <syntax block="yes"/>
544 <default/>
545 <context>main</context>
546 <para>
547 为HTTP服务器提供配置上下文。
548 </para>
549 </directive>
550
551
552 <directive name="if_modified_since">
553 <syntax>
554 <literal>off</literal> |
555 <literal>exact</literal> |
556 <literal>before</literal></syntax>
557 <default>exact</default>
558 <context>http</context>
559 <context>server</context>
560 <context>location</context>
561 <appeared-in>0.7.24</appeared-in>
562
563 <para>
564 指定响应的修改时间和<header>If-Modified-Since</header>请求头的比较方法：
565
566 <list type="tag">
567
568 <tag-name><literal>off</literal></tag-name>
569 <tag-desc>
570 忽略<header>If-Modified-Since</header>请求头(0.7.34)；
571 </tag-desc>
572
573 <tag-name><literal>exact</literal></tag-name>
574 <tag-desc>
575 精确匹配；
576 </tag-desc>
577
578 <tag-name><literal>before</literal></tag-name>
579 <tag-desc>
580 响应的修改时间小于等于<header>If-Modified-Since</header>请求头指定的时间。
581 </tag-desc>
582
583 </list>
584 </para>
585
586 </directive>
587
588
589 <directive name="ignore_invalid_headers">
590 <syntax><literal>on</literal> | <literal>off</literal></syntax>
591 <default>on</default>
592 <context>http</context>
593 <context>server</context>
594
595 <para>
596 控制是否忽略非法的请求头字段名。
597 合法的名字是由英文字母、数字和连字符组成，当然也可以包含下划线(由<link id="underscores_in_headers"/>指令控制)。
598 </para>
599
600 <para>
601 本指令可以在默认虚拟主机的<link id="server"/>配置层级中定义一次，那么这个值在监听在相同地址和端口的所有虚拟主机上都生效。
602 </para>
603
604 </directive>
605
606
607 <directive name="internal">
608 <syntax/>
609 <default/>
610 <context>location</context>
611
612 <para>
613 指定一个路径是否只能用于内部访问。如果是外部访问，客户端将收到<http-status code="404" text="Not Found"/>错误。
614 下列请求是内部请求：
615
616 <list type="bullet">
617
618 <listitem>
619 由<link id="error_page"/>指令、<link doc="ngx_http_index_module.xml" id="index"/>指令、
620 <link doc="ngx_http_random_index_module.xml" id="random_index"/>指令
621 和<link id="try_files"/>指令引起的重定向请求；
622 </listitem>
623
624 <listitem>
625 由后端服务器返回的<header>X-Accel-Redirect</header>响应头引起的重定向请求；
626 </listitem>
627
628 <listitem>
629 由<link doc="ngx_http_ssi_module.xml">ngx_http_ssi_module</link>模块
630 和<link doc="ngx_http_addition_module.xml">ngx_http_addition_module</link>模块
631 的“<command>include virtual</command>”指令产生的子请求；
632 </listitem>
633
634 <listitem>
635 用<link doc="ngx_http_rewrite_module.xml" id="rewrite"/>指令对请求进行修改。
636 </listitem>
637
638 </list>
639 </para>
640
641 <para>
642 举例：
643 <example>
644 error_page 404 /404.html;
645
646 location /404.html {
647 internal;
648 }
649 </example>
650 <note>
651 nginx限制每个请求只能最多进行10次内部重定向，以防配置错误引起请求处理出现问题。
652 如果内部重定向次数已达到10次，nginx将返回<http-status code="500" text="Internal Server Error"/>错误。
653 同时，错误日志中将有“rewrite or internal redirection cycle”的信息。
654 </note>
655 </para>
656
657 </directive>
658
659
660 <directive name="keepalive_disable">
661 <syntax><literal>none</literal> | <value>browser</value> ...</syntax>
662 <default>msie6</default>
663 <context>http</context>
664 <context>server</context>
665 <context>location</context>
666
667 <para>
668 针对行为异常的浏览器关闭长连接功能。
669 <value>browser</value>参数指定那些浏览器会受到影响。
670 值为<literal>msie6</literal>表示在遇到POST请求时，关闭与老版MSIE浏览器建立长连接。
671 值为<literal>safari</literal>表示在遇到Mac OS X和类Mac OS X操作系统下的Safari浏览器和类Safari浏览器时，不与浏览器建立长连接。
672 值为<literal>none</literal>表示为所有浏览器开启长连接功能。
673 <note>
674 在nginx 1.1.18版本及以前，<literal>safari</literal>将匹配所有操作系统上的Safari和类Safari浏览器，并默认不与这些浏览器建立长连接。
675 </note>
676 </para>
677
678 </directive>
679
680
681 <directive name="keepalive_requests">
682 <syntax><value>number</value></syntax>
683 <default>100</default>
684 <context>http</context>
685 <context>server</context>
686 <context>location</context>
687 <appeared-in>0.8.0</appeared-in>
688
689 <para>
690 设置通过一个长连接可以处理的最大请求数。
691 请求数超过此值，长连接将关闭。
692 </para>
693
694 </directive>
695
696
697 <directive name="keepalive_timeout">
698 <syntax>
699 <value>timeout</value>
700 [<value>header_timeout</value>]</syntax>
701 <default>75s</default>
702 <context>http</context>
703 <context>server</context>
704 <context>location</context>
705
706 <para>
707 第一个参数设置客户端的长连接在服务器端保持的最长时间（在此时间客户端未发起新请求，则长连接关闭）。
708 第二个参数为可选项，设置<header>Keep-Alive: timeout=<value>time</value></header>响应头的值。
709 可以为这两个参数设置不同的值。
710 </para>
711
712 <para>
713 <header>Keep-Alive: timeout=<value>time</value></header>响应头可以被Mozilla和Konqueror浏览器识别和处理。
714 MSIE浏览器在大约60秒后会关闭长连接。
715 </para>
716
717 </directive>
718
719
720 <directive name="large_client_header_buffers">
721 <syntax><value>number</value> <value>size</value></syntax>
722 <default>4 8k</default>
723 <context>http</context>
724 <context>server</context>
725
726 <para>
727 设置读取客户端请求超大请求的缓冲最大<value>number(数量)</value>和每块缓冲的<value>size(容量)</value>。
728 HTTP请求行的长度不能超过一块缓冲的容量，否则nginx返回错误<http-status code="414" text="Request-URI Too Large"/>到客户端。
729 每个请求头的长度也不能超过一块缓冲的容量，否则nginx返回错误<http-status code="400" text="Bad Request"/>到客户端。
730 缓冲仅在必需是才分配，默认每块的容量是8K字节。
731 即使nginx处理完请求后与客户端保持入长连接，nginx也会释放这些缓冲。
732 </para>
733
734 </directive>
735
736
737 <directive name="limit_except">
738 <syntax block="yes"><value>method</value> ...</syntax>
739 <default/>
740 <context>location</context>
741
742 <para>
743 允许按请求的HTTP方法限制对某路径的请求。<value>method</value>用于指定不由这些限制条件进行过滤的HTTP方法，可选值有
744 <literal>GET</literal>、
745 <literal>HEAD</literal>、
746 <literal>POST</literal>、
747 <literal>PUT</literal>、
748 <literal>DELETE</literal>、
749 <literal>MKCOL</literal>、
750 <literal>COPY</literal>、
751 <literal>MOVE</literal>、
752 <literal>OPTIONS</literal>、
753 <literal>PROPFIND</literal>、
754 <literal>PROPPATCH</literal>、
755 <literal>LOCK</literal>、
756 <literal>UNLOCK</literal>
757 或者
758 <literal>PATCH</literal>。
759 指定<value>method</value>为<literal>GET</literal>方法的同时，nginx会自动添加<literal>HEAD</literal>方法。
760 那么其他HTTP方法的请求就会由指令引导的配置块中的<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>
761 模块和<link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>模块的指令来限制访问。如：
762 <example>
763 limit_except GET {
764 allow 192.168.1.0/32;
765 deny all;
766 }
767 </example>
768 请留意上面的例子将对<emphasis>除</emphasis>GET和HEAD方法以外的所有HTTP方法的请求进行访问限制。
769 </para>
770
771 </directive>
772
773
774 <directive name="limit_rate">
775 <syntax><value>rate</value></syntax>
776 <default>0</default>
777 <context>http</context>
778 <context>server</context>
779 <context>location</context>
780 <context>if in location</context>
781
782 <para>
783 限制向客户端传送响应的速率限制。参数<value>rate</value>的单位是字节/秒，设置为0将关闭限速。
784 <!--
785 速率越小，限速越精确。
786 -->
787 nginx按连接限速，所以如果某个客户端同时开启了两个连接，那么客户端的整体速率是这条指令设置值的2倍。
788 </para>
789
790 <para>
791 也可以利用<var>$limit_rate</var>变量设置流量限制。如果想在特定条件下限制响应传输速率，可以使用这个功能：
792 <example>
793 server {
794
795 if ($slow) {
796 set $limit_rate 4k;
797 }
798
799 ...
800 }
801 </example>
802 </para>
803
804 <para>
805 此外，也可以通过<header>X-Accel-Limit-Rate</header>响应头来完成速率限制。
806 这种机制可以用<link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/>指令和
807 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_ignore_headers"/>指令关闭。
808 </para>
809
810 </directive>
811
812
813 <directive name="limit_rate_after">
814 <syntax><value>size</value></syntax>
815 <default>0</default>
816 <context>http</context>
817 <context>server</context>
818 <context>location</context>
819 <context>if in location</context>
820 <appeared-in>0.8.0</appeared-in>
821
822 <para>
823 设置不限速传输的响应大小。当传输量大于此值时，超出部分将限速传送。
824 </para>
825
826 <para>
827 比如:
828 <example>
829 location /flv/ {
830 flv;
831 limit_rate_after 500k;
832 limit_rate 50k;
833 }
834 </example>
835 </para>
836
837 </directive>
838
839
840 <directive name="lingering_close">
841 <syntax>
842 <literal>off</literal> |
843 <literal>on</literal> |
844 <literal>always</literal></syntax>
845 <default>on</default>
846 <context>http</context>
847 <context>server</context>
848 <context>location</context>
849 <appeared-in>1.1.0</appeared-in>
850 <appeared-in>1.0.6</appeared-in>
851
852 <para>
853 控制nginx如何关闭客户端连接。
854 </para>
855
856 <para>
857 默认值“<literal>on</literal>”指示nginx在完成关闭连接前<link id="lingering_timeout">等待</link>和
858 <link id="lingering_time">处理</link>客户端发来的额外数据。但只有在预测客户端可能发送更多数据的情况才会做此处理。
859 </para>
860
861 <para>
862 “<literal>always</literal>”指示nginx无条件等待和处理客户端的额外数据。
863 </para>
864
865 <para>
866 “<literal>off</literal>”指示nginx立即关闭连接，而绝不等待客户端传送额外数据。
867 这样做破坏了协议，所以正常条件下不应使用。
868 </para>
869
870 </directive>
871
872
873 <directive name="lingering_time">
874 <syntax><value>time</value></syntax>
875 <default>30s</default>
876 <context>http</context>
877 <context>server</context>
878 <context>location</context>
879
880 <para>
881 <link id="lingering_close"/>生效时，这条指令定义nginx处理(读取但忽略)客户端额外数据的最长时间。
882 超过这段时间后，nginx将关闭连接，不论是否还有更多数据待处理。
883 </para>
884
885 </directive>
886
887
888 <directive name="lingering_timeout">
889 <syntax><value>time</value></syntax>
890 <default>5s</default>
891 <context>http</context>
892 <context>server</context>
893 <context>location</context>
894
895 <para>
896 <link id="lingering_close"/>生效时，这条指令定义nginx等待客户端更多数据到来的最长时间。
897 如果在这段时间内，nginx没有接收到数据，nginx将关闭连接。否则，nginx将接收数据，忽略它，然后再等待更多数据。
898 这个“等待——接收——忽略”的循环一直重复，但总时间不会超过<link id="lingering_time"/>指令定义的时间。
899 </para>
900
901 </directive>
902
903
904 <directive name="listen">
905 <syntax>
906 <value>address</value>[:<value>port</value>]
907 [<literal>default_server</literal>]
908 [<literal>setfib</literal>=<value>number</value>]
909 [<literal>backlog</literal>=<value>number</value>]
910 [<literal>rcvbuf</literal>=<value>size</value>]
911 [<literal>sndbuf</literal>=<value>size</value>]
912 [<literal>accept_filter</literal>=<value>filter</value>]
913 [<literal>deferred</literal>]
914 [<literal>bind</literal>]
915 [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>]
916 [<literal>ssl</literal>]
917 [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax>
918 <syntax>
919 <value>port</value>
920 [<literal>default_server</literal>]
921 [<literal>setfib</literal>=<value>number</value>]
922 [<literal>backlog</literal>=<value>number</value>]
923 [<literal>rcvbuf</literal>=<value>size</value>]
924 [<literal>sndbuf</literal>=<value>size</value>]
925 [<literal>accept_filter</literal>=<value>filter</value>]
926 [<literal>deferred</literal>]
927 [<literal>bind</literal>]
928 [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>]
929 [<literal>ssl</literal>]
930 [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax>
931 <syntax>
932 <literal>unix:</literal><value>path</value>
933 [<literal>default_server</literal>]
934 [<literal>backlog</literal>=<value>number</value>]
935 [<literal>rcvbuf</literal>=<value>size</value>]
936 [<literal>sndbuf</literal>=<value>size</value>]
937 [<literal>accept_filter</literal>=<value>filter</value>]
938 [<literal>deferred</literal>]
939 [<literal>bind</literal>]
940 [<literal>ssl</literal>]
941 [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax>
942 <default>*:80 | *:8000</default>
943 <context>server</context>
944
945 <para>
946 设置nginx监听地址，nginx从这里接受请求。对于IP协议，这个地址就是<value>address</value>和<value>port</value>；对于UNIX域套接字协议，这个地址就是<value>path</value>。
947 一条listen指令只能指定一个<value>address</value>或者<value>port</value>。
948 <value>address</value>也可以是主机名。
949 比如：
950 <example>
951 listen 127.0.0.1:8000;
952 listen 127.0.0.1;
953 listen 8000;
954 listen *:8000;
955 listen localhost:8000;
956 </example>
957 IPv6地址(0.7.36版)用方括号来表示：
958 <example>
959 listen [::]:8000;
960 listen [fe80::1];
961 </example>
962 UNIX域套接字(0.8.21版)则使用“<literal>unix:</literal>”前缀：
963 <example>
964 listen unix:/var/run/nginx.sock;
965 </example>
966 </para>
967
968 <para>
969 如果只定义了<value>address</value>，nginx将使用80端口。
970 </para>
971
972 <para>
973 在没有定义listen指令的情况下，如果以超级用户权限运行nginx，它将监听<literal>*:80</literal>，否则他将监听<literal>*:8000</literal>。
974 </para>
975
976 <para>
977 如果listen指令携带<literal>default_server</literal>参数，当前虚拟主机将成为指定<value>address</value>:<value>port</value>的默认虚拟主机。
978 如果任何listen指令都没有携带<literal>default_server</literal>参数，那么第一个监听<value>address</value>:<value>port</value>的虚拟主机将被作为这个地址的默认虚拟主机。
979 <note>
980 0.8.21版以前，这个参数的名称是<literal>default</literal>。
981 </note>
982 </para>
983
984 <para>
985 可以为<literal>listen</literal>指令定义若干额外的参数，这些参数用于套接字相关的系统调用。
986 这些参数可以在任何<literal>listen</literal>指令中指定，但是对于每个<value>address</value>:<value>port</value>，只能定义一次。
987 <note>
988 0.8.21版以前，只有为<literal>listen</literal>指令定义了<literal>default</literal>参数，才能定义这些额外的参数。
989 </note>
990 <list type="tag">
991
992 <tag-name>
993 <literal>setfib</literal>=<value>number</value>
994 </tag-name>
995 <tag-desc>
996 这个参数(0.8.44)为监听套接字设置关联路由表FIB(<c-def>SO_SETFIB</c-def>选项)。
997 当前这个参数仅工作在FreeBSD上。
998 </tag-desc>
999
1000 <tag-name>
1001 <literal>backlog</literal>=<value>number</value>
1002 </tag-name>
1003 <tag-desc>
1004 为系统调用<c-func>listen</c-func>设置<literal>backlog</literal>参数，用以限制未接受(Accept)连接的队列的最大长度。
1005 FreeBSD和Mac OS X下，<literal>backlog</literal>的默认值是-1，在其他系统中，默认值是511。
1006 </tag-desc>
1007
1008
1009 <tag-name>
1010 <literal>rcvbuf</literal>=<value>size</value>
1011 </tag-name>
1012 <tag-desc>
1013 为监听套接字设置接收缓冲区大小(<c-def>SO_RCVBUF</c-def>参数)。
1014 </tag-desc>
1015
1016 <tag-name>
1017 <literal>sndbuf</literal>=<value>size</value>
1018 </tag-name>
1019 <tag-desc>
1020 为监听套接字设置发送缓冲区大小(<c-def>SO_SNDBUF</c-def>参数)。
1021 </tag-desc>
1022
1023 <tag-name>
1024 <literal>accept_filter</literal>=<value>filter</value>
1025 </tag-name>
1026 <tag-desc>
1027 为监听套接字设置接受过滤器的名称(<c-def>SO_ACCEPTFILTER</c-def>选项)。
1028 对每个到来的连接，接受过滤器先进行过滤，然后才将它们呈现给<c-func>accept</c-func>。
1029 本特性仅工作在FreeBSD系统和NetBSD 5.0+系统下。
1030 可接受的值是
1031 <link url="http://man.freebsd.org/accf_data">dataready</link>
1032 和
1033 <link url="http://man.freebsd.org/accf_http">httpready</link>。
1034 </tag-desc>
1035
1036 <tag-name>
1037 <literal>deferred</literal>
1038 </tag-name>
1039 <tag-desc>
1040 指示在Linux系统使用延迟的<c-func>accept</c-func>(<c-def>TCP_DEFER_ACCEPT</c-def>选项)。
1041 </tag-desc>
1042
1043 <tag-name>
1044 <literal>bind</literal>
1045 </tag-name>
1046 <tag-desc>
1047 指示nginx为设置的<value>address</value>:<value>port</value>单独调用一次<c-func>bind</c-func>。
1048 这是因为当有多条<literal>listen</literal>指令监听不同地址下的相同端口，
1049 而其中一条<literal>listen</literal>指令监听了这个端口的所有地址(<literal>*:</literal><value>port</value>)时，
1050 nginx只会为<literal>*:</literal><value>port</value>调用一次<c-func>bind</c-func>绑定套接字。
1051 需要留意的是，这种情况下，nginx会调用<c-func>getsockname</c-func>系统调用来确定接受请求的套接字地址。
1052 如果为某个<value>address</value>:<value>port</value>定义了参数<literal>backlog</literal>、<literal>rcvbuf</literal>、
1053 <literal>sndbuf</literal>、<literal>accept_filter</literal>、<literal>deferred</literal>或者<literal>so_keepalive</literal>，
1054 nginx总会为这个地址单独调用一次<c-func>bind</c-func>绑定套接字。
1055 </tag-desc>
1056
1057 <tag-name>
1058 <literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>
1059 </tag-name>
1060 <tag-desc>
1061 这个参数(0.7.42)(通过<c-def>IPV6_V6ONLY</c-def>选项)决定监听在通配地址<literal>[::]</literal>上的IPv6套接字是只支持IPv6连接，还是同时支持IPv6和IPv4连接。
1062 这个参数默认打开，并且只能在nginx启动时设置。
1063 <note>
1064 在1.3.4版以前，如果省略此参数，那么操作系统的套接字设置将生效。
1065 </note>
1066 </tag-desc>
1067
1068 <tag-name>
1069 <literal>ssl</literal>
1070 </tag-name>
1071 <tag-desc>
1072 本参数(0.7.14)与套接字相关的系统调用无关，但是它可以指定从这个端口接受的连接应该以SSL模式工作。
1073 本参数在某服务器同时处理HTTP和HTTPS请求时，可以使<link doc="configuring_https_servers.xml" id="single_http_https_server">配置</link>更为紧凑。
1074 <example>
1075 listen 80;
1076 listen 443 ssl;
1077 </example>
1078 </tag-desc>
1079
1080 <tag-name>
1081 <literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]
1082 </tag-name>
1083 <tag-desc>
1084 这个参数(1.1.11)为监听套接字配置“TCP keepalive”行为。
1085 如果省略此参数，操作系统默认的设置将对此端口生效。
1086 如果参数值设置为“<literal>on</literal>”，监听套接字的<c-def>SO_KEEPALIVE</c-def>属性将被开启。
1087 如果参数值设置为“<literal>off</literal>”，监听套接字的<c-def>SO_KEEPALIVE</c-def>属性将被关闭。
1088 有些操作系统支持为每个连接调整TCP长连接的参数。调整参数可以使用套接字选项<c-def>TCP_KEEPIDLE</c-def>，<c-def>TCP_KEEPINTVL</c-def>和<c-def>TCP_KEEPCNT</c-def>。
1089 在这些操作系统上(当前就是Linux 2.4+，嬀NetBSD 5+FreeBSD 9.0-STABLE)，可以使用<value>keepidle</value>，<value>keepintvl</value>和<value>keepcnt</value>参数来配置。
1090 省略一到两个参数的话，对应套接字属性的系统默认设置将生效。
1091 比如，
1092 <example>so_keepalive=30m::10</example>将
1093 设置空闲超时(<c-def>TCP_KEEPIDLE</c-def>)为30分钟，
1094 设置探测次数(<c-def>TCP_KEEPCNT</c-def>)为10次，
1095 保留探测时间间隔(<c-def>TCP_KEEPINTVL</c-def>)为系统默认值。
1096 </tag-desc>
1097
1098 </list>
1099 </para>
1100
1101 <para>
1102 举例：
1103 <example>
1104 listen 127.0.0.1 default_server accept_filter=dataready backlog=1024;
1105 </example>
1106 </para>
1107
1108 </directive>
1109
1110
1111 <directive name="location">
1112 <syntax block="yes">[
1113 <literal>=</literal> |
1114 <literal>~</literal> |
1115 <literal>~*</literal> |
1116 <literal>^~</literal>
1117 ] <value>uri</value></syntax>
1118 <syntax block="yes"><literal>@</literal><value>name</value></syntax>
1119 <default/>
1120 <context>server</context>
1121 <context>location</context>
1122
1123 <para>
1124 为某个请求URI（路径）建立配置。
1125 </para>
1126
1127 <para>
1128 路径匹配在URI规范化以后进行。所谓规范化，就是先将URI中形如“<literal>%XX</literal>”的编码字符进行解码，
1129 再解析URI中的相对路径“<literal>.</literal>”和“<literal>..</literal>”部分，
1130 另外还可能会<link id="merge_slashes">压缩</link>相邻的两个或多个斜线成为一个斜线。
1131 </para>
1132
1133 <para>
1134 可以使用前缀字符串或者正则表达式定义路径。使用正则表达式需要在路径开始添加“<literal>~*</literal>”前缀
1135 (不区分大小写)，或者“<literal>~</literal>”前缀(区分大小写)。为了根据请求URI查找路径，nginx先检查前缀字符串定义的路径
1136 (前缀路径)，在这些路径中找到能最精确匹配请求URI的路径。然后nginx按在配置文件中的出现顺序检查正则表达式路径，
1137 匹配上某个路径后即停止匹配并使用该路径的配置，否则使用最大前缀匹配的路径的配置。
1138 </para>
1139
1140 <para>
1141 路径可以嵌套，但有例外，后面将提到。
1142 </para>
1143
1144 <para>
1145 在不区分大小写的操作系统（诸如Mac OS X和Cygwin）上，前缀匹配忽略大小写(0.7.7)。但是，比较仅限于单字节的编码区域(one-byte locale)。
1146 </para>
1147
1148 <para>
1149 正则表达式中可以包含匹配组(0.7.40)，结果可以被后面的其他指令使用。
1150 </para>
1151
1152 <para>
1153 如果最大前缀匹配的路径以“<literal>^~</literal>”开始，那么nginx不再检查正则表达式。
1154 </para>
1155
1156 <para>
1157 而且，使用“<literal>=</literal>”前缀可以定义URI和路径的精确匹配。如果发现匹配，则终止路径查找。
1158 比如，如果请求“<literal>/</literal>”出现频繁，定义“<literal>location = /</literal>”可以提高这些请求的处理速度，
1159 因为查找过程在第一次比较以后即结束。这样的路径明显不可能包含嵌套路径。
1160 </para>
1161
1162 <para>
1163 <note>
1164 在0.7.1到0.8.41的所有nginx中，如果请求匹配的前缀字符串路径并没有“<literal>=</literal>”或“<literal>^~</literal>”前缀，
1165 路径查找过程仍然会停止，而不进行正则表达式匹配。
1166 </note>
1167 </para>
1168
1169 <para>
1170 让我们用一个例子解释上面的说法：
1171 <example>
1172 location = / {
1173 [ configuration A ]
1174 }
1175
1176 location / {
1177 [ configuration B ]
1178 }
1179
1180 location /documents/ {
1181 [ configuration C ]
1182 }
1183
1184 location ^~ /images/ {
1185 [ configuration D ]
1186 }
1187
1188 location ~* \.(gif|jpg|jpeg)$ {
1189 [ configuration E ]
1190 }
1191 </example>
1192 请求“<literal>/</literal>”匹配配置A，
1193 请求“<literal>/index.html</literal>”匹配配置B，
1194 请求“<literal>/documents/document.html</literal>”匹配配置C，
1195 请求“<literal>/images/1.gif</literal>”匹配配置D，
1196 请求“<literal>/documents/1.jpg</literal>”匹配配置E。
1197 </para>
1198
1199 <para>
1200 前缀“<literal>@</literal>”定义了命名路径。这种路径不在一般的请求处理中使用，
1201 而是用在请求重定向中。这些路径不能嵌套，也不能包含嵌套路径。
1202 </para>
1203
1204 <!--
1205 <migration from="Apache" directive="Location" />
1206 -->
1207
1208 </directive>
1209
1210
1211 <directive name="log_not_found">
1212 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1213 <default>on</default>
1214 <context>http</context>
1215 <context>server</context>
1216 <context>location</context>
1217
1218 <para>
1219 开启或者关闭在<link doc="../ngx_core_module.xml" id="error_log"/>中记录文件不存在的错误。
1220 </para>
1221
1222 </directive>
1223
1224
1225 <directive name="log_subrequest">
1226 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1227 <default>off</default>
1228 <context>http</context>
1229 <context>server</context>
1230 <context>location</context>
1231
1232 <para>
1233 开启或者关闭在<link doc="ngx_http_log_module.xml" id="access_log"/>中记录子请求的访问日志。
1234 </para>
1235
1236 </directive>
1237
1238
1239 <directive name="max_ranges">
1240 <syntax><value>number</value></syntax>
1241 <default/>
1242 <context>http</context>
1243 <context>server</context>
1244 <context>location</context>
1245 <appeared-in>1.1.2</appeared-in>
1246
1247 <para>
1248 如果请求中含有字节范围的请求头，这条指令可以限制此范围允许的最大值。如果请求头的值超过此限制，将按请求未携带此请求头的情况处理。
1249 默认nginx对此不做限制。设置为0将使nginx完全不支持HTTP字节范围特性。
1250 </para>
1251
1252 </directive>
1253
1254
1255 <directive name="merge_slashes">
1256 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1257 <default>on</default>
1258 <context>http</context>
1259 <context>server</context>
1260
1261 <para>
1262 开启或者关闭将请求URI中相邻两个或更多斜线合并成一个的功能。
1263 </para>
1264
1265 <para>
1266 注意压缩URI对于前缀匹配和正则匹配的正确性是很重要的。没有开启这个功能时，请求“<literal>//scripts/one.php</literal>”将不能匹配
1267 <example>
1268 location /scripts/ {
1269 ...
1270 }
1271 </example>
1272 而被按静态文件的流程处理，所以将它变换成“<literal>/scripts/one.php</literal>”。
1273 </para>
1274
1275 <para>
1276 如果URI中包含base64编码的内容，必须将斜线压缩调整成<literal>off</literal>，因为base64编码本身会使用“<literal>/</literal>”字符。
1277 然而。出于安全方面的考虑，最好还是不要关闭压缩。
1278 </para>
1279
1280 <para>
1281 这条指令可以指定在默认虚拟主机的<link id="server"/>配置级别。这样的话，这个配置可以覆盖监听同一地址和端口的所有虚拟主机。
1282 </para>
1283
1284 </directive>
1285
1286
1287 <directive name="msie_padding">
1288 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1289 <default>on</default>
1290 <context>http</context>
1291 <context>server</context>
1292 <context>location</context>
1293
1294 <para>
1295 在响应状态码大于等于400时，在响应正文中添加一段注释，使响应正文达到512字节。
1296 本指令可以为MSIE客户端开启或关闭这个功能。
1297 </para>
1298
1299 </directive>
1300
1301
1302 <directive name="msie_refresh">
1303 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1304 <default>off</default>
1305 <context>http</context>
1306 <context>server</context>
1307 <context>location</context>
1308
1309 <para>
1310 为MSIE客户端开启或者关闭用页面刷新取代页面重定向的功能。
1311 </para>
1312
1313 </directive>
1314
1315
1316 <directive name="open_file_cache">
1317 <syntax><literal>off</literal></syntax>
1318 <syntax>
1319 <literal>max</literal>=<value>N</value>
1320 [<literal>inactive</literal>=<value>time</value>]</syntax>
1321 <default>off</default>
1322 <context>http</context>
1323 <context>server</context>
1324 <context>location</context>
1325
1326 <para>
1327 用于配置文件缓存，可缓存：
1328 <list type="bullet">
1329
1330 <listitem>
1331 打开文件的描述符，大小和修改时间；
1332 </listitem>
1333
1334 <listitem>
1335 目录查找结果；
1336 </listitem>
1337
1338 <listitem>
1339 文件查找时的错误结果，诸如“file not found”(文件不存在)、“no read permission”(无读权限)等等。
1340 <note>
1341 应单独使用<link id="open_file_cache_errors"/>指令开启缓存错误结果的功能。
1342 </note>
1343 </listitem>
1344
1345 </list>
1346 </para>
1347
1348 <para>
1349 指令有下列参数：
1350 <list type="tag">
1351
1352 <tag-name>
1353 <literal>max</literal>
1354 </tag-name>
1355 <tag-desc>
1356 设置缓存中元素的最大数量，当缓存溢出时，使用LRU(最近最少使用)算法删除缓存中的元素；
1357 </tag-desc>
1358
1359 <tag-name>
1360 <literal>inactive</literal>
1361 </tag-name>
1362 <tag-desc>
1363 设置超时，在这段时间内缓存元素如果没有被访问，将从缓存中删除。
1364 默认超时是60秒；
1365 </tag-desc>
1366
1367 <tag-name>
1368 <literal>off</literal>
1369 </tag-name>
1370 <tag-desc>
1371 关闭缓存。
1372 </tag-desc>
1373
1374 </list>
1375 </para>
1376
1377 <para>
1378 举例：
1379 <example>
1380 open_file_cache max=1000 inactive=20s;
1381 open_file_cache_valid 30s;
1382 open_file_cache_min_uses 2;
1383 open_file_cache_errors on;<!--
1384 open_file_cache_events on;
1385 -->
1386 </example>
1387 </para>
1388
1389 </directive>
1390
1391
1392 <directive name="open_file_cache_errors">
1393 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1394 <default>off</default>
1395 <context>http</context>
1396 <context>server</context>
1397 <context>location</context>
1398
1399 <para>
1400 开启或者关闭<link id="open_file_cache">缓存文件</link>查找的错误结果。
1401 </para>
1402
1403 </directive>
1404
1405
1406 <!--
1407
1408 <directive name="open_file_cache_events">
1409 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1410 <default>off</default>
1411 <context>http</context>
1412 <context>server</context>
1413 <context>location</context>
1414
1415 <para>
1416 Enables to use kernel events to validate
1417 <link id="open_file_cache"/>
1418 elements.
1419 This directive works with the
1420 <link doc="../events.xml" id="kqueue"/>
1421 method only.
1422 Note that only NetBSD&nbsp;2.0+ and FreeBSD&nbsp;6.0+
1423 support events for arbitrary file system types.
1424 Other operating systems support events only for essential
1425 file systems such as UFS or FFS.
1426 </para>
1427
1428 </directive>
1429
1430 -->
1431
1432
1433 <directive name="open_file_cache_min_uses">
1434 <syntax><value>number</value></syntax>
1435 <default>1</default>
1436 <context>http</context>
1437 <context>server</context>
1438 <context>location</context>
1439
1440 <para>
1441 设置在由<link id="open_file_cache"/>指令的<literal>inactive</literal>参数配置的超时时间内，
1442 文件应该被访问的最小<value>number(次数)</value>。如果访问次数大于等于此值，文件描述符会保留在缓存中，否则从缓存中删除。
1443 </para>
1444
1445 </directive>
1446
1447
1448 <directive name="open_file_cache_valid">
1449 <syntax><value>time</value></syntax>
1450 <default>60s</default>
1451 <context>http</context>
1452 <context>server</context>
1453 <context>location</context>
1454
1455 <para>
1456 设置检查<link id="open_file_cache"/>缓存的元素的时间间隔。
1457 <!--
1458 When
1459 <link id="open_file_cache_events"/>
1460 is enabled, open file descriptors
1461 are checked only once, and then updated right after they get changed.
1462 -->
1463 </para>
1464
1465 </directive>
1466
1467
1468 <directive name="optimize_server_names">
1469 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1470 <default>off</default>
1471 <context>http</context>
1472 <context>server</context>
1473
1474 <para>
1475 这条指令已经被废弃，请使用<link id="server_name_in_redirect"/>指令。
1476 </para>
1477
1478 <!--
1479 <para>
1480 Enables or disables optimization of hostname checking in name-based
1481 virtual servers.
1482 In particular, the checking affects hostnames used in redirects.
1483 If optimization is enabled, and all name-based servers listening on
1484 the same address:port pair have identical configuration, then
1485 names are not checked during request processing, and the first
1486 server name is used in redirects.
1487 In case redirects should use hostnames sent by clients,
1488 optimization needs to be disabled.
1489 </para>
1490 -->
1491
1492 </directive>
1493
1494
1495 <directive name="port_in_redirect">
1496 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1497 <default>on</default>
1498 <context>http</context>
1499 <context>server</context>
1500 <context>location</context>
1501
1502 <para>
1503 开启或关闭nginx发起重定向时指定端口。
1504 </para>
1505
1506 <para>
1507 重定向中首要主机名的使用由<link id="server_name_in_redirect"/>指令控制。
1508 </para>
1509
1510 </directive>
1511
1512
1513 <directive name="postpone_output">
1514 <syntax><value>size</value></syntax>
1515 <default>1460</default>
1516 <context>http</context>
1517 <context>server</context>
1518 <context>location</context>
1519
1520 <para>
1521 如果可能，到客户端的数据将被推迟发送，直到nginx需要发送的数据至少有<value>size</value>字节。
1522 设置为0将关闭推迟发送的功能。
1523 </para>
1524
1525 </directive>
1526
1527
1528 <directive name="read_ahead">
1529 <syntax><value>size</value></syntax>
1530 <default>0</default>
1531 <context>http</context>
1532 <context>server</context>
1533 <context>location</context>
1534
1535 <para>
1536 设置内核参数，控制文件预读的数量。
1537 </para>
1538
1539 <para>
1540 在Linux上，因为使用的是<literal>posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL)</literal>系统调用，所以<value>size</value>无用。
1541 </para>
1542
1543 <para>
1544 在FreeBSD上，访问的是<literal>fcntl(O_READAHEAD,</literal><value>size</value><literal>)</literal>系统调用。
1545 该系统调用在FreeBSD&nbsp;9.0-CURRENT才被支持，在FreeBSD&nbsp;7上则需要<link url="http://sysoev.ru/freebsd/patch.readahead.txt">打补丁</link>。
1546 </para>
1547
1548 </directive>
1549
1550
1551 <directive name="recursive_error_pages">
1552 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1553 <default>off</default>
1554 <context>http</context>
1555 <context>server</context>
1556 <context>location</context>
1557
1558 <para>
1559 允许或禁止<link id="error_page"/>指令进行多次重定向。
1560 允许的话，重定向次数也有<link id="internal">限制</link>。
1561 而禁止此功能时，当访问<link id="error_page"/>指令重定向的错误页面出现任何问题时，nginx将直接输出默认错误页面。
1562 </para>
1563
1564 </directive>
1565
1566
1567 <directive name="request_pool_size">
1568 <syntax><value>size</value></syntax>
1569 <default>4k</default>
1570 <context>http</context>
1571 <context>server</context>
1572
1573 <para>
1574 允许对每个请求的内存分配进行细调。这条指令对性能影响很小，通常情况下不应使用。
1575 </para>
1576
1577 </directive>
1578
1579
1580 <directive name="reset_timedout_connection">
1581 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1582 <default>off</default>
1583 <context>http</context>
1584 <context>server</context>
1585 <context>location</context>
1586
1587 <para>
1588 开启或关闭重置超时连接的功能。重置连接是这样执行的：关闭套接字以前，设置<c-def>SO_LINGER</c-def>选项的超时值为0，
1589 那么当关闭套接字时，nginx向客户端发送TCP RST，并且释放此套接字占用的所有内存。
1590 这样可以避免某个已关闭的套接字长时间处于FIN_WAIT1状态，并占用内存缓冲区。
1591 </para>
1592
1593 <para>
1594 应该注意的事，超时的长连接仍然是正常关闭。
1595 </para>
1596
1597 </directive>
1598
1599
1600 <directive name="resolver">
1601 <syntax>
1602 <value>address</value> ...
1603 [<literal>valid</literal>=<value>time</value>]</syntax>
1604 <default/>
1605 <context>http</context>
1606 <context>server</context>
1607 <context>location</context>
1608
1609 <para>
1610 配置将后端服务器的名字解析成ip地址的名字服务器，比如：
1611 <example>
1612 resolver 127.0.0.1 [::1]:5353;
1613 </example>
1614 这里地址可以指定域名或者ip地址，可以带端口号(1.3.1，1.2.2)。如果未指定端口，nginx使用53端口。
1615 以轮询方式发送请求到多台名字服务器。
1616 <note>
1617 在1.1.7版以前，只允许配置一个名字服务器。而支持使用IPv6地址定义名字服务器则是从1.3.1和1.2.2版本开始。
1618 </note>
1619 nginx会缓存名字解析的结果。默认情况下，缓存时间是名字解析响应中的TTL字段的值。也允许通过<literal>valid</literal>参数覆盖它：
1620 <example>
1621 resolver 127.0.0.1 [::1]:5353 valid=30s;
1622 </example>
1623 <note>
1624 在1.1.9版以前，不可能调节缓存时间，nginx总会将响应缓存5分钟。
1625 </note>
1626 </para>
1627
1628 </directive>
1629
1630
1631 <directive name="resolver_timeout">
1632 <syntax><value>time</value></syntax>
1633 <default>30s</default>
1634 <context>http</context>
1635 <context>server</context>
1636 <context>location</context>
1637
1638 <para>
1639 为名字解析设置超时，比如：
1640 <example>
1641 resolver_timeout 5s;
1642 </example>
1643 </para>
1644
1645 </directive>
1646
1647
1648 <directive name="root">
1649 <syntax><value>path</value></syntax>
1650 <default>html</default>
1651 <context>http</context>
1652 <context>server</context>
1653 <context>location</context>
1654 <context>if in location</context>
1655
1656 <para>
1657 为请求设置根目录。比如，如果配置如下
1658 <example>
1659 location /i/ {
1660 root /data/w3;
1661 }
1662 </example>
1663 那么nginx将使用文件<path>/data/w3/i/top.gif</path>响应请求“<literal>/i/top.gif</literal>”。
1664 </para>
1665
1666 <para>
1667 <value>path</value>的值中可以包含除<var>$document_root</var>和<var>$realpath_root</var>以外的变量。
1668 </para>
1669
1670 <para>
1671 文件路径的构造仅仅是将URI拼在<literal>root</literal>指令的值后面。如果需要修改URI，应该使用<link id="alias"/>指令。
1672 </para>
1673
1674 </directive>
1675
1676
1677 <directive name="satisfy">
1678 <syntax><literal>all</literal> | <literal>any</literal></syntax>
1679 <default>all</default>
1680 <context>http</context>
1681 <context>server</context>
1682 <context>location</context>
1683
1684 <para>
1685 nginx进行访问限制的有<link doc="ngx_http_access_module.xml">ngx_http_access_module</link>模块和
1686 <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>模块。
1687 本指令设置成<literal>all</literal>时，表示只有当两个模块的所有限制条件(写入配置的)都授权访问时，允许请求访问；
1688 设置成<literal>any</literal>时，表示如果当任意模块的任意限制条件授权访问时，允许请求访问。
1689 </para>
1690
1691 <para>
1692 举例：
1693 <example>
1694 location / {
1695 satisfy any;
1696
1697 allow 192.168.1.0/32;
1698 deny all;
1699
1700 auth_basic "closed site";
1701 auth_basic_user_file conf/htpasswd;
1702 }
1703 </example>
1704 </para>
1705
1706 </directive>
1707
1708
1709 <directive name="satisfy_any">
1710 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1711 <default>off</default>
1712 <context>http</context>
1713 <context>server</context>
1714 <context>location</context>
1715
1716 <para>
1717 这条指令已被<link id="satisfy"/>指令的<literal>any</literal>参数取代。
1718 </para>
1719
1720 </directive>
1721
1722
1723 <directive name="send_lowat">
1724 <syntax><value>size</value></syntax>
1725 <default>0</default>
1726 <context>http</context>
1727 <context>server</context>
1728 <context>location</context>
1729
1730 <para>
1731 如果设置成非0值，nginx将尝试最小化向客户端发送数据的次数。
1732 这是通过将<link doc="../events.xml" id="kqueue"/>方法的<c-def>NOTE_LOWAT</c-def>标志，
1733 或者将套接字的<c-def>SO_SNDLOWAT</c-def>属性设置成指定的<value>size</value>实现的。
1734 </para>
1735
1736 <para>
1737 这条指令在Linux、Solaris和Windows操作系统无效。
1738 </para>
1739
1740 </directive>
1741
1742
1743 <directive name="send_timeout">
1744 <syntax><value>time</value></syntax>
1745 <default>60s</default>
1746 <context>http</context>
1747 <context>server</context>
1748 <context>location</context>
1749
1750 <para>
1751 设置向客户端传输响应的超时。超时仅指两次相邻写操作之间的时间间隔，而非整个响应的传输时间。
1752 如果客户端在这段时间中没有收到任何数据，连接将关闭。
1753 </para>
1754
1755 </directive>
1756
1757
1758 <directive name="sendfile">
1759
1760 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1761 <default>off</default>
1762 <context>http</context>
1763 <context>server</context>
1764 <context>location</context>
1765 <context>if in location</context>
1766
1767 <para>
1768 开启或关闭使用<c-func>sendfile</c-func>调用。
1769 </para>
1770
1771 </directive>
1772
1773
1774 <directive name="sendfile_max_chunk">
1775
1776 <syntax><value>size</value></syntax>
1777 <default>0</default>
1778 <context>http</context>
1779 <context>server</context>
1780 <context>location</context>
1781
1782 <para>
1783 设置为非0值时，可以限制在一次<c-func>sendfile</c-func>调用时传输的数据量。
1784 如果不进行限制，一个快速的连接可能会霸占整个worker进程的所有资源。
1785 </para>
1786
1787 </directive>
1788
1789
1790 <directive name="server">
1791 <syntax block="yes"/>
1792 <default/>
1793 <context>http</context>
1794
1795 <para>
1796 表示开始设置虚拟主机的配置。
1797 nginx没有明显分隔IP-based(基于IP地址)和name-based(基于<header>Host</header>请求头)这两种类型的虚拟主机，
1798 而是用<link id="listen"/>指令描述虚拟主机接受连接的地址和端口，用<link id="server_name"/>指令列出虚拟主机的所有主机名。
1799 在文档“<link doc="request_processing.xml">Nginx如何处理一个请求</link>”中提供了示例配置。
1800 </para>
1801
1802 </directive>
1803
1804
1805 <directive name="server_name">
1806 <syntax><value>name</value> ...</syntax>
1807 <default>""</default>
1808 <context>server</context>
1809
1810 <para>
1811 设置虚拟主机名，比如：
1812 <example>
1813 server {
1814 server_name example.com www.example.com;
1815 }
1816 </example>
1817 </para>
1818
1819 <para>
1820 第一个名字成为虚拟主机的首要主机名。
1821 </para>
1822
1823 <para>
1824 主机名中可以含有星号(“<literal>*</literal>”)，以替代名字的开始部分或结尾部分：
1825 <example>
1826 server {
1827 server_name example.com *.example.com www.example.*;
1828 }
1829 </example>
1830 上面这些名字称为通配符主机名。
1831 </para>
1832
1833 <para>
1834 上面例子中的前两个名字可以组合成一个：
1835 <example>
1836 server {
1837 server_name .example.com;
1838 }
1839 </example>
1840 </para>
1841
1842 <para>
1843 也可以在主机名中使用正则表达式，就是在名字前面补一个波浪线(“<literal>~</literal>”)：
1844 <example>
1845 server {
1846 server_name www.example.com ~^www\d+\.example\.com$;
1847 }
1848 </example>
1849 </para>
1850
1851 <para>
1852 可以在正则表达式中包含匹配组(0.7.40)，后续被其他指令使用：
1853 <example>
1854 server {
1855 server_name ~^(www\.)?(.+)$;
1856
1857 location / {
1858 root /sites/$2;
1859 }
1860 }
1861
1862 server {
1863 server_name _;
1864
1865 location / {
1866 root /sites/default;
1867 }
1868 }
1869 </example>
1870 </para>
1871
1872 <para>
1873
1874 正则表达式中的命名匹配组可以创建变量(0.8.25)，后续被其他指令使用：
1875 <example>
1876 server {
1877 server_name ~^(www\.)?(?&lt;domain&gt;.+)$;
1878
1879 location / {
1880 root /sites/$domain;
1881 }
1882 }
1883
1884 server {
1885 server_name _;
1886
1887 location / {
1888 root /sites/default;
1889 }
1890 }
1891 </example>
1892 </para>
1893
1894 <para>
1895 如果参数值等于“<var>$hostname</var>”(0.9.4)，将使用机器的hostname来替换。
1896 </para>
1897
1898 <para>
1899 nginx也允许定义空主机名(0.7.11)：
1900 <example>
1901 server {
1902 server_name www.example.com "";
1903 }
1904 </example>
1905 这种主机名可以让虚拟主机处理没有<header>Host</header>请求头的请求，而不是让指定“地址:端口”的默认虚拟主机来处理。
1906 这是本指令的默认设置。
1907 <note>
1908 在0.8.48版以前，机器的hostname被用作默认设置。
1909 </note>
1910 </para>
1911
1912 <para>
1913 通过名字查找虚拟主机时，如果一个名字可以匹配多个指定的配置，比如同时匹配上通配符和正则表达式，
1914 按下面优先级，使用先匹配上的虚拟主机：
1915 <list type="enum">
1916
1917 <listitem>
1918 确切的名字；
1919 </listitem>
1920
1921 <listitem>
1922 最长的以星号起始的通配符名字，比如“<literal>*.example.com</literal>”；
1923 </listitem>
1924
1925 <listitem>
1926 最长的以星号结束的通配符名字，比如“<literal>mail.*</literal>”；
1927 </listitem>
1928
1929 <listitem>
1930 第一个匹配的正则表达式名字（按在配置文件中出现的顺序）。
1931 </listitem>
1932
1933 </list>
1934 </para>
1935
1936 <para>
1937 另一篇文档“<link doc="server_names.xml">虚拟主机名</link>”对虚拟主机名的有详细的描述。
1938 </para>
1939
1940 </directive>
1941
1942
1943 <directive name="server_name_in_redirect">
1944 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1945 <default>off</default>
1946 <context>http</context>
1947 <context>server</context>
1948 <context>location</context>
1949
1950 <para>
1951 开启或关闭nginx将<link id="server_name"/>指令指定的首要虚拟主机名用于发起的重定向的功能。
1952 关闭此功能时，nginx将使用<header>Host</header>请求头的中的名字，如果没有此请求头，nginx将使用虚拟主机所在的IP地址。
1953 </para>
1954
1955 <para>
1956 重定向中端口的使用由<link id="port_in_redirect"/>指令控制。
1957 </para>
1958
1959 </directive>
1960
1961
1962 <directive name="server_names_hash_bucket_size">
1963 <syntax><value>size</value></syntax>
1964 <default>32|64|128</default>
1965 <context>http</context>
1966
1967 <para>
1968 设置主机名哈希表的表项长度，其默认值取决于处理器的缓存线长度。
1969 另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。
1970 </para>
1971
1972 </directive>
1973
1974
1975 <directive name="server_names_hash_max_size">
1976 <syntax><value>size</value></syntax>
1977 <default>512</default>
1978 <context>http</context>
1979
1980 <para>
1981 设置主机名哈希表的最大<value>size</value>(桶容量)。
1982 另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。
1983 </para>
1984
1985 </directive>
1986
1987
1988 <directive name="server_tokens">
1989 <syntax><literal>on</literal> | <literal>off</literal></syntax>
1990 <default>on</default>
1991 <context>http</context>
1992 <context>server</context>
1993 <context>location</context>
1994
1995 <para>
1996 开启或关闭在错误信息的<header>Server</header>响应头中输出nginx版本号。
1997 </para>
1998
1999 </directive>
2000
2001
2002 <directive name="tcp_nodelay">
2003 <syntax><literal>on</literal> | <literal>off</literal></syntax>
2004 <default>on</default>
2005 <context>http</context>
2006 <context>server</context>
2007 <context>location</context>
2008
2009 <para>
2010 开启或关闭nginx使用<c-def>TCP_NODELAY</c-def>选项的功能。
2011 这个选项仅在将连接转变为长连接的时候才被启用。（译者注，在upstream发送响应到客户端时也会启用）。
2012 </para>
2013
2014 </directive>
2015
2016
2017 <directive name="tcp_nopush">
2018 <syntax><literal>on</literal> | <literal>off</literal></syntax>
2019 <default>off</default>
2020 <context>http</context>
2021 <context>server</context>
2022 <context>location</context>
2023
2024 <para>
2025 开启或者关闭nginx在FreeBSD上使用<c-def>TCP_NOPUSH</c-def>套接字选项，
2026 在Linux上使用<c-def>TCP_CORK</c-def>套接字选项。
2027 选项仅在使用<link id="sendfile"/>的时候才开启。
2028 开启此选项允许
2029 <list type="bullet">
2030
2031 <listitem>
2032 在Linux和FreeBSD&nbsp;4.*上将响应头和正文的开始部分一起发送；
2033 </listitem>
2034
2035 <listitem>
2036 一次性发送整个文件。
2037 </listitem>
2038
2039 </list>
2040 </para>
2041
2042 </directive>
2043
2044
2045 <directive name="try_files">
2046 <syntax><value>file</value> ... <value>uri</value></syntax>
2047 <syntax><value>file</value> ... =<value>code</value></syntax>
2048 <default/>
2049 <context>server</context>
2050 <context>location</context>
2051
2052 <para>
2053 按指定顺序检查文件是否存在，并且使用第一个找到的文件来处理请求，那么处理过程就是在当前上下文环境中进行的。
2054 文件路径是根据<link id="root"/>指令和<link id="alias"/>指令，将<value>file</value>参数拼接而成。
2055 可以在名字尾部添加斜线以检查目录是否存在，比如“<literal>$uri/</literal>”。
2056 如果找不到任何文件，将按最后一个参数指定的<value>uri</value>进行内部跳转。
2057 比如：
2058 <example>
2059 location /images/ {
2060 try_files $uri /images/default.gif;
2061 }
2062
2063 location = /images/default.gif {
2064 expires 30s;
2065 }
2066 </example>
2067 最后一个参数也可以指向一个命名路径，如下面的例子所示。
2068 从0.7.51版开始，最后一个参数也可以是<value>code</value>：
2069 <example>
2070 location / {
2071 try_files $uri $uri/index.html $uri.html =404;
2072 }
2073 </example>
2074 </para>
2075
2076 <para>
2077 下面是代理Mongrel的例子：
2078 <example>
2079 location / {
2080 try_files /system/maintenance.html
2081 $uri $uri/index.html $uri.html
2082 @mongrel;
2083 }
2084
2085 location @mongrel {
2086 proxy_pass http://mongrel;
2087 }
2088 </example>
2089 </para>
2090
2091 <para>
2092 下面是Drupal用FastCGI的例子：
2093 <example>
2094 location / {
2095 try_files $uri $uri/ @drupal;
2096 }
2097
2098 location ~ \.php$ {
2099 try_files $uri @drupal;
2100
2101 fastcgi_pass ...;
2102
2103 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
2104 fastcgi_param SCRIPT_NAME $fastcgi_script_name;
2105 fastcgi_param QUERY_STRING $args;
2106
2107 ... other fastcgi_param's
2108 }
2109
2110 location @drupal {
2111 fastcgi_pass ...;
2112
2113 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
2114 fastcgi_param SCRIPT_NAME /index.php;
2115 fastcgi_param QUERY_STRING q=$uri&amp;$args;
2116
2117 ... other fastcgi_param's
2118 }
2119 </example>
2120 而下面的例子中
2121 <example>
2122 location / {
2123 try_files $uri $uri/ @drupal;
2124 }
2125 </example>
2126 <literal>try_files</literal>指令等价于
2127 <example>
2128 location / {
2129 error_page 404 = @drupal;
2130 log_not_found off;
2131 }
2132 </example>
2133 然后是这里，
2134 <example>
2135 location ~ \.php$ {
2136 try_files $uri @drupal;
2137
2138 fastcgi_pass ...;
2139
2140 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
2141
2142 ...
2143 }
2144 </example>
2145 <literal>try_files</literal>在将请求发送到FastCGI服务器以前检查PHP文件是否存在。
2146 </para>
2147
2148 <para>
2149 下面是Wordpress和Joomla的例子：
2150 <example>
2151 location / {
2152 try_files $uri $uri/ @wordpress;
2153 }
2154
2155 location ~ \.php$ {
2156 try_files $uri @wordpress;
2157
2158 fastcgi_pass ...;
2159
2160 fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name;
2161 ... other fastcgi_param's
2162 }
2163
2164 location @wordpress {
2165 fastcgi_pass ...;
2166
2167 fastcgi_param SCRIPT_FILENAME /path/to/index.php;
2168 ... other fastcgi_param's
2169 }
2170 </example>
2171 </para>
2172
2173 </directive>
2174
2175
2176 <directive name="types">
2177 <syntax block="yes"/>
2178 <default>
2179 text/html html;
2180 image/gif gif;
2181 image/jpeg jpg;
2182 </default>
2183 <context>http</context>
2184 <context>server</context>
2185 <context>location</context>
2186
2187 <para>
2188 设置文件扩展名和响应的MIME类型的映射表。
2189 可以将多个扩展名映射到同一种类型，比如：
2190 <example>
2191 types {
2192 application/octet-stream bin exe dll;
2193 application/octet-stream deb;
2194 application/octet-stream dmg;
2195 }
2196 </example>
2197 </para>
2198
2199 <para>
2200 随nginx发行的<path>conf/mime.types</path>文件中包含了足够全面的映射表。
2201 </para>
2202
2203 <para>
2204 为了是为某个路径的所有请求生成MIME类型“<literal>application/octet-stream</literal>”，
2205 可以使用下面配置：
2206 <example>
2207 location /download/ {
2208 types { }
2209 default_type application/octet-stream;
2210 }
2211 </example>
2212 </para>
2213
2214 </directive>
2215
2216
2217 <directive name="types_hash_bucket_size">
2218 <syntax><value>size</value></syntax>
2219 <default>32|64|128</default>
2220 <context>http</context>
2221 <context>server</context>
2222 <context>location</context>
2223
2224 <para>
2225 设置MIME类型哈希表的表项长度，其默认值取决于处理器的缓存线长度。
2226 另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。
2227 </para>
2228
2229 </directive>
2230
2231
2232 <directive name="types_hash_max_size">
2233 <syntax><value>size</value></syntax>
2234 <default>1024</default>
2235 <context>http</context>
2236 <context>server</context>
2237 <context>location</context>
2238
2239 <para>
2240 设置MIME类型哈希表的最大<value>size</value>(桶容量)。
2241 另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。
2242 </para>
2243
2244 </directive>
2245
2246
2247 <directive name="underscores_in_headers">
2248 <syntax><literal>on</literal> | <literal>off</literal></syntax>
2249 <default>off</default>
2250 <context>http</context>
2251 <context>server</context>
2252
2253 <para>
2254 允许或禁止在客户端请求头中使用下划线。
2255 如果禁止，含有下划线的请求头将被标志为非法请求头并接受<link id="ignore_invalid_headers"/>指令的处理。
2256 </para>
2257
2258 <para>
2259 可以在默认主机的<link id="server"/>配置级别定义此命令。这样，指令设置将覆盖监听同一地址和端口的所有虚拟主机。
2260 </para>
2261
2262 </directive>
2263
2264
2265 <directive name="variables_hash_bucket_size">
2266 <syntax><value>size</value></syntax>
2267 <default>64</default>
2268 <context>http</context>
2269
2270 <para>
2271 设置变量哈希表的表项长度，其默认值取决于处理器的缓存线长度。
2272 另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。
2273 </para>
2274
2275 </directive>
2276
2277
2278 <directive name="variables_hash_max_size">
2279 <syntax><value>size</value></syntax>
2280 <default>512</default>
2281 <context>http</context>
2282
2283 <para>
2284 设置变量哈希表的最大<value>size</value>(桶容量)。
2285 另一篇文档“<link doc="../hash.xml">设置哈希表</link>”详细介绍了如何设置哈希表。
2286 </para>
2287
2288 </directive>
2289
2290 </section>
2291
2292
2293 <section id="variables" name="内嵌变量">
2294
2295 <para>
2296 <literal>ngx_http_core_module</literal>模块支持内嵌变量，变量名与Apache服务器对应。
2297 首先，这些变量可以表示客户端的请求头字段，诸如<var>$http_user_agent</var>、<var>$http_cookie</var>等等。
2298 nginx也支持其他变量：
2299 <list type="tag">
2300
2301 <tag-name id="var_arg_"><var>$arg_</var><value>name</value></tag-name>
2302 <tag-desc>
2303 请求行中的<value>name</value>参数。
2304 </tag-desc>
2305
2306 <tag-name id="var_args"><var>$args</var></tag-name>
2307 <tag-desc>
2308 请求行中参数字符串。
2309 </tag-desc>
2310
2311 <tag-name id="var_binary_remote_addr"><var>$binary_remote_addr</var></tag-name>
2312 <tag-desc>
2313 客户端IP地址的二进制形式，值的长度总是4字节。
2314 </tag-desc>
2315
2316 <tag-name id="var_body_bytes_sent"><var>$body_bytes_sent</var></tag-name>
2317 <tag-desc>
2318 nginx返回给客户端的字节数，不含响应头。
2319 </tag-desc>
2320
2321 <tag-name id="var_bytes_sent"><var>$bytes_sent</var></tag-name>
2322 <tag-desc>
2323 nginx返回给客户端的字节数(1.3.8, 1.2.5)。
2324 </tag-desc>
2325
2326 <tag-name id="var_connection"><var>$connection</var></tag-name>
2327 <tag-desc>
2328 连接的序列号(1.3.8, 1.2.5)。
2329 </tag-desc>
2330
2331 <tag-name id="var_content_length"><var>$content_length</var></tag-name>
2332 <tag-desc>
2333 <header>Content-Length</header>请求头的值。
2334 </tag-desc>
2335
2336 <tag-name id="var_content_type"><var>$content_type</var></tag-name>
2337 <tag-desc>
2338 <header>Content-Type</header>请求头的值。
2339 </tag-desc>
2340
2341 <tag-name id="var_cookie_"><var>$cookie_</var><value>name</value></tag-name>
2342 <tag-desc>
2343 名为<value>name</value>的cookie。
2344 </tag-desc>
2345
2346 <tag-name id="var_document_root"><var>$document_root</var></tag-name>
2347 <tag-desc>
2348 当前请求的<link id="root"/>指令或<link id="alias"/>指令的配置值。
2349 </tag-desc>
2350
2351 <tag-name id="var_document_uri"><var>$document_uri</var></tag-name>
2352 <tag-desc>
2353 与<var>$uri</var>相同。
2354 </tag-desc>
2355
2356 <tag-name id="var_host"><var>$host</var></tag-name>
2357 <tag-desc>
2358 <header>Host</header>请求头的值，如果没有该请求头，则为与请求对应的虚拟主机的首要主机名。
2359 </tag-desc>
2360
2361 <tag-name id="var_hostname"><var>$hostname</var></tag-name>
2362 <tag-desc>
2363 机器名称。
2364 </tag-desc>
2365
2366 <tag-name id="var_http_"><var>$http_</var><value>name</value></tag-name>
2367 <tag-desc>
2368 任意请求头的值；变量名的后半部为转化为小写并且用下划线替代横线后的请求头名称。
2369 </tag-desc>
2370
2371 <tag-name id="var_https"><var>$https</var></tag-name>
2372 <tag-desc>
2373 如果连接是SSL模块，返回“<literal>on</literal>”，否则返回空字符串。
2374 </tag-desc>
2375
2376 <tag-name id="var_is_args"><var>$is_args</var></tag-name>
2377 <tag-desc>
2378 如果请求行带有参数，返回“<literal>?</literal>”，否则返回空字符串。
2379 </tag-desc>
2380
2381 <tag-name id="var_limit_rate"><var>$limit_rate</var></tag-name>
2382 <tag-desc>
2383 允许设置此值来限制连接的传输速率。
2384 </tag-desc>
2385
2386 <tag-name id="var_msec"><var>$msec</var></tag-name>
2387 <tag-desc>
2388 当前时间，单位是秒，精度是毫秒。(1.3.9, 1.2.6)
2389 </tag-desc>
2390
2391 <tag-name id="var_nginx_version"><var>$nginx_version</var></tag-name>
2392 <tag-desc>
2393 nginx版本号。
2394 </tag-desc>
2395
2396 <tag-name id="var_pid"><var>$pid</var></tag-name>
2397 <tag-desc>
2398 worker进程的PID。
2399 </tag-desc>
2400
2401 <tag-name id="var_query_string"><var>$query_string</var></tag-name>
2402 <tag-desc>
2403 与<var>$args</var>相同。
2404 </tag-desc>
2405
2406 <tag-name id="var_realpath_root"><var>$realpath_root</var></tag-name>
2407 <tag-desc>
2408 按<link id="root"/>指令或<link id="alias"/>指令算出的当前请求的绝对路径。其中的符号链接都会解析成真是文件路径。
2409 </tag-desc>
2410
2411 <tag-name id="var_remote_addr"><var>$remote_addr</var></tag-name>
2412 <tag-desc>
2413 客户端IP地址。
2414 </tag-desc>
2415
2416 <tag-name id="var_remote_port"><var>$remote_port</var></tag-name>
2417 <tag-desc>
2418 客户端端口。
2419 </tag-desc>
2420
2421 <tag-name id="var_remote_user"><var>$remote_user</var></tag-name>
2422 <tag-desc>
2423 为基本用户认证提供的用户名。
2424 </tag-desc>
2425
2426 <tag-name id="var_request"><var>$request</var></tag-name>
2427 <tag-desc>
2428 完整的原始请求行。
2429 </tag-desc>
2430
2431 <tag-name id="var_request_body"><var>$request_body</var></tag-name>
2432 <tag-desc>
2433 请求正文。
2434 <para>
2435 在由<link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>指令和
2436 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>指令处理的路径中，
2437 这个变量值可用。
2438 </para>
2439 </tag-desc>
2440
2441 <tag-name id="var_reuqest_body_file"><var>$request_body_file</var></tag-name>
2442 <tag-desc>
2443 请求正文的临时文件名。
2444 <para>
2445 处理完成时，临时文件将被删除。
2446 如果希望总是将请求正文写入文件，需要开启<link id="client_body_in_file_only"/>。
2447 如果在被代理的请求或FastCGI请求中传递临时文件名，就应该禁止传递请求正文本身。
2448 使用<link doc="ngx_http_proxy_module.xml" id="proxy_pass_request_body">proxy_pass_request_body off</link>指令
2449 和<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass_request_body">fastcgi_pass_request_body off</link>指令
2450 分别禁止在代理和FastCGI中传递请求正文。
2451 </para>
2452 </tag-desc>
2453
2454 <tag-name id="var_request_complete"><var>$request_completion</var></tag-name>
2455 <tag-desc>
2456 请求完成时返回“<literal>OK</literal>”，否则返回空字符串。
2457 </tag-desc>
2458
2459 <tag-name id="var_request_filename"><var>$request_filename</var></tag-name>
2460 <tag-desc>
2461 基于<link id="root"/>指令或<link id="alias"/>指令，以及请求URI，得到的当前请求的文件路径。
2462 </tag-desc>
2463
2464 <tag-name id="var_request_method"><var>$request_method</var></tag-name>
2465 <tag-desc>
2466 HTTP方法，通常为“<literal>GET</literal>”或者“<literal>POST</literal>”。
2467 </tag-desc>
2468
2469 <tag-name id="var_request_time"><var>$request_time</var></tag-name>
2470 <tag-desc>
2471 请求处理的时间，单位为秒，精度是毫秒(1.3.9, 1.2.6)；请求处理时间从由客户端接收到第一个字节开始计算。
2472 </tag-desc>
2473
2474 <tag-name id="var_request_uri"><var>$request_uri</var></tag-name>
2475 <tag-desc>
2476 完整的原始请求行（带参数）。
2477 </tag-desc>
2478
2479 <tag-name id="var_scheme"><var>$scheme</var></tag-name>
2480 <tag-desc>
2481 请求协议类型，为“<literal>http</literal>”或“<literal>https</literal>”。
2482 </tag-desc>
2483
2484 <tag-name id="var_sent_http_"><var>$sent_http_</var><value>name</value></tag-name>
2485 <tag-desc>
2486 任意的响应头字段的值。
2487 变量名的后半部为转化为小写并且用下划线替代横线后的响应头名称。
2488 </tag-desc>
2489
2490 <tag-name id="var_server_addr"><var>$server_addr</var></tag-name>
2491 <tag-desc>
2492 接受请求的服务器地址。
2493 <para>
2494 为计算这个值，通常需要进行一次系统调用。为了避免系统调用，必须指定<link id="listen"/>指令
2495 的地址，并且使用<literal>bind</literal>参数。
2496 </para>
2497 </tag-desc>
2498
2499 <tag-name id="var_server_name"><var>$server_name</var></tag-name>
2500 <tag-desc>
2501 接受请求的虚拟主机的首要主机名。
2502 </tag-desc>
2503
2504 <tag-name id="var_server_port"><var>$server_port</var></tag-name>
2505 <tag-desc>
2506 接受请求的虚拟主机的端口。
2507 </tag-desc>
2508
2509 <tag-name id="var_server_protocol"><var>$server_protocol</var></tag-name>
2510 <tag-desc>
2511 请求协议，通常为“<literal>HTTP/1.0</literal>”或“<literal>HTTP/1.1</literal>”。
2512 </tag-desc>
2513
2514 <tag-name id="var_status"><var>$status</var></tag-name>
2515 <tag-desc>
2516 响应状态码。
2517 </tag-desc>
2518
2519 <tag-name id="var_tcpinfo_">
2520 <var>$tcpinfo_rtt</var>,
2521 <var>$tcpinfo_rttvar</var>,
2522 <var>$tcpinfo_snd_cwnd</var>,
2523 <var>$tcpinfo_rcv_space</var>
2524 </tag-name>
2525 <tag-desc>
2526 客户端TCP连接的信息，在支持套接字选项<c-def>TCP_INFO</c-def>的系统中可用。
2527 </tag-desc>
2528
2529 <tag-name id="var_uri"><var>$uri</var></tag-name>
2530 <tag-desc>
2531 当前请求<link id="location">规范化</link>以后的URI。
2532 <para>
2533 变量<var>$uri</var>的值可能随请求的处理过程而改变。
2534 比如，当进行内部跳转时，或者使用默认页文件。
2535 </para>
2536 </tag-desc>
2537
2538 </list>
2539 </para>
2540
2541 </section>
2542
2543 </module>