Panduan Konfigurasi Perkhidmatan Proksi Terbalik Ngrok dalam ServBay

Ngrok ialah alat terowong selamat yang sangat berkuasa, berdasarkan teknologi proksi terbalik, membolehkan anda melangkaui firewall dan NAT untuk memetakan perkhidmatan tempatan anda ke nama domain yang boleh diakses dari internet. Panduan ini akan menerangkan secara terperinci bagaimana mengintegrasi dan mengkonfigurasi Ngrok dalam persekitaran pembangunan tempatan ServBay, bagi mencapai akses Internet untuk perkhidmatan web, API, atau servis lain anda — sesuai untuk demonstrasi jarak jauh, kerjasama pasukan, atau ujian callback pihak ketiga.

Prinsip Teknologi

Prinsip asas Ngrok adalah dengan membina satu sambungan terowong terenkripsi di antara mesin tempatan anda dan pelayan Ngrok. Apabila pengguna luaran mengakses melalui domain awam yang diberikan Ngrok, permintaan akan sampai ke pelayan Ngrok terlebih dahulu, kemudian diteruskan ke perkhidmatan yang anda jalankan dalam ServBay melalui terowong selamat tersebut. Ini membolehkan anda menyediakan servis ke luar walaupun mesin anda tidak mempunyai IP awam atau berada di belakang firewall. Dalam senario ServBay, ini bermaksud anda boleh berkongsi laman web tempatan, API backend, atau mana-mana perkhidmatan berasaskan HTTP/HTTPS secara langsung kepada dunia luar untuk ujian dan demonstrasi.

Persediaan Persekitaran

Sebelum mengkonfigurasi Ngrok, pastikan anda telah melengkapkan perkara berikut:

1. ServBay telah dipasang dan berjalan: Pastikan aplikasi ServBay telah berjaya dipasang dan servis web yang ingin anda ekspos melalui Ngrok (contohnya, laman web) telah dikonfigurasi serta berjalan dengan lancar. Anda boleh menyemak dan menguruskan konfigurasi laman web dalam panel "Laman Web" ServBay.
2. Pemasangan klien Ngrok: Pasang alat baris arahan Ngrok melalui langkah berikut:
   1. Lawati Halaman Muat Turun Rasmi Ngrok untuk dapatkan pakej pemasangan mengikut sistem operasi anda.
   2. Ekstrak fail muat turun, kemudian salin atau pindahkan fail boleh laku ngrok ke direktori dalam PATH sistem anda (contoh: /usr/local/bin untuk macOS) supaya anda boleh jalankan perintah ngrok dari mana-mana terminal.

      # Contoh untuk macOS ARM64
      sudo unzip ~/Downloads/ngrok-v3-stable-darwin-arm64.zip -d /usr/local/bin

   3. Sahkan pemasangan dengan menjalankan perintah ngrok version untuk memastikan ia berfungsi:

      ngrok version
      # Contoh output: ngrok version 3.5.0

3. Akaun Ngrok (Pilihan, tapi disyorkan): Memiliki akaun Ngrok (percuma atau berbayar) memudahkan pengurusan terowong dan penggunaan ciri lanjutan seperti domain tetap. Daftar di Laman Rasmi Ngrok dan dapatkan Token Pengesahan anda (ngrok config add-authtoken <YOUR_AUTH_TOKEN>), yang membuang had masa sambungan terowong dan membuka lebih banyak ciri.
4. Laman web tempatan telah dikonfigurasi: Pastikan anda sudah ada sekurang-kurangnya satu laman web tempatan dalam ServBay yang ingin anda ekspos melalui Ngrok, contohnya menggunakan domain servbay.local atau yourproject.servbay.demo untuk capaian tempatan.

Konfigurasi Terowong: Langkah Praktikal

Penjelasan Parameter Utama

Struktur perintah untuk pemetaan servis standard adalah seperti berikut:

ngrok http --domain=<NGROK_DOMAIN> <LOCAL_ENDPOINT> \
  --request-header-add='host: <VIRTUAL_HOST>'

