Pular para conteúdo

memc: Versão estendida do módulo padrão memcached do NGINX

Instalação

Você pode instalar este módulo em qualquer distribuição baseada em RHEL, incluindo, mas não se limitando a:

  • RedHat Enterprise Linux 7, 8, 9 e 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 e Amazon Linux 2023
dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-memc

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-memc

Ative o módulo adicionando o seguinte no topo de /etc/nginx/nginx.conf:

load_module modules/ngx_http_memc_module.so;

Este documento descreve o nginx-module-memc v0.21 lançado em 07 de junho de 2026.

 # GET /foo?key=dog
 #
 # POST /foo?key=cat
 # Valor do gato...
 #
 # PUT /foo?key=bird
 # Valor do pássaro...
 #
 # DELETE /foo?key=Tiger
 location /foo {
     set $memc_key $arg_key;

     # $memc_cmd padrão é get para GET,
     #   add para POST, set para PUT, e
     #   delete para o método de requisição DELETE.

     memc_pass 127.0.0.1:11211;
 }

 # GET /bar?cmd=get&key=cat
 #
 # POST /bar?cmd=set&key=dog
 # Meu valor para a chave "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; # padrão é 0
     set $memc_exptime $arg_exptime; # padrão é 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; # padrão é 0
     set $memc_exptime $arg_exptime; # padrão é 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;
         }
         ...
     }
   }
   ...

 # lê os flags do memcached no cabeçalho Last-Modified
 # para responder 304 a GETs condicionais
 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;

     # acessa o socket de domínio unix escutado pelo memcached
     memc_pass unix:/tmp/memcached.sock;
 }

Descrição

Este módulo estende o módulo memcached padrão para suportar quase todo o protocolo ascii do memcached.

Ele permite que você defina uma interface REST personalizada para seus servidores memcached ou acesse o memcached de maneira muito eficiente a partir do servidor nginx por meio de subrequisições ou requisições falsas independentes.

Este módulo não deve ser mesclado ao núcleo do Nginx porque eu usei Ragel para gerar os analisadores de resposta do memcached (em C) para alegria :)

Se você vai usar este módulo para armazenar em cache respostas de localização prontas para uso, experimente o srcache-nginx-module com este módulo para alcançar isso.

Quando usado em conjunto com o lua-nginx-module, é recomendável usar a biblioteca lua-resty-memcached em vez deste módulo, pois a primeira é muito mais flexível e eficiente em termos de memória.

Conexões keep-alive com servidores memcached

Você precisa do HttpUpstreamKeepaliveModule junto com este módulo para conexões TCP keep-alive com seus servidores memcached de backend.

Aqui está uma configuração de exemplo:

   http {
     upstream backend {
       server 127.0.0.1:11211;

       # um pool com no máximo 1024 conexões
       # e não distingue os servidores:
       keepalive 1024;
     }

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

Como funciona

Ele implementa o protocolo TCP do memcached por conta própria, baseado no mecanismo upstream. Tudo que envolve I/O é não bloqueante.

O módulo em si não mantém conexões TCP com os servidores memcached upstream entre requisições, assim como outros módulos upstream. Para uma solução funcional, veja a seção Conexões keep-alive com servidores memcached.

Comandos do Memcached suportados

Os comandos de armazenamento do memcached set, add, replace, prepend, e append usam o $memc_key como a chave, $memc_exptime como o tempo de expiração (ou atraso) (padrão é 0), $memc_flags como os flags (padrão é 0), para construir as consultas correspondentes do memcached.

Se $memc_value não estiver definido, o corpo da requisição será usado como o valor de $memc_value, exceto para os comandos incr e decr. Note que se $memc_value for definido como uma string vazia (""), essa string vazia ainda será usada como o valor.

Os seguintes comandos do memcached foram implementados e testados (com seus parâmetros marcados pelas variáveis nginx correspondentes definidas por este módulo):

get $memc_key

Recupera o valor usando uma chave.

   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;
   }

