Mercurial > hg > nginx-site

comparison xml/ru/docs/stream/ngx_stream_upstream_module.xml @ 3043:9eadb98ec770

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Free nginx: removed commercial version documentation.
author Maxim Dounin <mdounin@mdounin.ru>
date Wed, 14 Feb 2024 20:05:49 +0300
parents 3a2d342533fb
children
comparison
equal deleted inserted replaced
3042:19e4897acb84 3043:9eadb98ec770
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8 8
9 <module name="Модуль ngx_stream_upstream_module" 9 <module name="Модуль ngx_stream_upstream_module"
10 link="/ru/docs/stream/ngx_stream_upstream_module.html" 10 link="/ru/docs/stream/ngx_stream_upstream_module.html"
11 lang="ru" 11 lang="ru"
12 rev="39"> 12 rev="40">
13 13
14 <section id="summary"> 14 <section id="summary">
15 15
16 <para> 16 <para>
17 Модуль <literal>ngx_stream_upstream_module</literal> (1.9.0) 17 Модуль <literal>ngx_stream_upstream_module</literal> (1.9.0)
39 } 39 }
40 40
41 server { 41 server {
42 listen 12346; 42 listen 12346;
43 proxy_pass <emphasis>backend</emphasis>; 43 proxy_pass <emphasis>backend</emphasis>;
44 }
45 </example>
46 </para>
47
48 <para>
49 Динамически настраиваемая группа
50 с периодическими
51 <link doc="ngx_stream_upstream_hc_module.xml">проверками работоспособности</link>
52 доступна как часть
53 <commercial_version>коммерческой подписки</commercial_version>:
54 <example>
55 resolver 10.0.0.1;
56
57 upstream <emphasis>dynamic</emphasis> {
58 zone upstream_dynamic 64k;
59
60 server backend1.example.com:12345 weight=5;
61 server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
62 server 192.0.2.1:12345 max_fails=3;
63 server backend3.example.com:12345 resolve;
64 server backend4.example.com service=http resolve;
65
66 server backup1.example.com:12345 backup;
67 server backup2.example.com:12345 backup;
68 }
69
70 server {
71 listen 12346;
72 proxy_pass <emphasis>dynamic</emphasis>;
73 health_check;
74 } 44 }
75 </example> 45 </example>
76 </para> 46 </para>
77 47
78 </section> 48 </section>
154 ограничивает максимальное <value>число</value> одновременных 124 ограничивает максимальное <value>число</value> одновременных
155 соединений к проксируемому серверу (1.11.5). 125 соединений к проксируемому серверу (1.11.5).
156 Значение по умолчанию равно 0 и означает, что ограничения нет. 126 Значение по умолчанию равно 0 и означает, что ограничения нет.
157 Если группа не находится в <link id="zone">зоне разделяемой памяти</link>, 127 Если группа не находится в <link id="zone">зоне разделяемой памяти</link>,
158 то ограничение работает отдельно для каждого рабочего процесса. 128 то ограничение работает отдельно для каждого рабочего процесса.
159 <note>
160 До версии 1.11.5 этот параметр был доступен как часть
161 <commercial_version>коммерческой подписки</commercial_version>.
162 </note>
163 </tag-desc> 129 </tag-desc>
164 130
165 <tag-name id="max_fails"> 131 <tag-name id="max_fails">
166 <literal>max_fails</literal>=<value>число</value> 132 <literal>max_fails</literal>=<value>число</value>
167 </tag-name> 133 </tag-name>
218 184
219 </list> 185 </list>
220 </para> 186 </para>
221 187
222 <para> 188 <para>
223 Кроме того,
224 следующие параметры доступны как часть
225 <commercial_version>коммерческой подписки</commercial_version>:
226 <list type="tag">
227
228 <tag-name id="resolve">
229 <literal>resolve</literal>
230 </tag-name>
231 <tag-desc>
232 отслеживает изменения IP-адресов, соответствующих доменному имени сервера,
233 и автоматически изменяет конфигурацию группы
234 без необходимости перезапуска nginx.
235 Группа должна находиться в <link id="zone">зоне разделяемой памяти</link>.
236 <para>
237 Для работы этого параметра
238 директива <literal>resolver</literal>
239 должна быть задана в блоке
240 <link doc="ngx_stream_core_module.xml" id="resolver">stream</link>
241 или в соответствующем блоке <link id="resolver">upstream</link>.
242 </para>
243 </tag-desc>
244
245 <tag-name id="service">
246 <literal>service</literal>=<value>имя</value>
247 </tag-name>
248 <tag-desc>
249 включает преобразование
250 <link url="https://datatracker.ietf.org/doc/html/rfc2782">SRV</link>-записей
251 DNS и задаёт <value>имя</value> сервиса (1.9.13).
252 Для работы параметра необходимо указать
253 параметр <link id="resolve"/> для сервера
254 и не указывать порт сервера.
255 <para>
256 Если имя сервиса не содержит точку (“<literal>.</literal>”), то
257 имя составляется в соответствии с
258 <link url="https://datatracker.ietf.org/doc/html/rfc2782">RFC</link>
259 и в префикс службы добавляется протокол TCP.
260 Например, для получения
261 SRV-записи <literal>_http._tcp.backend.example.com</literal>
262 необходимо указать директиву:
263 <example>
264 server backend.example.com service=http resolve;
265 </example>
266 Если имя сервиса содержит одну и более точек, то имя составляется
267 при помощи соединения префикса службы и имени сервера.
268 Например, для получения SRV-записей
269 <literal>_http._tcp.backend.example.com</literal>
270 и <literal>server1.backend.example.com</literal>
271 необходимо указать директивы:
272 <example>
273 server backend.example.com service=_http._tcp resolve;
274 server example.com service=server1.backend resolve;
275 </example>
276 </para>
277
278 <para>
279 SRV-записи с наивысшим приоритетом
280 (записи с одинаковым наименьшим значением приоритета)
281 преобразуются в основные серверы,
282 остальные SRV-записи преобразуются в запасные серверы.
283 Если в конфигурации сервера указан параметр <link id="backup"/>,
284 высокоприоритетные SRV-записи преобразуются в запасные серверы,
285 остальные SRV-записи игнорируются.
286 </para>
287 </tag-desc>
288
289 <tag-name id="slow_start">
290 <literal>slow_start</literal>=<value>время</value>
291 </tag-name>
292 <tag-desc>
293 задаёт <value>время</value>, в течение которого вес сервера
294 восстановится от нуля до своего номинального значения в ситуации, когда
295 неработоспособный (unhealthy) сервер вновь становится работоспособным
296 (<link doc="ngx_stream_upstream_hc_module.xml" id="health_check">healthy</link>)
297 или когда сервер становится доступным по прошествии времени,
298 в течение которого он считался <link id="fail_timeout">недоступным</link>.
299 Значение по умолчанию равно нулю и означает, что медленный старт выключен.
300 <note> 189 <note>
301 Параметр нельзя использовать совместно с 190 Если в группе только один сервер,
302 методами балансировки нагрузки <link id="hash"/> и <link id="random"/>. 191 параметры <literal>max_fails</literal> и <literal>fail_timeout</literal>
303 </note>
304 </tag-desc>
305
306 </list>
307 </para>
308
309 <para>
310 <note>
311 Если в группе только один сервер, параметры <literal>max_fails</literal>,
312 <literal>fail_timeout</literal> и <literal>slow_start</literal>
313 игнорируются и такой сервер никогда не будет считаться недоступным. 192 игнорируются и такой сервер никогда не будет считаться недоступным.
314 </note> 193 </note>
315 </para> 194 </para>
316 195
317 </directive> 196 </directive>
326 Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти, 205 Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти,
327 в которой хранятся конфигурация группы и её рабочее состояние, 206 в которой хранятся конфигурация группы и её рабочее состояние,
328 разделяемые между рабочими процессами. 207 разделяемые между рабочими процессами.
329 В одной и той же зоне могут быть сразу несколько групп. 208 В одной и той же зоне могут быть сразу несколько групп.
330 В этом случае достаточно указать <value>размер</value> только один раз. 209 В этом случае достаточно указать <value>размер</value> только один раз.
331 </para>
332
333 <para>
334 Дополнительно, как часть
335 <commercial_version>коммерческой подписки</commercial_version>,
336 в таких группах для изменения состава группы
337 или настроек отдельных серверов
338 нет необходимости перезапускать nginx.
339 Конфигурация доступна через
340 модуль <link doc="../http/ngx_http_api_module.xml">API</link> (1.13.3).
341 <note>
342 До версии 1.13.3
343 конфигурация была доступна только через специальный location,
344 в котором указана директива
345 <link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>.
346 </note>
347 </para>
348
349 </directive>
350
351
352 <directive name="state">
353 <syntax><value>файл</value></syntax>
354 <default/>
355 <context>upstream</context>
356 <appeared-in>1.9.7</appeared-in>
357
358 <para>
359 Задаёт <value>файл</value>, в котором хранится состояние
360 динамически настраиваемой группы.
361 </para>
362
363 <para>
364 Примеры:
365 <example>
366 state /var/lib/nginx/state/servers.conf; # путь для Linux
367 state /var/db/nginx/state/servers.conf; # путь для FreeBSD
368 </example>
369 </para>
370
371 <para>
372 В данный момент состояние ограничено списком серверов с их параметрами.
373 Файл читается при парсинге конфигурации и обновляется каждый раз при
374 <link doc="../http/ngx_http_api_module.xml" id="stream_upstreams_stream_upstream_name_servers_">изменении</link>
375 конфигурации группы.
376 Изменение содержимого файла напрямую не рекомендуется.
377 Директиву нельзя использовать
378 совместно с директивой <link id="server"/>.
379 </para>
380
381 <para>
382 <note>
383 Изменения, совершённые в момент
384 <link doc="../control.xml" id="reconfiguration">перезагрузки конфигурации</link>
385 или <link doc="../control.xml" id="upgrade">обновления бинарного файла</link>,
386 могут быть потеряны.
387 </note>
388 </para>
389
390 <para>
391 <note>
392 Эта директива доступна как часть
393 <commercial_version>коммерческой подписки</commercial_version>.
394 </note>
395 </para> 210 </para>
396 211
397 </directive> 212 </directive>
398 213
399 214
448 </para> 263 </para>
449 264
450 </directive> 265 </directive>
451 266
452 267
453 <directive name="least_time">
454 <syntax>
455 <literal>connect</literal> |
456 <literal>first_byte</literal> |
457 <literal>last_byte</literal>
458 [<literal>inflight</literal>]</syntax>
459 <default/>
460 <context>upstream</context>
461
462 <para>
463 Задаёт для группы метод балансировки нагрузки, при котором соединение
464 передаётся серверу с наименьшими средним временем ответа и
465 числом активных соединений с учётом весов серверов.
466 Если подходит сразу несколько серверов, то они выбираются циклически
467 (в режиме round-robin) с учётом их весов.
468 </para>
469
470 <para>
471 Если указан параметр <literal>connect</literal>,
472 то учитывается время
473 <link id="var_upstream_connect_time">соединения</link> с сервером группы.
474 Если указан параметр <literal>first_byte</literal>,
475 то учитывается время получения
476 <link id="var_upstream_first_byte_time">первого байта</link> данных.
477 Если указан параметр <literal>last_byte</literal>,
478 то учитывается время получения
479 <link id="var_upstream_session_time">последнего байта</link> данных.
480 Если указан параметр <literal>inflight</literal> (1.11.6),
481 то также учитываются незавершённые соединения.
482 <note>
483 До версии 1.11.6
484 незавершённые соединения учитывались по умолчанию.
485 </note>
486 </para>
487
488 <para>
489 <note>
490 Эта директива доступна как часть
491 <commercial_version>коммерческой подписки</commercial_version>.
492 </note>
493 </para>
494
495 </directive>
496
497
498 <directive name="random"> 268 <directive name="random">
499 <syntax>[<literal>two</literal> [<value>метод</value>]]</syntax> 269 <syntax>[<literal>two</literal> [<value>метод</value>]]</syntax>
500 <default/> 270 <default/>
501 <context>upstream</context> 271 <context>upstream</context>
502 <appeared-in>1.15.1</appeared-in> 272 <appeared-in>1.15.1</appeared-in>
516 Методом по умолчанию является <literal>least_conn</literal>, 286 Методом по умолчанию является <literal>least_conn</literal>,
517 при котором соединение передаётся на сервер 287 при котором соединение передаётся на сервер
518 с наименьшим количеством активных соединений. 288 с наименьшим количеством активных соединений.
519 </para> 289 </para>
520 290
521 <para id="random_least_time">
522 Если указан метод <literal>least_time</literal>, то соединение передаётся
523 серверу
524 с наименьшими средним временем ответа и числом активных соединений.
525 Если указан <literal>least_time=connect</literal>,
526 то учитывается время
527 <link id="var_upstream_connect_time">соединения</link> с сервером группы.
528 Если указан <literal>least_time=first_byte</literal>,
529 то учитывается время получения
530 <link id="var_upstream_first_byte_time">первого байта</link> данных.
531 Если указан <literal>least_time=last_byte</literal>,
532 то учитывается время получения
533 <link id="var_upstream_session_time">последнего байта</link> данных.
534 <note>
535 Метод <literal>least_time</literal> доступен как часть
536 <commercial_version>коммерческой подписки</commercial_version>.
537 </note>
538 </para>
539
540 </directive>
541
542
543 <directive name="resolver">
544 <syntax>
545 <value>адрес</value> ...
546 [<literal>valid</literal>=<value>время</value>]
547 [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>]
548 [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]
549 [<literal>status_zone</literal>=<value>зона</value>]</syntax>
550 <default/>
551 <context>upstream</context>
552 <appeared-in>1.17.5</appeared-in>
553
554 <para>
555 Задаёт серверы DNS, используемые для преобразования имён вышестоящих серверов
556 в адреса, например:
557 <example>
558 resolver 127.0.0.1 [::1]:5353;
559 </example>
560 Адрес может быть указан в виде доменного имени или IP-адреса,
561 и необязательного порта.
562 Если порт не указан, используется порт 53.
563 Серверы DNS опрашиваются циклически.
564 </para>
565
566 <para id="resolver_ipv6">
567 По умолчанию nginx будет искать как IPv4-, так и IPv6-адреса
568 при преобразовании имён в адреса.
569 Если поиск IPv4- или IPv6-адресов нежелателен,
570 можно указать параметр <literal>ipv4=off</literal> (1.23.1) или
571 <literal>ipv6=off</literal>.
572 </para>
573
574 <para id="resolver_valid">
575 По умолчанию nginx кэширует ответы, используя значение TTL из ответа.
576 Необязательный параметр <literal>valid</literal> позволяет это
577 переопределить:
578 <example>
579 resolver 127.0.0.1 [::1]:5353 valid=30s;
580 </example>
581 <note>
582 Для предотвращения DNS-спуфинга рекомендуется
583 использовать DNS-серверы в защищённой доверенной локальной сети.
584 </note>
585 </para>
586
587 <para id="resolver_status_zone">
588 Необязательный параметр <literal>status_zone</literal>
589 включает
590 <link doc="../http/ngx_http_api_module.xml" id="resolvers_">сбор информации</link>
591 о запросах и ответах сервера DNS
592 в указанной <value>зоне</value>.
593 </para>
594
595 <para>
596 <note>
597 Эта директива доступна как часть
598 <commercial_version>коммерческой подписки</commercial_version>.
599 </note>
600 </para>
601
602 </directive>
603
604
605 <directive name="resolver_timeout">
606 <syntax><value>время</value></syntax>
607 <default>30s</default>
608 <context>upstream</context>
609 <appeared-in>1.17.5</appeared-in>
610
611 <para>
612 Задаёт таймаут для преобразования имени в адрес, например:
613 <example>
614 resolver_timeout 5s;
615 </example>
616 </para>
617
618 <para>
619 <note>
620 Эта директива доступна как часть
621 <commercial_version>коммерческой подписки</commercial_version>.
622 </note>
623 </para>
624
625 </directive> 291 </directive>
626 292
627 </section> 293 </section>
628 294
629 295