Перейти к содержанию

memc: Расширенная версия стандартного модуля memcached для NGINX

Установка на Debian/Ubuntu

Эти документы применимы к пакету APT nginx-module-memc, предоставляемому репозиторием GetPageSpeed Extras.

  1. Настройте APT репозиторий, как описано в настройке APT репозитория.
  2. Установите модуль:
sudo apt-get update
sudo apt-get install nginx-module-memc
Показать дистрибутивы и архитектуры 
| Дистрибутив | Версия            | Компонент  | Архитектуры   |
|-------------|-------------------|------------|----------------|
| debian      | bookworm          | main       | amd64, arm64   |
| debian      | bookworm-mainline | main       | amd64, arm64   |
| debian      | trixie            | main       | amd64, arm64   |
| debian      | trixie-mainline   | main       | amd64, arm64   |
| ubuntu      | focal             | main       | amd64, arm64   |
| ubuntu      | focal-mainline    | main       | amd64, arm64   |
| ubuntu      | jammy             | main       | amd64, arm64   |
| ubuntu      | jammy-mainline    | main       | amd64, arm64   |
| ubuntu      | noble             | main       | amd64, arm64   |
| ubuntu      | noble-mainline    | main       | amd64, arm64   |

ngx_memc - Расширенная версия стандартного модуля memcached, которая поддерживает команды set, add, delete и многие другие команды memcached.

Синопсис

 # GET /foo?key=dog
 #
 # POST /foo?key=cat
 # Значение кота...
 #
 # PUT /foo?key=bird
 # Значение птицы...
 #
 # DELETE /foo?key=Tiger
 location /foo {
     set $memc_key $arg_key;

     # $memc_cmd по умолчанию равен get для GET,
     #   add для POST, set для PUT и
     #   delete для метода запроса DELETE.

     memc_pass 127.0.0.1:11211;
 }

 # GET /bar?cmd=get&key=cat
 #
 # POST /bar?cmd=set&key=dog
 # Моё значение для ключа "dog"...
 #
 # DELETE /bar?cmd=delete&key=dog
 # GET /bar?cmd=delete&key=dog
 location /bar {
     set $memc_cmd $arg_cmd;
     set $memc_key $arg_key;
     set $memc_flags $arg_flags; # по умолчанию 0
     set $memc_exptime $arg_exptime; # по умолчанию 0

     memc_pass 127.0.0.1:11211;
 }

 # GET /bar?cmd=get&key=cat
 # GET /bar?cmd=set&key=dog&val=animal&flags=1234&exptime=2
 # GET /bar?cmd=delete&key=dog
 # GET /bar?cmd=flush_all
 location /bar {
     set $memc_cmd $arg_cmd;
     set $memc_key $arg_key;
     set $memc_value $arg_val;
     set $memc_flags $arg_flags; # по умолчанию 0
     set $memc_exptime $arg_exptime; # по умолчанию 0

     memc_cmds_allowed get set add delete flush_all;

     memc_pass 127.0.0.1:11211;
 }

   http {
     ...
     upstream backend {
        server 127.0.0.1:11984;
        server 127.0.0.1:11985;
     }
     server {
         location /stats {
             set $memc_cmd stats;
             memc_pass backend;
         }
         ...
     }
   }
   ...

 # считать флаги memcached в заголовок Last-Modified
 # чтобы ответить 304 на условный GET
 location /memc {
     set $memc_key $arg_key;

     memc_pass 127.0.0.1:11984;

     memc_flags_to_last_modified on;
 }

 location /memc {
     set $memc_key foo;
     set $memc_cmd get;

     # доступ к unix-сокету, к которому подключается memcached
     memc_pass unix:/tmp/memcached.sock;
 }

Описание

Этот модуль расширяет стандартный модуль memcached, чтобы поддерживать почти весь асси-протокол memcached.

