Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_upstream_module.xml @ 292:7bc830cc79bb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Revision.
author Ruslan Ermilov <ru@nginx.com>
date Wed, 28 Dec 2011 18:59:45 +0000
parents cbb789d3ce5e
children 1fb1c077658b
comparison
equal deleted inserted replaced
291:fd85955f31aa 292:7bc830cc79bb
1 <?xml version="1.0"?> 1 <?xml version="1.0"?>
2 2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4 4
5 <module name="Директивы модуля ngx_http_upstream_module" 5 <module name="Модуль ngx_http_upstream_module"
6 link="/ru/docs/http/ngx_http_upstream_module.html" 6 link="/ru/docs/http/ngx_http_upstream_module.html"
7 lang="ru"> 7 lang="ru">
8 8
9 <section id="summary"> 9 <section id="summary">
10 10
11 <para> 11 <para>
12 Модуль позволяет описывать группы серверов, 12 Модуль <literal>ngx_http_upstream_module</literal>
13 позволяет описывать группы серверов,
13 которые могут использоваться в директивах 14 которые могут использоваться в директивах
14 <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/> 15 <link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>
15 и <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>. 16 и <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>.
16 </para> 17 </para>
17 18
18 </section> 19 </section>
19 20
20 21
21 <section name="Пример конфигурации" id="example"> 22 <section id="example" name="Пример конфигурации">
22 23
23 <para> 24 <para>
24 <example> 25 <example>
25 upstream <emphasis>backend</emphasis> { 26 upstream <emphasis>backend</emphasis> {
26 server backend1.example.com weight=5; 27 server backend1.example.com weight=5;
27 server backend2.example.com:8080; 28 server backend2.example.com:8080;
28 server unix:/tmp/backend3; 29 server unix:/tmp/backend3;
29 30
30 server backup1.example.com:8080 backup; 31 server backup1.example.com:8080 backup;
31 server backup2.example.com:8080 backup; 32 server backup2.example.com:8080 backup;
32 } 33 }
33 34
34 server { 35 server {
35 location / { 36 location / {
36 proxy_pass http://<emphasis>backend</emphasis>; 37 proxy_pass http://<emphasis>backend</emphasis>;
37 } 38 }
38 } 39 }
39 </example> 40 </example>
40 </para> 41 </para>
41 42
42 </section> 43 </section>
43 44
44 45
45 <section name="Директивы" id="directives"> 46 <section id="directives" name="Директивы">
46 47
47 <directive name="ip_hash"> 48 <directive name="ip_hash">
48 <syntax/> 49 <syntax/>
49 <default/> 50 <default/>
50 <context>upstream</context> 51 <context>upstream</context>
51 52
52 <para> 53 <para>
53 Директива задаёт метод распределения запросов по серверам на основе 54 Задаёт для группы метод распределения запросов по серверам
54 IP-адресов клиентов. В качестве ключа для хеширования используется сеть 55 на основе IP-адресов клиентов.
55 класса C, в которой находится адрес клиента. 56 В качестве ключа для хэширования используется сеть класса C,
56 Метод гарантирует, что запросы клиента будут передаваться на один и тот же 57 в которой находится адрес клиента.
57 сервер. Если же этот сервер будет считаться неработающим, то запросы этого 58 Метод гарантирует, что запросы одного и того же клиента
58 клиента будут передаваться на другой сервер. С большой долей вероятности 59 будут всегда передаваться на один и тот же сервер.
59 это также будет один и тот же сервер. 60 Если же этот сервер будет считаться неработающим,
60 </para> 61 то запросы этого клиента будут передаваться на другой сервер.
61 62 С большой долей вероятности это также будет один и тот же сервер.
62 <para> 63 </para>
63 Для серверов, использующих метод распределения ip_hash, нельзя задать вес. 64
65 <para>
66 Для серверов, использующих метод распределения <literal>ip_hash</literal>,
67 нельзя задать вес.
64 Если один из серверов нужно убрать на некоторое время, то для сохранения 68 Если один из серверов нужно убрать на некоторое время, то для сохранения
65 текущего хеширования IP-адресов клиентов этот сервер нужно пометить 69 текущего хэширования IP-адресов клиентов этот сервер нужно пометить
66 параметром down. 70 параметром <literal>down</literal>.
67 </para> 71 </para>
68 72
69 <para> 73 <para>
70 Пример конфигурации: 74 Пример:
71 <example> 75 <example>
72 upstream backend { 76 upstream backend {
73 ip_hash; 77 ip_hash;
74 78
75 server backend1.example.com; 79 server backend1.example.com;
76 server backend2.example.com; 80 server backend2.example.com;
77 server backend3.example.com down; 81 server backend3.example.com <emphasis>down</emphasis>;
78 server backend4.example.com; 82 server backend4.example.com;
79 } 83 }
80 </example> 84 </example>
81 </para> 85 </para>
82 86
83 </directive> 87 </directive>
87 <syntax><value>название</value> [<value>параметры</value>]</syntax> 91 <syntax><value>название</value> [<value>параметры</value>]</syntax>
88 <default/> 92 <default/>
89 <context>upstream</context> 93 <context>upstream</context>
90 94
91 <para> 95 <para>
92 Директива задаёт имя и параметры сервера. 96 Задаёт <value>имя</value> и другие <value>параметры</value> сервера.
93 В качестве имени можно использовать доменное имя, адрес, порт или путь 97 В качестве имени можно использовать доменное имя, адрес, порт или путь
94 unix-сокета. Если доменное имя резолвится в несколько адресов, то 98 UNIX-сокета.
95 используются все. 99 Если доменному имени соответствует несколько адресов, то все они используются.
96 <list type="bullet"> 100 <list type="tag">
97 101
98 <listitem> 102 <tag-name><literal>weight</literal>=<value>число</value></tag-name>
99 weight=число — задаёт вес сервера, по умолчанию вес равен одному. 103 <tag-desc>
100 </listitem> 104 задаёт вес сервера, по умолчанию 1.
101 105 </tag-desc>
102 <listitem> 106
103 max_fails=число — задаёт число неудачных попыток работы с сервером 107 <tag-name><literal>max_fails</literal>=<value>число</value></tag-name>
104 в течение времени, заданного параметром fail_timeout, 108 <tag-desc>
105 после которых он считается неработающим также в течение времени 109 задаёт число неудачных попыток работы с сервером
106 заданного параметром fail_timeout. 110 в течение времени, заданного параметром <literal>fail_timeout</literal>,
107 По умолчанию число попыток равно одной. 111 после которого он считается неработающим, также в течение времени
112 заданного параметром <literal>fail_timeout</literal>.
113 По умолчанию число попыток устанавливается равным 1.
108 Нулевое значение запрещает учёт попыток. 114 Нулевое значение запрещает учёт попыток.
109 Что считается неудачной попыткой, задаётся директивами 115 Что считается неудачной попыткой, задаётся директивами
110 <link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/> 116 <link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>
111 и <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>. 117 и <link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>.
112 Состояние http_404 не считается неудачной попыткой. 118 Состояние <literal>http_404</literal>
113 </listitem> 119 не считается неудачной попыткой.
114 120 </tag-desc>
115 <listitem> 121
116 fail_timeout=время — задаёт 122 <tag-name><literal>fail_timeout</literal>=<value>время</value></tag-name>
123 <tag-desc>
124 задаёт
117 <list type="bullet"> 125 <list type="bullet">
118 126
119 <listitem> 127 <listitem>
120 время, в течение которого должно произойти заданное число неудачных 128 время, в течение которого должно произойти заданное число неудачных
121 попыток работы с сервером для того, чтобы сервер считался неработающим; 129 попыток работы с сервером для того, чтобы сервер считался неработающим;
124 <listitem> 132 <listitem>
125 и время, в течение которого сервер будет считаться неработающим. 133 и время, в течение которого сервер будет считаться неработающим.
126 </listitem> 134 </listitem>
127 135
128 </list> 136 </list>
129 По умолчанию время равно 10 секундам. 137 По умолчанию таймаут равен 10 секундам.
130 </listitem> 138 </tag-desc>
131 139
132 <listitem> 140 <tag-name><literal>backup</literal></tag-name>
133 backup — помечает сервер как запасной сервер. На него будут 141 <tag-desc>
134 передаваться запросы в случае, если не работают основные сервера. 142 помечает сервер как запасной сервер.
135 </listitem> 143 На него будут передаваться запросы в случае, если не работают основные серверы.
136 144 </tag-desc>
137 <listitem> 145
138 down — помечает сервер как постоянно неработающий, используется 146 <tag-name><literal>down</literal></tag-name>
147 <tag-desc>
148 помечает сервер как постоянно неработающий; используется
139 совместно с директивой <link id="ip_hash"/>. 149 совместно с директивой <link id="ip_hash"/>.
140 </listitem> 150 </tag-desc>
141 151
142 </list> 152 </list>
143 </para> 153 </para>
144 154
145 <para> 155 <para>
146 Пример конфигурации: 156 Пример:
147 <example> 157 <example>
148 upstream backend { 158 upstream backend {
149 server backend1.example.com weight=5; 159 server backend1.example.com weight=5;
150 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; 160 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
151 server unix:/tmp/backend3; 161 server unix:/tmp/backend3;
152 162
153 server backup1.example.com:8080 backup; 163 server backup1.example.com:8080 backup;
154 } 164 }
155 </example> 165 </example>
156 </para> 166 </para>
157 167
158 </directive> 168 </directive>
162 <syntax block="yes"><value>название</value></syntax> 172 <syntax block="yes"><value>название</value></syntax>
163 <default/> 173 <default/>
164 <context>http</context> 174 <context>http</context>
165 175
166 <para> 176 <para>
167 Директива описывает группу серверов. 177 Описывает группу серверов.
168 Сервера могут слушать на разных портах, кроме того, можно одновременно 178 Серверы могут слушать на разных портах.
169 использовать сервера, слушающие на TCP и unix сокетах. 179 Кроме того, можно одновременно использовать серверы,
170 </para> 180 слушающие на TCP- и UNIX-сокетах.
171 181 </para>
172 <para> 182
173 Пример конфигурации: 183 <para>
174 <example> 184 Пример:
175 upstream backend { 185 <example>
176 server backend1.example.com weight=5; 186 upstream backend {
177 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; 187 server backend1.example.com weight=5;
178 server unix:/tmp/backend3; 188 server 127.0.0.1:8080 max_fails=3 fail_timeout=30s;
179 } 189 server unix:/tmp/backend3;
180 </example> 190 }
181 </para> 191 </example>
182 192 </para>
183 <para> 193
184 Запросы распределяются по серверам в режиме round-robin с учётом весов серверов. 194 <para>
185 В вышеприведённом примере каждые 7 семь запросов будут распределены так: 195 Запросы распределяются по серверам циклически (в режиме round-robin)
186 5 запросов на backend1.example.com и по одному запросу на второй и третий 196 с учётом весов серверов.
187 сервера. 197 В вышеприведённом примере каждые 7 запросов будут распределены так:
198 5 запросов на <literal>backend1.example.com</literal>
199 и по одному запросу на второй и третий серверы.
188 Если при попытке работы с сервером произошла ошибка, то запрос будет 200 Если при попытке работы с сервером произошла ошибка, то запрос будет
189 передан следующему серверу и так до тех пор, пока не будут опробованы 201 передан следующему серверу, и так до тех пор, пока не будут опробованы
190 все работающие сервера. Если не удастся получить успешный ответ 202 все работающие серверы.
191 от всех серверов, то клиенту будет возвращён результат работы 203 Если не удастся получить успешный ответ
204 ни от одного из серверов, то клиенту будет возвращён результат работы
192 с последним сервером. 205 с последним сервером.
193 </para> 206 </para>
194 207
195 </directive> 208 </directive>
196 209
197 </section> 210 </section>
198 211
199 212
200 <section name="Встроенные переменные" id="variables"> 213 <section id="variables" name="Встроенные переменные">
201 214
202 <para> 215 <para>
203 Модуль ngx_http_upstream_module поддерживает следующие встроенные переменные: 216 Модуль <literal>ngx_http_upstream_module</literal>
204 <list type="bullet"> 217 поддерживает следующие встроенные переменные:
205 218 <list type="tag">
206 <listitem> 219
207 $upstream_addr — в переменной хранятся ip-адрес и порт сервера 220 <tag-name><var>$upstream_addr</var></tag-name>
208 или путь к unix-сокету. 221 <tag-desc>
222 хранит IP-адрес и порт сервера или путь к UNIX-сокету.
209 Если при обработке запроса были сделаны обращения к нескольким серверам, 223 Если при обработке запроса были сделаны обращения к нескольким серверам,
210 то их адреса разделяются запятой, например, 224 то их адреса разделяются запятой, например,
211 "192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock". 225 “<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”.
212 Если произошло внутреннее перенаправление от одной группы серверов на другую 226 Если произошло внутреннее перенаправление от одной группы серверов на другую
213 с помощью 227 с помощью
214 "X-Accel-Redirect" или error_page, то эти группы серверов разделяются 228 <header>X-Accel-Redirect</header> или
215 двоеточием, например, 229 <link doc="ngx_http_core_module.xml" id="error_page"/>,
216 "192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80". 230 то эти группы серверов разделяются двоеточием, например,
217 </listitem> 231 “<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>”.
218 232 </tag-desc>
219 <listitem> 233
220 $upstream_response_time — в переменной хранятся времена ответов серверов 234 <tag-name><var>$upstream_response_time</var></tag-name>
221 в секундах с точностью до миллисекунд. 235 <tag-desc>
236 хранит времена ответов серверов в секундах с точностью до миллисекунд.
222 Несколько ответов также разделяются запятыми и двоеточиями. 237 Несколько ответов также разделяются запятыми и двоеточиями.
223 </listitem> 238 </tag-desc>
224 239
225 <listitem> 240 <tag-name><var>$upstream_status</var></tag-name>
226 $upstream_status — в переменной хранятся коды ответов серверов. 241 <tag-desc>
242 хранит коды ответов серверов.
227 Несколько ответов также разделяются запятыми и двоеточиями. 243 Несколько ответов также разделяются запятыми и двоеточиями.
228 </listitem> 244 </tag-desc>
229 245
230 <listitem> 246 <tag-name><var>$upstream_http_...</var></tag-name>
231 $upstream_http_... — в переменных хранятся строки заголовков ответов 247 <tag-desc>
232 серверов, например, строка заголовка ответа "Server" доступна в переменной 248 хранят поля заголовка ответа сервера.
233 $upstream_http_server. Необходимо иметь в виду, что запоминаются только 249 Например, поле заголовка ответа <header>Server</header>
234 строки последнего сервера. 250 доступно в переменной <var>$upstream_http_server</var>.
235 </listitem> 251 Необходимо иметь в виду, что запоминаются только поля заголовка ответа
252 последнего сервера.
253 </tag-desc>
236 254
237 </list> 255 </list>
238 </para> 256 </para>
239 257
240 </section> 258 </section>