Retorna 200 OK com o valor colocado no corpo da resposta se a chave for encontrada, ou 404 Not Found caso contrário. O número de flags será definido na variável $memc_flags, então é frequentemente desejável colocar essa informação nos cabeçalhos de resposta por meio da diretiva padrão add_header.

Retorna 502 para ERROR, CLIENT_ERROR ou SERVER_ERROR.

set $memc_key $memc_flags $memc_exptime $memc_value

Para usar o corpo da requisição como o valor do memcached, basta evitar definir a variável $memc_value:

   # POST /foo
   # meu valor...
   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;
   }

Ou deixe o $memc_value conter o valor:

   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;
   }

Retorna 201 Created se o servidor memcached upstream responder STORED, 200 para NOT_STORED, 404 para NOT_FOUND, 502 para ERROR, CLIENT_ERROR ou SERVER_ERROR.

As respostas originais do memcached são retornadas como o corpo da resposta, exceto para 404 NOT FOUND.

add $memc_key $memc_flags $memc_exptime $memc_value

Semelhante ao comando set.

replace $memc_key $memc_flags $memc_exptime $memc_value

Semelhante ao comando set.

append $memc_key $memc_flags $memc_exptime $memc_value

Semelhante ao comando set.

Note que pelo menos a versão 1.2.2 do memcached não suporta os comandos "append" e "prepend". Pelo menos as versões 1.2.4 e posteriores parecem suportar esses dois comandos.

prepend $memc_key $memc_flags $memc_exptime $memc_value

Semelhante ao comando append.

delete $memc_key

Exclui a entrada do memcached usando uma chave.

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

       memc_pass 127.0.0.1:11211;
   }

Retorna 200 OK se excluído com sucesso, 404 Not Found para NOT_FOUND, ou 502 para ERROR, CLIENT_ERROR ou SERVER_ERROR.

As respostas originais do memcached são retornadas como o corpo da resposta, exceto para 404 NOT FOUND.

delete $memc_key $memc_exptime

Semelhante ao comando delete $memc_key exceto que aceita um tempo de expiração opcional especificado pela variável $memc_exptime.

Este comando não está mais disponível na versão mais recente do memcached 1.4.4.

incr $memc_key $memc_value

Incrementa o valor existente de $memc_key pela quantidade especificada por $memc_value:

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

No exemplo anterior, toda vez que acessamos /foo, o valor de my_key é incrementado em 2.

Retorna 200 OK com o novo valor associado a essa chave como o corpo da resposta se bem-sucedido, ou 404 Not Found se a chave não for encontrada.

Retorna 502 para ERROR, CLIENT_ERROR ou SERVER_ERROR.

decr $memc_key $memc_value

Semelhante ao incr $memc_key $memc_value.

flush_all

Marca todas as chaves no servidor memcached como expiradas:

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

flush_all $memc_exptime

Assim como flush_all, mas também aceita um tempo de expiração especificado pela variável $memc_exptime.

stats

Faz com que o servidor memcached exiba estatísticas e configurações de uso geral.

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

Retorna 200 OK se a requisição for bem-sucedida, ou 502 para ERROR, CLIENT_ERROR ou SERVER_ERROR.

A saída bruta do comando stats do servidor memcached upstream será colocada no corpo da resposta.

Diretrizes

Todas as diretrizes do módulo memcached padrão no nginx 0.8.28 são herdadas diretamente, com os prefixos memcached_ substituídos por memc_. Por exemplo, a diretiva memcached_pass é escrita como memc_pass.

Aqui documentamos apenas as duas diretrizes mais importantes (a última é uma nova diretiva introduzida por este módulo).

memc_pass

sintaxe: memc_pass <endereço IP do servidor memcached>:<porta do servidor memcached>

sintaxe: memc_pass <nome do host do servidor memcached>:<porta do servidor memcached>

sintaxe: memc_pass <nome_backend_upstream>

sintaxe: memc_pass unix:<caminho_para_socket_de_dominio_unix>

padrão: nenhum

contexto: http, server, location, if

fase: content

Especifica o backend do servidor memcached.

memc_cmds_allowed