Он позволяет вам определить пользовательский REST интерфейс для ваших серверов memcached или получить доступ к memcached очень эффективно изнутри сервера nginx с помощью подзапросов или независимых фейковых запросов.

Этот модуль не предполагается объединить с основным Nginx, потому что я использовал Ragel, чтобы сгенерировать парсеры ответов memcached (на C) для радости :)

Если вы собираетесь использовать этот модуль для кеширования ответов по умолчанию, попробуйте модуль srcache-nginx-module с этим модулем, чтобы добиться этого.

При использовании совместно с lua-nginx-module рекомендуется использовать библиотеку lua-resty-memcached вместо этого модуля, потому что первая гораздо более гибкая и эффективная по памяти.

Соединения keep-alive с серверами memcached

Вам нужен HttpUpstreamKeepaliveModule вместе с этим модулем для поддержания TCP-соединений keep-alive с вашими задними серверами memcached.

Вот пример конфигурации:

   http {
     upstream backend {
       server 127.0.0.1:11211;

       # пул с максимум 1024 соединениями
       # и не различает сервера:
       keepalive 1024;
     }

     server {
         ...
         location /memc {
             set $memc_cmd get;
             set $memc_key $arg_key;
             memc_pass backend;
         }
     }
   }

Как это работает

Он реализует протокол TCP для memcached полностью самостоятельно, основываясь на механизме upstream. Все операции ввода-вывода являются неблокирующими.

Сам модуль не поддерживает TCP-соединения с серверами memcached на верхнем уровне между запросами, как и другие модули upstream. Для рабочей версии см. раздел Соединения keep-alive с серверами memcached.

Поддерживаемые команды Memcached

Хранения команд memcached set, add, replace, prepend и append используют $memc_key как ключ, $memc_exptime как время истечения (или задержки) (по умолчанию 0), $memc_flags как флаги (по умолчанию 0), чтобы построить соответствующие запросы memcached.

Если $memc_value вообще не определено, то тело запроса будет использоваться как значение для $memc_value, за исключением команд incr и decr. Обратите внимание, что если $memc_value определено как пустая строка (""), то эта пустая строка все равно будет использоваться как значение.

Следующие команды memcached были реализованы и протестированы (с их параметрами, обозначенными соответствующими переменными nginx, определенными этим модулем):

get $memc_key

Извлекает значение с использованием ключа.

   location /foo {
       set $memc_cmd 'get';
       set $memc_key 'my_key';

       memc_pass 127.0.0.1:11211;

       add_header X-Memc-Flags $memc_flags;
   }

Возвращает 200 OK с помещенным в тело ответа значением, если ключ найден, или 404 Not Found в противном случае. Число flags будет записано в переменную $memc_flags, поэтому часто желательно добавить эту информацию в заголовки ответа с помощью стандартной директивы add_header.

Вернет 502 для ERROR, CLIENT_ERROR или SERVER_ERROR.

set $memc_key $memc_flags $memc_exptime $memc_value

Чтобы использовать тело запроса в качестве значения memcached, просто избегайте настройки переменной $memc_value:

   # POST /foo
   # моё значение...
   location /foo {
       set $memc_cmd 'set';
       set $memc_key 'my_key';
       set $memc_flags 12345;
       set $memc_exptime 24;

       memc_pass 127.0.0.1:11211;
   }

Или позвольте переменной $memc_value содержать значение:

   location /foo {
       set $memc_cmd 'set';
       set $memc_key 'my_key';
       set $memc_flags 12345;
       set $memc_exptime 24;
       set $memc_value 'my_value';

       memc_pass 127.0.0.1:11211;
   }

Возвращает 201 Created, если сервер memcached ответит STORED, 200 для NOT_STORED, 404 для NOT_FOUND, 502 для ERROR, CLIENT_ERROR или SERVER_ERROR.

Оригинальные ответы memcached возвращаются как тело ответа, за исключением 404 NOT FOUND.

