Zum Inhalt

memc: Erweiterte Version des Standard-NGINX memcached Moduls

Installation

Sie können dieses Modul in jeder RHEL-basierten Distribution installieren, einschließlich, aber nicht beschränkt auf:

  • RedHat Enterprise Linux 7, 8, 9 und 10
  • CentOS 7, 8, 9
  • AlmaLinux 8, 9
  • Rocky Linux 8, 9
  • Amazon Linux 2 und 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

Aktivieren Sie das Modul, indem Sie Folgendes an den Anfang von /etc/nginx/nginx.conf hinzufügen:

load_module modules/ngx_http_memc_module.so;

Dieses Dokument beschreibt nginx-module-memc v0.21 veröffentlicht am 07. Juni 2026.

 # GET /foo?key=dog
 #
 # POST /foo?key=cat
 # Wert der Katze...
 #
 # PUT /foo?key=bird
 # Wert des Vogels...
 #
 # DELETE /foo?key=Tiger
 location /foo {
     set $memc_key $arg_key;

     # $memc_cmd ist standardmäßig auf get für GET,
     #   add für POST, set für PUT und
     #   delete für die DELETE-Anforderungsmethode.

     memc_pass 127.0.0.1:11211;
 }

 # GET /bar?cmd=get&key=cat
 #
 # POST /bar?cmd=set&key=dog
 # Mein Wert für den "dog" Schlüssel...
 #
 # 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; # standardmäßig 0
     set $memc_exptime $arg_exptime; # standardmäßig 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; # standardmäßig 0
     set $memc_exptime $arg_exptime; # standardmäßig 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;
         }
         ...
     }
   }
   ...

 # Lesen Sie die memcached-Flags in den Last-Modified-Header
 # um mit 304 auf bedingtes GET zu antworten
 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;

     # Greifen Sie auf den von memcached überwachten Unix-Domain-Socket zu
     memc_pass unix:/tmp/memcached.sock;
 }

Beschreibung

Dieses Modul erweitert das Standard-memcached Modul, um fast das gesamte memcached ASCII-Protokoll zu unterstützen.

Es ermöglicht Ihnen, eine benutzerdefinierte REST Schnittstelle zu Ihren memcached-Servern zu definieren oder memcached auf sehr effiziente Weise von innerhalb des NGINX-Servers durch Subanfragen oder unabhängige gefälschte Anfragen zuzugreifen.

Dieses Modul soll nicht in den NGINX-Kern integriert werden, da ich Ragel verwendet habe, um die memcached-Antwortparser (in C) zu generieren, um Freude zu haben :)

Wenn Sie dieses Modul verwenden möchten, um Standortantworten sofort zu cachen, versuchen Sie das srcache-nginx-module zusammen mit diesem Modul, um dies zu erreichen.

Wenn es in Verbindung mit dem lua-nginx-module verwendet wird, wird empfohlen, die lua-resty-memcached Bibliothek anstelle dieses Moduls zu verwenden, da erstere viel flexibler und speichereffizienter ist.

Keep-alive-Verbindungen zu memcached-Servern

Sie benötigen das HttpUpstreamKeepaliveModule zusammen mit diesem Modul für Keep-alive TCP-Verbindungen zu Ihren Backend-memcached-Servern.

Hier ist eine Beispielkonfiguration:

   http {
     upstream backend {
       server 127.0.0.1:11211;

       # ein Pool mit maximal 1024 Verbindungen
       # und keine Unterscheidung der Server:
       keepalive 1024;
     }

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

Wie es funktioniert

Es implementiert das memcached TCP-Protokoll ganz allein, basierend auf dem upstream Mechanismus. Alles, was mit I/O zu tun hat, ist nicht-blockierend.

Das Modul selbst hält keine TCP-Verbindungen zu den upstream-memcached-Servern über Anfragen hinweg, genau wie andere Upstream-Module. Für eine funktionierende Lösung siehe Abschnitt Keep-alive-Verbindungen zu memcached-Servern.

Unterstützte Memcached-Befehle

Die memcached-Speicherbefehle set, add, replace, prepend und append verwenden den $memc_key als Schlüssel, $memc_exptime als Ablaufzeit (oder Verzögerung) (standardmäßig 0), $memc_flags als Flags (standardmäßig 0), um die entsprechenden memcached-Abfragen zu erstellen.

Wenn $memc_value überhaupt nicht definiert ist, wird der Anfragekörper als Wert von $memc_value verwendet, mit Ausnahme der incr und decr Befehle. Beachten Sie, dass, wenn $memc_value als leere Zeichenfolge ("") definiert ist, diese leere Zeichenfolge weiterhin als Wert verwendet wird.

Die folgenden memcached-Befehle wurden implementiert und getestet (mit ihren Parametern, die durch die entsprechenden nginx-Variablen definiert sind, die von diesem Modul bereitgestellt werden):

get $memc_key

Ruft den Wert mit einem Schlüssel ab.

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

Gibt 200 OK mit dem Wert zurück, der in den Antwortkörper eingefügt wird, wenn der Schlüssel gefunden wird, oder 404 Not Found andernfalls. Die flags-Nummer wird in die Variable $memc_flags gesetzt, sodass es oft gewünscht ist, diese Informationen über die Standard-add_header-Direktive in die Antwort-Header einzufügen.

Es gibt 502 für ERROR, CLIENT_ERROR oder SERVER_ERROR zurück.

set $memc_key $memc_flags $memc_exptime $memc_value

Um den Anfragekörper als memcached-Wert zu verwenden, vermeiden Sie einfach die Festlegung der $memc_value-Variablen:

   # POST /foo
   # mein Wert...
   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;
   }