Komponen Parameter	Penjelasan Fungsi
http	Membina terowong berasaskan protokol HTTP. Ngrok akan mengurus permintaan HTTP/HTTPS yang masuk.
--domain <NGROK_DOMAIN>	Menetapkan nama domain tetap yang diberikan Ngrok (ganti dengan domain sebenar yang dikonfigurasi dalam Dashboard Ngrok anda). Untuk rancangan percuma, biasanya parameter ini tidak diperlukan kerana Ngrok akan memberikan subdomain rawak secara automatik.
<LOCAL_ENDPOINT>	Alamat servis ServBay tempatan anda. Untuk virtual host dalam ServBay, selalunya adalah nama domain capaian tempatan (contoh https://servbay.local). Boleh juga menggunakan http://localhost:port.
--request-header-add='host: <VIRTUAL_HOST>'	[Penting] Menukar Host header dalam permintaan. ServBay biasanya membezakan laman web tempatan (virtual host) melalui Host header HTTP. Dengan parameter ini, Host header permintaan luar akan diubah kepada domain virtual host tempatan anda (cth: servbay.local) supaya ServBay boleh memadankan permintaan ke laman web yang betul.

Contoh Konfigurasi

Jika anda telah sediakan laman web tempatan dalam ServBay dengan domain servbay.local dan ingin mengeksposnya ke internet melalui Ngrok, untuk akaun percuma Ngrok, anda boleh menghubungkan alamat tempatan terus:

# Memetakan laman web tempatan ServBay servbay.local ke domain rawak yang diberikan Ngrok
ngrok http https://servbay.local --request-header-add='host: servbay.local'

Jika anda mempunyai domain tetap yang dikonfigurasi dalam Ngrok Dashboard seperti your-servbay-demo.ngrok-free.app (atau domain kustom untuk pengguna berbayar), gunakan parameter --domain:

# Memetakan laman web tempatan ServBay servbay.local ke domain tertentu dalam Ngrok
ngrok http --domain=your-servbay-demo.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'

Setelah berjaya menjalankan perintah di atas, klien Ngrok akan memaparkan status terowong dalam terminal, termasuk alamat akses awam (contoh: https://xxxx.ngrok-free.app atau domain anda sendiri) serta pautan dashboard pemantauan trafik masa nyata (http://127.0.0.1:4040 biasanya).

Pengesahan Perkhidmatan

Selepas konfigurasi dan terowong Ngrok berjaya dimulakan, semak akses ke web melalui langkah berikut:

1. Peroleh alamat awam: Cari baris Forwarding dalam terminal Ngrok dan salin URL bermula dengan https://.
2. Akses melalui pelayar web: Dari mana-mana peranti yang tersambung ke internet, buka browser dan lawati URL awam Ngrok yang diperoleh (cth: https://cunning-lacewing-fresh.ngrok-free.app atau domain tetap anda).
3. Sahkan hasil:
   • Pastikan laman web yang dihoskan dalam ServBay dipaparkan dengan betul di browser.
   • Semak jika simbol HTTPS selamat dipaparkan di bar alamat. Ngrok menyediakan sijil SSL yang sah secara lalai untuk terowongnya.
   • Anda juga boleh menyemak log permintaan dan statistik trafik melalui antaramuka web tempatan Ngrok (http://127.0.0.1:4040) atau terus di terminal untuk pastikan permintaan benar-benar sampai dan diproses oleh ServBay.

Rajah: Laman berjaya diakses melalui terowong yang dicipta Ngrok dalam pelayar web

Tips Lanjutan & Perhatian

1. Pengurusan Domain:
   • Dengan pelan percuma Ngrok, subdomain rawak .ngrok-free.app akan diberikan dan terowong mempunyai had masa sambungan.
   • Daftar akaun Ngrok serta konfigurasikan domain tetap di Dashboard Ngrok untuk elak perubahan alamat awam setiap kali terowong dimulakan.
   • Pelan berbayar memberi anda kebolehan ikat domain anda sendiri, lebih lebar jalur, sambungan serentak, dan ciri lanjutan lain.
2. Pemetaan multi-perkhidmatan: Untuk mengekspos beberapa perkhidmatan tempatan di ServBay ke internet, anda boleh jalankan beberapa proses Ngrok serentak, atau gunakan fail konfigurasi Ngrok (jadi ~/.config/ngrok/ngrok.yml) untuk mentakrif dan menguruskan pelbagai terowong. Contohnya memetakan laman web ServBay dan aplikasi Node.js:

   # Pemetaan servbay.local dalam ServBay (melalui HTTPS 443 & Host header)
   ngrok http --domain=servbay-website.ngrok-free.app https://servbay.local --request-header-add='host: servbay.local'
   
   # Dari terminal lain atau melalui fail konfigurasi, peta aplikasi Node.js tempatan pada port 3000
   ngrok http --domain=nodejs-api.ngrok-free.app http://localhost:3000

   Nota: Untuk virtual host dalam ServBay, disarankan guna https://[domain tempatan] beserta --request-header-add dan elakkan pemetaan terus pada port 80/443 kerana ServBay menguruskan semua permintaan virtual host pada port tersebut.
3. Perintah Diagnostik:
   • ngrok config check: Sahkan sintaksis fail konfigurasi Ngrok (~/.config/ngrok/ngrok.yml).
   • ngrok logs: Papar log terperinci Ngrok secara masa nyata untuk diagnosis isu sambungan atau ralat routing permintaan.
4. Keselamatan: Mengekspos perkhidmatan tempatan ke internet mempunyai risiko keselamatan. Pastikan servis yang diekspos itu selamat dan hanya hidupkan terowong Ngrok apabila benar-benar diperlukan. Pelan berbayar menawarkan sekatan IP, kawalan akses, dan ciri keselamatan canggih lain.

Penyelesaian Masalah

Isu	Penyelesaian
Sambungan tamat masa atau laman tidak dimuatkan	Pastikan laman sasaran dalam ServBay aktif dan boleh dicapai dari browser tempatan (https://servbay.local). Periksa juga sama ada pelayan web ServBay (contoh Caddy atau Nginx) berjalan dengan baik, serta firewall tempatan membenarkan sambungan klien Ngrok.
Amaran ralat sijil HTTPS	Ngrok menyediakan sijil SSL yang sah secara lalai untuk domain awamnya. Jika berlaku ralat sijil semasa akses, selalunya berkait dengan konfigurasi terowong Ngrok atau isu rangkaian, bukan masalah dengan ServBay. Pastikan anda hanya melawat alamat https:// yang diberi Ngrok. Untuk isu sijil semasa akses domain tempatan, semak konfigurasi SSL pada ServBay.
Sambungan putus-putus atau perlahan	Periksa kestabilan sambungan Internet anda. Gangguan jaringan boleh memutus terowong. Gunakan rangkaian berwayar jika boleh. Untuk kestabilan tinggi, pertimbangkan pelan berbayar Ngrok yang menawarkan infrastruktur lebih mantap dan bandwith lebih tinggi.
Hanya laman default ServBay dipaparkan	Pastikan <LOCAL_ENDPOINT> dalam perintah ngrok http betul, dan nilai <VIRTUAL_HOST> dalam --request-header-add='host: <VIRTUAL_HOST>' juga tepat dengan domain laman web tempatan anda di ServBay. Ini penting bagi routing tepat permintaan ke laman yang diinginkan.

Soalan Lazim (FAQ)

• S: Bolehkah memetakan perkhidmatan pangkalan data ServBay?

  J: Ngrok direka untuk terowong HTTP/HTTPS. Walaupun Ngrok menyokong terowong TCP untuk servis seperti pangkalan data, ia di luar skop panduan HTTP ini, dan biasanya mengekspos pangkalan data ke internet secara terus tidak disarankan atas sebab keselamatan. Untuk akses jauh ke pangkalan data, pertimbangkan SSH tunnel atau kaedah yang lebih selamat.

• S: Adakah domain awam berubah setiap kali Ngrok dimulakan?

  J: Dengan pelan percuma, subdomain .ngrok-free.app yang diperoleh adalah rawak setiap kali. Untuk domain tetap, anda perlu daftar akaun Ngrok dan konfigurasikan domain tetap di Dashboard atau naik taraf ke pelan berbayar.

• S: Adakah Ngrok menjejaskan prestasi ServBay tempatan saya?

  J: Ngrok menambah sedikit latensi rangkaian kerana semua trafik perlu melalui pelayan Ngrok. Untuk pembangunan, ujian, dan demo, kelewatan ini biasanya boleh diterima. Prestasi pemprosesan sebenar laman web/aplikasi unsur ServBay masih bergantung kepada prestasi komputer anda dan kecekapan aplikasi itu sendiri.

Rumusan

Dengan integrasi Ngrok, pengguna ServBay boleh berkongsi hasil pembangunan web tempatan mereka ke internet dengan mudah dan selamat tanpa konfigurasi rangkaian yang rumit. Penyelesaian ini amat sesuai untuk kolaborasi jarak jauh, demonstrasi klien, ujian mudah alih atau pengesahan perkhidmatan pihak ketiga. Ngrok turut membekalkan pemantauan trafik masa nyata serta pilihan keselamatan (sesetengahnya hanya untuk pelan berbayar). Untuk aplikasi kritikal atau yang memerlukan domain tetap, disarankan pertimbangkan pelan berbayar Ngrok demi kestabilan dan fungsi yang lebih menyeluruh.