Subprojects di Balik OpenResty

API7.ai

September 12, 2022

OpenResty (NGINX + Lua)

Bagaimana cara mengekstrak kode Lua dari nginx.conf dan tetap membuatnya mudah dibaca dan dipelihara? Solusinya cukup sederhana. Mari kita lihat bagaimana mengimplementasikan ini dengan OpenResty.

Pertama, buat direktori bernama lua. Kemudian, kita akan menempatkan semua file .lua di dalamnya.

$ mkdir lua

$ cat lua/hello.lua
ngx.say("hello, world")

Kedua, gunakan content_by_lua_block untuk menggantikan content_by_lua_file di file nginx.conf.

pid logs/nginx.pid;
events {
  worker_connections 1024;
}

http {
  server {
    listen 8080;
    location / {
      content_by_lua_file lua/hello.lua;
      }
    }
  }

Ketiga, restart layanan OpenResty, dan selesai!

$ sudo kill -HUP `cat logs/nginx.pid`

Dengan menggunakan content_by_lua_file, kita dapat memperbarui file Lua secara langsung tanpa harus memperbarui nginx.conf. Namun, ada beberapa pertanyaan:

  1. Kita menggunakan path relatif di bagian content_by_lua_file lua/hello.lua. Bagaimana OpenResty menemukan file Lua yang sebenarnya?
  2. Setelah memodifikasi kode Lua, kita perlu me-restart OpenResty agar berfungsi, apakah ada cara untuk melakukan debug dengan efisien?
  3. Bagaimana menambahkan direktori yang berisi file Lua ke path pencarian OpenResty?

Saya mendorong Anda untuk memikirkan pertanyaan-pertanyaan ini, yang semuanya dapat dijawab dalam dokumentasi resmi. Itulah mengapa saya selalu menekankan pentingnya dokumentasi.

Untuk pertanyaan pertama, jika path relatif diberikan, maka saat OpenResty dimulai, ia akan menambahkan prefiks -p PATH dalam parameter baris perintah saat memulai OpenResty dan menggabungkan path relatif menjadi path absolut. Dengan cara ini, OpenResty dapat menemukan file Lua dengan lancar.

Masalah kedua adalah bahwa kode Lua dimuat pada permintaan pertama dan di-cache secara default. Jadi setiap kali Anda mengubah file sumber Lua, Anda harus memuat ulang OpenResty agar berfungsi. Anda dapat menghindari pemuatan ulang dengan mematikan lua_code_cache di nginx.conf. Namun, penting untuk dicatat bahwa metode ini hanya dapat digunakan sementara untuk pengembangan dan debugging. Jadi jika Anda melakukan deployment di produksi, Anda harus mengaktifkan cache. Jika tidak, ini akan berdampak signifikan pada performa.

Untuk pertanyaan terakhir, OpenResty menyediakan direktif lua_package_path untuk mengatur path pencarian modul Lua. Misalnya, kita dapat mengatur lua_package_path ke $prefix/lua/?.lua;;:

  • $prefix adalah -p PATH dalam parameter startup.
  • /lua/?.lua menunjukkan semua file di direktori Lua dengan akhiran .lua.
  • Dua titik koma terakhir mewakili path pencarian kode bawaan.

Struktur direktori setelah instalasi

Setelah memahami program hello world pertama, mari kita lihat lebih dalam seperti apa struktur direktori OpenResty setelah diinstal dan file apa saja yang ada di dalamnya.

Pertama, kita menggunakan opsi -V untuk melihat di mana OpenResty berada. Untuk hasil berikut, saya menghilangkan banyak parameter kompilasi modul, yang akan kita tambahkan nanti:

$ openresty -V

nginx version: openresty/1.13.6.2
built by clang 10.0.0 (clang-1000.10.44.4)
built with OpenSSL 1.1.0h  27 Mar 2018
TLS SNI support enabled
configure arguments: --prefix=/usr/local/Cellar/openresty/1.13.6.2/nginx ...