Oder lassen Sie die $memc_value den Wert halten:

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

Gibt 201 Created zurück, wenn der upstream-memcached-Server mit STORED antwortet, 200 für NOT_STORED, 404 für NOT_FOUND, 502 für ERROR, CLIENT_ERROR oder SERVER_ERROR.

Die ursprünglichen memcached-Antworten werden als Antwortkörper zurückgegeben, mit Ausnahme von 404 NOT FOUND.

add $memc_key $memc_flags $memc_exptime $memc_value

Ähnlich wie der set-Befehl.

replace $memc_key $memc_flags $memc_exptime $memc_value

Ähnlich wie der set-Befehl.

append $memc_key $memc_flags $memc_exptime $memc_value

Ähnlich wie der set-Befehl.

Beachten Sie, dass mindestens memcached Version 1.2.2 die Befehle "append" und "prepend" nicht unterstützt. Mindestens 1.2.4 und spätere Versionen scheinen diese beiden Befehle zu unterstützen.

prepend $memc_key $memc_flags $memc_exptime $memc_value

Ähnlich wie der append-Befehl.

delete $memc_key

Löscht den memcached-Eintrag mit einem Schlüssel.

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

       memc_pass 127.0.0.1:11211;
   }

Gibt 200 OK zurück, wenn erfolgreich gelöscht, 404 Not Found für NOT_FOUND oder 502 für ERROR, CLIENT_ERROR oder SERVER_ERROR.

Die ursprünglichen memcached-Antworten werden als Antwortkörper zurückgegeben, mit Ausnahme von 404 NOT FOUND.

delete $memc_key $memc_exptime

Ähnlich wie der delete $memc_key Befehl, außer dass er eine optionale expiration-Zeit akzeptiert, die durch die Variable $memc_exptime angegeben wird.

Dieser Befehl ist in der neuesten memcached-Version 1.4.4 nicht mehr verfügbar.

incr $memc_key $memc_value

Erhöht den vorhandenen Wert von $memc_key um den Betrag, der durch $memc_value angegeben ist:

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

Im vorhergehenden Beispiel wird jeder Zugriff auf /foo den Wert von my_key um 2 erhöhen.

Gibt 200 OK mit dem neuen Wert, der mit diesem Schlüssel als Antwortkörper verknüpft ist, zurück, wenn erfolgreich, oder 404 Not Found, wenn der Schlüssel nicht gefunden wird.

Es gibt 502 für ERROR, CLIENT_ERROR oder SERVER_ERROR zurück.

decr $memc_key $memc_value

Ähnlich wie incr $memc_key $memc_value.

flush_all

Markiert alle Schlüssel auf dem memcached-Server als abgelaufen:

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

flush_all $memc_exptime

Genau wie flush_all, akzeptiert jedoch auch eine Ablaufzeit, die durch die Variable $memc_exptime angegeben wird.

stats

Veranlasst den memcached-Server, allgemeine Statistiken und Einstellungen auszugeben.

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

Gibt 200 OK zurück, wenn die Anfrage erfolgreich ist, oder 502 für ERROR, CLIENT_ERROR oder SERVER_ERROR.

Die rohe stats-Befehlsausgabe vom upstream-memcached-Server wird in den Antwortkörper eingefügt.

Direktiven

Alle Standard-memcached Modul Direktiven in nginx 0.8.28 werden direkt übernommen, wobei die memcached_ Präfixe durch memc_ ersetzt werden. Zum Beispiel wird die memcached_pass Direktive als memc_pass geschrieben.

Hier dokumentieren wir nur die zwei wichtigsten Direktiven (die letztere ist eine neue Direktive, die von diesem Modul eingeführt wurde).

memc_pass

syntax: memc_pass <IP-Adresse des memcached-Servers>:<Port des memcached-Servers>

syntax: memc_pass <Hostname des memcached-Servers>:<Port des memcached-Servers>

syntax: memc_pass <upstream_backend_name>

syntax: memc_pass unix:<Pfad_zum_unix_domain_socket>

default: keine

