Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_proxy_module.xml @ 189:f9db3712d47d
Markup fixed.
author | Maxim Konovalov <maxim@nginx.com> |
---|---|
date | Tue, 22 Nov 2011 10:48:13 +0000 |
parents | edf8c90f8085 |
children | bfe3eff81d04 |
line wrap: on
line source
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Директивы модуля ngx_http_proxy_module" link="/ru/docs/http/ngx_http_proxy_module.html" lang="ru"> <section id="summary"> <para> Модуль ngx_http_proxy_module позволяет передавать запросы другому серверу. </para> </section> <section name="Пример конфигурации" id="example"> <para> <example> location / { proxy_pass http://localhost:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } </example> </para> </section> <section name="Директивы" id="directives"> <directive name="proxy_buffer_size"> <syntax><value>размер</value></syntax> <default>4k/8k</default> <context>http, server, location</context> <para> Директива задаёт размер буфера, в который будет читаться первая часть ответа, получаемого от проксируемого сервера. В этой части ответа находится, как правило, небольшой заголовок ответа. По умолчанию размер буфера равен размеру одного буфера в директиве <link id="proxy_buffers"/>, однако его можно сделать меньше. </para> </directive> <directive name="proxy_buffering"> <syntax><value>on|off</value></syntax> <default>on</default> <context>http, server, location</context> <para> Директива разрешает использовать буферизацию ответа проксируемого сервера. Если буферизация включена, то nginx принимает ответ проксируемого сервера как можно быстрее, сохраняя его в буфера, заданные директивами <link id="proxy_buffer_size"/> и <link id="proxy_buffers"/>. Если ответ не помещается полностью в память, то его часть записывается на диск. </para> <para> Если буферизация выключена, то ответ синхронно передаётся клиенту сразу же по мере его поступления. nginx не пытается считать весь ответ проксируемого сервера, максимальный размер данных, который nginx может принять от сервера задаётся директивой <link id="proxy_buffer_size"/>. </para> </directive> <directive name="proxy_buffers"> <syntax><value>число размер</value></syntax> <default>8 4k/8k</default> <context>http, server, location</context> <para> Директива задаёт число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от проксируемого сервера. По умолчанию размер одного буфера равен размеру страницы, в зависимости от платформы это или 4K, или 8K. </para> </directive> <directive name="proxy_cache"> <syntax><value>[зона|off]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива задаёт зону для кэширования. Одна и та же зона может использоваться в нескольких местах. Параметр "off" запрещает кэширование, унаследованное с предыдущего уровня конфигурации. </para> </directive> <directive name="proxy_cache_bypass"> <syntax><value>строка [...]</value></syntax> <default/> <context>http, server, location</context> <para> Директива задаёт условия, при которых ответ не будет браться из кэша. Если значение хотя бы одной из строк переменных не пустое и не равно "0", то ответ не берётся из кэша: <example> proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment; proxy_cache_bypass $http_pragma $http_authorization; </example> Можно использовать совместно с директивой <link id="proxy_no_cache"/>. </para> </directive> <directive name="proxy_cache_key"> <syntax><value>строка</value></syntax> <default>$scheme$proxy_host$request_uri</default> <context>http, server, location</context> <para> Директива задаёт ключ для кэширования, например, <example> proxy_cache_key "$host$request_uri $cookie_user"; </example> По умолчанию значение директивы близко к строке <example> proxy_cache_key $scheme$proxy_host$uri$is_args$args; </example> </para> </directive> <directive name="proxy_cache_path"> <syntax><value>путь [levels=уровни] keys_zone=название:размер [inactive=время] [max_size=размер]</value></syntax> <default/> <context>http</context> <para> Директива задаёт путь и другие параметры кэша. Данные кэша хранятся в файлах. Ключом и именем файла в кэше является результат функции md5 от проксированного URL. Параметр levels задаёт уровни иерархии кэша, например, при использовании <example> proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; </example> имена файлов в кэше будут такого вида: <example> /data/nginx/cache/<emphasis>c/29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis> </example> </para> <para> Кэшируемый ответ записывается во временный файл, а потом этот файл переименовывается. Начиная с версии 0.8.9, временные файлы и кэш могут располагаться на разных файловых системах, но нужно учитывать, что в этом случае вместо дешёвой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если кэш будет находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой <link id="proxy_temp_path"/> для данного location. </para> <para> Кроме того, все активные ключи и информация о данных хранятся в разделяемой памяти — зоне, имя и размер которой задаётся параметром keys_zone. Если к данным кэша не обращются в течение времени, заданного параметром inactive, то данные удаляются, независимо от их свежести. По умолчанию inactive равен 10 минутам. </para> <para> Специальный процесс "cache manager" следит за максимальным размером кэша, заданным параметром max_size, и при превышении его размеров удаляет самые невостребованные данные. </para> </directive> <directive name="proxy_cache_min_uses"> <syntax><value>число</value></syntax> <default>1</default> <context>http, server, location</context> <para> Директива задаёт число запросов, после которого ответ будет закэширован. </para> </directive> <directive name="proxy_cache_valid"> <syntax><value>ответ [ответ ...] время</value> </syntax> <default/> <context>http, server, location</context> <para> Директива задаёт время кэширования для разных ответов. Например, директивы <example> proxy_cache_valid 200 302 10m; proxy_cache_valid 404 1m; </example> задают время кэширования 10 минут для ответов 200 и 302, и 1 минуту для ответов 404. </para> <para> Если указано только время кэширования, <example> proxy_cache_valid 5m; </example> то кэшируются только ответы 200, 301 и 302. </para> <para> Кроме того, может кэшировать любые ответы с помощью параметра "any": <example> proxy_cache_valid 200 302 10m; proxy_cache_valid 301 1h; proxy_cache_valid any 1m; </example> </para> </directive> <directive name="proxy_cache_use_stale"> <syntax><value>[error | timeout | invalid_header | updating | http_500 | http_502 | http_503 | http_504 | http_404 | off] [...]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива определяет, в каких случаях можно использовать устаревший закэшированный ответ, если при работе с проксированным сервером возникла ошибка. Параметры директивы совпадают с параметрами директивы <link id="proxy_next_upstream"/>. И, кроме того, есть параметр updating, которой разрешает использовать устаревший закэшированный ответ, если на данный момент он уже обновляется. </para> </directive> <directive name="proxy_connect_timeout"> <syntax><value>время</value></syntax> <default>60</default> <context>http, server, location</context> <para> Директива задаёт таймаут для соединения с проксированным сервером. Необходимо иметь в виду, что этот таймаут не может быть больше 75 секунд. </para> </directive> <directive name="proxy_hide_header"> <syntax><value>имя</value></syntax> <default/> <context>http, server, location</context> <para> nginx не передаёт клиенту строки заголовка "Date", "Server", "X-Pad" и "X-Accel-..." из ответа проксированного сервера. Директива proxy_hide_header задаёт дополнительные строки. Если же строки нужно наоброт разрешить, то нужно воспользоваться директивой <link id="proxy_pass_header"/>. </para> </directive> <directive name="proxy_ignore_client_abort"> <syntax><value>[on|off]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива определяет, закрывать ли соединение с проксированным сервером в случае, если клиент закрыл соединение, не дождавшись ответа. </para> </directive> <directive name="proxy_ignore_headers"> <syntax><value>имя [имя ...]</value></syntax> <default/> <context>http, server, location</context> <para> Директива proxy_ignore_headers запрещает обработку некоторых строк заголовка из ответа проксированного сервера. В директиве можно указать строки "X-Accel-Redirect", "X-Accel-Expires", "X-Accel-Limit-Rate" (1.1.6), "X-Accel-Buffering" (1.1.6), "X-Accel-Charset" (1.1.6), "Expires", "Cache-Control" и "Set-Cookie" (0.8.44). </para> </directive> <directive name="proxy_intercept_errors"> <syntax><value>[on|off]</value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива определяет, передавать ли клиенту проксированные ответы с кодом больше или равные 400 или же перенаправлять их на обработку nginx'у с помощью директивы error_page. </para> </directive> <directive name="proxy_next_upstream"> <syntax><value>[error | timeout | invalid_header | http_500 | http_502 | http_503 | http_504 | http_404 | off] [...]</value></syntax> <default>error timeout</default> <context>http, server, location</context> <para> Директива определяет, в каких случаях запрос будет передан следующему серверу: <list type="bullet"> <listitem> error — произшла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; </listitem> <listitem> timeout — произошёл таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера; </listitem> <listitem> invalid_header — сервер вернул пустой или неверный ответ; </listitem> <listitem> http_500 — сервер вернул ответ с кодом 500; </listitem> <listitem> http_502 — сервер вернул ответ с кодом 502; </listitem> <listitem> http_503 — сервер вернул ответ с кодом 503; </listitem> <listitem> http_504 — сервер вернул ответ с кодом 504; </listitem> <listitem> http_404 — сервер вернул ответ с кодом 404; </listitem> <listitem> off — запрещает передачу запроса следующему серверу; </listitem> </list> </para> <para> Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту ещё ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа, то исправить это уже невозможно. </para> </directive> <directive name="proxy_no_cache"> <syntax><value>строка [...]</value></syntax> <default/> <context>http, server, location</context> <para> Директива задаёт условия, при которых ответ не будет сохраняться в кэш. Если значение хотя бы одной из строк переменных не пустое и не равно "0", то ответ не будет сохранён: <example> proxy_no_cache $cookie_nocache $arg_nocache$arg_comment; proxy_no_cache $http_pragma $http_authorization; </example> Можно использовать совместно с директивой <link id="proxy_cache_bypass"/>. </para> </directive> <directive name="proxy_pass"> <syntax><value>URL</value></syntax> <default/> <context>location, if в location, limit_except</context> <para> Директива задаёт адрес проксируемоего сервера и URI, на который будет отображаться location. Адрес может быть указан в виде доменного имени или адреса и порта, например, <example> proxy_pass http://localhost:8000/uri/; </example> или в виде пути unix сокета: <example> proxy_pass http://unix:/tmp/backend.socket:/uri/; </example> путь указан после слова unix и заключён между двумя двоеточиями. </para> <para> Если доменное имя резолвится в несколько адресов, то все они будут использоваться в режиме round-robin. И кроме того, адрес можно задать <link doc="ngx_http_upstream_module.xml">группой серверов</link>. </para> <para> При передаче запроса серверу часть URI, соответствующая location, заменяется на URI, указанный в директиве proxy_pass. Но из этого правила есть два исключения, в которых нельзя определить заменяемый location: <list type="bullet"> <listitem> если location задан регулярным выражением; </listitem> <listitem> если внутри проксируемого location с помощью директивы rewrite изменяется URI и именно с этой конфигурацией будет обрабатываться запрос (break): <example> location /name/ { rewrite /name/([^/]+) /users?name=$1 break; proxy_pass http://127.0.0.1; } </example> Для этих случаев URI передаётся без отображения. </listitem> </list> </para> <para> Кроме того, можно указать, чтобы URI запроса передавалось в том же виде, как его прислал клиент, а не в в обработанном виде. Во время обработки <list type="bullet"> <listitem> два и более слэшей преобразуются в один слэш: "//" — "/"; </listitem> <listitem> убираются ссылки на текущий каталог: "/./" — "/"; </listitem> <listitem> убираются ссылки на предыдущий каталог: "/dir/../" — "/". </listitem> </list> </para> <para> Если на сервер нужно передать URI в необработанном виде, то для этого в директиве proxy_pass нужно указать URL сервера без URI: <example> location /some/path/ { proxy_pass http://127.0.0.1; } </example> </para> <para> Имя сервера, его порт и передаваемый URI можно также полностью задать в помощью переменных: <example> proxy_pass http://$host$uri; </example> или так: <example> proxy_pass $request; </example> </para> <para> В этом случае имя сервера ищется среди описанных <link doc="ngx_http_upstream_module.xml">групп серверов</link> и если не найдено, то определяется с помощью <link doc="ngx_http_core_module.xml" id="resolver">resolver'а</link>. </para> </directive> <directive name="proxy_pass_header"> <syntax><value>имя</value></syntax> <default/> <context>http, server, location</context> <para> Директива разрешает передавать от проксируемого сервера клиенту запрещённые для передачи строки. </para> </directive> <directive name="proxy_redirect"> <syntax><value>[default|off|редирект замена]</value> </syntax> <default>default</default> <context>http, server, location</context> <para> Директива задаёт текст, который нужно изменить в строках заголовка "Location" и "Refresh" в ответе проксируемого сервера. Предположим, проксируемый сервер вернул строку "Location: http://localhost:8000/two/some/uri/". Директива <example> proxy_redirect http://localhost:8000/two/ http://frontend/one/; </example> перепишет эту строку в виде "Location: http://frontend/one/some/uri/". </para> <para> В заменяемой строке можно не указывать имя сервера: <example> proxy_redirect http://localhost:8000/two/ /; </example> тогда будет поставлено основное имя сервера и порт, если он отличен от 80. </para> <para> Изменение по умолчанию, задаваемое параметром "default", использует параметры директив location и proxy_pass. Поэтому две нижеприведённые конфигурации одинаковы: <example> location /one/ { proxy_pass http://upstream:port/two/; proxy_redirect default; </example> <example> location /one/ { proxy_pass http://upstream:port/two/; proxy_redirect http://upstream:port/two/ /one/; </example> </para> <para> В заменяемой строке можно использовать переменные: <example> proxy_redirect http://localhost:8000/ http://$host:$server_port/; </example> </para> <para> Директив может быть несколько: <example> proxy_redirect default; proxy_redirect http://localhost:8000/ /; proxy_redirect http://www.example.com/ /; </example> </para> <para> Параметр "off" запрещает все директивы proxy_redirect на данном уровне: <example> proxy_redirect off; proxy_redirect default; proxy_redirect http://localhost:8000/ /; proxy_redirect http://www.example.com/ /; </example> </para> <para> С помощью этой директивы можно также добавлять имя хоста к относительным редиректам, выдаваемым проксируемым сервером: <example> proxy_redirect / /; </example> </para> </directive> <directive name="proxy_read_timeout"> <syntax><value>время</value></syntax> <default>60</default> <context>http, server, location</context> <para> Директива задаёт таймаут при чтении ответа проксированного сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени проксируемый сервер ничего не передаст, то nginx закрывает соединение. </para> </directive> <directive name="proxy_send_timeout"> <syntax><value>время</value></syntax> <default>60</default> <context>http, server, location</context> <para> Директива задаёт таймаут при передаче запроса проксированному серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени проксируемый сервер не примет новых данных, то nginx закрывает соединение. </para> </directive> <directive name="proxy_set_header"> <syntax><value>заголовок значение</value></syntax> <default>Host $proxy_host</default> <default>Connection close</default> <context>http, server, location</context> <para> Директива позволяет переопределять или добавлять строки заголовка запроса, передаваемые проксируемому серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня при условии, что на данном уровне не описаны свои директивы proxy_set_header. По умолчанию переопределяются только две строки: <example> proxy_set_header Host $proxy_host; proxy_set_header Connection close; </example> </para> <para> Неизменённую строку заголовка запроса "Host" можно передать так: <example> proxy_set_header Host $http_host; </example> </para> <para> Однако, если эта строка отсутствует в запросе клиента, то ничего передаваться не будет. В этом случае лучше воспользоваться переменной $host, её значение равно имени сервера в строке заголовка запроса "Host" или же основному имени сервера, если строки нет: <example> proxy_set_header Host $host; </example> </para> <para> Кроме того, можно передать имя сервера вместе с портом проксируемого сервера: <example> proxy_set_header Host $host:$proxy_port; </example> </para> <para> Если значение строки заголовка — пустая строка, то строка вообще не будет передаваться проксируемому серверу: <example> proxy_set_header Accept-Encoding ""; </example> </para> </directive> <directive name="proxy_ssl_session_reuse"> <syntax><value>[on|off]</value></syntax> <default>on</default> <context>http, server, location</context> <para> Директива определяет, использовать ли повторно SSL-сессии при работе с проксированным сервером. Если в логах появляются ошибки "SSL3_GET_FINISHED:digest check failed", то можно попробовать выключить повторное использование сессий. </para> </directive> <directive name="proxy_store"> <syntax><value>on | off | строка </value></syntax> <default>off</default> <context>http, server, location</context> <para> Директива разрешает сохранение на диск файлов. Параметр "on" сохраняет файлы в соответствии с путями, указаными в директивах <link doc="ngx_http_core_module.xml" id="alias"/> или <link doc="ngx_http_core_module.xml" id="root"/>. Параметр "off" запрещает сохранение файлов. Кроме того, имя файла можно явно задать с помощью строки с переменными: <example> proxy_store /data/www$original_uri; </example> </para> <para> Время модификации файлов выставляется согласно полученной строке "Last-Modified" в заголовке ответа. Ответ записывается во временный файл, а потом этот файл переименовывается. Начиная с версии 0.8.9, временный файл и постоянное место хранения ответа могут располагаться на разных файловых системах, но нужно учитывать, что в этом случае вместо дешёвой операции переименовывания в пределах одной файловой системы файл копируется с одной файловой системы на другую. Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой системе, что и каталог с временными файлами, задаваемый директивой <link id="proxy_temp_path"/> для данного location. </para> <para> Директиву можно использовать для создания локальных копий статических неизменяемых файлов, например, так: <example> location /images/ { root /data/www; open_file_cache_errors off; error_page 404 = /fetch$uri; } location /fetch/ { internal; proxy_pass http://backend/; proxy_store on; proxy_store_access user:rw group:rw all:r; proxy_temp_path /data/temp; alias /data/www/; } </example> </para> <para> или так: <example> location /images/ { root /data/www; error_page 404 = @fetch; } location @fetch { internal; proxy_pass http://backend; proxy_store on; proxy_store_access user:rw group:rw all:r; proxy_temp_path /data/temp; root /data/www; } </example> </para> </directive> <directive name="proxy_store_access"> <syntax><value>пользователи:права [пользователи:права] ...</value></syntax> <default>user:rw</default> <context>http, server, location</context> <para> Директива задаёт права доступа для создаваемых файлов и каталогов, например, <example> proxy_store_access user:rw group:rw all:r; </example> </para> <para> Если заданы какие-либо права для groups или all, то права для user указывать необязательно: <example> proxy_store_access group:rw all:r; </example> </para> </directive> <directive name="proxy_temp_path"> <syntax><value>путь [ уровень1 [ уровень2 [ уровень3 ] ] ] </value></syntax> <default>proxy_temp</default> <context>http, server, location</context> <para> Директива задаёт имя каталога для хранения временных файлов полученных от другого сервера. В каталоге может использоваться иерархия подкаталогов до трёх уровней. Например, при такой конфигурации <example> proxy_temp_path /spool/nginx/proxy_temp 1 2; </example> имя временного будет такого вида: <example> /spool/nginx/proxy_temp/7/45/00000123457 </example> </para> </directive> </section> <section name="Встроенные переменные" id="variables"> <para> В модуле ngx_http_proxy_module есть встроенные переменные, которые можно использовать для формирования заголовков с помощью директивы <link id="proxy_set_header"/>: <list type="bullet"> <listitem> $proxy_host, эта переменная равна имени проксируемого хоста и порта; </listitem> <listitem> $proxy_port, эта переменная равна порту проксируемого хоста; </listitem> <listitem> $proxy_add_x_forwarded_for, эта переменная равна строке заголовка запроса клиента "X-Forwarded-For" и добавленной к ней через запятую переменной $remote_addr. Если же строки "X-Forwarded-For" в запросе клиента нет, то переменная $proxy_add_x_forwarded_for равна переменной $remote_addr. </listitem> </list> </para> </section> </module>