Mercurial > hg > nginx-site

comparison xml/cn/docs/http/ngx_http_proxy_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
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_proxy_module 模块"
11 link="/cn/docs/http/ngx_http_proxy_module.html"
12 lang="cn"
13 translator="cfsego"
14 rev="1">
15
16 <section id="summary">
17
18 <para>
19 <literal>ngx_http_proxy_module</literal> 模块允许传送请求到其它服务器。
20 </para>
21
22 </section>
23
24
25 <section id="example" name="配置示例">
26
27 <para>
28 <example>
29 location / {
30 proxy_pass http://localhost:8000;
31 proxy_set_header Host $host;
32 proxy_set_header X-Real-IP $remote_addr;
33 }
34 </example>
35 </para>
36
37 </section>
38
39
40 <section id="directives" name="指令">
41
42 <directive name="proxy_buffer_size">
43 <syntax><value>size</value></syntax>
44 <default>4k|8k</default>
45 <context>http</context>
46 <context>server</context>
47 <context>location</context>
48
49 <para>
50 设置缓冲区的大小为<value>size</value>。nginx从被代理的服务器读取响应时，使用该缓冲区保存响应的开始部分。这部分通常包含着一个小小的响应头。该缓冲区大小默认等于<link id="proxy_buffers"/>指令设置的一块缓冲区的大小，但它也可以被设置得更小。
51 </para>
52
53 </directive>
54
55
56 <directive name="proxy_buffering">
57 <syntax><literal>on</literal> | <literal>off</literal></syntax>
58 <default>on</default>
59 <context>http</context>
60 <context>server</context>
61 <context>location</context>
62
63 <para>
64 代理的时候，开启或关闭缓冲后端服务器的响应。
65 </para>
66
67 <para>
68 当开启缓冲时，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"/>指令可以控制临时文件的写入。
69 </para>
70
71 <para>
72 当关闭缓冲时，收到响应后，nginx立即将其同步传给客户端。nginx不会尝试从被代理的服务器读取整个请求，而是将<link id="proxy_buffer_size"/>指令设定的大小作为一次读取的最大长度。
73 </para>
74
75 <para>
76 响应头<header>X-Accel-Buffering</header>传递“<literal>yes</literal>”或“<literal>no</literal>”可以动态地开启或关闭代理的缓冲功能。
77 这个能力可以通过<link doc="ngx_http_proxy_module.xml" id="proxy_ignore_headers"/>指令关闭。
78 </para>
79
80 </directive>
81
82
83 <directive name="proxy_buffers">
84 <syntax><value>number</value> <value>size</value></syntax>
85 <default>8 4k|8k</default>
86 <context>http</context>
87 <context>server</context>
88 <context>location</context>
89
90 <para>
91 为每个连接设置缓冲区的数量为<value>number</value>，每块缓冲区的大小为<value>size</value>。这些缓冲区用于保存从被代理的服务器读取的响应。每块缓冲区默认等于一个内存页的大小。这个值是4K还是8K，取决于平台。
92 </para>
93
94 </directive>
95
96
97 <directive name="proxy_busy_buffers_size">
98 <syntax><value>size</value></syntax>
99 <default>8k|16k</default>
100 <context>http</context>
101 <context>server</context>
102 <context>location</context>
103
104 <para>
105 当开启<link id="proxy_buffering">缓冲</link>响应的功能以后，在没有读到全部响应的情况下，写缓冲到达一定<value>大小</value>时，nginx一定会向客户端发送响应，直到缓冲小于此值。这条指令用来设置此值。
106 同时，剩余的缓冲区可以用于接收响应，如果需要，一部分内容将缓冲到临时文件。该<value>大小</value>默认是<link id="proxy_buffer_size"/>和<link id="proxy_buffers"/>指令设置单块缓冲大小的两倍。
107 </para>
108
109 </directive>
110
111
112 <directive name="proxy_cache">
113 <syntax><value>zone</value> | <literal>off</literal></syntax>
114 <default>off</default>
115 <context>http</context>
116 <context>server</context>
117 <context>location</context>
118
119 <para>
120 指定用于页面缓存的共享内存。同一块共享内存可以在多个地方使用。<literal>off</literal>参数可以屏蔽从上层配置继承的缓存功能。
121 </para>
122
123 </directive>
124
125
126 <directive name="proxy_cache_bypass">
127 <syntax><value>string</value> ...</syntax>
128 <default/>
129 <context>http</context>
130 <context>server</context>
131 <context>location</context>
132
133 <para>
134 定义nginx不从缓存取响应的条件。如果至少一个字符串条件非空而且非“0”，nginx就不会从缓存中去取响应：
135 <example>
136 proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
137 proxy_cache_bypass $http_pragma $http_authorization;
138 </example>
139 本指令可和与<link id="proxy_no_cache"/>一起使用。
140 </para>
141
142 </directive>
143
144
145 <directive name="proxy_cache_key">
146 <syntax><value>string</value></syntax>
147 <default>$scheme$proxy_host$request_uri</default>
148 <context>http</context>
149 <context>server</context>
150 <context>location</context>
151
152 <para>
153 定义如何生成缓存的键，比如
154 <example>
155 proxy_cache_key "$host$request_uri $cookie_user";
156 </example>
157 这条指令的默认值类似于下面字符串
158 <example>
159 proxy_cache_key $scheme$proxy_host$uri$is_args$args;
160 </example>
161 </para>
162
163 </directive>
164
165
166 <directive name="proxy_cache_lock">
167 <syntax><literal>on</literal> | <literal>off</literal></syntax>
168 <default>off</default>
169 <context>http</context>
170 <context>server</context>
171 <context>location</context>
172 <appeared-in>1.1.12</appeared-in>
173
174 <para>
175 开启此功能时，对于相同的请求，同时只允许一个请求发往后端，并根据<link id="proxy_cache_key"/>指令的设置在缓存中植入一个新条目。
176 其他请求相同条目的请求将一直等待，直到缓存中出现相应的内容，或者锁在<link id="proxy_cache_lock_timeout"/>指令设置的超时后被释放。
177 </para>
178
179 </directive>
180
181
182 <directive name="proxy_cache_lock_timeout">
183 <syntax><value>time</value></syntax>
184 <default>5s</default>
185 <context>http</context>
186 <context>server</context>
187 <context>location</context>
188 <appeared-in>1.1.12</appeared-in>
189
190 <para>
191 为<link id="proxy_cache_lock"/>指令设置锁的超时。
192 </para>
193
194 </directive>
195
196
197 <directive name="proxy_cache_min_uses">
198 <syntax><value>number</value></syntax>
199 <default>1</default>
200 <context>http</context>
201 <context>server</context>
202 <context>location</context>
203
204 <para>
205 设置响应被缓存的最小请求<value>次数</value>。
206 </para>
207
208 </directive>
209
210
211 <directive name="proxy_cache_path">
212 <syntax>
213 <value>path</value>
214 [<literal>levels</literal>=<value>levels</value>]
215 <literal>keys_zone</literal>=<value>name</value>:<value>size</value>
216 [<literal>inactive</literal>=<value>time</value>]
217 [<literal>max_size</literal>=<value>size</value>]
218 [<literal>loader_files</literal>=<value>number</value>]
219 [<literal>loader_sleep</literal>=<value>time</value>]
220 [<literal>loader_threshold</literal>=<value>time</value>]</syntax>
221 <default/>
222 <context>http</context>
223
224 <para>
225 设置缓存的路径和其他参数。缓存数据是保存在文件中的，缓存的键和文件名都是在代理URL上执行MD5的结果。
226
227 <literal>levels</literal>参数定义了缓存的层次结构。比如，下面配置
228 <example>
229 proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
230 </example>
231 缓存中文件名看起来是这样的：
232 <example>
233 /data/nginx/cache/<emphasis>c</emphasis>/<emphasis>29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis>
234 </example>
235 </para>
236
237 <para>
238 被缓存的响应首先写入一个临时文件，然后进行重命名。从0.8.9版本开始，临时文件和缓存可以放在不同的文件系统。但请注意，这将导致文件在这两个文件系统中进行拷贝，而不是廉价的重命名操作。因此，针对任何路径，都建议将缓存和<link id="proxy_temp_path"/>指令设置的临时文件目录放在同一文件系统。
239 </para>
240
241 <para>
242 此外，所有活动的键和缓存数据相关的信息都被存放在共享内存中。共享内存通过<literal>keys_zone</literal>参数的<value>name</value>和<value>size</value>来定义。被缓存的数据如果在<literal>inactive</literal>参数指定的时间内未被访问，就会被从缓存中移除，不论它是否是刚产生的。<literal>inactive</literal>的默认值是10分钟。
243 </para>
244
245 <para>
246 特殊进程“cache manager”监控缓存的条目数量，如果超过<literal>max_size</literal>参数设置的最大值，使用LRU算法移除缓存数据。
247 </para>
248
249 <para>
250 nginx新启动后不就，特殊进程“cache loader”就被启动。该进程将文件系统上保存的过去缓存的数据的相关信息重新加载到共享内存。加载过程分多次迭代完成，每次迭代，进程只加载不多于<literal>loader_files</literal>参数指定的文件数量（默认值为100）。此外，每次迭代过程的持续时间不能超过<literal>loader_threshold</literal>参数的值（默认200毫秒）。每次迭代之间，nginx的暂停时间由<literal>loader_sleep</literal>参数指定（默认50毫秒）。
251 </para>
252
253 </directive>
254
255
256 <directive name="proxy_cache_use_stale">
257 <syntax>
258 <literal>error</literal> |
259 <literal>timeout</literal> |
260 <literal>invalid_header</literal> |
261 <literal>updating</literal> |
262 <literal>http_500</literal> |
263 <literal>http_502</literal> |
264 <literal>http_503</literal> |
265 <literal>http_504</literal> |
266 <literal>http_404</literal> |
267 <literal>off</literal>
268 ...</syntax>
269 <default>off</default>
270 <context>http</context>
271 <context>server</context>
272 <context>location</context>
273
274 <para>
275 如果后端服务器出现状况，nginx是可以使用过期的响应缓存的。这条指令就是定义何种条件下允许开启此机制。这条指令的参数与<link id="proxy_next_upstream"/>指令的参数相同。
276 </para>
277
278 <para>
279 此外，<literal>updating</literal>参数允许nginx在正在更新缓存的情况下使用过期的缓存作为响应。这样做可以使更新缓存数据时，访问源服务器的次数最少。
280 </para>
281
282 <para>
283 在植入新的缓存条目时，如果想使访问源服务器的次数最少，可以使用<link id="proxy_cache_lock"/>指令。
284 </para>
285
286 </directive>
287
288
289 <directive name="proxy_cache_valid">
290 <syntax>[<value>code</value> ...] <value>time</value></syntax>
291 <default/>
292 <context>http</context>
293 <context>server</context>
294 <context>location</context>
295
296 <para>
297 为不同的响应状态码设置不同的缓存时间。比如，下面指令
298 <example>
299 proxy_cache_valid 200 302 10m;
300 proxy_cache_valid 404 1m;
301 </example>
302 设置状态码为200和302的响应的缓存时间为10分钟，状态码为404的响应的缓存时间为1分钟。
303 </para>
304
305 <para>
306 如果仅仅指定了<value>time</value>，
307 <example>
308 proxy_cache_valid 5m;
309 </example>
310 那么只有状态码为200、300和302的响应会被缓存。
311 </para>
312
313 <para>
314 如果使用了<literal>any</literal>参数，那么就可以缓存任何响应：
315 <example>
316 proxy_cache_valid 200 302 10m;
317 proxy_cache_valid 301 1h;
318 proxy_cache_valid any 1m;
319 </example>
320 </para>
321
322 <para>
323 缓存参数也可以直接在响应头中设定。这种方式的优先级高于使用这条指令设置缓存时间。
324 <header>X-Accel-Expires</header>响应头可以以秒为单位设置响应的缓存时间，如果值为0，表示禁止缓存响应，如果值以<literal>@</literal>开始，表示自1970年1月1日以来的秒数，响应一直会被缓存到这个绝对时间点。
325 如果不含<header>X-Accel-Expires</header>响应头，缓存参数仍可能被<header>Expires</header>或者<header>Cache-Control</header>响应头设置。
326 如果响应头含有<header>Set-Cookie</header>，响应将不能被缓存。
327 这些头的处理过程可以使用指令<link id="proxy_ignore_headers"/>忽略。
328 </para>
329
330 </directive>
331
332
333 <directive name="proxy_connect_timeout">
334 <syntax><value>time</value></syntax>
335 <default>60s</default>
336 <context>http</context>
337 <context>server</context>
338 <context>location</context>
339
340 <para>
341 设置与后端服务器建立连接的超时时间。应该注意这个超时一般不可能大于75秒。
342 </para>
343
344 </directive>
345
346
347 <directive name="proxy_cookie_domain">
348 <syntax><literal>off</literal></syntax>
349 <syntax><value>domain</value> <value>replacement</value></syntax>
350 <default>off</default>
351 <context>http</context>
352 <context>server</context>
353 <context>location</context>
354 <appeared-in>1.1.15</appeared-in>
355
356 <para>
357 设置<header>Set-Cookie</header>响应头中的<literal>domain</literal>属性的替换文本。
358 假设后端服务器返回的<header>Set-Cookie</header>响应头含有属性“<literal>domain=localhost</literal>”，那么指令
359 <example>
360 proxy_cookie_domain localhost example.org;
361 </example>
362 将这个属性改写为“<literal>domain=example.org</literal>”。
363 </para>
364
365 <para>
366 <value>domain</value>和<value>replacement</value>配置字符串，以及<literal>domain</literal>属性中起始的点将被忽略。
367 匹配过程大小写不敏感。
368 </para>
369
370 <para>
371 <value>domain</value>和<value>replacement</value>配置字符串中可以包含变量：
372 <example>
373 proxy_cookie_domain www.$host $host;
374 </example>
375 </para>
376
377 <para>
378 这条指令同样可以使用正则表达式。这时，<value>domain</value>应以“<literal>~</literal>”标志开始，且可以使用命名匹配组和位置匹配组，而<value>replacement</value>可以引用这些匹配组：
379 <example>
380 proxy_cookie_domain ~\.(?P&lt;sl_domain&gt;[-0-9a-z]+\.[a-z]+)$ $sl_domain;
381 </example>
382 </para>
383
384 <para>
385 可以同时定义多条<literal>proxy_cookie_domain</literal>指令：
386 <example>
387 proxy_cookie_domain localhost example.org;
388 proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;
389 </example>
390 </para>
391
392 <para>
393 <literal>off</literal>参数可以取消当前配置级别的所有<literal>proxy_cookie_domain</literal>指令：
394 <example>
395 proxy_cookie_domain off;
396 proxy_cookie_domain localhost example.org;
397 proxy_cookie_domain www.example.org example.org;
398 </example>
399 </para>
400
401 </directive>
402
403
404 <directive name="proxy_cookie_path">
405 <syntax><literal>off</literal></syntax>
406 <syntax><value>path</value> <value>replacement</value></syntax>
407 <default>off</default>
408 <context>http</context>
409 <context>server</context>
410 <context>location</context>
411 <appeared-in>1.1.15</appeared-in>
412
413 <para>
414 设置<header>Set-Cookie</header>响应头中的<literal>path</literal>属性的替换文本。
415 假设后端服务器返回的<header>Set-Cookie</header>响应头含有属性“<literal>path=/two/some/uri/</literal>”，那么指令
416 <example>
417 proxy_cookie_path /two/ /;
418 </example>
419 将这个属性改写为“<literal>path=/some/uri/</literal>”。
420 </para>
421
422 <para>
423 <value>path</value>和<value>replacement</value>配置字符串可以包含变量：
424 <example>
425 proxy_cookie_path $uri /some$uri;
426 </example>
427 </para>
428
429 <para>
430 这条指令同样可以使用正则表达式。如果使用大小写敏感的匹配，<value>path</value>应以“<literal>~</literal>”标志开始，如果使用大小写不敏感的匹配，<value>path</value>应以“<literal>~*</literal>”标志开始。<value>path</value>可以使用命名匹配组和位置匹配组，<value>replacement</value>可以引用这些匹配组：
431 <example>
432 proxy_cookie_path ~*^/user/([^/]+) /u/$1;
433 </example>
434 </para>
435
436 <para>
437 可以同时定义多条<literal>proxy_cookie_path</literal>指令：
438 <example>
439 proxy_cookie_path /one/ /;
440 proxy_cookie_path / /two/;
441 </example>
442 </para>
443
444 <para>
445 <literal>off</literal>参数可以取消当前配置级别的所有<literal>proxy_cookie_path</literal>指令：
446 <example>
447 proxy_cookie_path off;
448 proxy_cookie_path /two/ /;
449 proxy_cookie_path ~*^/user/([^/]+) /u/$1;
450 </example>
451 </para>
452
453 </directive>
454
455
456 <directive name="proxy_hide_header">
457 <syntax><value>field</value></syntax>
458 <default/>
459 <context>http</context>
460 <context>server</context>
461 <context>location</context>
462
463 <para>
464 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"/>指令。
465 </para>
466
467 </directive>
468
469
470 <directive name="proxy_http_version">
471 <syntax><literal>1.0</literal> | <literal>1.1</literal></syntax>
472 <default>1.0</default>
473 <context>http</context>
474 <context>server</context>
475 <context>location</context>
476 <appeared-in>1.1.4</appeared-in>
477
478 <para>
479 设置代理使用的HTTP协议版本。默认使用的版本是1.0，而1.1版本则推荐在使用<link doc="ngx_http_upstream_module.xml" id="keepalive"/>连接时一起使用。
480 </para>
481
482 </directive>
483
484
485 <directive name="proxy_ignore_client_abort">
486 <syntax><literal>on</literal> | <literal>off</literal></syntax>
487 <default>off</default>
488 <context>http</context>
489 <context>server</context>
490 <context>location</context>
491
492 <para>
493 决定当客户端在响应传输完成前就关闭连接时，nginx是否应关闭后端连接。
494 </para>
495
496 </directive>
497
498
499 <directive name="proxy_ignore_headers">
500 <syntax><value>field</value> ...</syntax>
501 <default/>
502 <context>http</context>
503 <context>server</context>
504 <context>location</context>
505
506 <para>
507 不处理后端服务器返回的指定响应头。下面的响应头可以被设置：
508 <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)，
509 <header>X-Accel-Charset</header> (1.1.6)，<header>Expires</header>，<header>Cache-Control</header>，和<header>Set-Cookie</header> (0.8.44)。
510 </para>
511
512 <para>
513 如果不被取消，这些头部的处理可能产生下面结果：
514 <list type="bullet" compact="no">
515
516 <listitem>
517 <header>X-Accel-Expires</header>，<header>Expires</header>，<header>Cache-Control</header>，和<header>Set-Cookie</header>
518 设置响应<link id="proxy_cache_valid">缓存</link>的参数；
519 </listitem>
520
521 <listitem>
522 <header>X-Accel-Redirect</header>执行到指定URI的<link doc="ngx_http_core_module.xml" id="internal">内部跳转</link>；
523 </listitem>
524
525 <listitem>
526 <header>X-Accel-Limit-Rate</header>设置响应到客户端的传输<link doc="ngx_http_core_module.xml" id="limit_rate">速率限制</link>；
527 </listitem>
528
529 <listitem>
530 <header>X-Accel-Buffering</header>启动或者关闭响应<link id="proxy_buffering">缓冲</link>；
531 </listitem>
532
533 <listitem>
534 <header>X-Accel-Charset</header>设置响应所需的<link doc="ngx_http_charset_module.xml" id="charset">字符集</link>。
535 </listitem>
536
537 </list>
538 </para>
539
540 </directive>
541
542
543 <directive name="proxy_intercept_errors">
544 <syntax><literal>on</literal> | <literal>off</literal></syntax>
545 <default>off</default>
546 <context>http</context>
547 <context>server</context>
548 <context>location</context>
549
550 <para>
551 当后端服务器的响应状态码大于等于400时，决定是否直接将响应发送给客户端，亦或将响应转发给nginx由<link doc="ngx_http_core_module.xml" id="error_page"/>指令来处理。
552 </para>
553
554 </directive>
555
556
557 <directive name="proxy_max_temp_file_size">
558 <syntax><value>size</value></syntax>
559 <default>1024m</default>
560 <context>http</context>
561 <context>server</context>
562 <context>location</context>
563
564 <para>
565 打开响应<link id="proxy_buffering">缓冲</link>以后，如果整个响应不能存放在<link id="proxy_buffer_size"/>和<link id="proxy_buffers"/>指令设置的缓冲区内，部分响应可以存放在临时文件中。
566 这条指令可以设置临时文件的最大<value>容量</value>。而每次写入临时文件的数据量则由<link id="proxy_temp_file_write_size"/>指令定义。
567 </para>
568
569 <para>
570 将此值设置为0将禁止响应写入临时文件。
571 </para>
572
573 </directive>
574
575
576 <directive name="proxy_next_upstream">
577 <syntax>
578 <literal>error</literal> |
579 <literal>timeout</literal> |
580 <literal>invalid_header</literal> |
581 <literal>http_500</literal> |
582 <literal>http_502</literal> |
583 <literal>http_503</literal> |
584 <literal>http_504</literal> |
585 <literal>http_404</literal> |
586 <literal>off</literal>
587 ...</syntax>
588 <default>error timeout</default>
589 <context>http</context>
590 <context>server</context>
591 <context>location</context>
592
593 <para>
594 指定在何种情况下一个失败的请求应该被发送到下一台后端服务器：
595 <list type="tag">
596
597 <tag-name><literal>error</literal></tag-name>
598 <tag-desc>和后端服务器建立连接时，或者向后端服务器发送请求时，或者从后端服务器接收响应头时，出现错误；</tag-desc>
599
600 <tag-name><literal>timeout</literal></tag-name>
601 <tag-desc>和后端服务器建立连接时，或者向后端服务器发送请求时，或者从后端服务器接收响应头时，出现超时；</tag-desc>
602
603 <tag-name><literal>invalid_header</literal></tag-name>
604 <tag-desc>后端服务器返回空响应或者非法响应头；</tag-desc>
605
606 <tag-name><literal>http_500</literal></tag-name>
607 <tag-desc>后端服务器返回的响应状态码为500；</tag-desc>
608
609 <tag-name><literal>http_502</literal></tag-name>
610 <tag-desc>后端服务器返回的响应状态码为502；</tag-desc>
611
612 <tag-name><literal>http_503</literal></tag-name>
613 <tag-desc>后端服务器返回的响应状态码为503；</tag-desc>
614
615 <tag-name><literal>http_504</literal></tag-name>
616 <tag-desc>后端服务器返回的响应状态码为504；</tag-desc>
617
618 <tag-name><literal>http_404</literal></tag-name>
619 <tag-desc>后端服务器返回的响应状态码为404；</tag-desc>
620
621 <tag-name><literal>off</literal></tag-name>
622 <tag-desc>停止将请求发送给下一台后端服务器。</tag-desc>
623
624 </list>
625 </para>
626
627 <para>
628 需要理解一点的是，只有在没有向客户端发送任何数据以前，将请求转给下一台后端服务器才是可行的。也就是说，如果在传输响应到客户端时出现错误或者超时，这类错误是不可能恢复的。
629 </para>
630
631 </directive>
632
633
634 <directive name="proxy_no_cache">
635 <syntax><value>string</value> ...</syntax>
636 <default/>
637 <context>http</context>
638 <context>server</context>
639 <context>location</context>
640
641 <para>
642 定义nginx不将响应写入缓存的条件。如果至少一个字符串条件非空而且非“0”，nginx就不将响应存入缓存：
643 <example>
644 proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
645 proxy_no_cache $http_pragma $http_authorization;
646 </example>
647 这条指令可以和<link id="proxy_cache_bypass"/>指令一起使用。
648 </para>
649
650 </directive>
651
652
653 <directive name="proxy_pass">
654 <syntax><value>URL</value></syntax>
655 <default/>
656 <context>location</context>
657 <context>if in location</context>
658 <context>limit_except</context>
659
660 <para>
661 设置后端服务器的协议和地址，还可以设置可选的URI以定义本地路径和后端服务器的映射关系。
662 这条指令可以设置的协议是“<literal>http</literal>”或者“<literal>https</literal>”，而地址既可以使用域名或者IP地址加端口（可选）的形式来定义：
663 <example>
664 proxy_pass http://localhost:8000/uri/;
665 </example>
666 又可以使用UNIX域套接字路径来定义。该路径接在“<literal>unix</literal>”字符串后面，两端由冒号所包围，比如：
667 <example>
668 proxy_pass http://unix:/tmp/backend.socket:/uri/;
669 </example>
670 </para>
671
672 <para>
673 如果解析一个域名得到多个地址，所有的地址都会以轮转的方式被使用。当然，也可以使用<link doc="ngx_http_upstream_module.xml">服务器组</link>来定义地址。
674 </para>
675
676 <para>
677 请求URI按下面规则传送给后端服务器：
678 <list type="bullet" compact="no">
679
680 <listitem>
681 如果<literal>proxy_pass</literal>使用了URI，当传送请求到后端服务器时，<link doc="ngx_http_core_module.xml" id="location">规范化</link>以后的请求路径与配置中的路径的匹配部分将被替换为指令中定义的URI：
682 <example>
683 location /name/ {
684 proxy_pass http://127.0.0.1/remote/;
685 }
686 </example>
687 </listitem>
688
689 <listitem>
690 如果<literal>proxy_pass</literal>没有使用URI，传送到后端服务器的请求URI一般客户端发起的原始URI，如果nginx改变了请求URI，则传送的URI是nginx改变以后完整的规范化URI：
691 <example>
692 location /some/path/ {
693 proxy_pass http://127.0.0.1;
694 }
695 </example>
696 <note>
697 在1.1.12版以前，如果<literal>proxy_pass</literal>没有使用URI，某些情况下，nginx改变URI以后，会错误地将原始URI而不是改变以后的URI发送到后端服务器。
698 </note>
699 </listitem>
700 </list>
701 </para>
702
703 <para>
704 某些情况下，无法确定请求URI中应该被替换的部分：
705 <list type="bullet" compact="no">
706
707 <listitem>
708 使用正则表达式定义路径。
709 <para>
710 这种情况下，指令不应该使用URI。
711 </para>
712 </listitem>
713
714 <listitem>
715 在需要代理的路径中，使用<link doc="ngx_http_rewrite_module.xml" id="rewrite"/>指令改变了URI，但仍使用相同配置处理请求(<literal>break</literal>)：
716 <example>
717 location /name/ {
718 rewrite /name/([^/]+) /users?name=$1 break;
719 proxy_pass http://127.0.0.1;
720 }
721 </example>
722 <para>
723 这种情况下，本指令设置的URI会被忽略，改变后的URI将被发送给后端服务器。
724 </para>
725 </listitem>
726 </list>
727 </para>
728
729 <para>
730 后端服务器的地址，端口和URI中都可以使用变量：
731 <example>
732 proxy_pass http://$host$uri;
733 </example>
734 甚至像这样：
735 <example>
736 proxy_pass $request;
737 </example>
738 </para>
739
740 <para>
741 这种情况下，后端服务器的地址将会在定义的<link doc="ngx_http_upstream_module.xml">服务器组</link>中查找。如果查找不到，nginx使用<link doc="ngx_http_core_module.xml" id="resolver"/>来查找该地址。
742 </para>
743
744 </directive>
745
746
747 <directive name="proxy_pass_header">
748 <syntax><value>field</value></syntax>
749 <default/>
750 <context>http</context>
751 <context>server</context>
752 <context>location</context>
753
754 <para>
755 允许传送<link id="proxy_hide_header">被屏蔽</link>的后端服务器响应头到客户端。
756 </para>
757
758 </directive>
759
760
761 <directive name="proxy_read_timeout">
762 <syntax><value>time</value></syntax>
763 <default>60s</default>
764 <context>http</context>
765 <context>server</context>
766 <context>location</context>
767
768 <para>
769 定义从后端服务器读取响应的超时。此超时是指相邻两次读操作之间的最长时间间隔，而不是整个响应传输完成的最长时间。如果后端服务器在超时时间段内没有传输任何数据，连接将被关闭。
770 </para>
771
772 </directive>
773
774
775 <directive name="proxy_redirect">
776 <syntax><literal>default</literal></syntax>
777 <syntax><literal>off</literal></syntax>
778 <syntax><value>redirect</value> <value>replacement</value></syntax>
779 <default>default</default>
780 <context>http</context>
781 <context>server</context>
782 <context>location</context>
783
784 <para>
785 设置后端服务器<header>Location</header>响应头和<header>Refresh</header>响应头的替换文本。
786 假设后端服务器返回的响应头是
787 “<literal>Location: http://localhost:8000/two/some/uri/</literal>”，那么指令
788 <example>
789 proxy_redirect http://localhost:8000/two/ http://frontend/one/;
790 </example>
791 将把字符串改写为
792 “<literal>Location: http://frontend/one/some/uri/</literal>”。
793 </para>
794
795 <para>
796 <value>replacement</value>字符串可以省略服务器名：
797 <example>
798 proxy_redirect http://localhost:8000/two/ /;
799 </example>
800 此时将使用代理服务器的主域名和端口号来替换。如果端口是80，可以不加。
801 </para>
802
803 <para>
804 用<literal>default</literal>参数指定的默认替换使用了<link doc="ngx_http_core_module.xml" id="location"/>和<link id="proxy_pass"/>指令的参数。因此，下面两例配置等价：
805 <example>
806 location /one/ {
807 proxy_pass http://upstream:port/two/;
808 proxy_redirect default;
809 </example>
810
811 <example>
812 location /one/ {
813 proxy_pass http://upstream:port/two/;
814 proxy_redirect http://upstream:port/two/ /one/;
815 </example>
816 而且因为同样的原因，<link id="proxy_pass"/>指令使用变量时，不允许本指令使用<literal>default</literal>参数。
817 </para>
818
819 <para>
820 <value>replacement</value>字符串可以包含变量：
821 <example>
822 proxy_redirect http://localhost:8000/ http://$host:$server_port/;
823 </example>
824 </para>
825
826 <para>
827 而<value>redirect</value>字符串从1.1.11版本开始也可以包含变量：
828 <example>
829 proxy_redirect http://$proxy_host:8000/ /;
830 </example>
831 </para>
832
833 <para>
834 同时，从1.1.11版本开始，指令支持正则表达式。使用正则表达式的话，如果是大小写敏感的匹配，<value>redirect</value>以“<literal>~</literal>”作为开始，如果是大小写不敏感的匹配，<value>redirect</value>以“<literal>~*</literal>”作为开始。而且<value>redirect</value>的正则表达式中可以包含命名匹配组和位置匹配组，而在<value>replacement</value>中可以引用这些匹配组的值：
835 <example>
836 proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
837 proxy_redirect ~*/user/([^/]+)/(.+)$ http://$1.example.com/$2;
838 </example>
839 </para>
840
841 <para>
842 除此以外，可以同时定义多个<literal>proxy_redirect</literal>指令：
843 <example>
844 proxy_redirect default;
845 proxy_redirect http://localhost:8000/ /;
846 proxy_redirect http://www.example.com/ /;
847 </example>
848 </para>
849
850 <para>
851 另外，<literal>off</literal>参数可以使所有相同配置级别的<literal>proxy_redirect</literal>指令无效：
852 <example>
853 proxy_redirect off;
854 proxy_redirect default;
855 proxy_redirect http://localhost:8000/ /;
856 proxy_redirect http://www.example.com/ /;
857 </example>
858 </para>
859
860 <para>
861 最后，使用这条指令也可以为地址为相对地址的重定向添加域名：
862 <example>
863 proxy_redirect / /;
864 </example>
865 </para>
866
867 </directive>
868
869
870 <directive name="proxy_send_timeout">
871 <syntax><value>time</value></syntax>
872 <default>60s</default>
873 <context>http</context>
874 <context>server</context>
875 <context>location</context>
876
877 <para>
878 定义向后端服务器传输请求的超时。此超时是指相邻两次写操作之间的最长时间间隔，而不是整个请求传输完成的最长时间。如果后端服务器在超时时间段内没有接收到任何数据，连接将被关闭。
879 </para>
880
881 </directive>
882
883
884 <directive name="proxy_set_header">
885 <syntax><value>field</value> <value>value</value></syntax>
886 <default>Host $proxy_host</default>
887 <default>Connection close</default>
888 <context>http</context>
889 <context>server</context>
890 <context>location</context>
891
892 <para>
893 允许重新定义或者添加发往后端服务器的请求头。<value>value</value>可以包含文本、变量或者它们的组合。
894 当且仅当当前配置级别中没有定义<literal>proxy_set_header</literal>指令时，会从上面的级别继承配置。
895 默认情况下，只有两个请求头会被重新定义：
896 <example>
897 proxy_set_header Host $proxy_host;
898 proxy_set_header Connection close;
899 </example>
900 </para>
901
902 <para>
903 如果不想改变请求头<header>Host</header>的值，可以这样来设置：
904 <example>
905 proxy_set_header Host $http_host;
906 </example>
907 </para>
908
909 <para>
910 但是，如果客户端请求头中没有携带这个头部，那么传递到后端服务器的请求也不含这个头部。
911 这种情况下，更好的方式是使用<var>$host</var>变量——它的值在请求包含<header>Host</header>请求头时为<header>Host</header>字段的值，在请求未携带<header>Host</header>请求头时为虚拟主机的主域名：
912 <example>
913 proxy_set_header Host $host;
914 </example>
915 </para>
916
917 <para>
918 此外，服务器名可以和后端服务器的端口一起传送：
919 <example>
920 proxy_set_header Host $host:$proxy_port;
921 </example>
922 </para>
923
924 <para>
925 如果某个请求头的值为空，那么这个请求头将不会传送给后端服务器：
926 <example>
927 proxy_set_header Accept-Encoding "";
928 </example>
929 </para>
930
931 </directive>
932
933
934 <directive name="proxy_ssl_session_reuse">
935 <syntax><literal>on</literal> | <literal>off</literal></syntax>
936 <default>on</default>
937 <context>http</context>
938 <context>server</context>
939 <context>location</context>
940
941 <para>
942 决定是否重用与后端服务器的SSL会话。如果日志中出现“<literal>SSL3_GET_FINISHED:digest check failed</literal>”错误，请尝试关闭会话重用。
943 </para>
944
945 </directive>
946
947
948 <directive name="proxy_store">
949 <syntax>
950 <literal>on</literal> |
951 <literal>off</literal> |
952 <value>string</value></syntax>
953 <default>off</default>
954 <context>http</context>
955 <context>server</context>
956 <context>location</context>
957
958 <para>
959 开启将文件保存到磁盘上的功能。如果设置为<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>参数来指定：
960 <example>
961 proxy_store /data/www$original_uri;
962 </example>
963 </para>
964
965 <para>
966 保存文件的修改时间根据接收到的<header>Last-Modified</header>响应头来设置。响应都是先写到临时文件，然后进行重命名来生成的。从0.8.9版本开始，临时文件和持久化存储可以放在不同的文件系统，但是需要注意这时文件执行的是在两个文件系统间拷贝操作，而不是廉价的重命名操作。因此建议保存文件的路径和<link id="proxy_temp_path"/>指令设置的临时文件的路径在同一个文件系统中。
967 </para>
968
969 <para>
970 这条指令可以用于创建静态无更改文件的本地拷贝，比如：
971 <example>
972 location /images/ {
973 root /data/www;
974 open_file_cache_errors off;
975 error_page 404 = /fetch$uri;
976 }
977
978 location /fetch/ {
979 internal;
980
981 proxy_pass http://backend/;
982 proxy_store on;
983 proxy_store_access user:rw group:rw all:r;
984 proxy_temp_path /data/temp;
985
986 alias /data/www/;
987 }
988 </example>
989 </para>
990
991 <para>
992 或者像这样：
993 <example>
994 location /images/ {
995 root /data/www;
996 error_page 404 = @fetch;
997 }
998
999 location @fetch {
1000 internal;
1001
1002 proxy_pass http://backend;
1003 proxy_store on;
1004 proxy_store_access user:rw group:rw all:r;
1005 proxy_temp_path /data/temp;
1006
1007 root /data/www;
1008 }
1009 </example>
1010 </para>
1011
1012 </directive>
1013
1014
1015 <directive name="proxy_store_access">
1016 <syntax><value>users</value>:<value>permissions</value> ...</syntax>
1017 <default>user:rw</default>
1018 <context>http</context>
1019 <context>server</context>
1020 <context>location</context>
1021
1022 <para>
1023 设置新创建的文件和目录的访问权限，比如：
1024 <example>
1025 proxy_store_access user:rw group:rw all:r;
1026 </example>
1027 </para>
1028
1029 <para>
1030 如果指定了任何<literal>group</literal>或者<literal>all</literal>的访问权限，那么可以略去<literal>user</literal>的访问权限：
1031 <example>
1032 proxy_store_access group:rw all:r;
1033 </example>
1034 </para>
1035
1036 </directive>
1037
1038
1039 <directive name="proxy_temp_file_write_size">
1040 <syntax><value>size</value></syntax>
1041 <default>8k|16k</default>
1042 <context>http</context>
1043 <context>server</context>
1044 <context>location</context>
1045
1046 <para>
1047 在开启缓冲后端服务器响应到临时文件的功能后，设置nginx每次写数据到临时文件的<value>size(大小)</value>限制。
1048 <value>size</value>的默认值是<link id="proxy_buffer_size"/>指令和<link id="proxy_buffers"/>指令定义的每块缓冲区大小的两倍，
1049 而临时文件最大容量由<link id="proxy_max_temp_file_size"/>指令设置。
1050 </para>
1051
1052 </directive>
1053
1054
1055 <directive name="proxy_temp_path">
1056 <syntax>
1057 <value>path</value>
1058 [<value>level1</value>
1059 [<value>level2</value>
1060 [<value>level3</value>]]]</syntax>
1061 <default>proxy_temp</default>
1062 <context>http</context>
1063 <context>server</context>
1064 <context>location</context>
1065
1066 <para>
1067 定义从后端服务器接收的临时文件的存放路径，可以为临时文件路径定义至多三层子目录的目录树。
1068 比如，下面配置
1069 <example>
1070 proxy_temp_path /spool/nginx/proxy_temp 1 2;
1071 </example>
1072 那么临时文件的路径看起来会是这样：
1073 <example>
1074 /spool/nginx/proxy_temp/<emphasis>7</emphasis>/<emphasis>45</emphasis>/00000123<emphasis>457</emphasis>
1075 </example>
1076 </para>
1077
1078 </directive>
1079
1080 </section>
1081
1082
1083 <section id="variables" name="内嵌变量">
1084
1085 <para>
1086 <literal>ngx_http_proxy_module</literal>支持内嵌变量，可以用于在<link id="proxy_set_header"/>指令中构造请求头：
1087 <list type="tag">
1088
1089 <tag-name><var>$proxy_host</var></tag-name>
1090 <tag-desc>后端服务器的主机名和端口；</tag-desc>
1091
1092 <tag-name><var>$proxy_port</var></tag-name>
1093 <tag-desc>后端服务器的端口；</tag-desc>
1094
1095 <tag-name><var>$proxy_add_x_forwarded_for</var></tag-name>
1096 <tag-desc>将<var>$remote_addr</var>变量值添加在客户端<header>X-Forwarded-For</header>请求头的后面，并以逗号分隔。
1097 如果客户端请求未携带<header>X-Forwarded-For</header>请求头，<var>$proxy_add_x_forwarded_for</var>变量值将与<var>$remote_addr</var>变量相同。</tag-desc>
1098 </list>
1099 </para>
1100
1101 </section>
1102
1103 </module>