Mercurial > hg > nginx-site

comparison xml/cn/docs/http/ngx_http_upstream_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_upstream_module模块"
11 link="/cn/docs/http/ngx_http_upstream_module.html"
12 lang="cn"
13 translator="Weibin Yao"
14 rev="1">
15
16 <section id="summary">
17
18 <para>
19 <literal>ngx_http_upstream_module</literal>模块
20 允许定义一组服务器。它们可以在指令<link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>、
21 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>和
22 <link doc="ngx_http_memcached_module.xml" id="memcached_pass"/>中被引用到。
23 </para>
24
25 </section>
26
27
28 <section id="example" name="配置例子">
29
30 <para>
31 <example>
32 upstream <emphasis>backend</emphasis> {
33 server backend1.example.com weight=5;
34 server backend2.example.com:8080;
35 server unix:/tmp/backend3;
36
37 server backup1.example.com:8080 backup;
38 server backup2.example.com:8080 backup;
39 }
40
41 server {
42 location / {
43 proxy_pass http://<emphasis>backend</emphasis>;
44 }
45 }
46 </example>
47 </para>
48
49 </section>
50
51
52 <section id="directives" name="指令">
53
54 <directive name="upstream">
55 <syntax block="yes"><value>name</value></syntax>
56 <default/>
57 <context>http</context>
58
59 <para>
60 定义一组服务器。
61 这些服务器可以监听不同的端口。
62 而且，监听在TCP和UNIX域套接字的服务器可以混用。
63 </para>
64
65 <para>
66 例子：
67 <example>
68 upstream backend {
69 server backend1.example.com weight=5;
70 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
71 server unix:/tmp/backend3;
72 }
73 </example>
74 </para>
75
76 <para>
77 默认情况下，nginx按加权轮转的方式将请求分发到各服务器。
78 在上面的例子中，每7个请求会通过以下方式分发：
79 5个请求分到<literal>backend1.example.com</literal>，
80 一个请求分到第二个服务器，一个请求分到第三个服务器。
81 与服务器通信的时候，如果出现错误，请求会被传给下一个服务器，直到所有可用的服务器都被尝试过。
82 如果所有服务器都返回失败，客户端将会得到最后通信的那个服务器的（失败）响应结果。
83 </para>
84
85 </directive>
86
87
88 <directive name="server">
89 <syntax><value>address</value> [<value>parameters</value>]</syntax>
90 <default/>
91 <context>upstream</context>
92
93 <para>
94 定义服务器的地址<value>address</value>和其他参数<value>parameters</value>。
95 地址可以是域名或者IP地址，端口是可选的，或者是指定“<literal>unix:</literal>”前缀的UNIX域套接字的路径。如果没有指定端口，就使用80端口。
96 如果一个域名解析到多个IP，本质上是定义了多个server。
97 </para>
98
99 <para>
100 你可以定义下面的参数：
101 <list type="tag">
102
103 <tag-name><literal>weight</literal>=<value>number</value></tag-name>
104 <tag-desc>
105 设定服务器的权重，默认是1。
106 </tag-desc>
107
108 <tag-name><literal>max_fails</literal>=<value>number</value></tag-name>
109 <tag-desc>
110 设定Nginx与服务器通信的尝试失败的次数。在<literal>fail_timeout</literal>参数定义的时间段内，如果失败的次数达到此值，Nginx就认为服务器不可用。在下一个<literal>fail_timeout</literal>时间段，服务器不会再被尝试。
111 失败的尝试次数默认是1。设为0就会停止统计尝试次数，认为服务器是一直可用的。
112 你可以通过指令<link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>、
113 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>和
114 <link doc="ngx_http_memcached_module.xml" id="memcached_next_upstream"/>来配置什么是失败的尝试。
115 默认配置时，<literal>http_404</literal>状态不被认为是失败的尝试。
116 </tag-desc>
117
118 <tag-name><literal>fail_timeout</literal>=<value>time</value></tag-name>
119 <tag-desc>
120 设定
121 <list type="bullet">
122
123 <listitem>
124 统计失败尝试次数的时间段。在这段时间中，服务器失败次数达到指定的尝试次数，服务器就被认为不可用。
125 </listitem>
126
127 <listitem>
128 服务器被认为不可用的时间段。
129 </listitem>
130
131 </list>
132 默认情况下，该超时时间是10秒。
133 </tag-desc>
134
135 <tag-name><literal>backup</literal></tag-name>
136 <tag-desc>
137 标记为备用服务器。当主服务器不可用以后，请求会被传给这些服务器。
138 </tag-desc>
139
140 <tag-name><literal>down</literal></tag-name>
141 <tag-desc>
142 标记服务器永久不可用，可以跟<link id="ip_hash"/>指令一起使用。
143 </tag-desc>
144
145 </list>
146 </para>
147
148 <para>
149 Example:
150 <example>
151 upstream backend {
152 server backend1.example.com weight=5;
153 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
154 server unix:/tmp/backend3;
155
156 server backup1.example.com:8080 backup;
157 }
158 </example>
159 </para>
160
161 </directive>
162
163
164 <directive name="ip_hash">
165 <syntax/>
166 <default/>
167 <context>upstream</context>
168
169 <para>
170 指定服务器组的负载均衡方法，请求基于客户端的IP地址在服务器间进行分发。
171 IPv4地址的前三个字节或者IPv6的整个地址，会被用来作为一个散列key。
172 这种方法可以确保从同一个客户端过来的请求，会被传给同一台服务器。除了当服务器被认为不可用的时候，这些客户端的请求会被传给其他服务器，而且很有可能也是同一台服务器。
173 <note>
174 从1.3.2和1.2.2版本开始支持IPv6地址。
175 </note>
176 </para>
177
178 <para>
179 如果其中一个服务器想暂时移除，应该加上<literal>down</literal>参数。这样可以保留当前客户端IP地址散列分布。
180 </para>
181
182 <para>
183 例子：
184 <example>
185 upstream backend {
186 ip_hash;
187
188 server backend1.example.com;
189 server backend2.example.com;
190 server backend3.example.com <emphasis>down</emphasis>;
191 server backend4.example.com;
192 }
193 </example>
194 </para>
195
196 <para>
197 <note>
198 从1.3.1和1.2.2版本开始，<literal>ip_hash</literal>的负载均衡方法才支持设置服务器权重值。
199 </note>
200 </para>
201
202 </directive>
203
204
205 <directive name="keepalive">
206 <syntax><value>connections</value></syntax>
207 <default/>
208 <context>upstream</context>
209 <appeared-in>1.1.4</appeared-in>
210
211 <para>
212 激活对上游服务器的连接进行缓存。
213 </para>
214
215 <para>
216 <value>connections</value>参数设置每个worker进程与后端服务器保持连接的最大数量。这些保持的连接会被放入缓存。
217 如果连接数大于这个值时，最久未使用的连接会被关闭。
218 <note>
219 需要注意的是，<literal>keepalive</literal>指令不会限制Nginx进程与上游服务器的连接总数。
220 新的连接总会按需被创建。
221 <value>connections</value>参数应该稍微设低一点，以便上游服务器也能处理额外新进来的连接。
222 </note>
223 </para>
224
225 <para>
226 配置memcached上游服务器连接keepalive的例子：
227 <example>
228 upstream memcached_backend {
229 server 127.0.0.1:11211;
230 server 10.0.0.2:11211;
231
232 keepalive 32;
233 }
234
235 server {
236 ...
237
238 location /memcached/ {
239 set $memcached_key $uri;
240 memcached_pass memcached_backend;
241 }
242
243 }
244 </example>
245 </para>
246
247 <para>
248 对于HTTP代理，<link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/>指令应该设置为“<literal>1.1</literal>”，同时<header>Connection</header>头的值也应被清空。
249 <example>
250 upstream http_backend {
251 server 127.0.0.1:8080;
252
253 keepalive 16;
254 }
255
256 server {
257 ...
258
259 location /http/ {
260 proxy_pass http://http_backend;
261 proxy_http_version 1.1;
262 proxy_set_header Connection "";
263 ...
264 }
265 }
266 </example>
267 </para>
268
269 <para>
270 <note>
271 另外一种选择是，HTTP/1.0协议的持久连接也可以通过发送<header>Connection: Keep-Alive</header>头来实现。不过不建议这样用。
272 </note>
273 </para>
274
275 <para>
276 对于FastCGI的服务器，需要设置
277 <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_keep_conn"/>
278 指令来让连接keepalive工作：
279 <example>
280 upstream fastcgi_backend {
281 server 127.0.0.1:9000;
282
283 keepalive 8;
284 }
285
286 server {
287 ...
288
289 location /fastcgi/ {
290 fastcgi_pass fastcgi_backend;
291 fastcgi_keep_conn on;
292 ...
293 }
294 }
295 </example>
296 </para>
297
298 <para>
299 <note>
300 当使用的负载均衡方法不是默认的轮转法时，必须在<literal>keepalive</literal> 指令之前配置。
301 </note>
302
303 <note>
304 针对SCGI和uwsgi协议，还没有实现其keepalive连接的打算。
305 </note>
306 </para>
307
308 </directive>
309
310
311 <directive name="least_conn">
312 <syntax/>
313 <default/>
314 <context>upstream</context>
315 <appeared-in>1.3.1</appeared-in>
316 <appeared-in>1.2.2</appeared-in>
317
318 <para>
319 指定服务器组的负载均衡方法，根据其权重值，将请求发送到活跃连接数最少的那台服务器。
320 如果这样的服务器有多台，那就采取有权重的轮转法进行尝试。
321 </para>
322
323 </directive>
324
325 </section>
326
327
328 <section id="variables" name="嵌入的变量">
329
330 <para>
331 <literal>ngx_http_upstream_module</literal>模块支持以下嵌入变量：
332
333 <list type="tag">
334
335 <tag-name><var>$upstream_addr</var></tag-name>
336 <tag-desc>
337 保存服务器的IP地址和端口或者是UNIX域套接字的路径。
338 在请求处理过程中，如果有多台服务器被尝试了，它们的地址会被拼接起来，以逗号隔开，比如：
339 “<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”。
340 如果在服务器之间通过<header>X-Accel-Redirect</header>头或者<link doc="ngx_http_core_module.xml" id="error_page"/>有内部跳转，那么这些服务器组之间会以冒号隔开，比如：“<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80</literal>”。
341 </tag-desc>
342
343 <tag-name><var>$upstream_response_time</var></tag-name>
344 <tag-desc>
345 以毫秒的精度保留服务器的响应时间，（输出）单位是秒。
346 出现多个响应时，也是以逗号和冒号隔开。
347 </tag-desc>
348
349 <tag-name><var>$upstream_status</var></tag-name>
350 <tag-desc>
351 保存服务器的响应代码。
352 出现多个响应时，也是以逗号和冒号隔开。
353 </tag-desc>
354
355 <tag-name><var>$upstream_http_...</var></tag-name>
356 <tag-desc>
357 保存服务器的响应头的值。比如<header>Server</header>响应头的值可以通过<var>$upstream_http_server</var>变量来获取。
358 需要注意的是只有最后一个响应的头会被保留下来。
359 </tag-desc>
360
361 </list>
362 </para>
363
364 </section>
365
366 </module>