Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_upstream_module.xml @ 1259:954dcc02cb63

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Upstream: "session learn" sticky method and upstream_conf changes.
author Ruslan Ermilov <ru@nginx.com>
date Thu, 17 Jul 2014 18:39:52 +0400
parents 831215432a4f
children 5e45198fa991
comparison
equal deleted inserted replaced
1258:700487454cf2 1259:954dcc02cb63
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9 9
10 <module name="Модуль ngx_http_upstream_module" 10 <module name="Модуль ngx_http_upstream_module"
11 link="/ru/docs/http/ngx_http_upstream_module.html" 11 link="/ru/docs/http/ngx_http_upstream_module.html"
12 lang="ru" 12 lang="ru"
13 rev="6"> 13 rev="28">
14 14
15 <section id="summary"> 15 <section id="summary">
16 16
17 <para> 17 <para>
18 Модуль <literal>ngx_http_upstream_module</literal> 18 Модуль <literal>ngx_http_upstream_module</literal>
52 <para> 52 <para>
53 Динамически настраиваемая группа, 53 Динамически настраиваемая группа,
54 доступна как часть 54 доступна как часть
55 <commercial_version>коммерческой подписки</commercial_version>: 55 <commercial_version>коммерческой подписки</commercial_version>:
56 <example> 56 <example>
57 upstream <emphasis>appservers</emphasis> { 57 upstream <emphasis>dynamic</emphasis> {
58 zone appservers 64k; 58 zone upstream_dynamic 64k;
59 59
60 server appserv1.example.com weight=5; 60 server backend1.example.com weight=5;
61 server appserv2.example.com:8080 fail_timeout=5s slow_start=30s; 61 server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
62 server 192.0.2.1 max_fails=3; 62 server 192.0.2.1 max_fails=3;
63 63
64 server reserve1.example.com:8080 backup; 64 server backup1.example.com:8080 backup;
65 server reserve2.example.com:8080 backup; 65 server backup2.example.com:8080 backup;
66 } 66 }
67 67
68 server { 68 server {
69 location / { 69 location / {
70 proxy_pass http://<emphasis>appservers</emphasis>; 70 proxy_pass http://<emphasis>dynamic</emphasis>;
71 health_check; 71 health_check;
72 } 72 }
73 73
74 location /upstream_conf { 74 location /upstream_conf {
75 upstream_conf; 75 upstream_conf;
830 830
831 </directive> 831 </directive>
832 832
833 833
834 <directive name="sticky"> 834 <directive name="sticky">
835 <syntax><literal>cookie</literal> <value>имя</value> 835 <syntax>
836 [<literal>expires=</literal><value>время</value>] 836 <literal>cookie</literal> <value>имя</value>
837 [<literal>domain=</literal><value>домен</value>] 837 [<literal>expires=</literal><value>время</value>]
838 [<literal>path=</literal><value>путь</value>]</syntax> 838 [<literal>domain=</literal><value>домен</value>]
839 <syntax><literal>route</literal> <value>переменная</value> ...</syntax> 839 [<literal>path=</literal><value>путь</value>]</syntax>
840 <syntax>
841 <literal>route</literal> <value>переменная</value> ...</syntax>
842 <syntax>
843 <literal>learn</literal>
844 <literal>create=</literal><value>$переменная</value>
845 <literal>lookup=</literal><value>$переменная</value>
846 <literal>zone=</literal><value>имя</value>:<value>размер</value>
847 [<literal>timeout=</literal><value>время</value>]</syntax>
840 <default/> 848 <default/>
841 <context>upstream</context> 849 <context>upstream</context>
842 <appeared-in>1.5.7</appeared-in> 850 <appeared-in>1.5.7</appeared-in>
843 851
844 <para> 852 <para>
845 Включает режим привязки сеансов, в котором запросы клиента 853 Включает режим привязки сеансов, в котором запросы клиента
846 будут передаваться на один и тот же сервер группы. 854 будут передаваться на один и тот же сервер группы.
847 Доступны два метода: 855 Доступны три метода:
848 <literal>cookie</literal> и <literal>route</literal>. 856 <list type="tag">
849 </para> 857 <tag-name id="sticky_cookie"><literal>cookie</literal></tag-name>
858 <tag-desc>
850 859
851 <para> 860 <para>
852 При использовании метода <literal>cookie</literal> информация о 861 При использовании метода <literal>cookie</literal> информация о
853 назначенном сервере передаётся в HTTP-куке: 862 назначенном сервере передаётся в HTTP-куке:
854 <example> 863 <example>
893 </tag-desc> 902 </tag-desc>
894 903
895 </list> 904 </list>
896 Если пропущен тот или иной параметр, то соответствующего поля в куке не будет. 905 Если пропущен тот или иной параметр, то соответствующего поля в куке не будет.
897 </para> 906 </para>
907 </tag-desc>
908
909 <tag-name id="sticky_route"><literal>route</literal></tag-name>
910 <tag-desc>
898 911
899 <para> 912 <para>
900 При использовании метода <literal>route</literal> проксируемый сервер назначает 913 При использовании метода <literal>route</literal> проксируемый сервер назначает
901 клиенту маршрут по получении первого запроса. 914 клиенту маршрут по получении первого запроса.
902 Все последующие запросы от этого клиента будут содержать информацию о 915 Все последующие запросы от этого клиента будут содержать информацию о
936 В этом примере маршрут берётся из куки “<literal>JSESSIONID</literal>”, 949 В этом примере маршрут берётся из куки “<literal>JSESSIONID</literal>”,
937 если она присутствует в запросе. 950 если она присутствует в запросе.
938 В противном случае используется маршрут из URI. 951 В противном случае используется маршрут из URI.
939 </para> 952 </para>
940 953
954 </tag-desc>
955
956 <tag-name id="sticky_learn"><literal>learn</literal></tag-name>
957 <tag-desc>
958 <para>
959 При использовании метода <literal>learn</literal> (1.7.1) nginx
960 анализирует ответы от вышестоящего сервера и запоминает
961 начатые им сессии, которые обычно передаются в HTTP-куке.
962 <example>
963 upstream backend {
964 server backend1.example.com:8080;
965 server backend2.example.com:8081;
966
967 sticky learn
968 create=$upstream_cookie_sessionid
969 lookup=$cookie_sessionid
970 zone=client_sessions:1m;
971 }
972 </example>
973
974 В примере выше сервер группы создаёт сессию путём установки
975 куки “<literal>SESSIONID</literal>” в своём ответе.
976 Последующие запросы с этой кукой будут передаваться на этот же сервер.
977 Если сервер не может обработать запрос, выбирается новый
978 сервер как если бы клиент не имел привязки к серверу.
979 </para>
980
981 <para>
982 Параметры <literal>create</literal> и <literal>lookup</literal>
983 задают переменные, в которых соответственно указывается способ
984 создания новых и поиска существующих сессий.
985 Оба параметра могут быть указаны больше одного раза
986 (в этом случае используется первая непустая переменная).
987 </para>
988
989 <para>
990 Сессии хранятся в зоне разделяемой памяти, <value>имя</value> и
991 <value>размер</value> которой задаются параметром <literal>zone</literal>.
992 Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч сессий
993 на 64-битной платформе.
994 Сессии, к которым не было обращений в течение времени, заданного параметром
995 <literal>timeout</literal>, удаляются из зоны.
996 По умолчанию <literal>timeout</literal> равен 10 минутам.
997 </para>
998
999 </tag-desc>
1000 </list>
1001 </para>
1002
941 <para> 1003 <para>
942 <note> 1004 <note>
943 Эта директива доступна как часть 1005 Эта директива доступна как часть
944 <commercial_version>коммерческой подписки</commercial_version>. 1006 <commercial_version>коммерческой подписки</commercial_version>.
945 </note> 1007 </note>
963 <note> 1025 <note>
964 <literal>sticky cookie</literal> <value>имя</value> 1026 <literal>sticky cookie</literal> <value>имя</value>
965 [<literal>expires=</literal><value>время</value>] 1027 [<literal>expires=</literal><value>время</value>]
966 [<literal>domain=</literal><value>домен</value>] 1028 [<literal>domain=</literal><value>домен</value>]
967 [<literal>path=</literal><value>путь</value>]; 1029 [<literal>path=</literal><value>путь</value>];
1030 </note>
1031 </para>
1032
1033 </directive>
1034
1035
1036 <directive name="upstream_conf">
1037 <syntax/>
1038 <default/>
1039 <context>location</context>
1040
1041 <para>
1042 Активирует HTTP-интерфейс для настройки групп серверов в содержащем location.
1043 Доступ в location следует
1044 <link doc="ngx_http_core_module.xml" id="satisfy">ограничить</link>.
1045 </para>
1046
1047 <para>
1048 С помощью команд настройки можно:
1049 <list type="bullet">
1050
1051 <listitem>просматривать конфигурацию группы;</listitem>
1052
1053 <listitem>
1054 просматривать или изменять конфигурацию, а также
1055 удалять отдельные серверы;
1056 </listitem>
1057
1058 <listitem>добавлять новые серверы.</listitem>
1059
1060 </list>
1061 <note>
1062 Поскольку адреса в группе не обязаны быть уникальными,
1063 обращение к отдельным серверам в группе осуществляется по их идентификаторам.
1064 Идентификаторы назначаются автоматически и показываются при добавлении сервера
1065 или просмотре конфигурации группы.
1066 </note>
1067 </para>
1068
1069 <para>
1070 Команда настройки состоит из параметров, передаваемых в аргументах запроса,
1071 например:
1072 <example>
1073 http://127.0.0.1/upstream_conf?upstream=dynamic
1074 </example>
1075 </para>
1076
1077 <para>
1078 Поддерживаются следующие параметры:
1079
1080 <list type="tag" compact="no">
1081
1082 <tag-name>
1083 <literal>upstream=</literal><value>имя</value></tag-name>
1084 <tag-desc>
1085 Выбирает группу серверов для работы.
1086 Параметр является обязательным.
1087 </tag-desc>
1088
1089 <tag-name>
1090 <literal>id=</literal><value>число</value></tag-name>
1091 <tag-desc>
1092 Выбирает отдельный сервер для просмотра, изменения или удаления.
1093 </tag-desc>
1094
1095 <tag-name>
1096 <literal>remove=</literal></tag-name>
1097 <tag-desc>
1098 Удаляет выбранный сервер из группы.
1099 </tag-desc>
1100
1101 <tag-name>
1102 <literal>add=</literal></tag-name>
1103 <tag-desc>
1104 Добавляет новый сервер в группу.
1105 </tag-desc>
1106
1107 <tag-name>
1108 <literal>backup=</literal></tag-name>
1109 <tag-desc>
1110 Необходим для добавления запасного сервера.
1111 <note>
1112 До версии 1.7.2 параметр <literal>backup=</literal> требовался
1113 также для просмотра, изменения или удаления существующих запасных серверов.
1114 </note>
1115 </tag-desc>
1116
1117 <tag-name>
1118 <literal>server=</literal><value>адрес</value></tag-name>
1119 <tag-desc>
1120 То же, что и параметр “<literal>адрес</literal>”
1121 директивы <link id="server"/>.
1122 <para>
1123 При добавлении сервер можно задать в виде доменного имени.
1124 В этом случае любые изменения IP-адресов, соответствующих доменному имени
1125 сервера, отслеживаются и автоматически применяются к конфигурации группы
1126 без необходимости перезапуска nginx (1.7.2).
1127 Для этого в блоке <link doc="ngx_http_core_module.xml" id="http"/> должна
1128 быть задана директива <link doc="ngx_http_core_module.xml" id="resolver"/>.
1129 См. также параметр
1130 <link id="resolve"/> директивы <link id="server"/>.
1131 </para>
1132 </tag-desc>
1133
1134 <tag-name>
1135 <literal>weight=</literal><value>число</value></tag-name>
1136 <tag-desc>
1137 То же, что и параметр “<literal>weight</literal>”
1138 директивы <link id="server"/>.
1139 </tag-desc>
1140
1141 <tag-name>
1142 <literal>max_fails=</literal><value>число</value></tag-name>
1143 <tag-desc>
1144 То же, что и параметр “<literal>max_fails</literal>”
1145 директивы <link id="server"/>.
1146 </tag-desc>
1147
1148 <tag-name>
1149 <literal>fail_timeout=</literal><value>время</value></tag-name>
1150 <tag-desc>
1151 То же, что и параметр “<literal>fail_timeout</literal>”
1152 директивы <link id="server"/>.
1153 </tag-desc>
1154
1155 <tag-name>
1156 <literal>slow_start=</literal><value>время</value></tag-name>
1157 <tag-desc>
1158 То же, что и параметр “<literal>slow_start</literal>”
1159 директивы <link id="server"/>.
1160 </tag-desc>
1161
1162 <tag-name>
1163 <literal>down=</literal></tag-name>
1164 <tag-desc>
1165 То же, что и параметр “<literal>down</literal>”
1166 директивы <link id="server"/>.
1167 </tag-desc>
1168
1169 <tag-name>
1170 <literal>up=</literal></tag-name>
1171 <tag-desc>
1172 Параметр, обратный по значению параметру “<literal>down</literal>”
1173 директивы <link id="server"/>.
1174 </tag-desc>
1175
1176 <tag-name>
1177 <literal>route=</literal><value>строка</value></tag-name>
1178 <tag-desc>
1179 То же, что и параметр “<literal>route</literal>”
1180 директивы <link id="server"/>.
1181 </tag-desc>
1182
1183 </list>
1184
1185 Первые два параметра выбирают объект.
1186 Объектом может быть либо группа серверов, либо отдельный сервер.
1187 Если остальные параметры не указаны, то показывается конфигурация выбранной
1188 группы или сервера.
1189 </para>
1190
1191 <para>
1192 Например, команда для просмотра конфигурации всей группы
1193 выглядит следующим образом:
1194 <example>
1195 http://127.0.0.1/upstream_conf?upstream=dynamic
1196 </example>
1197
1198 Для просмотра конфигурации отдельного сервера следует указать его идентификатор:
1199 <example>
1200 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42
1201 </example>
1202
1203 </para>
1204
1205 <para>
1206 Для добавления нового сервера в группу
1207 следует указать его адрес в параметре “<literal>server=</literal>”.
1208 Если остальные параметры не указаны, то при добавлении сервера
1209 их значения будут установлены по умолчанию (см. директиву <link id="server"/>).
1210 </para>
1211
1212 <para>
1213 Например, команда для добавления нового основного сервера в группу
1214 выглядит следующим образом:
1215 <example>
1216 http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;server=127.0.0.1:8080
1217 </example>
1218
1219 Добавление нового запасного сервера происходит следующим образом:
1220 <example>
1221 http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;backup=&amp;server=127.0.0.1:8080
1222 </example>
1223
1224 Добавление нового основного сервера с нестандартными
1225 значениями параметров и с пометкой его как постоянно недоступного
1226 (“<literal>down</literal>”) происходит следующим образом:
1227 <example>
1228 http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;server=127.0.0.1:8080&amp;weight=2&amp;down=
1229 </example>
1230 </para>
1231
1232 <para>
1233 Для удаления сервера следует указать его идентификатор:
1234 <example>
1235 http://127.0.0.1/upstream_conf?remove=&amp;upstream=dynamic&amp;id=42
1236 </example>
1237 </para>
1238
1239 <para>
1240 Пометка существующего сервера как постоянно недоступного
1241 (“<literal>down</literal>”) происходит следующим образом:
1242 <example>
1243 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;down=
1244 </example>
1245
1246 Изменение адреса существующего сервера происходит следующим образом:
1247 <example>
1248 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;server=192.0.2.3:8123
1249 </example>
1250
1251 Изменение других параметров существующего сервера происходит следующим образом:
1252 <example>
1253 http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;max_fails=3&amp;weight=4
1254 </example>
1255
1256 </para>
1257
1258 <para>
1259 <note>
1260 Эта директива доступна как часть
1261 <commercial_version>коммерческой подписки</commercial_version>.
968 </note> 1262 </note>
969 </para> 1263 </para>
970 1264
971 </directive> 1265 </directive>
972 1266