add $memc_key $memc_flags $memc_exptime $memc_value

Похоже на команду set.

replace $memc_key $memc_flags $memc_exptime $memc_value

Похоже на команду set.

append $memc_key $memc_flags $memc_exptime $memc_value

Похоже на команду set.

Обратите внимание, что по состоянию на версию memcached 1.2.2 команды "append" и "prepend" не поддерживаются. По крайней мере версии 1.2.4 и более поздние версии, похоже, поддерживают эти две команды.

prepend $memc_key $memc_flags $memc_exptime $memc_value

Похоже на команду append.

delete $memc_key

Удаляет запись memcached с использованием ключа.

   location /foo {
       set $memc_cmd delete;
       set $memc_key my_key;

       memc_pass 127.0.0.1:11211;
   }

Возвращает 200 OK, если удаление прошло успешно, 404 Not Found для NOT_FOUND, или 502 для ERROR, CLIENT_ERROR или SERVER_ERROR.

Оригинальные ответы memcached возвращаются как тело ответа, за исключением 404 NOT FOUND.

delete $memc_key $memc_exptime

Похоже на команду delete $memc_key, за исключением того, что она принимает необязательное время expiration, заданное переменной $memc_exptime.

Эта команда больше недоступна в последней версии memcached 1.4.4.

incr $memc_key $memc_value

Увеличивает существующее значение $memc_key на количество, указанное в $memc_value:

   location /foo {
       set $memc_cmd incr;
       set $memc_key my_key;
       set $memc_value 2;
       memc_pass 127.0.0.1:11211;
   }

В приведенном выше примере каждый раз, когда мы обращаемся к /foo, значение my_key увеличивается на 2.

Возвращает 200 OK с новым значением, связанным с этим ключом, в теле ответа, если операция выполнена успешно, или 404 Not Found, если ключ не найден.

Вернет 502 для ERROR, CLIENT_ERROR или SERVER_ERROR.

decr $memc_key $memc_value

Похоже на incr $memc_key $memc_value.

flush_all

Обозначает все ключи на сервере memcached как истекшие:

   location /foo {
       set $memc_cmd flush_all;
       memc_pass 127.0.0.1:11211;
   }

flush_all $memc_exptime

Точно так же, как flush_all, но также принимает время истечения, заданное переменной $memc_exptime.

stats

Вызывает вывод общих статистических данных и настроек сервера memcached

   location /foo {
       set $memc_cmd stats;
       memc_pass 127.0.0.1:11211;
   }

Возвращает 200 OK, если запрос выполнен успешно, или 502 для ERROR, CLIENT_ERROR или SERVER_ERROR.

Сырой вывод команды stats от верхнего сервера memcached будет помещен в тело ответа.

Директивы

Все стандартные директивы модуля memcached в nginx 0.8.28 наследуются прямо, с заменой префикса memcached_ на memc_. Например, директива memcached_pass записывается как memc_pass.

Здесь мы документируем только две самые важные директивы (вторая - это новая директива, введенная этим модулем).

memc_pass

синтаксис: memc_pass <IP-адрес memcached-сервера>:<порт memcached-сервера>

синтаксис: memc_pass <имя хоста memcached-сервера>:<порт memcached-сервера>

синтаксис: memc_pass <имя_upstream_backend>

синтаксис: memc_pass unix:<путь_к_unix_домашнему_сокету>

по умолчанию: нет

контекст: http, server, location, if

фаза: контент

Укажите бэкенд сервера memcached.

memc_cmds_allowed

синтаксис: memc_cmds_allowed <cmd>...

по умолчанию: нет

контекст: http, server, location, if

Перечисляет команды memcached, которые разрешено использовать. По умолчанию доступны все команды memcached, поддерживаемые этим модулем. Пример:

    location /foo {
        set $memc_cmd $arg_cmd;
        set $memc_key $arg_key;
        set $memc_value $arg_val;

        memc_pass 127.0.0.1:11211;

        memc_cmds_allowed get;
    }

