Zum Inhalt

memc: Erweiterte Version des standardmäßigen 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.20 veröffentlicht am 27. Dezember 2023.

 # 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 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 auf 0
     set $memc_exptime $arg_exptime; # standardmäßig auf 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 auf 0
     set $memc_exptime $arg_exptime; # standardmäßig auf 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;

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

Beschreibung

Dieses Modul erweitert das standardmäßige 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 innerhalb des NGINX-Servers durch Subanfragen oder unabhängige Fake-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, zur Freude :)

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 alleine, 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 auf 0), $memc_flags als Flags (standardmäßig auf 0), um die entsprechenden memcached-Abfragen zu erstellen.

Wenn $memc_value überhaupt nicht definiert ist, wird der Anforderungstext als Wert von $memc_value verwendet, mit Ausnahme der incr und decr Befehle. Beachten Sie, dass, wenn $memc_value als leerer String ("") definiert ist, dieser leere String 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 unter Verwendung eines Schlüssels 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, der in den Antworttext eingefügt wird, zurück, wenn der Schlüssel gefunden wird, oder 404 Not Found, wenn nicht. Die flags-Nummer wird in die Variable $memc_flags gesetzt, sodass es oft wünschenswert ist, diese Informationen in die Antwort-Header mithilfe der standardmäßigen add_header-Direktive 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 Anforderungstext als memcached-Wert zu verwenden, vermeiden Sie einfach, die Variable $memc_value zu setzen:

   # 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 Antworttext 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 "append"- und "prepend"-Befehle 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 unter Verwendung eines Schlüssels.

   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 Antworttext 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 bestehenden Wert von $memc_key um den Betrag, der durch $memc_value angegeben wird:

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

Im vorherigen Beispiel wird jedes Mal, wenn wir auf /foo zugreifen, der Wert von my_key um 2 erhöht.

Gibt 200 OK mit dem neuen Wert, der mit diesem Schlüssel als Antworttext 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 Antworttext eingefügt.

Direktiven

Alle standardmäßigen 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 beiden 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

Geben Sie 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 Seitengröß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 Version hinzugefügt.

Änderungen

Die Änderungen jeder Version dieses Moduls können aus den Änderungsprotokollen des OpenResty-Bundles entnommen 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) über alle Testskripte (.t-Dateien) verwendet wird, ist es bedeutungslos, die Test-Suite parallel auszuführen, indem Sie -jN beim Aufrufen des prove-Dienstprogramms angeben.

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

Einige Teile der Test-Suite erfordern, dass die Module rewrite und echo ebenfalls aktiviert sind, wenn Nginx gebaut wird.

Siehe auch

GitHub

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