sintaxe: memc_cmds_allowed <cmd>...

padrão: nenhum

contexto: http, server, location, if

Lista os comandos do memcached que são permitidos para acesso. Por padrão, todos os comandos do memcached suportados por este módulo são acessíveis. Um exemplo é

    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

sintaxe: memc_flags_to_last_modified on|off

padrão: off

contexto: http, server, location, if

Lê os flags do memcached como segundos desde a época e os define como o valor do cabeçalho Last-Modified. Para GETs condicionais, isso sinalizará ao nginx para retornar a resposta 304 Not Modified para economizar largura de banda.

memc_connect_timeout

sintaxe: memc_connect_timeout <tempo>

padrão: 60s

contexto: http, server, location

O tempo limite para conectar ao servidor memcached, em segundos por padrão.

É prudente sempre especificar explicitamente a unidade de tempo para evitar confusões. As unidades de tempo suportadas são "s" (segundos), "ms" (milissegundos), "y" (anos), "M" (meses), "w" (semanas), "d" (dias), "h" (horas) e "m" (minutos).

Esse tempo deve ser inferior a 597 horas.

memc_send_timeout

sintaxe: memc_send_timeout <tempo>

padrão: 60s

contexto: http, server, location

O tempo limite para enviar requisições TCP ao servidor memcached, em segundos por padrão.

É prudente sempre especificar explicitamente a unidade de tempo para evitar confusões. As unidades de tempo suportadas são "s" (segundos), "ms" (milissegundos), "y" (anos), "M" (meses), "w" (semanas), "d" (dias), "h" (horas) e "m" (minutos).

Esse tempo deve ser inferior a 597 horas.

memc_read_timeout

sintaxe: memc_read_timeout <tempo>

padrão: 60s

contexto: http, server, location

O tempo limite para ler respostas TCP do servidor memcached, em segundos por padrão.

É prudente sempre especificar explicitamente a unidade de tempo para evitar confusões. As unidades de tempo suportadas são "s" (segundos), "ms" (milissegundos), "y" (anos), "M" (meses), "w" (semanas), "d" (dias), "h" (horas) e "m" (minutos).

Esse tempo deve ser inferior a 597 horas.

memc_buffer_size

sintaxe: memc_buffer_size <tamanho>

padrão: 4k/8k

contexto: http, server, location

Esse tamanho de buffer é usado para o buffer de memória para armazenar

  • a resposta completa para comandos do memcached que não sejam get,
  • o cabeçalho de resposta completo (ou seja, a primeira linha da resposta) para o comando get do memcached.

Esse tamanho padrão é o tamanho da página, pode ser 4k ou 8k.

memc_ignore_client_abort

sintaxe: memc_ignore_client_abort on|off

padrão: off

contexto: location

Determina se a conexão com um servidor memcached deve ser fechada quando um cliente fecha uma conexão sem esperar por uma resposta.

Esta diretiva foi adicionada pela primeira vez na versão v0.14.

Mudanças

As mudanças de cada versão deste módulo podem ser obtidas nos logs de mudanças do pacote OpenResty:

http://openresty.org/#Changes

Conjunto de Testes

Este módulo vem com um conjunto de testes dirigido por Perl. Os casos de teste também são declarativos. Graças ao módulo Test::Base no mundo Perl.

Para executá-lo do seu lado:

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

Você precisa encerrar qualquer processo do Nginx antes de executar o conjunto de testes se você tiver alterado o binário do servidor Nginx.

Ou LWP::UserAgent ou IO::Socket é usado pelo test scaffold.

Como um único servidor nginx (por padrão, localhost:1984) é usado em todos os scripts de teste (.t), não faz sentido executar o conjunto de testes em paralelo especificando -jN ao invocar a utilidade prove.

Você também deve manter um servidor memcached escutando na porta 11211 em localhost antes de executar o conjunto de testes.

Algumas partes do conjunto de testes requerem que os módulos rewrite e echo sejam habilitados também ao construir o Nginx.

Veja Também

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório do GitHub para nginx-module-memc.