memc_flags_to_last_modified

синтаксис: memc_flags_to_last_modified on|off

по умолчанию: off

контекст: http, server, location, if

Читает флаги memcached как секундный временной формат и устанавливает его как значение заголовка Last-Modified. Для условного GET это будет сигнализировать nginx об ответе 304 Not Modified, чтобы сэкономить трафик.

memc_connect_timeout

синтаксис: memc_connect_timeout <время>

по умолчанию: 60s

контекст: http, server, location

Таймаут на соединение с сервером memcached, по умолчанию в секундах.

Разумно всегда явно указывать единицу времени, чтобы избежать путаницы. Поддерживаемые единицы времени: "s" (секунды), "ms" (миллисекунды), "y" (годы), "M" (месяцы), "w" (недели), "d" (дни), "h" (часы) и "m" (минуты).

Это время должно быть меньше 597 часов.

memc_send_timeout

синтаксис: memc_send_timeout <время>

по умолчанию: 60s

контекст: http, server, location

Таймаут на отправку TCP-запросов на сервер memcached, по умолчанию в секундах.

Разумно всегда явно указывать единицу времени, чтобы избежать путаницы. Поддерживаемые единицы времени: "s" (секунды), "ms" (миллисекунды), "y" (годы), "M" (месяцы), "w" (недели), "d" (дни), "h" (часы) и "m" (минуты).

Это время должно быть меньше 597 часов.

memc_read_timeout

синтаксис: memc_read_timeout <время>

по умолчанию: 60s

контекст: http, server, location

Таймаут на чтение TCP-ответов от сервера memcached, по умолчанию в секундах.

Разумно всегда явно указывать единицу времени, чтобы избежать путаницы. Поддерживаемые единицы времени: "s" (секунды), "ms" (миллисекунды), "y" (годы), "M" (месяцы), "w" (недели), "d" (дни), "h" (часы) и "m" (минуты).

Это время должно быть меньше 597 часов.

memc_buffer_size

синтаксис: memc_buffer_size <размер>

по умолчанию: 4k/8k

контекст: http, server, location

Этот размер буфера используется для памяти, чтобы удерживать

  • полный ответ для команд memcached, кроме get,
  • полный заголовок ответа (т.е. первая строка ответа) для команды get memcached.

Этот размер по умолчанию соответствует размеру страницы, может быть 4k или 8k.

memc_ignore_client_abort

синтаксис: memc_ignore_client_abort on|off

по умолчанию: off

контекст: location

Определяет, следует ли закрывать соединение с сервером memcached, когда клиент закрывает соединение, не дождавшись ответа.

Эта директива была впервые добавлена в выпуске v0.14.

Изменения

Изменения каждого релиза этого модуля можно получить из журналов изменений пакета OpenResty:

http://openresty.org/#Changes

Набор тестов

Этот модуль поставляется с набором тестов, управляемым Perl. Тестовые случаи также декларативны. Спасибо модулю Test::Base из мира Perl.

Чтобы запустить его на своей стороне:

 $ PATH=/path/to/your/nginx-with-memc-module:$PATH prove -r t

Вам нужно завершить все процессы Nginx, прежде чем запускать набор тестов, если вы изменили двоичный файл сервера Nginx.

Либо LWP::UserAgent, либо IO::Socket используется тестовым каркасом test scaffold.

Поскольку один сервер nginx (по умолчанию, localhost:1984) используется во всех тестовых скриптах (.t файлы), нет смысла запускать набор тестов параллельно, указывая -jN при вызове утилиты prove.

Вам также следует убедиться, что сервер memcached слушает на порту 11211 на localhost перед выполнением набора тестов.

Некоторые части набора тестов требуют, чтобы модули rewrite и echo также были включены при сборке Nginx.

См. также