context: http, server, location, if

phase: content

Gibt den memcached-Server-Backend an.

memc_cmds_allowed

syntax: memc_cmds_allowed <cmd>...

default: keine

context: http, server, location, if

Listet die memcached-Befehle auf, die zugänglich sind. Standardmäßig sind alle von diesem Modul unterstützten memcached-Befehle zugänglich. Ein Beispiel ist

    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

syntax: memc_flags_to_last_modified on|off

default: off

context: http, server, location, if

Liest die memcached-Flags als Epoch-Sekunden und setzt sie als Wert des Last-Modified Headers. Für bedingtes GET signalisiert es NGINX, eine 304 Not Modified Antwort zurückzugeben, um Bandbreite zu sparen.

memc_connect_timeout

syntax: memc_connect_timeout <time>

default: 60s

context: http, server, location

Der Timeout für die Verbindung zum memcached-Server, standardmäßig in Sekunden.

Es ist ratsam, immer die Zeiteinheit explizit anzugeben, um Verwirrung zu vermeiden. Unterstützte Zeiteinheiten sind "s" (Sekunden), "ms" (Millisekunden), "y" (Jahre), "M" (Monate), "w" (Wochen), "d" (Tage), "h" (Stunden) und "m" (Minuten).

Diese Zeit muss weniger als 597 Stunden betragen.

memc_send_timeout

syntax: memc_send_timeout <time>

default: 60s

context: http, server, location

Der Timeout für das Senden von TCP-Anfragen an den memcached-Server, standardmäßig in Sekunden.

Es ist ratsam, immer die Zeiteinheit explizit anzugeben, um Verwirrung zu vermeiden. Unterstützte Zeiteinheiten sind "s" (Sekunden), "ms" (Millisekunden), "y" (Jahre), "M" (Monate), "w" (Wochen), "d" (Tage), "h" (Stunden) und "m" (Minuten).

Diese Zeit muss weniger als 597 Stunden betragen.

memc_read_timeout

syntax: memc_read_timeout <time>

default: 60s

context: http, server, location

Der Timeout für das Lesen von TCP-Antworten vom memcached-Server, standardmäßig in Sekunden.

Es ist ratsam, immer die Zeiteinheit explizit anzugeben, um Verwirrung zu vermeiden. Unterstützte Zeiteinheiten sind "s" (Sekunden), "ms" (Millisekunden), "y" (Jahre), "M" (Monate), "w" (Wochen), "d" (Tage), "h" (Stunden) und "m" (Minuten).

Diese Zeit muss weniger als 597 Stunden betragen.

memc_buffer_size

syntax: memc_buffer_size <size>

default: 4k/8k

context: http, server, location

Diese Puffergröße wird für den Speicherpuffer verwendet, um

  • die vollständige Antwort für memcached-Befehle außer get,
  • die vollständige Antwort-Header (d.h. die erste Zeile der Antwort) für den get memcached-Befehl zu halten.

Diese Standardgröße ist die Seiten Größe und kann 4k oder 8k sein.

memc_ignore_client_abort

syntax: memc_ignore_client_abort on|off

default: off

context: location

Bestimmt, ob die Verbindung zu einem memcache-Server geschlossen werden soll, wenn ein Client eine Verbindung schließt, ohne auf eine Antwort zu warten.

Diese Direktive wurde erstmals in der v0.14 Veröffentlichung hinzugefügt.

Änderungen

Die Änderungen jeder Veröffentlichung dieses Moduls können aus den Änderungsprotokollen des OpenResty-Bundles abgerufen werden:

http://openresty.org/#Changes

Test Suite

Dieses Modul wird mit einer Perl-gesteuerten Test Suite geliefert. Die Testfälle sind ebenfalls deklarativ. Dank des Test::Base Moduls in der Perl-Welt.

Um es auf Ihrer Seite auszuführen:

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

Sie müssen alle NGINX-Prozesse beenden, bevor Sie die Test Suite ausführen, wenn Sie die NGINX-Server-Binärdatei geändert haben.

Entweder LWP::UserAgent oder IO::Socket wird von dem Testgerüst verwendet.

Da ein einzelner NGINX-Server (standardmäßig localhost:1984) in allen Testskripten (.t-Dateien) verwendet wird, ist es bedeutungslos, die Test Suite parallel auszuführen, indem Sie -jN beim Aufruf des prove-Dienstprogramms angeben.

Sie sollten auch einen memcached-Server haben, der auf dem Port 11211 auf localhost lauscht, bevor Sie die Test Suite ausführen.

Einige Teile der Test Suite erfordern auch, dass die Module rewrite und echo beim Erstellen von NGINX aktiviert sind.

Siehe auch

GitHub

Sie finden möglicherweise zusätzliche Konfigurationstipps und Dokumentationen für dieses Modul im GitHub-Repository für nginx-module-memc.