NGINX JavaScript, auch bekannt als NJS, ist ein dynamisches Modul für NGINX, das die Erweiterung der integrierten Funktionalität mithilfe der vertrauten JavaScript-Syntax ermöglicht. Die NJS-Sprache ist eine Teilmenge von JavaScript, kompatibel mit ES5 (ECMAScript 5.1 Strict Variant) mit einigen ES6 (ECMAScript 6) und neueren Erweiterungen. Weitere Einzelheiten finden Sie unter Kompatibilität.
Wie es funktioniert
Herunterladen und installieren
Bereitstellung des NGINX-Paket-Repositorys
Installation der NGINX-JavaScript-Module
Installierte Dateien und Speicherorte
Erste Schritte mit NGINX-JavaScript
Stellen Sie sicher, dass NGINX ausgeführt wird
Aktivieren der NGINX-JavaScript-Module
Grundlagen zum Schreiben von .js-Skriptdateien
Referenz auf benutzerdefinierte Objekte, Methoden und Eigenschaften
Beispiel: Hallo Welt
Die NJS-Befehlszeilenschnittstelle (CLI)
Bauen aus der Quelle
Abhängigkeiten installieren
Klonen des NGINX-JavaScript-GitHub-Repositorys
Erstellen eines eigenständigen Befehlszeilenschnittstellen-Dienstprogramms (optional)
Klonen des NGINX-GitHub-Repositorys
Erstellen von NGINX-JavaScript als Modul von NGINX
Technische Spezifikationen für NGINX JavaScript
Unterstützte Distributionen
Unterstützte Bereitstellungsumgebungen
Unterstützte NGINX-Versionen
Größenempfehlungen
Fragen stellen, Probleme melden und Beiträge leisten
Änderungsprotokoll
Lizenz
NGINX JavaScript wird als zwei dynamische Module für NGINX bereitgestellt (ngx_http_js_module und ngx_stream_js_module) und kann ohne Neukompilierung zu jeder unterstützten NGINX Open Source- oder NGINX Plus-Installation hinzugefügt werden.
Das NJS-Modul ermöglicht NGINX-Administratoren:
Fügen Sie komplexe Zugriffskontrollen und Sicherheitsprüfungen hinzu, bevor Anfragen die Upstream-Server erreichen
Antwortheader bearbeiten
Schreiben Sie flexible, asynchrone Inhaltshandler, Filter und mehr!
Sehen Sie sich Beispiele und unsere verschiedenen mit NJS entwickelten Projekte an:
Erweitert die NGINX Plus-Funktionalität, um direkt mit OIDC-kompatiblen Identitätsanbietern zu kommunizieren, Benutzer zu authentifizieren und von NGINX Plus bereitgestellte Inhalte zu autorisieren.
Referenzimplementierung von NGINX Plus als Dienstanbieter für SAML-Authentifizierung.
Stellt den Prometheus-Metrik-Endpunkt direkt aus NGINX Plus bereit.
Tipp
NJS kann auch mit dem NGINX Unit-Anwendungsserver verwendet werden. Erfahren Sie mehr über die Steuerungs-API von NGINX Unit und wie Sie Funktionsaufrufe mit NJS definieren.
Befolgen Sie diese Schritte, um vorkompilierte NGINX- und NGINX-JavaScript-Linux-Binärdateien herunterzuladen und zu installieren. Sie können das Modul auch lokal aus dem Quellcode erstellen.
Befolgen Sie diese Anleitung, um das offizielle NGINX-Paket-Repository zu Ihrem System hinzuzufügen und NGINX Open Source zu installieren. Wenn Sie NGINX Open Source oder NGINX Plus bereits installiert haben, überspringen Sie den NGINX-Installationsabschnitt im letzten Schritt.
Sobald das Repository bereitgestellt wurde, können Sie NJS installieren, indem Sie den folgenden Befehl ausgeben:
sudo apt install nginx-module-njs
sudo yum install nginx-module-njs
sudo apk nginx-module-njs@nginx hinzufügen
sudo zypper install nginx-module-njs
Tipp
Das Paket-Repository enthält ein alternatives Modul, das Debug-Symbole ermöglicht. Obwohl dieses Modul nicht für Produktionsumgebungen empfohlen wird, kann es bei der Entwicklung von NJS-basierten Konfigurationen hilfreich sein. Um die Debug-Version des Moduls herunterzuladen und zu installieren, ersetzen Sie den Modulnamen im vorherigen Befehl durch nginx-module-njs-dbg .
Die Paketinstallationsskripte installieren zwei Module und unterstützen NGINX http und stream Kontexte.
ngx_http_js_module
Dieses NJS-Modul ermöglicht die Manipulation von über HTTP übertragenen Daten.
ngx_stream_js_module
Dieses NJS-Modul ermöglicht die Manipulation von Daten, die über Stream-Protokolle wie TCP und UDP übertragen werden.
Standardmäßig werden beide Module im Verzeichnis /etc/nginx/modules installiert.
Die Verwendung von NJS umfasst das Aktivieren des Moduls, das Hinzufügen von JavaScript-Dateien mit definierten Funktionen und das Aufrufen exportierter Funktionen in NGINX-Konfigurationsdateien.
NGINX JavaScript ist ein Modul für NGINX Open Source oder NGINX Plus. Wenn Sie dies noch nicht getan haben, befolgen Sie diese Schritte, um NGINX Open Source oder NGINX Plus zu installieren. Stellen Sie nach der Installation sicher, dass die NGINX-Instanz ausgeführt wird und auf HTTP-Anfragen reagieren kann.
Geben Sie den folgenden Befehl ein, um NGINX zu starten:
sudo nginx
curl -I 127.0.0.1
Sie sollten die folgende Antwort sehen:
HTTP/1.1 200 OK Server: nginx/1.25.5
Nach der Installation müssen eines (oder beide) NJS-Module in der NGINX-Konfigurationsdatei enthalten sein. Auf den meisten Systemen befindet sich die NGINX-Konfigurationsdatei standardmäßig unter /etc/nginx/nginx.conf .
sudo vi /etc/nginx/nginx.conf
Verwenden Sie die Direktive „load_module“ im Kontext der obersten Ebene („Hauptkontext“), um eines (oder beide) Module zu aktivieren.
Load_Module Module/ngx_http_js_module.so;Load_Module Module/ngx_stream_js_module.so;
NJS-Skriptdateien werden normalerweise mit der Erweiterung .js benannt und im Verzeichnis /etc/nginx/njs/ abgelegt. Sie bestehen normalerweise aus Funktionen, die dann exportiert werden und sie in NGINX-Konfigurationsdateien verfügbar machen.
NJS stellt eine Sammlung von Objekten mit zugehörigen Methoden und Eigenschaften bereit, die nicht Teil der ECMAScript-Definitionen sind. Sehen Sie sich die vollständige Referenz zu diesen Objekten an und erfahren Sie, wie sie zur weiteren Erweiterung und Anpassung von NGINX verwendet werden können.
Hier ist ein einfaches „Hello World“-Beispiel.
Die hello Funktion in dieser Datei gibt einen HTTP-200-OK-Statusantwortcode zusammen mit der Zeichenfolge „Hello World!“ zurück, gefolgt von einem Zeilenvorschub. Die Funktion wird dann zur Verwendung in einer NGINX-Konfigurationsdatei exportiert.
Fügen Sie diese Datei zum Verzeichnis /etc/nginx/njs hinzu:
Funktion hallo(r) {
r.return(200, "Hello world!n");}export default {hello} Wir ändern unsere NGINX-Konfiguration ( /etc/nginx/nginx.conf ), um die JavaScript-Datei zu importieren und die Funktion unter bestimmten Umständen auszuführen.
# Laden Sie das ngx_http_js_module moduleload_module module/ngx_http_js_module.so;events {}http { # Legen Sie den Pfad zu unseren njs-JavaScript-Dateien fest
js_path "/etc/nginx/njs/"; # Importieren Sie unsere JavaScript-Datei in die Variable „main“
js_import main von http/hello.js; server {listen 80;location / { # Führen Sie die in unserer JavaScript-Datei definierte „Hallo“-Funktion bei allen HTTP-Anfragen aus # und antworten Sie mit dem Inhalt unserer Funktion. js_content main.hello;
}
}
}Eine vollständige Liste der njs-Anweisungen finden Sie auf den Dokumentationsseiten zu den Modulen ngx_http_js_module und ngx_stream_js_module.
Tipp
Eine detailliertere Version dieses und anderer Beispiele finden Sie im offiziellen njs-examples-Repository.
NGINX JavaScript wird mit einem Befehlszeilenschnittstellen-Dienstprogramm installiert. Die Schnittstelle kann als interaktive Shell geöffnet oder zur Verarbeitung der JavaScript-Syntax aus vordefinierten Dateien oder Standardeingaben verwendet werden. Da das Dienstprogramm unabhängig ausgeführt wird, sind NGINX-spezifische Objekte wie HTTP und Stream innerhalb seiner Laufzeit nicht verfügbar.
$ njs>> globalThisglobal {
njs: njs {Version: '0.8.4'
},
global: [Rundschreiben],
Prozess: Prozess {argv: ['/usr/bin/njs'],env: { PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin: /bin“, HOSTNAME: „f777c149d4f8“, TERM: „xterm“, NGINX_VERSION: „1.25.5“, NJS_VERSION: '0.8.4', PKG_RELEASE: '1~buster', HOME: '/root'}
},
console: {log: [Funktion: native],dump: [Funktion: native],time: [Funktion: native],timeEnd: [Funktion: native]
},
print: [Funktion: native]}>>$ echo "2**3" | njs -q 8
Mit den folgenden Schritten können Sie NGINX-JavaScript als dynamisches Modul zur Integration in NGINX oder als eigenständige Binärdatei zur Verwendung als Befehlszeilenschnittstellen-Dienstprogramm erstellen.
Wichtig
Um das Modul für die Verwendung mit NGINX zu erstellen, müssen Sie NGINX auch klonen, konfigurieren und erstellen, indem Sie die in diesem Dokument beschriebenen Schritte befolgen.
Bei den meisten Linux-Distributionen müssen mehrere Abhängigkeiten installiert werden, um NGINX und NGINX-JavaScript zu erstellen. Die folgenden Anweisungen gelten speziell für den apt -Paketmanager, der auf den meisten Ubuntu/Debian-Distributionen und ihren Derivaten weit verbreitet ist.
Sudo apt install gcc make
sudo apt install libpcre3-dev zlib1g-dev libssl-dev libxml2-dev libxslt-dev
Zum Erstellen mit QuickJS müssen Sie auch die QuickJS-Bibliothek erstellen:
Git-Klon https://github.com/bellard/quickjscd quickjs CFLAGS='-fPIC' make libquickjs.a
Warnung
Dies ist der minimale Satz an Abhängigkeitsbibliotheken, die zum Erstellen von NGINX und NJS erforderlich sind. Weitere Abhängigkeiten können erforderlich sein, wenn Sie NGINX mit zusätzlichen Modulen erstellen möchten. Überwachen Sie die Ausgabe des in den folgenden Abschnitten beschriebenen Befehls configure , um Informationen darüber zu erhalten, welche Module möglicherweise fehlen.
Klonen Sie mit Ihrer bevorzugten Methode das NGINX-JavaScript-Repository in Ihr Entwicklungsverzeichnis. Weitere Hilfe finden Sie unter Klonen eines GitHub-Repositorys.
https://github.com/nginx/njs.git
Die folgenden Schritte sind optional und nur erforderlich, wenn Sie NJS als eigenständiges Dienstprogramm erstellen möchten.
Um die interaktive NJS-Shell verwenden zu können, müssen Sie die Bibliothek libedit-dev installieren
sudo apt install libedit-dev
Führen Sie die folgenden Befehle aus dem Stammverzeichnis Ihres geklonten Repositorys aus:
./konfigurieren
Erstellen Sie NGINX-JavaScript:
machen
Das Dienstprogramm sollte jetzt unter <NJS_SRC_ROOT_DIR>/build/njs verfügbar sein. Informationen zur Verwendung finden Sie unter Die NJS-Befehlszeilenschnittstelle (CLI).
Klonen Sie das NGINX-Quellcode-Repository in einem Verzeichnis außerhalb des zuvor geklonten NJS-Quellcode-Repositorys.
https://github.com/nginx/nginx.git
Um NGINX-JavaScript als dynamisches Modul zu erstellen, führen Sie die folgenden Befehle aus dem Stammverzeichnis des NGINX-Quellcode-Repositorys aus:
auto/configure --add-dynamic-module=<NJS_SRC_ROOT_DIR>/nginx
Um mit QuickJS-Unterstützung zu erstellen, geben Sie Include und Bibliothekspfad mit den Optionen --with-cc-opt= und --with-ld-opt= :
auto/configure --add-dynamic-module=<NJS_SRC_ROOT_DIR>/nginx
--with-cc-opt="-I<QUICKJS_SRC_ROOT_DIR>" --with-ld-opt="-L<QUICKJS_SRC_ROOT_DIR>"Warnung
Standardmäßig erstellt diese Methode nur das Modul ngx_http_js_module . Um NJS mit dem NGINX-Stream-Modul zu verwenden, müssen Sie es während des configure aktivieren, damit es mit der NGINX-Binärdatei erstellt wird. Dadurch wird das Modul ngx_stream_js_module automatisch kompiliert, wenn NJS zum Build hinzugefügt wird. Eine Möglichkeit, dies zu erreichen, besteht darin, den configure wie folgt zu ändern:
auto/configure --with-stream --add-dynamic-module=<NJS_SRC_ROOT_DIR>/nginx
Kompilieren Sie das Modul
machen
Tipp
Um NGINX mit in eine einzelne Binärdatei eingebettetem NGINX-JavaScript zu erstellen, ändern Sie den configure wie folgt:
auto/configure --add-module=<NJS_SRC_ROOT_DIR>/nginx
Bei der Erstellung als dynamische(s) Modul(e) sind die NGINX-JavaScript-Modul(e) im Verzeichnis <NGINX_SRC_ROOT_DIR>/objs/ verfügbar. Anschließend können die Module in eine bestehende NGINX-Installation kopiert und aktiviert werden. Weitere Informationen finden Sie unter Aktivieren der NGINX-JavaScript-Module.
Alternativ können Sie die erstellten NGINX- und NGINX-JavaScript-Binärdateien installieren, indem Sie den folgenden Befehl ausführen:
Wichtig
Wenn es als Standardmodul (nicht dynamisch) in die NGINX-Binärdatei integriert wird, ist dies die einfachste Installationsmethode
make installieren
Standardmäßig wird die NGINX-Binärdatei in /usr/local/nginx/sbin/nginx installiert. Die NGINX-JavaScript-Module werden nach /usr/local/nginx/modules/ kopiert.
Die technischen Spezifikationen für NJS sind identisch mit denen von NGINX.
Eine vollständige Liste der unterstützten Distributionen finden Sie unter Getestete Betriebssysteme und Plattformen.
Container
Öffentliche Cloud (AWS, Google Cloud Platform, Microsoft Azure)
Virtuelle Maschine
NGINX JavaScript wird von allen NGINX Open Source-Versionen ab nginx-1.14 und allen NGINX Plus-Versionen ab NGINX Plus R15 unterstützt.
Wir ermutigen Sie, mit uns in Kontakt zu treten. Informationen zum Stellen von Fragen, zum Melden von Problemen und zum Beitragen von Code finden Sie im Beitragsleitfaden.
Besuchen Sie unsere Release-Seite, um den Überblick über Updates zu behalten.
2-Klausel-BSD-ähnliche Lizenz
Zusätzliche Dokumentation verfügbar unter: https://nginx.org/en/docs/njs/
©2024 F5, Inc. Alle Rechte vorbehalten. https://www.f5.com/products/nginx
