Mercurial > hg > nginx-site

comparison xml/ru/docs/stream/ngx_stream_upstream_module.xml @ 1728:f93a5aadad2c

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Translated the stream upstream module into Russian.
author Yaroslav Zhuravlev <yar@nginx.com>
date Thu, 11 Jun 2015 19:06:06 +0300
parents xml/en/docs/stream/ngx_stream_upstream_module.xml@1a16dce51bce
children ab56dcd73af2
comparison
equal deleted inserted replaced
1727:1a16dce51bce 1728:f93a5aadad2c
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8
9 <module name="Модуль ngx_stream_upstream_module"
10 link="/ru/docs/stream/ngx_stream_upstream_module.html"
11 lang="ru"
12 rev="13">
13
14 <section id="summary">
15
16 <para>
17 Модуль <literal>ngx_stream_upstream_module</literal> (1.9.0)
18 позволяет описывать группы серверов,
19 которые могут использоваться в директиве
20 <link doc="ngx_stream_proxy_module.xml" id="proxy_pass"/>.
21 </para>
22
23 </section>
24
25
26 <section id="example" name="Пример конфигурации">
27
28 <para>
29 <example>
30 upstream <emphasis>backend</emphasis> {
31 hash $remote_addr consistent;
32
33 server backend1.example.com:12345 weight=5;
34 server backend2.example.com:12345;
35 server unix:/tmp/backend3;
36
37 server backup1.example.com:12345 backup;
38 server backup2.example.com:12345 backup;
39 }
40
41 server {
42 listen 12346;
43 proxy_pass <emphasis>backend</emphasis>;
44 }
45 </example>
46 </para>
47
48 <para>
49 Динамически настраиваемая группа,
50 доступна как часть
51 <commercial_version>коммерческой подписки</commercial_version>:
52 <example>
53 resolver 10.0.0.1;
54
55 upstream <emphasis>dynamic</emphasis> {
56 zone upstream_dynamic 64k;
57
58 server backend1.example.com:12345 weight=5;
59 server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
60 server 192.0.2.1:12345 max_fails=3;
61 server backend3.example.com:12345 resolve;
62 server backend4.example.com service=http resolve;
63
64 server backup1.example.com:12345 backup;
65 server backup2.example.com:12345 backup;
66 }
67
68 server {
69 listen 12346;
70 proxy_pass <emphasis>dynamic</emphasis>;
71 health_check;
72 }
73 </example>
74 </para>
75
76 </section>
77
78
79 <section id="directives" name="Директивы">
80
81 <directive name="upstream">
82 <syntax block="yes"><value>название</value></syntax>
83 <default/>
84 <context>stream</context>
85
86 <para>
87 Описывает группу серверов.
88 Серверы могут слушать на разных портах.
89 Кроме того, можно одновременно использовать серверы,
90 слушающие на TCP- и UNIX-сокетах.
91 </para>
92
93 <para>
94 Пример:
95 <example>
96 upstream backend {
97 server backend1.example.com:12345 weight=5;
98 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s;
99 server unix:/tmp/backend2;
100 server backend3.example.com:12345 resolve;
101
102 server backup1.example.com:12345 backup;
103 }
104 </example>
105 </para>
106
107 <para>
108 По умолчанию соединения распределяются по серверам циклически
109 (в режиме round-robin) с учётом весов серверов.
110 В вышеприведённом примере каждые 7 соединений будут распределены так:
111 5 соединений на <literal>backend1.example.com:12345</literal>
112 и по одному соединению на второй и третий серверы.
113 Если при попытке работы с сервером происходит ошибка, то соединение
114 передаётся следующему серверу, и так далее до тех пор, пока не будут опробованы
115 все работающие серверы.
116 Если связь с серверами не удалась, соединение будет закрыто.
117 </para>
118
119 </directive>
120
121
122 <directive name="server">
123 <syntax><value>адрес</value> [<value>параметры</value>]</syntax>
124 <default/>
125 <context>upstream</context>
126
127 <para>
128 Задаёт <value>адрес</value> и другие <value>параметры</value>
129 сервера.
130 Адрес может быть указан в виде доменного имени или IP-адреса,
131 и обязательного порта, или в виде пути UNIX-сокета, который
132 указывается после префикса “<literal>unix:</literal>”.
133 Доменное имя, которому соответствует несколько IP-адресов,
134 задаёт сразу несколько серверов.
135 </para>
136
137 <para>
138 Могут быть заданы следующие параметры:
139 <list type="tag">
140
141 <tag-name id="weight">
142 <literal>weight</literal>=<value>число</value>
143 </tag-name>
144 <tag-desc>
145 задаёт вес сервера, по умолчанию 1.
146 </tag-desc>
147
148 <tag-name id="max_fails">
149 <literal>max_fails</literal>=<value>число</value>
150 </tag-name>
151 <tag-desc>
152 задаёт число неудачных попыток работы с сервером, которые должны произойти
153 в течение времени, заданного параметром <literal>fail_timeout</literal>,
154 чтобы сервер считался недоступным на период времени, также заданный
155 параметром <literal>fail_timeout</literal>.
156 По умолчанию число попыток устанавливается равным 1.
157 Нулевое значение отключает учёт попыток.
158 В данном случае неудачной попыткой считается ошибка или таймаут
159 при установке соединения с сервером.
160 </tag-desc>
161
162 <tag-name id="fail_timeout">
163 <literal>fail_timeout</literal>=<value>время</value>
164 </tag-name>
165 <tag-desc>
166 задаёт
167 <list type="bullet">
168
169 <listitem>
170 время, в течение которого должно произойти заданное число неудачных
171 попыток работы с сервером для того, чтобы сервер считался недоступным;
172 </listitem>
173
174 <listitem>
175 и время, в течение которого сервер будет считаться недоступным.
176 </listitem>
177
178 </list>
179 По умолчанию параметр равен 10 секундам.
180 </tag-desc>
181
182 <tag-name id="backup">
183 <literal>backup</literal>
184 </tag-name>
185 <tag-desc>
186 помечает сервер как запасной сервер.
187 На него будут передаваться соединения в случае,
188 если не работают основные серверы.
189 </tag-desc>
190
191 <tag-name id="down">
192 <literal>down</literal>
193 </tag-name>
194 <tag-desc>
195 помечает сервер как постоянно недоступный.
196 </tag-desc>
197
198 </list>
199 </para>
200
201 <para>
202 Кроме того,
203 следующие параметры доступны как часть
204 <commercial_version>коммерческой подписки</commercial_version>:
205 <list type="tag">
206
207 <tag-name id="max_conns">
208 <literal>max_conns</literal>=<value>число</value>
209 </tag-name>
210 <tag-desc>
211 ограничивает максимальное <value>число</value> одновременных
212 соединений к проксируемому серверу.
213 Значение по умолчанию равно 0 и означает, что ограничения нет.
214 </tag-desc>
215
216 <tag-name id="resolve">
217 <literal>resolve</literal>
218 </tag-name>
219 <tag-desc>
220 отслеживает изменения IP-адресов, соответствующих доменному имени сервера,
221 и автоматически изменяет конфигурацию группы
222 без необходимости перезапуска nginx.
223 Группа должна находиться в <link id="zone">зоне разделяемой памяти</link>.
224 <para>
225 Для работы этого параметра
226 директива <link doc="ngx_stream_core_module.xml" id="resolver"/>
227 должна быть задана в блоке
228 <link doc="ngx_stream_core_module.xml" id="stream"/>.
229 Пример:
230 <example>
231 stream {
232 resolver 10.0.0.1;
233
234 upstream u {
235 zone ...;
236 ...
237 server example.com:12345 resolve;
238 }
239 }
240 </example>
241 </para>
242 </tag-desc>
243
244 <tag-name id="service">
245 <literal>service</literal>=<value>имя</value>
246 </tag-name>
247 <tag-desc>
248 включает преобразование
249 <link url="https://tools.ietf.org/html/rfc2782">SRV</link>-записей
250 DNS и задаёт <value>имя</value> сервиса (1.9.13).
251 Для работы параметра необходимо указать
252 параметр <link id="resolve"/> для сервера
253 и не указывать порт сервера.
254 <para>
255 Если имя сервиса не содержит точку (“<literal>.</literal>”), то
256 имя составляется в соответствии с
257 <link url="https://tools.ietf.org/html/rfc2782">RFC</link>
258 и в префикс службы добавляется протокол TCP.
259 Например, для получения
260 SRV-записи <literal>_http._tcp.backend.example.com</literal>
261 необходимо указать директиву:
262 <example>
263 server backend.example.com service=http resolve;
264 </example>
265 Если имя сервиса содержит одну и более точек, то имя составляется
266 при помощи соединения префикса службы и имени сервера.
267 Например, для получения SRV-записей
268 <literal>_http._tcp.backend.example.com</literal>
269 и <literal>server1.backend.example.com</literal>
270 необходимо указать директивы:
271 <example>
272 server backend.example.com service=_http._tcp resolve;
273 server example.com service=server1.backend resolve;
274 </example>
275 </para>
276
277 <para>
278 SRV-записи с наивысшим приоритетом
279 (записи с одинаковым наименьшим значением приоритета)
280 преобразуются в основные серверы,
281 остальные SRV-записи преобразуются в запасные серверы.
282 Если в конфигурации сервера указан параметр <link id="backup"/>,
283 высокоприоритетные SRV-записи преобразуются в запасные серверы,
284 остальные SRV-записи игнорируются.
285 </para>
286 </tag-desc>
287
288 <tag-name id="slow_start">
289 <literal>slow_start</literal>=<value>время</value>
290 </tag-name>
291 <tag-desc>
292 задаёт <value>время</value>, в течение которого вес сервера
293 восстановится от нуля до своего номинального значения в ситуации, когда
294 неработоспособный (unhealthy) сервер вновь становится работоспособным
295 (<link id="health_check">healthy</link>)
296 или когда сервер становится доступным по прошествии времени,
297 в течение которого он считался <link id="fail_timeout">недоступным</link>.
298 Значение по умолчанию равно нулю и означает, что медленный старт выключен.
299 </tag-desc>
300
301 </list>
302 </para>
303
304 <para>
305 <note>
306 Если в группе только один сервер, параметры <literal>max_fails</literal>,
307 <literal>fail_timeout</literal> и <literal>slow_start</literal>
308 игнорируются и такой сервер никогда не будет считаться недоступным.
309 </note>
310 </para>
311
312 </directive>
313
314
315 <directive name="zone">
316 <syntax><value>имя</value> [<value>размер</value>]</syntax>
317 <default/>
318 <context>upstream</context>
319
320 <para>
321 Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти,
322 в которой хранятся конфигурация группы и её рабочее состояние,
323 разделяемые между рабочими процессами.
324 В одной и той же зоне могут быть сразу несколько групп.
325 В этом случае достаточно указать <value>размер</value> только один раз.
326 </para>
327
328 <para>
329 Дополнительно, как часть
330 <commercial_version>коммерческой подписки</commercial_version>,
331 в таких группах для изменения состава группы
332 или настроек отдельных серверов
333 нет необходимости перезапускать nginx.
334 Конфигурация доступна через специальный location,
335 в котором указана директива
336 <link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>.
337 </para>
338
339 </directive>
340
341
342 <directive name="state">
343 <syntax><value>файл</value></syntax>
344 <default/>
345 <context>upstream</context>
346 <appeared-in>1.9.7</appeared-in>
347
348 <para>
349 Задаёт <value>файл</value>, в котором хранится состояние
350 динамически настраиваемой группы.
351 В данный момент состояние ограничено списком серверов с их параметрами.
352 Файл читается при парсинге конфигурации и обновляется каждый раз при
353 <link doc="ngx_http_upstream_conf_module.xml" id="upstream_conf">изменении</link>
354 конфигурации группы.
355 Изменение содержимого файла напрямую не рекомендуется.
356 Директиву нельзя использовать
357 совместно с директивой <link id="server"/>.
358 </para>
359
360 <para>
361 <note>
362 Изменения, совершённые в момент
363 <link doc="../control.xml" id="reconfiguration">перезагрузки конфигурации</link>
364 или <link doc="../control.xml" id="upgrade">обновления бинарного файла</link>,
365 могут быть потеряны.
366 </note>
367 </para>
368
369 <para>
370 <note>
371 Эта директива доступна как часть
372 <commercial_version>коммерческой подписки</commercial_version>.
373 </note>
374 </para>
375
376 </directive>
377
378
379 <directive name="hash">
380 <syntax><value>ключ</value> [<literal>consistent</literal>]</syntax>
381 <default/>
382 <context>upstream</context>
383
384 <para>
385 Задаёт метод балансировки нагрузки для группы, при котором
386 соответствие клиента серверу определяется при помощи
387 хэшированного значения <value>ключа</value>.
388 В настоящий момент единственно возможным значением для <literal>ключа</literal>
389 является удалённый адрес клиента,
390 указываемый как <literal>$remote_addr</literal>.
391 Следует отметить, что любое добавление или удаление серверов в группе
392 может привести к перераспределению большинства ключей на другие серверы.
393 Метод совместим с библиотекой Perl
394 <link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached">Cache::Memcached</link>.
395 </para>
396
397 <para>
398 Если задан параметр <literal>consistent</literal>, то вместо
399 вышеописанного метода будет использоваться метод консистентного хэширования
400 <link url="http://www.last.fm/user/RJ/journal/2007/04/10/392555/">ketama</link>.
401 Метод гарантирует, что при добавлении сервера в группу или его удалении
402 на другие серверы будет перераспределено минимальное число ключей.
403 Применение метода для кэширующих серверов обеспечивает
404 больший процент попаданий в кэш.
405 Метод совместим с библиотекой Perl
406 <link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached%3A%3AFast">Cache::Memcached::Fast</link>
407 при значении параметра <value>ketama_points</value> равным 160.
408 </para>
409
410 </directive>
411
412
413 <directive name="least_conn">
414 <syntax/>
415 <default/>
416 <context>upstream</context>
417
418 <para>
419 Задаёт для группы метод балансировки нагрузки, при котором соединение
420 передаётся серверу с наименьшим числом активных соединений,
421 с учётом весов серверов.
422 Если подходит сразу несколько серверов, они выбираются циклически
423 (в режиме round-robin) с учётом их весов.
424 </para>
425
426 </directive>
427
428
429 <directive name="least_time">
430 <syntax><literal>connect</literal> |
431 <literal>first_byte</literal> |
432 <literal>last_byte</literal></syntax>
433 <default/>
434 <context>upstream</context>
435
436 <para>
437 Задаёт для группы метод балансировки нагрузки, при котором соединение
438 передаётся серверу с наименьшими средним временем ответа и
439 числом активных соединений с учётом весов серверов.
440 Если подходит сразу несколько серверов, то они выбираются циклически
441 (в режиме round-robin) с учётом их весов.
442 </para>
443
444 <para>
445 Если указан параметр <literal>connect</literal>,
446 то учитывается время соединения с сервером группы.
447 Если указан параметр <literal>first_byte</literal>,
448 то учитывается время получения первого байта данных.
449 Если указан параметр <literal>last_byte</literal>,
450 то учитывается время получения ответа.
451 </para>
452
453 <para>
454 <note>
455 Эта директива доступна как часть
456 <commercial_version>коммерческой подписки</commercial_version>.
457 </note>
458 </para>
459
460 </directive>
461
462
463 <directive name="health_check">
464 <syntax>[<value>параметры</value>]</syntax>
465 <default/>
466 <context>server</context>
467
468 <para>
469 Активирует периодические проверки работоспособности серверов в
470 <link id="upstream">группе</link>.
471 </para>
472
473 <para>
474 Могут быть заданы следующие необязательные параметры:
475 <list type="tag">
476
477 <tag-name id="interval">
478 <literal>interval</literal>=<value>время</value>
479 </tag-name>
480 <tag-desc>
481 задаёт интервал между двумя последовательными проверками,
482 по умолчанию 5 секунд;
483 </tag-desc>
484
485 <tag-name id="fails">
486 <literal>fails</literal>=<value>число</value>
487 </tag-name>
488 <tag-desc>
489 задаёт число последовательных неуспешных проверок для определённого сервера,
490 после которых сервер будет считаться неработоспособным,
491 по умолчанию 1;
492 </tag-desc>
493
494 <tag-name id="passes">
495 <literal>passes</literal>=<value>число</value>
496 </tag-name>
497 <tag-desc>
498 задаёт число последовательных успешных проверок для определённого сервера,
499 после которых сервер будет считаться работоспособным,
500 по умолчанию 1;
501 </tag-desc>
502
503 <tag-name id="hc_match">
504 <literal>match</literal>=<value>имя</value>
505 </tag-name>
506 <tag-desc>
507 указывает на блок <literal>match</literal> с условиями, которым должно
508 удовлетворять соединение, чтобы результат проверки считался успешным;
509 по умолчанию проверяется лишь возможность установки TCP-соединения с сервером;
510 </tag-desc>
511
512 <tag-name id="health_check_port">
513 <literal>port</literal>=<value>число</value>
514 </tag-name>
515 <tag-desc>
516 задаёт порт, используемый при подключении к серверу
517 для проверки его работоспособности (1.9.7);
518 по умолчанию совпадает с портом <link id="server">сервера</link>.
519 </tag-desc>
520
521 <tag-name id="health_check_udp">
522 <literal>udp</literal>
523 </tag-name>
524 <tag-desc>
525 указывает, что для проверки работоспособности будет использоваться протокол
526 <literal>UDP</literal>
527 вместо протокола <literal>TCP</literal>, используемого по умолчанию (1.9.13);
528 тебует наличия блока <link id="hc_match">match</link> с параметрами
529 <link id="match_send">send</link> и <link id="match_expect">expect</link>.
530 </tag-desc>
531
532 </list>
533 </para>
534
535 <para>
536 В примере
537 <example>
538 server {
539 proxy_pass backend;
540 health_check;
541 }
542 </example>
543 для каждого сервера группы <literal>backend</literal>
544 с интервалом в 5 секунд проверяется возможность установки TCP-соединения.
545 Если соединение с сервером не может быть установлено,
546 проверка считается неуспешной и сервер
547 признаётся неработоспособным.
548 На неработоспособные серверы клиентские соединения передаваться не будут.
549 </para>
550
551 <para>
552 Проверки работоспособности могут тестировать данные, полученные от сервера.
553 Тесты настраиваются отдельно при помощи директивы <link id="match"/>
554 и указываются в параметре <literal>match</literal>.
555 </para>
556
557 <para>
558 Группа должна находиться в <link id="zone">зоне разделяемой памяти</link>.
559 </para>
560
561 <para>
562 Если для группы задано несколько проверок,
563 то при любой неуспешной проверке соответствующий сервер будет
564 считаться неработоспособным.
565 </para>
566
567 <para>
568 <note>
569 Эта директива доступна как часть
570 <commercial_version>коммерческой подписки</commercial_version>.
571 </note>
572 </para>
573
574 </directive>
575
576
577 <directive name="health_check_timeout">
578 <syntax><value>время</value></syntax>
579 <default>5s</default>
580 <context>stream</context>
581 <context>server</context>
582
583 <para>
584 Переопределяет значение
585 <link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/>
586 для проверок работоспособности.
587 </para>
588
589 <para>
590 <note>
591 Эта директива доступна как часть
592 <commercial_version>коммерческой подписки</commercial_version>.
593 </note>
594 </para>
595
596 </directive>
597
598
599 <directive name="match">
600 <syntax block="yes"><value>имя</value> </syntax>
601 <default/>
602 <context>stream</context>
603
604 <para>
605 Задаёт именованный набор тестов для для анализа ответов сервера
606 на запросы проверки работоспособности.
607 </para>
608
609 <para>
610 Могут быть заданы следующие параметры:
611 <list type="tag">
612
613 <tag-name id="match_send">
614 <literal>send</literal> <value>строка</value>;
615 </tag-name>
616 <tag-desc>
617 отправляет <value>строку</value> на сервер;
618 </tag-desc>
619
620 <tag-name id="match_expect">
621 <literal>expect</literal> <value>стока</value> |
622 <literal>~</literal> <value>regex</value>;
623 </tag-name>
624 <tag-desc>
625 текстовая строка (1.9.12) или регулярное выражение,
626 которым должны соответствовать данные, полученные с сервера.
627 Регулярное выражение задаётся либо с модификатором
628 “<literal>~*</literal>” (для поиска совпадения без учёта регистра символов),
629 либо с модификатором “<literal>~</literal>” (с учётом регистра).
630 </tag-desc>
631
632 </list>
633 Параметры <literal>send</literal> и <literal>expect</literal>
634 могут содержать строки в шестнадцатеричном виде
635 с префиксом “<literal>\x</literal>”
636 и последующими двумя шестнадцатеричными цифрами,
637 например “<literal>\x80</literal>” (1.9.12).
638 </para>
639
640 <para>
641 Проверка работоспособности считается успешной, если
642 <list type="bullet">
643 <listitem>
644 TCP-соединение успешно установлено;
645 </listitem>
646
647 <listitem>
648 <value>строка</value> из параметра <literal>send</literal>
649 была отправлена (если была задана);
650 </listitem>
651
652 <listitem>
653 данные, полученные от сервера, совпали со строкой или регулярным выражением
654 из параметра <literal>expect</literal> (если был задан);
655 </listitem>
656
657 <listitem>
658 истёкшее время не превышает значение, указанное
659 в директиве <link id="health_check_timeout"/>.
660 </listitem>
661
662 </list>
663 </para>
664
665 <para>
666 Пример:
667 <example>
668 upstream backend {
669 zone upstream_backend 10m;
670 server 127.0.0.1:12345;
671 }
672
673 match http {
674 send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
675 expect ~ "200 OK";
676 }
677
678 server {
679 listen 12346;
680 proxy_pass backend;
681 health_check match=http;
682 }
683 </example>
684 </para>
685
686 <para>
687 <note>
688 Проверяются лишь первые байты данных
689 <link doc="ngx_stream_proxy_module.xml" id="proxy_buffer_size"/>,
690 полученные от сервера.
691 </note>
692 </para>
693
694 <para>
695 <note>
696 Эта директива доступна как часть
697 <commercial_version>коммерческой подписки</commercial_version>.
698 </note>
699 </para>
700
701 </directive>
702
703 </section>
704
705 </module>