Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_upstream.xml @ 76:4a4caa566120

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Russian documentation import. Changes in module.dtd: <example> now allowed to contain <value> and <emphasis> elements (we need this to show important parts in examples), less strict checking of <directive> syntax (we don't want to fully document some directives, notably deprecated ones). Known issues: 1. <syntax> elements are preserved as is, they will require manual conversion (likely to some not-yet-existed format a la DocBook cmdsynopsis, as currently used one seems to be incomplete); 2. <value> no longer corresponds to replaceable content, and it's use in examples isn't correct; 3. <link doc="document#fragment"> doesn't work with current xslt, either should be supported or changed to <link doc="document" id="fragment">. The following files are intentionally omitted: maillists.xml (support.xml should be used instead), experimental.xml (obsolete), faq.xml (conflicts with existing one, needs discussion). Not yet linked to site.
author Maxim Dounin <mdounin@mdounin.ru>
date Tue, 11 Oct 2011 12:57:50 +0000
parents
children 0a45870d0160
comparison
equal deleted inserted replaced
75:2bf4cd2787c5 76:4a4caa566120
1 <?xml version="1.0" encoding="utf-8"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Директивы модуля ngx_http_upstream"
6 link="/ru/docs/http/ngx_http_upstream.html"
7 lang="ru">
8
9 <section name="" id="summary">
10
11 <para>
12 Модуль позволяет описывать группы серверов,
13 которые могут использоваться в директивах
14 <link doc="ngx_http_proxy_module.xml#proxy_pass">proxy_pass</link>
15 и <link doc="ngx_http_fastcgi_module.xml#fastcgi_pass">fastcgi_pass</link>.
16 </para>
17
18 </section>
19
20
21 <section name="Пример конфигурации" id="example">
22
23 <para>
24 <example>
25 upstream <emphasis>backend</emphasis> {
26 server backend1.example.com weight=5;
27 server backend2.example.com:8080;
28 server unix:/tmp/backend3;
29
30 server backup1.example.com:8080 backup;
31 server backup2.example.com:8080 backup;
32 }
33
34 server {
35 location / {
36 proxy_pass http://<emphasis>backend</emphasis>;
37 }
38 }
39 </example>
40 </para>
41
42 </section>
43
44
45 <section name="Директивы" id="directives">
46
47 <directive name="ip_hash">
48 <syntax>ip_hash</syntax>
49 <default>нет</default>
50 <context>upstream</context>
51
52 <para>
53 Директива задаёт метод распределения запросов по серверам на основе
54 IP-адресов клиентов. В качестве ключа для хеширования используется сеть
55 класса C, в которой находится адрес клиента.
56 Метод гарантирует, что запросы клиента будут передаваться на один и тот же
57 сервер. Если же этот сервер будет считаться неработающим, то запросы этого
58 клиента будут передаваться на другой сервер. С большой долей вероятности
59 это также будет один и тот же сервер.
60 </para>
61
62 <para>
63 Для серверов, использующих метод распределения ip_hash, нельзя задать вес.
64 Если один из серверов нужно убрать на некоторое время, то для сохранения
65 текущего хеширования IP-адресов клиентов этот сервер нужно пометить
66 параметром down.
67 </para>
68
69 <para>
70 Пример конфигурации:
71 <example>
72 upstream backend {
73 ip_hash;
74
75 server backend1.example.com;
76 server backend2.example.com;
77 server backend3.example.com down;
78 server backend4.example.com;
79 }
80 </example>
81 </para>
82
83 </directive>
84
85
86 <directive name="server">
87 <syntax>server <value>название [параметры]</value></syntax>
88 <default>нет</default>
89 <context>upstream</context>
90
91 <para>
92 Директива задаёт имя и параметры сервера.
93 В качестве имени можно использовать доменное имя, адрес, порт или путь
94 unix-сокета. Если доменное имя резолвится в несколько адресов, то
95 используются все.
96 <list type="bullet">
97
98 <listitem>
99 weight=число — задаёт вес сервера, по умолчанию вес равен одному.
100 </listitem>
101
102 <listitem>
103 max_fails=число — задаёт число неудачных попыток работы с сервером
104 в течение времени, заданного параметром fail_timeout,
105 после которых он считается неработающим также в течение времени
106 заданного параметром fail_timeout.
107 По умолчанию число попыток равно одной.
108 Нулевое значение запрещает учёт попыток.
109 Что считается неудачной попыткой, задаётся директивами
110 <link doc="ngx_http_proxy_module.xml#proxy_next_upstream">proxy_next_upstream</link>
111 и <link doc="ngx_http_fastcgi_module.xml#fastcgi_next_upstream">fastcgi_next_upstream</link>.
112 Состояние http_404 не считается неудачной попыткой.
113 </listitem>
114
115 <listitem>
116 fail_timeout=время — задаёт
117 <list type="bullet">
118
119 <listitem>
120 время, в течение которого должно произойти заданное число неудачных
121 попыток работы с сервером для того, чтобы сервер считался неработающим;
122 </listitem>
123
124 <listitem>
125 и время, в течение которого сервер будет считаться неработающим.
126 </listitem>
127
128 </list>
129 По умолчанию время равно 10 секундам.
130 </listitem>
131
132 <listitem>
133 backup — помечает сервер как запасной сервер. На него будут
134 передаваться запросы в случае, если не работают основные сервера.
135 </listitem>
136
137 <listitem>
138 down — помечает сервер как постоянно неработающий, используется
139 совместно с директивой <link id="ip_hash"/>.
140 </listitem>
141
142 </list>
143 </para>
144
145 <para>
146 Пример конфигурации:
147 <example>
148 upstream backend {
149 server backend1.example.com weight=5;
150 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
151 server unix:/tmp/backend3;
152
153 server backup1.example.com:8080 backup;
154 }
155 </example>
156 </para>
157
158 </directive>
159
160
161 <directive name="upstream">
162 <syntax>upstream <value>название</value> { ... }</syntax>
163 <default>нет</default>
164 <context>http</context>
165
166 <para>
167 Директива описывает группу серверов.
168 Сервера могут слушать на разных портах, кроме того, можно одновременно
169 использовать сервера, слушающие на TCP и unix сокетах.
170 </para>
171
172 <para>
173 Пример конфигурации:
174 <example>
175 upstream backend {
176 server backend1.example.com weight=5;
177 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
178 server unix:/tmp/backend3;
179 }
180 </example>
181 </para>
182
183 <para>
184 Запросы распределяются по серверам в режиме round-robin с учётом весов серверов.
185 В вышеприведённом примере каждые 7 семь запросов будут распределены так:
186 5 запросов на backend1.example.com и по одному запросу на второй и третий
187 сервера.
188 Если при попытке работы с сервером произошла ошибка, то запрос будет
189 передан следующему серверу и так до тех пор, пока не будут опробованы
190 все работающие сервера. Если не удастся получить успешный ответ
191 от всех серверов, то клиенту будет возвращён результат работы
192 с последним сервером.
193 </para>
194
195 </directive>
196
197 </section>
198
199
200 <section name="Встроенные переменные" id="variables">
201
202 <para>
203 Модуль ngx_http_upstream поддерживает следующие встроенные переменные:
204 <list type="bullet">
205
206 <listitem>
207 $upstream_addr — в переменной хранятся ip-адрес и порт сервера
208 или путь к unix-сокету.
209 Если при обработке запроса были сделаны обращения к нескольким серверам,
210 то их адреса разделяются запятой, например,
211 "192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock".
212 Если произошёл внутренний редирект от одной группы серверов на другую с помощью
213 "X-Accel-Redirect" или error_page, то эти группы серверов разделяются
214 двоеточием, например,
215 "192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80".
216 </listitem>
217
218 <listitem>
219 $upstream_response_time — в переменной хранятся времена ответов серверов
220 в секундах с точностью до миллисекунд.
221 Несколько ответов также разделяются запятыми и двоеточиями.
222 </listitem>
223
224 <listitem>
225 $upstream_status — в переменной хранятся коды ответов серверов.
226 Несколько ответов также разделяются запятыми и двоеточиями.
227 </listitem>
228
229 <listitem>
230 $upstream_http_... — в переменных хранятся строки заголовков ответов
231 серверов, например, строка заголовка ответа "Server" доступна в переменной
232 $upstream_http_server. Необходимо иметь ввиду, что запоминаются только
233 строки последнего сервера.
234 </listitem>
235
236 </list>
237 </para>
238
239 </section>
240
241 </module>