NGINX JavaScript, juga dikenal sebagai NJS, adalah modul dinamis untuk NGINX yang memungkinkan perluasan fungsionalitas bawaan menggunakan sintaksis JavaScript yang sudah dikenal. Bahasa NJS adalah bagian dari JavaScript, sesuai dengan ES5 (ECMAScript 5.1 Strict Variant) dengan beberapa ES6 (ECMAScript 6) dan ekstensi yang lebih baru. Lihat kompatibilitas untuk lebih jelasnya.
Bagaimana cara kerjanya
Mengunduh dan menginstal
Menyediakan repositori paket NGINX
Menginstal modul JavaScript NGINX
File dan lokasi yang diinstal
Memulai dengan NGINX JavaScript
Pastikan NGINX sedang berjalan
Mengaktifkan modul JavaScript NGINX
Dasar-dasar penulisan file skrip .js
Referensi objek, metode, dan properti khusus
Contoh: Halo Dunia
Antarmuka baris perintah NJS (CLI)
Membangun dari sumber
Menginstal dependensi
Mengkloning repositori NGINX JavaScript GitHub
Membangun utilitas antarmuka baris perintah mandiri (opsional)
Mengkloning repositori NGINX GitHub
Membangun JavaScript NGINX sebagai modul NGINX
Spesifikasi teknis JavaScript NGINX
Distribusi yang didukung
Lingkungan penerapan yang didukung
Versi NGINX yang didukung
Rekomendasi ukuran
Mengajukan pertanyaan, melaporkan masalah, dan berkontribusi
Ubah catatan
Lisensi
NGINX JavaScript disediakan sebagai dua modul dinamis untuk NGINX (ngx_http_js_module dan ngx_stream_js_module) dan dapat ditambahkan ke instalasi NGINX Open Source atau NGINX Plus yang didukung tanpa kompilasi ulang.
Modul NJS memungkinkan administrator NGINX untuk:
Tambahkan kontrol akses yang kompleks dan pemeriksaan keamanan sebelum permintaan mencapai server upstream
Memanipulasi header respons
Tulis penangan konten yang fleksibel dan asinkron, filter, dan banyak lagi!
Lihat contoh dan berbagai proyek kami yang dikembangkan bersama NJS:
Memperluas fungsionalitas NGINX Plus untuk berkomunikasi langsung dengan Penyedia Identitas yang kompatibel dengan OIDC, mengautentikasi pengguna dan mengotorisasi konten yang dikirimkan oleh NGINX Plus.
Referensi implementasi NGINX Plus sebagai penyedia layanan untuk otentikasi SAML.
Mengekspos titik akhir metrik Prometheus langsung dari NGINX Plus.
Tip
NJS juga dapat digunakan dengan server aplikasi NGINX Unit. Pelajari lebih lanjut tentang Control API Unit NGINX dan cara menentukan panggilan fungsi dengan NJS.
Ikuti langkah-langkah ini untuk mengunduh dan menginstal binari NGINX dan NGINX JavaScript Linux yang telah dikompilasi sebelumnya. Anda juga dapat memilih untuk membangun modul secara lokal dari kode sumber.
Ikuti panduan ini untuk menambahkan repositori paket NGINX resmi ke sistem Anda dan menginstal NGINX Open Source. Jika Anda sudah menginstal NGINX Open Source atau NGINX Plus, lewati bagian instalasi NGINX di langkah terakhir.
Setelah repositori disediakan, Anda dapat menginstal NJS dengan mengeluarkan perintah berikut:
sudo apt install nginx-module-njs
sudo yum instal nginx-module-njs
sudo apk tambahkan nginx-module-njs@nginx
sudo zypper instal nginx-module-njs
Tip
Repositori paket menyertakan modul alternatif yang mengaktifkan simbol debug. Meskipun tidak direkomendasikan untuk lingkungan produksi, modul ini mungkin berguna ketika mengembangkan konfigurasi berbasis NJS. Untuk mengunduh dan menginstal versi debug modul, ganti nama modul pada perintah sebelumnya dengan nginx-module-njs-dbg .
Skrip instalasi paket menginstal dua modul, mendukung NGINX http dan konteks stream .
ngx_http_js_module
Modul NJS ini memungkinkan manipulasi data yang dikirimkan melalui HTTP.
ngx_stream_js_module
Modul NJS ini memungkinkan manipulasi data yang dikirimkan melalui protokol aliran seperti TCP dan UDP.
Secara default, kedua modul diinstal ke direktori /etc/nginx/modules .
Penggunaan NJS melibatkan pengaktifan modul, penambahan file JavaScript dengan fungsi yang ditentukan, dan pemanggilan fungsi yang diekspor dalam file konfigurasi NGINX.
NGINX JavaScript adalah modul untuk NGINX Open Source atau NGINX Plus. Jika Anda belum melakukannya, ikuti langkah-langkah berikut untuk menginstal NGINX Open Source atau NGINX Plus. Setelah terinstal, pastikan instance NGINX berjalan dan mampu merespons permintaan HTTP.
Keluarkan perintah berikut untuk memulai NGINX:
sudo nginx
keriting -I 127.0.0.1
Anda akan melihat respons berikut:
HTTP/1.1 200 Oke Server: nginx/1.25.5
Setelah diinstal, salah satu (atau keduanya) modul NJS harus disertakan dalam file konfigurasi NGINX. Pada sebagian besar sistem, file konfigurasi NGINX terletak di /etc/nginx/nginx.conf secara default.
sudo vi /etc/nginx/nginx.conf
Gunakan direktif load_module dalam konteks tingkat atas (“utama”) untuk mengaktifkan salah satu (atau keduanya) modul.
load_module modul/ngx_http_js_module.so;load_module modul/ngx_stream_js_module.so;
File skrip NJS biasanya diberi nama dengan ekstensi .js dan ditempatkan di direktori /etc/nginx/njs/ . Mereka biasanya terdiri dari fungsi-fungsi yang kemudian diekspor, membuatnya tersedia dalam file konfigurasi NGINX.
NJS menyediakan kumpulan objek dengan metode dan properti terkait yang bukan merupakan bagian dari definisi ECMAScript. Lihat referensi lengkap mengenai objek-objek ini dan bagaimana objek tersebut dapat digunakan untuk memperluas dan menyesuaikan NGINX lebih lanjut.
Berikut adalah contoh dasar "Halo Dunia".
Fungsi hello dalam file ini mengembalikan kode respons status HTTP 200 OK bersama dengan string "Hello World!", diikuti dengan umpan baris. Fungsi tersebut kemudian diekspor untuk digunakan dalam file konfigurasi NGINX.
Tambahkan file ini ke direktori /etc/nginx/njs :
fungsi halo(r) {
r.return(200, "Halo dunia!n");}ekspor default {halo} Kami memodifikasi konfigurasi NGINX kami ( /etc/nginx/nginx.conf ) untuk mengimpor file JavaScript dan menjalankan fungsinya dalam keadaan tertentu.
# Muat ngx_http_js_module moduleload_module module/ngx_http_js_module.so;events {}http { # Tetapkan path ke file JavaScript njs kita
js_path "/etc/nginx/njs/"; # Impor file JavaScript kita ke variabel "main"
js_import utama dari http/hello.js; server {listen 80;location / { # Jalankan fungsi "halo" yang ditentukan dalam file JavaScript kami pada semua permintaan HTTP # dan tanggapi dengan konten fungsi kami. js_content main.halo;
}
}
}Untuk daftar lengkap arahan njs, lihat halaman dokumentasi modul ngx_http_js_module dan ngx_stream_js_module.
Tip
Versi lebih rinci tentang ini dan contoh lainnya dapat ditemukan di repositori resmi njs-examples.
NGINX JavaScript diinstal dengan utilitas antarmuka baris perintah. Antarmuka dapat dibuka sebagai shell interaktif atau digunakan untuk memproses sintaksis JavaScript dari file yang telah ditentukan sebelumnya atau input standar. Karena utilitas ini berjalan secara independen, objek khusus NGINX seperti HTTP dan Stream tidak tersedia dalam runtime-nya.
$ njs>> globalIniglobal {
njs: njs {versi: '0.8.4'
},
global: [melingkar],
proses: proses {argv: ['/usr/bin/njs'],env: { JALUR: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin: /bin', HOSTNAME: 'f777c149d4f8', JANGKA: 'xterm', NGINX_VERSION: '1.25.5', NJS_VERSION: '0.8.4', PKG_RELEASE: '1~buster', HOME: '/root'}
},
konsol: {log: [Fungsi: asli],dump: [Fungsi: asli],waktu: [Fungsi: asli],timeEnd: [Fungsi: asli]
},
cetak: [Fungsi: asli]}>>$ gema "2**3" | njs -q 8
Langkah-langkah berikut dapat digunakan untuk membangun NGINX JavaScript sebagai modul dinamis untuk diintegrasikan ke dalam NGINX atau biner mandiri untuk digunakan sebagai utilitas antarmuka baris perintah.
Penting
Untuk membuat modul yang akan digunakan dengan NGINX, Anda juga perlu mengkloning, mengonfigurasi, dan membuat NGINX dengan mengikuti langkah-langkah yang diuraikan dalam dokumen ini.
Sebagian besar distribusi Linux memerlukan beberapa dependensi untuk diinstal agar dapat membangun JavaScript NGINX dan NGINX. Petunjuk berikut khusus untuk manajer paket apt , tersedia secara luas di sebagian besar distribusi Ubuntu/Debian dan turunannya.
sudo apt install gcc make
sudo apt install libpcre3-dev zlib1g-dev libssl-dev libxml2-dev libxslt-dev
Untuk membangun dengan QuickJS, Anda juga perlu membangun perpustakaan QuickJS:
git clone https://github.com/bellard/quickjscd quickjs CFLAGS='-fPIC' membuat libquickjs.a
Peringatan
Ini adalah kumpulan pustaka ketergantungan minimal yang diperlukan untuk membangun NGINX dan NJS. Ketergantungan lain mungkin diperlukan jika Anda memilih untuk membangun NGINX dengan modul tambahan. Pantau output dari perintah configure yang dibahas di bagian berikut untuk informasi tentang modul mana yang mungkin hilang.
Dengan menggunakan metode pilihan Anda, kloning repositori JavaScript NGINX ke direktori pengembangan Anda. Lihat Mengkloning Repositori GitHub untuk bantuan tambahan.
https://github.com/nginx/njs.git
Langkah-langkah berikut bersifat opsional dan hanya diperlukan jika Anda memilih untuk membangun NJS sebagai utilitas mandiri.
Untuk menggunakan shell interaktif NJS, Anda perlu menginstal perpustakaan libedit-dev
sudo tepat instal libedit-dev
Jalankan perintah berikut dari direktori root repositori hasil kloning Anda:
./konfigurasi
Bangun JavaScript NGINX:
membuat
Utilitas tersebut sekarang seharusnya tersedia di <NJS_SRC_ROOT_DIR>/build/njs . Lihat Antarmuka Baris Perintah (CLI) NJS untuk informasi tentang penggunaan.
Kloning repositori kode sumber NGINX di direktori di luar repositori sumber NJS yang telah dikloning sebelumnya.
https://github.com/nginx/nginx.git
Untuk membangun NGINX JavaScript sebagai modul dinamis, jalankan perintah berikut dari direktori akar repositori kode sumber NGINX:
otomatis/konfigurasi --add-dynamic-module=<NJS_SRC_ROOT_DIR>/nginx
Untuk membangun dengan dukungan QuickJS, sediakan jalur penyertaan dan pustaka menggunakan opsi --with-cc-opt= dan --with-ld-opt= :
otomatis/konfigurasi --add-dynamic-module=<NJS_SRC_ROOT_DIR>/nginx
--dengan-cc-opt="-I<QUICKJS_SRC_ROOT_DIR>" --dengan-ld-opt="-L<QUICKJS_SRC_ROOT_DIR>"Peringatan
Secara default, metode ini hanya akan membangun modul ngx_http_js_module . Untuk menggunakan NJS dengan modul NGINX Stream, Anda harus mengaktifkannya selama langkah configure agar dapat dibangun dengan biner NGINX. Melakukan hal ini akan secara otomatis mengkompilasi modul ngx_stream_js_module ketika NJS ditambahkan ke build. Salah satu cara untuk mencapai hal ini adalah dengan mengubah langkah configure menjadi:
otomatis/konfigurasi --dengan-stream --add-dynamic-module=<NJS_SRC_ROOT_DIR>/nginx
Kompilasi modul
membuat
Tip
Untuk membangun NGINX dengan JavaScript NGINX yang tertanam dalam biner tunggal, ubah langkah configure menjadi berikut:
otomatis/konfigurasi --add-module=<NJS_SRC_ROOT_DIR>/nginx
Jika dibuat sebagai modul dinamis, modul JavaScript NGINX akan tersedia di direktori <NGINX_SRC_ROOT_DIR>/objs/ . Modul kemudian dapat disalin ke instalasi NGINX yang ada dan diaktifkan. Lihat Mengaktifkan Modul JavaScript NGINX untuk detailnya.
Alternatifnya, Anda dapat memilih untuk menginstal biner NGINX dan NGINX JavaScript bawaan dengan mengeluarkan perintah berikut:
Penting
Jika dibangun ke dalam biner NGINX sebagai modul standar (bukan dinamis), ini akan menjadi metode instalasi yang paling mudah
buat instal
Secara default, biner NGINX akan diinstal ke /usr/local/nginx/sbin/nginx . Modul JavaScript NGINX akan disalin ke /usr/local/nginx/modules/ .
Spesifikasi teknis NJS identik dengan NGINX.
Lihat Sistem Operasi dan Platform yang Diuji untuk daftar lengkap distribusi yang didukung.
Wadah
Cloud publik (AWS, Google Cloud Platform, Microsoft Azure)
Mesin virtual
NGINX JavaScript didukung oleh semua versi NGINX Open Source yang dimulai dengan nginx-1.14 dan semua versi NGINX Plus yang dimulai dengan NGINX Plus R15.
Kami mendorong Anda untuk terlibat dengan kami. Silakan lihat panduan Berkontribusi untuk informasi tentang cara mengajukan pertanyaan, melaporkan masalah, dan menyumbangkan kode.
Lihat halaman rilis kami untuk melacak pembaruan.
Lisensi mirip BSD 2 klausa
Dokumentasi tambahan tersedia di: https://nginx.org/en/docs/njs/
©2024 F5, Inc. Semua hak dilindungi undang-undang. https://www.f5.com/products/nginx