Saya menggunakan brew untuk menginstal OpenResty di Mac saya. Path-nya adalah /usr/local/Cellar/openresty/1.13.6.2/nginx, yang mungkin berbeda dengan lingkungan Anda. Path ini berisi direktori bin, luajit, lualib, nginx, pod, dan lainnya. Penting untuk memahami arti dari folder-folder ini agar kita dapat mempelajari OpenResty dengan lebih baik. Jadi mari kita lihat satu per satu.

Pertama adalah direktori bin yang penting.

$ ll /usr/local/Cellar/openresty/1.13.6.2/bin

total 320
-r-xr-xr-x  1 ming  admin    19K  3 27 12:54 md2pod.pl
-r-xr-xr-x  1 ming  admin    15K  3 27 12:54 nginx-xml2pod
lrwxr-xr-x  1 ming  admin    19B  3 27 12:54 openresty -> ../nginx/sbin/nginx
-r-xr-xr-x  1 ming  admin    62K  3 27 12:54 opm
-r-xr-xr-x  1 ming  admin    29K  3 27 12:54 resty
-r-xr-xr-x  1 ming  admin    15K  3 27 12:54 restydoc
-r-xr-xr-x  1 ming  admin   8.3K  3 27 12:54 restydoc-index

Ini berisi CLI OpenResty resty yang kita sebutkan di bagian sebelumnya dan executable inti, openresty, yang sebenarnya adalah tautan simbolis ke nginx. Adapun alat lain di direktori ini, tidak diragukan lagi, seperti resty, semuanya adalah skrip Perl.

Di antaranya, opm adalah alat manajemen paket yang memungkinkan kita mengelola berbagai paket pihak ketiga, yang akan dibahas di bagian selanjutnya; dan restydoc, teman lama dari bagian pertama, adalah penampil dokumentasi yang disediakan oleh OpenResty, yang memungkinkan kita melihat dokumentasi OpenResty dan NGINX.

$ restydoc -s ngx.say
$ restydoc -s proxy_pass

Dua contoh di atas masing-masing menanyakan API OpenResty dan perintah NGINX. restydoc adalah alat yang sangat membantu bagi insinyur sisi server untuk fokus pada pengembangan.

Setelah menjelajahi direktori bin, mari kita lanjutkan ke direktori pod.

Pertama, mari kita tekankan bahwa pod di sini tidak ada hubungannya dengan konsep pod di Kubernetes. Sebaliknya, pod adalah bahasa markup yang digunakan dalam Perl untuk menulis dokumentasi modul Perl. Dan direktori ini berisi dokumentasi untuk OpenResty, NGINX, lua-resty-*, dan LuaJIT, yang semuanya terkait dengan restydoc yang disebutkan sebelumnya.

Selanjutnya adalah direktori NGINX dan luajit yang sudah familiar. Kedua direktori ini mudah dipahami. Mereka terutama menyimpan file executable NGINX dan LuaJIT serta dependensinya, dan merupakan landasan OpenResty. Banyak orang mengatakan OpenResty berbasis Lua, tetapi itu tidak akurat. Seperti yang bisa kita lihat di atas, OpenResty sebenarnya berbasis LuaJIT.

Faktanya, pada tahap awal, OpenResty dilengkapi dengan Lua dan LuaJIT, dan kita dapat memutuskan apakah akan menggunakan Lua atau LuaJIT dengan opsi kompilasi. Namun, Lua sedang dihapus, dan hanya LuaJIT yang berkinerja lebih tinggi yang didukung.

Terakhir, mari kita lihat direktori lualib. Ini berisi pustaka Lua yang digunakan di OpenResty, terutama dibagi menjadi dua direktori: ngx dan resty.

  • Direktori ngx menyimpan kode Lua dari proyek resmi lua-resty-core, yang merupakan implementasi ulang API OpenResty berbasis FFI. Saya akan menjelaskan di bab khusus mengapa kita perlu mengimplementasikannya kembali.
  • Direktori resty berisi kode Lua dari berbagai proyek lua-resty-*, yang akan kita bahas selanjutnya.

