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.
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:
Sehen Sie sich Beispiele und unsere verschiedenen mit NJS entwickelten Projekte an:
Erweitert die Funktionalität von NGINX Plus, 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-njssudo yum install nginx-module-njssudo apk add nginx-module-njs@nginxsudo zypper install nginx-module-njsTipp
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 nginxcurl -I 127.0.0.1Sie 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.confVerwenden Sie die Direktive „load_module“ im Kontext der obersten Ebene („Hauptkontext“), um eines (oder beide) Module zu aktivieren.
load_module modules/ngx_http_js_module.so;
load_module modules/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:
function hello ( 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.
# Load the ngx_http_js_module module
load_module modules/ngx_http_js_module.so;
events {}
http {
# Set the path to our njs JavaScript files
js_path "/etc/nginx/njs/" ;
# Import our JavaScript file into the variable "main"
js_import main from http/hello.js;
server {
listen 80 ;
location / {
# Execute the "hello" function defined in our JavaScript file on all HTTP requests
# and respond with the contents of our function.
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
>> globalThis
global {
njs: njs {
version : '0.8.4'
} ,
global : [ Circular ] ,
process : process {
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 : [ Function : native ] ,
dump : [ Function : native ] ,
time : [ Function : native ] ,
timeEnd : [ Function : native ]
} ,
print : [ Function : native ]
}
>>$ echo " 2**3 " | njs -q
8Mit 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 makesudo apt install libpcre3-dev zlib1g-dev libssl-dev libxml2-dev libxslt-devZum Erstellen mit QuickJS müssen Sie auch die QuickJS-Bibliothek erstellen:
git clone https://github.com/bellard/quickjs
cd quickjs
CFLAGS= ' -fPIC ' make libquickjs.aWarnung
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.gitDie 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-devFühren Sie die folgenden Befehle aus dem Stammverzeichnis Ihres geklonten Repositorys aus:
./configureErstellen Sie NGINX-JavaScript:
make Das Dienstprogramm sollte jetzt unter
Klonen Sie das NGINX-Quellcode-Repository in einem Verzeichnis außerhalb des zuvor geklonten NJS-Quellcode-Repositorys.
https://github.com/nginx/nginx.gitUm 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" --with-ld-opt= " -L"
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 > /nginxKompilieren Sie das Modul
makeTipp
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
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 install 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.
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
