Mercurial > hg > nginx-site
comparison xml/ru/docs/http/ngx_http_rewrite_module.xml @ 382:b838f6e9192e
Revision.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Tue, 31 Jan 2012 16:29:31 +0000 |
parents | 4c6d2c614d2c |
children | 1702722eca07 |
comparison
equal
deleted
inserted
replaced
381:8ad9df891e23 | 382:b838f6e9192e |
---|---|
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_rewrite_module" | 5 <module name="Модуль ngx_http_rewrite_module" |
6 link="/ru/docs/http/ngx_http_rewrite_module.html" | 6 link="/ru/docs/http/ngx_http_rewrite_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 Модуль ngx_http_rewrite_module позволяет изменять URI с помощью | 12 Модуль <literal>ngx_http_rewrite_module</literal> позволяет |
13 регулярных выражений, делать перенаправления и выбирать конфигурацию | 13 изменять URI с помощью регулярных выражений, делать перенаправления |
14 в зависимости от переменных. Если директивы этого модуля описаны | 14 и выбирать конфигурацию в зависимости от переменных. |
15 на уровне сервера, то они выполняются до того, как определяется | 15 Если директивы этого модуля описаны на уровне сервера, то они |
16 location для запроса. Если в выбранном location тоже есть | 16 выполняются до того, как определяется location для запроса. |
17 директивы модуля ngx_http_rewrite_module, то они также выполняются. | 17 Если в выбранном location тоже есть директивы модуля |
18 <literal>ngx_http_rewrite_module</literal>, то они также выполняются. | |
18 Если URI изменился в результате исполнения директив внутри location, | 19 Если URI изменился в результате исполнения директив внутри location, |
19 то снова определяется location для уже нового URI. Этот цикл может | 20 то снова определяется location для уже нового URI. |
20 повторяться до 10 раз, после чего nginx возвращает ошибку | 21 Этот цикл может повторяться до 10 раз, после чего nginx возвращает |
21 "Server Internal Error" (500). | 22 ошибку <http-status code="500" text="Internal Server Error"/>. |
22 </para> | 23 </para> |
23 | 24 |
24 </section> | 25 </section> |
25 | 26 |
26 | 27 |
27 <section name="Директивы" id="directives"> | 28 <section id="directives" name="Директивы"> |
28 | 29 |
29 <directive name="break"> | 30 <directive name="break"> |
30 <syntax/> | 31 <syntax/> |
31 <default/> | 32 <default/> |
32 <context>server, location, if</context> | 33 <context>server</context> |
33 | 34 <context>location</context> |
34 <para> | 35 <context>if</context> |
35 Директива завершает обработку текущего набора директив | 36 |
36 ngx_http_rewrite_module. | 37 <para> |
37 </para> | 38 Завершает обработку текущего набора директив модуля |
38 | 39 <literal>ngx_http_rewrite_module</literal>. |
39 <para> | 40 </para> |
40 Пример использования: | 41 |
41 <example> | 42 <para> |
42 if ($slow) { | 43 Пример: |
43 limit_rate 10k; | 44 <example> |
44 break; | 45 if ($slow) { |
45 } | 46 limit_rate 10k; |
47 break; | |
48 } | |
46 </example> | 49 </example> |
47 </para> | 50 </para> |
48 | 51 |
49 </directive> | 52 </directive> |
50 | 53 |
51 | 54 |
52 <directive name="if"> | 55 <directive name="if"> |
53 <syntax block="yes">(<value>условие</value>)</syntax> | 56 <syntax block="yes">(<value>условие</value>)</syntax> |
54 <default/> | 57 <default/> |
55 <context>server, location</context> | 58 <context>server</context> |
56 | 59 <context>location</context> |
57 <para> | 60 |
58 Директива if проверяет истинность условия, если оно истинно, | 61 <para> |
62 Проверяет истинность условия. | |
63 Если оно истинно, | |
59 то выполняется указанный в фигурных скобках код и запрос обрабатывается | 64 то выполняется указанный в фигурных скобках код и запрос обрабатывается |
60 в соответствии с заданной там же конфигурацией. | 65 в соответствии с заданной там же конфигурацией. |
61 Конфигурация внутри директивы if наследуется из предыдущего уровня. | 66 Конфигурация внутри директивы <literal>if</literal> наследуется с |
67 предыдущего уровня. | |
62 </para> | 68 </para> |
63 | 69 |
64 <para> | 70 <para> |
65 В качестве условия могут быть заданы: | 71 В качестве условия могут быть заданы: |
66 <list type="bullet"> | 72 <list type="bullet"> |
67 | 73 |
68 <listitem> | 74 <listitem> |
69 имя переменной; ложными значениями переменной являются пустая строка "" | 75 имя переменной; ложными значениями переменной являются пустая строка “” |
70 или любая строка, начинающиеся на "0"; | 76 или любая строка, начинающаяся на “<literal>0</literal>”; |
71 </listitem> | 77 </listitem> |
72 | 78 |
73 <listitem> | 79 <listitem> |
74 сравнение переменной со строкой с помощью операторов "=" и "!="; | 80 сравнение переменной со строкой с помощью операторов |
75 </listitem> | 81 “<literal>=</literal>” и “<literal>!=</literal>”; |
76 | 82 </listitem> |
77 <listitem> | 83 |
78 проверка переменной с помощью регулярного выражения без учёта | 84 <listitem> |
79 регистра символов — "~*" и с учётом — "~". | 85 проверка переменной с помощью регулярного выражения с учётом |
86 регистра символов — “<literal>~</literal>” и без него — “<literal>~*</literal>”. | |
80 В регулярных выражениях можно использовать выделения, которые затем | 87 В регулярных выражениях можно использовать выделения, которые затем |
81 доступны в виде переменных $1 — $9. | 88 доступны в виде переменных <var>$1</var> — <var>$9</var>. |
82 Также можно использовать отрицательные операторы "!~" и "!~*". | 89 Также можно использовать отрицательные операторы “<literal>!~</literal>” |
83 Если в регулярном выражении встречаются символы "}" или ";", то | 90 и “<literal>!~*</literal>”. |
84 всё выражение нужно заключить в одинарные или двойные кавычки. | 91 Если в регулярном выражении встречаются символы “<literal>}</literal>” |
85 </listitem> | 92 или “<literal>;</literal>”, то всё выражение нужно заключить в одинарные |
86 | 93 или двойные кавычки. |
87 <listitem> | 94 </listitem> |
88 проверка существования файла с помощью операторов "-f" и "!-f"; | 95 |
89 </listitem> | 96 <listitem> |
90 | 97 проверка существования файла с помощью операторов “<literal>-f</literal>” |
91 <listitem> | 98 и “<literal>!-f</literal>”; |
92 проверка существования каталога с помощью операторов "-d" и "!-d"; | 99 </listitem> |
100 | |
101 <listitem> | |
102 проверка существования каталога с помощью операторов “<literal>-d</literal>” | |
103 и “<literal>!-d</literal>”; | |
93 </listitem> | 104 </listitem> |
94 | 105 |
95 <listitem> | 106 <listitem> |
96 проверка существования файла, каталога или символической ссылки | 107 проверка существования файла, каталога или символической ссылки |
97 с помощью операторов "-e" и "!-e"; | 108 с помощью операторов “<literal>-e</literal>” и “<literal>!-e</literal>”; |
98 </listitem> | 109 </listitem> |
99 | 110 |
100 <listitem> | 111 <listitem> |
101 проверка исполняемости файла с помощью операторов "-x" и "!-x". | 112 проверка исполняемости файла с помощью операторов “<literal>-x</literal>” |
113 и “<literal>!-x</literal>”. | |
102 </listitem> | 114 </listitem> |
103 | 115 |
104 </list> | 116 </list> |
105 </para> | 117 </para> |
106 | 118 |
107 <para> | 119 <para> |
108 Примеры использования: | 120 Примеры: |
109 <example> | 121 <example> |
110 if ($http_user_agent ~ MSIE) { | 122 if ($http_user_agent ~ MSIE) { |
111 rewrite ^(.*)$ /msie/$1 break; | 123 rewrite ^(.*)$ /msie/$1 break; |
112 } | 124 } |
113 | 125 |
114 if ($http_cookie ~* "id=([^;]+)(?:;|$)" ) { | 126 if ($http_cookie ~* "id=([^;]+)(?:;|$)") { |
115 set $id $1; | 127 set $id $1; |
116 } | 128 } |
117 | 129 |
118 if ($request_method = POST ) { | 130 if ($request_method = POST) { |
119 return 405; | 131 return 405; |
120 } | 132 } |
121 | 133 |
122 | 134 |
123 if ($slow) { | 135 if ($slow) { |
124 limit_rate 10k; | 136 limit_rate 10k; |
125 } | 137 } |
126 | 138 |
127 if ($invalid_referer) { | 139 if ($invalid_referer) { |
128 return 403; | 140 return 403; |
129 } | 141 } |
130 </example> | 142 </example> |
131 Значение встроенной переменной $invalid_referer задаётся директивой | 143 Значение встроенной переменной <var>$invalid_referer</var> задаётся директивой |
132 <link doc="ngx_http_referer_module.xml" id="valid_referers"/>. | 144 <link doc="ngx_http_referer_module.xml" id="valid_referers"/>. |
133 </para> | 145 </para> |
134 | 146 |
135 </directive> | 147 </directive> |
136 | 148 |
137 | 149 |
138 <directive name="return"> | 150 <directive name="return"> |
139 <syntax><value>код</value></syntax> | 151 <syntax><value>код</value></syntax> |
140 <default/> | 152 <default/> |
141 <context>server, location, if</context> | 153 <context>server</context> |
142 | 154 <context>location</context> |
143 <para> | 155 <context>if</context> |
144 Директива return завершает исполнение кода и возвращает клиенту | 156 |
145 указанный код. Можно использовать следующие значения: 204, 400, | 157 <para> |
158 Завершает исполнение кода и возвращает клиенту указанный код. | |
159 Можно использовать следующие значения: 204, 400, | |
146 402 — 406, 408, 410, 411, 413, 416 и 500 — 504. | 160 402 — 406, 408, 410, 411, 413, 416 и 500 — 504. |
147 Кроме того, нестандартный код 444 закрывает соединение без передачи | 161 Кроме того, нестандартный код 444 закрывает соединение без передачи |
148 заголовка ответа. | 162 заголовка ответа. |
149 </para> | 163 </para> |
150 | 164 |
151 </directive> | 165 </directive> |
152 | 166 |
153 | 167 |
154 <directive name="rewrite"> | 168 <directive name="rewrite"> |
155 <syntax><value>regex</value> <value>замена</value> <value>флаг</value></syntax> | 169 <syntax> |
156 <default/> | 170 <value>regex</value> |
157 <context>server, location, if</context> | 171 <value>замена</value> |
158 | 172 [<value>флаг</value>]</syntax> |
159 <para> | 173 <default/> |
160 Директива rewrite изменяет URI в соответствии с регулярным выражением | 174 <context>server</context> |
161 и строкой замены. Директивы выполняются в порядке их следования в | 175 <context>location</context> |
162 конфигурационном файле. С помощью флагов можно досрочно прекратить | 176 <context>if</context> |
163 исполнение директив. Если строка замены начинается с "http://", то | 177 |
164 клиенту будет возвращено перенаправление и обработка директив также завершается. | 178 <para> |
179 Изменяет URI в соответствии с регулярным выражением и строкой замены. | |
180 Директивы выполняются в порядке их следования в конфигурационном файле. | |
181 С помощью флагов можно досрочно прекратить исполнение директив. | |
182 Если строка замены начинается с “<literal>http://</literal>”, то клиенту | |
183 будет возвращено перенаправление и обработка директив также завершается. | |
165 </para> | 184 </para> |
166 | 185 |
167 <para> | 186 <para> |
168 Флаги могут быть следующими: | 187 Флаги могут быть следующими: |
169 <list type="bullet"> | 188 <list type="tag"> |
170 | 189 |
171 <listitem> | 190 <tag-name><literal>last</literal></tag-name> |
172 last — завершает обработку текущего набора директив | 191 <tag-desc> |
173 ngx_http_rewrite_module, после чего ищется соответствие URI и location; | 192 завершает обработку текущего набора директив модуля |
174 </listitem> | 193 <literal>ngx_http_rewrite_module</literal>, |
175 | 194 после чего ищется соответствие URI и location; |
176 <listitem> | 195 </tag-desc> |
177 break — завершает обработку текущего набора директив | 196 |
178 ngx_http_rewrite_module; | 197 <tag-name><literal>break</literal></tag-name> |
179 </listitem> | 198 <tag-desc> |
180 | 199 завершает обработку текущего набора директив модуля |
181 <listitem> | 200 <literal>ngx_http_rewrite_module</literal>; |
182 redirect — возвращает временное перенаправление с кодом 302; | 201 </tag-desc> |
183 используется, если заменяющая строка не начинается с "http://"; | 202 |
184 </listitem> | 203 <tag-name><literal>redirect</literal></tag-name> |
185 | 204 <tag-desc> |
186 <listitem> | 205 возвращает временное перенаправление с кодом 302; |
187 permanent — возвращает постоянное перенаправление с кодом 301. | 206 используется, если заменяющая строка не начинается с |
188 </listitem> | 207 “<literal>http://</literal>”; |
208 </tag-desc> | |
209 | |
210 <tag-name><literal>permanent</literal></tag-name> | |
211 <tag-desc> | |
212 возвращает постоянное перенаправление с кодом 301. | |
213 </tag-desc> | |
189 | 214 |
190 </list> | 215 </list> |
191 </para> | 216 </para> |
192 | 217 |
193 <para> | 218 <para> |
194 </para> | 219 Пример: |
195 | 220 <example> |
196 <para> | 221 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; |
197 Пример использования: | 222 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last; |
198 <example> | 223 return 403; |
199 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; | 224 </example> |
200 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last; | 225 </para> |
201 return 403; | 226 |
202 </example> | 227 <para> |
203 </para> | 228 Если же эти директивы поместить в location “<literal>/download/</literal>”, |
204 | 229 то нужно заменить флаг <literal>last</literal> на <literal>break</literal>, |
205 <para> | 230 иначе nginx сделает 10 циклов и вернёт ошибку 500: |
206 Если же эти директивы поместить в location /download/, то нужно | 231 <example> |
207 заменить флаг last на break, иначе nginx сделает 10 циклов и вернёт | 232 location /download/ { |
208 ошибку 500: | 233 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; |
209 <example> | 234 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break; |
210 location /download/ { | 235 return 403; |
211 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; | 236 } |
212 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break; | |
213 return 403; | |
214 } | |
215 </example> | 237 </example> |
216 </para> | 238 </para> |
217 | 239 |
218 <para> | 240 <para> |
219 Если в строке замены указаны аргументы, то предыдущие аргументы запроса | 241 Если в строке замены указаны аргументы, то предыдущие аргументы запроса |
220 добавляются после них. Можно отказаться от этого добавления, указав | 242 добавляются после них. |
221 в конце строки замены знак вопроса: | 243 Можно отказаться от этого добавления, указав в конце строки замены знак вопроса: |
222 <example> | 244 <example> |
223 rewrite ^/users/(.*)$ /show?user=$1? last; | 245 rewrite ^/users/(.*)$ /show?user=$1? last; |
224 </example> | 246 </example> |
225 </para> | 247 </para> |
226 | 248 |
227 <para> | 249 <para> |
228 Если в регулярном выражении встречаются символы "}" или ";", то | 250 Если в регулярном выражении встречаются символы “<literal>}</literal>” |
229 всё выражение нужно заключить в одинарные или двойные кавычки. | 251 или “<literal>;</literal>”, то всё выражение нужно заключить в одинарные |
252 или двойные кавычки. | |
230 </para> | 253 </para> |
231 | 254 |
232 </directive> | 255 </directive> |
233 | 256 |
234 | 257 |
235 <directive name="set"> | 258 <directive name="set"> |
236 <syntax><value>переменная</value> <value>значение</value></syntax> | 259 <syntax><value>переменная</value> <value>значение</value></syntax> |
237 <default/> | 260 <default/> |
238 <context>server, location, if</context> | 261 <context>server</context> |
239 | 262 <context>location</context> |
240 <para> | 263 <context>if</context> |
241 Директива устанавливает значение для указанной переменной. | 264 |
265 <para> | |
266 Устанавливает значение для указанной переменной. | |
242 В качестве значения можно использовать текст, переменные и их комбинации. | 267 В качестве значения можно использовать текст, переменные и их комбинации. |
243 </para> | 268 </para> |
244 | 269 |
245 </directive> | 270 </directive> |
246 | 271 |
247 | 272 |
248 <directive name="uninitialized_variable_warn"> | 273 <directive name="uninitialized_variable_warn"> |
249 <syntax><literal>on</literal> | <literal>off</literal></syntax> | 274 <syntax><literal>on</literal> | <literal>off</literal></syntax> |
250 <default>on</default> | 275 <default>on</default> |
251 <context>http, server, location, if</context> | 276 <context>http</context> |
252 | 277 <context>server</context> |
253 <para> | 278 <context>location</context> |
254 Директива определяет, нужно ли писать в лог предупреждение | 279 <context>if</context> |
280 | |
281 <para> | |
282 Определяет, нужно ли писать в лог предупреждение | |
255 о неинициализированной переменной. | 283 о неинициализированной переменной. |
256 </para> | 284 </para> |
257 | 285 |
258 </directive> | 286 </directive> |
259 | 287 |
260 </section> | 288 </section> |
261 | 289 |
262 | 290 |
263 <section name="Внутреннее устройство" id="internals"> | 291 <section id="internals" name="Внутреннее устройство"> |
264 | 292 |
265 <para> | 293 <para> |
266 Директивы модуля ngx_http_rewrite_module компилируется на стадии | 294 Директивы модуля <literal>ngx_http_rewrite_module</literal> |
267 конфигурирования во внутренние коды, исполняемые во время запроса | 295 компилируются на стадии конфигурации во внутренние коды, |
268 интерпретатором. Интерпретатор представляет из себя простую | 296 исполняемые во время запроса интерпретатором. |
269 стековую виртуальную машину. | 297 Интерпретатор представляет из себя простую стековую виртуальную машину. |
270 </para> | 298 </para> |
271 | 299 |
272 <para> | 300 <para> |
273 Например, директивы | 301 Например, директивы |
274 <example> | 302 <example> |
275 location /download/ { | 303 location /download/ { |
276 if ($forbidden) { | 304 if ($forbidden) { |
277 return 403; | 305 return 403; |
278 } | |
279 | |
280 if ($slow) { | |
281 limit_rate 10k; | |
282 } | |
283 | |
284 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; | |
285 } | 306 } |
307 | |
308 if ($slow) { | |
309 limit_rate 10k; | |
310 } | |
311 | |
312 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; | |
313 } | |
286 </example> | 314 </example> |
287 будет скомпилированы в такие коды: | 315 будет скомпилированы в такие коды: |
288 <example> | 316 <example> |
289 переменная $forbidden | 317 переменная $forbidden |
290 проверка на ноль | 318 проверка на ноль |
291 возврат 403 | 319 возврат 403 |
292 завершение всего кода | |
293 переменная $slow | |
294 проверка на ноль | |
295 проверка регулярного выражения | |
296 копирование "/" | |
297 копирование $1 | |
298 копирование "/mp3/" | |
299 копирование $2 | |
300 копирование ".mp3" | |
301 завершение регулярного выражения | |
302 завершение всего кода | 320 завершение всего кода |
303 </example> | 321 переменная $slow |
304 </para> | 322 проверка на ноль |
305 | 323 проверка регулярного выражения |
306 <para> | 324 копирование "/" |
307 Обратите внимание, что кода для директивы limit_rate нет, поскольку | 325 копирование $1 |
308 она не имеет отношения к модулю ngx_http_rewrite_module. Для блока | 326 копирование "/mp3/" |
309 if создаётся такая же конфигурация, как и для блока location. | 327 копирование $2 |
328 копирование ".mp3" | |
329 завершение регулярного выражения | |
330 завершение всего кода | |
331 </example> | |
332 </para> | |
333 | |
334 <para> | |
335 Обратите внимание, что кода для директивы | |
336 <link doc="ngx_http_core_module.xml" id="limit_rate"/> | |
337 нет, поскольку она не имеет отношения к модулю | |
338 <literal>ngx_http_rewrite_module</literal>. | |
339 Для блока <link id="if"/> создаётся такая же конфигурация, как и для блока | |
340 <link doc="ngx_http_core_module.xml" id="location"/>. | |
310 Если условие истинно, то запрос получает конфигурацию, соответствующую | 341 Если условие истинно, то запрос получает конфигурацию, соответствующую |
311 блоку if, и в этой конфигурации limit_rate равен 10k. | 342 блоку <literal>if</literal>, |
343 и в этой конфигурации <literal>limit_rate</literal> равен 10k. | |
312 </para> | 344 </para> |
313 | 345 |
314 <para> | 346 <para> |
315 Директиву | 347 Директиву |
316 <example> | 348 <example> |
317 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; | 349 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; |
318 </example> | 350 </example> |
319 можно сделать на один код меньше, если в регулярном выражении включить | 351 можно сделать на один код меньше, если в регулярном выражении включить |
320 первый слэш в скобки: | 352 первый слэш в скобки: |
321 <example> | 353 <example> |
322 rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; | 354 rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; |
323 </example> | 355 </example> |
324 тогда её коды будут выглядеть так: | 356 тогда её коды будут выглядеть так: |
325 <example> | 357 <example> |
326 проверка регулярного выражения | 358 проверка регулярного выражения |
327 копирование $1 | 359 копирование $1 |
328 копирование "/mp3/" | 360 копирование "/mp3/" |
329 копирование $2 | 361 копирование $2 |
330 копирование ".mp3" | 362 копирование ".mp3" |
331 завершение регулярного выражения | 363 завершение регулярного выражения |
332 завершение всего кода | 364 завершение всего кода |
333 </example> | 365 </example> |
334 </para> | 366 </para> |
335 | 367 |
336 </section> | 368 </section> |
337 | 369 |