Mengikuti konvensi kursus ini, pada titik ini saya akan memberikan sumber dari sumber direktori ini. Ini juga merupakan salah satu kegembiraan dari proyek open source. Jika Anda suka menggali lebih dalam, Anda akan selalu menemukan hal-hal yang lebih menarik.

Berikut adalah skrip pengemasan OpenResty untuk CentOS, yang berisi semua direktori yang disebutkan di atas.

%files
%defattr(-,root,root,-)

/etc/init.d/%{name}
/usr/bin/%{name}
%{orprefix}/bin/openresty
%{orprefix}/site/lualib/
%{orprefix}/luajit/*
%{orprefix}/lualib/*
%{orprefix}/nginx/html/*
%{orprefix}/nginx/logs/
%{orprefix}/nginx/sbin/*
%{orprefix}/nginx/tapset/*
%config(noreplace) %{orprefix}/nginx/conf/*
%{orprefix}/COPYRIGHT

Ikhtisar proyek OpenResty

Ketika berbicara tentang OpenResty, kita akan memikirkan lua-nginx-module. Ya, modul C NGINX ini memang merupakan inti dari OpenResty, tetapi tidak setara dengan OpenResty. Banyak insinyur menyebut OpenResty sebagai ngx + lua, yang juga digunakan dalam buku yang dibagikan dan diterbitkan oleh banyak konferensi teknis. Ini tidak ketat dan tidak didukung oleh komunitas OpenResty.

Mari saya jelaskan mengapa dan proyek terkait apa saja selain lua-nginx-module yang ada di OpenResty.

Buka halaman utama proyek OpenResty di GitHub, dan Anda dapat melihat bahwa OpenResty berisi 68 proyek publik, yang secara kasar dibagi menjadi tujuh kategori berikut. Mari saya perkenalkan secara singkat sehingga Anda dapat memiliki gambaran awal dan mempelajarinya dengan cepat.

Modul C NGINX

Penamaan proyek OpenResty distandarisasi, dan yang bernama *-nginx-module adalah modul C NGINX.

Ada lebih dari 20 modul C di OpenResty, dan kita dapat menemukannya dengan menggunakan openresty -V, yang kita gunakan di awal bagian ini.

$ openresty -V

nginx version: openresty/1.13.6.2
built by clang 10.0.0 (clang-1000.10.44.4)
built with OpenSSL 1.1.0h  27 Mar 2018
TLS SNI support enabled
configure arguments: --prefix=/usr/local/Cellar/openresty/1.13.6.2/nginx --with-cc-opt='-O2 -I/usr/local/include -I/usr/local/opt/pcre/include -I/usr/local/opt/openresty-openssl/include' --add-module=../ngx_devel_kit-0.3.0 --add-module=../echo-nginx-module-0.61 --add-module=../xss-nginx-module-0.06 --add-module=../ngx_coolkit-0.2rc3 --add-module=../set-misc-nginx-module-0.32 --add-module=../form-input-nginx-module-0.12 --add-module=../encrypted-session-nginx-module-0.08 --add-module=../srcache-nginx-module-0.31 --add-module=../ngx_lua-0.10.13 --add-module=../ngx_lua_upstream-0.07 --add-module=../headers-more-nginx-module-0.33 --add-module=../array-var-nginx-module-0.05 --add-module=../memc-nginx-module-0.19 --add-module=../redis2-nginx-module-0.15 --add-module=../redis-nginx-module-0.3.7 --add-module=../ngx_stream_lua-0.0.5 --with-ld-opt='-Wl,-rpath,/usr/local/Cellar/openresty/1.13.6.2/luajit/lib -L/usr/local/lib -L/usr/local/opt/pcre/lib -L/usr/local/opt/openresty-openssl/lib' --pid-path=/usr/local/var/run/openresty.pid --lock-path=/usr/local/var/run/openresty.lock --conf-path=/usr/local/etc/openresty/nginx.conf --http-log-path=/usr/local/var/log/nginx/access.log --error-log-path=/usr/local/var/log/nginx/error.log --with-pcre-jit --with-ipv6 --with-stream --with-stream_ssl_module --with-stream_ssl_preread_module --with-http_v2_module --without-mail_pop3_module --without-mail_imap_module --without-mail_smtp_module --with-http_stub_status_module --with-http_realip_module --with-http_addition_module --with-http_auth_request_module --with-http_secure_link_module --with-http_random_index_module --with-http_geoip_module --with-http_gzip_static_module --with-http_sub_module --with-http_dav_module --with-http_flv_module --with-http_mp4_module --with-http_gunzip_module --with-threads --with-dtrace-probes --with-stream --with-stream_ssl_module --with-http_ssl_module

Di sini --add-module= diikuti oleh modul C OpenResty. Yang inti adalah lua-nginx-module dan stream-lua-nginx-module, yang pertama untuk menangani lalu lintas Layer 7 dan yang kedua untuk menggerakkan lalu lintas Layer 4.

Beberapa modul C ini memerlukan perhatian khusus dan tidak direkomendasikan, meskipun mereka dikompilasi ke OpenResty secara default. Misalnya, redis2-nginx-module, redis-nginx-module, dan memc-nginx-module digunakan untuk berinteroperasi dengan Redis dan Memcached. Pustaka C ini direkomendasikan oleh OpenResty pada tahap awal, tetapi telah digantikan oleh lua-resty-redis dan lua-resty-memcached setelah fitur cosocket ditambahkan, dan tidak lagi aktif dikembangkan.

OpenResty tidak akan mengembangkan lebih banyak pustaka C NGINX di masa depan, tetapi akan fokus pada pustaka Lua berbasis cosocket, yang merupakan masa depan.

Pustaka lua-resty-*

Repositori resmi OpenResty berisi 18 pustaka lua-resty-*, termasuk Redis, MySQL, Memcached, WebSocket, DNS, kontrol lalu lintas, pemrosesan string, caching dalam proses, dan pustaka standar lainnya. Selain yang resmi yang disertakan, ada lebih banyak pustaka pihak ketiga. Mereka sangat penting, dan kita akan mencurahkan lebih banyak waktu untuk pustaka ini di bagian selanjutnya.

Cabang LuaJIT yang dikelola sendiri

OpenResty mengelola cabang LuaJIT sendiri selain patch OpenSSL-nya. Pada tahun 2015, penulis LuaJIT Mike Pall mengumumkan pensiun untuk mencari pengelola baru LuaJIT, tetapi Mike tidak menemukan pengelola yang cocok. Dia sekarang terutama melakukan perbaikan bug, dan pengembangan fitur baru telah dihentikan, sehingga OpenResty mengelola cabang LuaJIT-nya sendiri.

Dibandingkan dengan Lua, LuaJIT menambahkan banyak fungsi penting dan unik, tetapi tidak banyak insinyur yang mengetahuinya, jadi ini adalah keterampilan semi-terpendam yang akan saya perkenalkan nanti.

Kerangka Pengujian

Kerangka pengujian OpenResty adalah test-nginx, juga dikembangkan dalam Perl, dan seperti yang bisa Anda lihat dari namanya, ini dirancang khusus untuk menguji proyek terkait NGINX. Semua kasus uji resmi OpenResty untuk modul C dan pustaka lua-resty didorong oleh test-nginx. Ini adalah sistem yang jauh lebih kuat dan independen, tidak seperti kerangka berbasis asersi yang umum.

Beberapa kontributor OpenResty juga belum memahami kerangka pengujian ini dan terkadang mengirimkan PR yang berisi kode C dan Lua yang kompleks tetapi masih sering takut dengan ide menulis kasus uji yang sesuai. Jadi jika Anda telah melihat beberapa kasus uji di direktori /t proyek OpenResty dan masih bingung, jangan meragukan diri Anda sendiri. Kebanyakan orang sama.

Selain test-nginx, proyek mockeagain mensimulasikan jaringan yang lambat, memungkinkan program membaca dan menulis satu byte pada satu waktu. Ini adalah alat yang sangat berguna untuk server web.

Rantai alat debug

Proyek OpenResty telah menghabiskan banyak upaya untuk bagaimana melakukan debug kode secara ilmiah dan dinamis.

Dua proyek OpenResty, openresty-systemtap-toolkit, dan stapxx, didasarkan pada systemtap, alat debug dan pelacakan dinamis. Keuntungan terbesar menggunakan systemtap adalah memungkinkan analisis in vivo sementara sama sekali tidak mengganggu aplikasi target.

Misalnya, systemtap seperti pergi ke rumah sakit dan melakukan pemindaian CT, tanpa rasa sakit dan tidak terasa. Bahkan lebih baik, systemtap dapat menghasilkan grafik api visual untuk analisis performa, yang akan saya jelaskan nanti, jadi berikut adalah grafik api untuk memberi Anda gambaran.

Grafik Api Terkait OpenResty

Paket

Skrip pengemasan OpenResty di berbagai sistem operasi distribusi (seperti CentOS, Ubuntu, macOS, dll.) ditulis tangan untuk kontrol yang lebih memuaskan. Ketika kami memperkenalkan struktur direktori setelah instalasi, kami sudah membahas proyek terkait pengemasan ini: openresty-packaging dan home-brew. Jika Anda tertarik dengan ini, Anda dapat mempelajarinya sendiri, dan saya tidak akan mengulanginya di sini.

Alat Rekayasa

Selain proyek-proyek besar ini, OpenResty memiliki beberapa alat rekayasa yang sebagian besar tersembunyi.

Misalnya, openresty-devel-utils adalah kumpulan alat untuk mengembangkan OpenResty dan NGINX. Tentu saja, mereka juga dikembangkan dalam Perl, dan sebagian besar alat tidak terdokumentasi. Tetapi bagi pengembang OpenResty, alat-alat ini sangat berguna. Saya akan memulai dengan memilih beberapa dan memperkenalkannya secara singkat.

  • lj-releng adalah alat inspeksi kode LuaJIT yang sederhana dan efektif, mirip dengan luacheck, yang dapat menemukan masalah potensial dengan variabel global.
  • reindex, yang berarti membangun kembali indeks, adalah alat untuk memformat kasus uji test-nginx, mengatur ulang nomor kasus uji, dan menghapus spasi ekstra. reindex adalah salah satu alat yang digunakan pengembang OpenResty setiap hari.
  • opsboy digunakan untuk melakukan deployment otomatis. Ini digunakan untuk melakukan deployment dan menjalankan uji regresi yang dilakukan OpenResty pada kluster AWS EC2 sebelum setiap rilis. Untuk informasi lebih lanjut, Anda dapat merujuk ke dokumentasi resmi. opsboy adalah DSL yang diimplementasikan dalam Perl. Penulis OpenResty suka membuat DSL yang berbeda untuk menyelesaikan masalah.

Ringkasan

Hari ini, kita terutama mempelajari struktur direktori OpenResty setelah instalasi dan beberapa sub-proyek di baliknya. Setelah mempelajari konten hari ini, saya harap Anda dapat mempelajari lebih lanjut tentang proyek-proyek OpenResty. OpenResty telah melampaui lingkup load balancing dan reverse proxy NGINX dan telah mewujudkan ekosistemnya sendiri. Lain kali kita akan membahas ini secara detail.

Bacaan Lebih Lanjut