Mengakses Persekitaran Pembangunan ServBay Secara Umum dengan FRP (Penembusan NAT)

FRP ialah alat proksi terbalik berprestasi tinggi dan mudah digunakan, sangat sesuai untuk situasi di mana anda perlu mendedahkan perkhidmatan pembangunan tempatan (seperti laman web, API, pangkalan data, dan lain-lain) ke internet awam secara selamat dan mudah. Melalui seni bina klien (frpc) dan pelayan (frps), FRP dapat melaksanakan penembusan NAT dengan cekap.

Panduan ini akan memberikan tunjuk ajar terperinci kepada pengguna ServBay, khususnya pada macOS, bagaimana untuk menyediakan dan menggunakan klien FRP (frpc) bagi mencipta terowong selamat, supaya perkhidmatan web tempatan yang dijalankan dalam ServBay boleh diakses dari internet awam. Ini amat penting untuk demonstrasi jarak jauh, pembangunan kerjasama, menerima permintaan Webhook, atau melakukan ujian API luaran.

Ringkasan Prinsip Teknikal

Prinsip utama FRP ialah membina satu terowong komunikasi terenkripsi dari mesin dalaman (menjalankan frpc, iaitu mesin ServBay anda) ke pelayan awam (menjalankan frps). Apabila pengguna luar mengakses perkhidmatan anda melalui internet, permintaan akan sampai ke pelayan awam yang menjalankan frps. frps kemudian akan memajukan permintaan itu melalui terowong yang sedia ada ke frpc dalaman anda. Selepas menerima permintaan, frpc akan mengalihkannya ke perkhidmatan tempatan yang dijalankan dalam ServBay (contohnya, laman web atau API anda). Respon perkhidmatan tersebut akan dihantar semula ke pengguna luar melalui laluan bertentangan.

Mekanisme ini dengan bijak memintas sekatan firewall dan router dalaman, membolehkan pendedahan perkhidmatan dalaman kepada luar, dan menyokong pelbagai protokol seperti TCP/UDP/HTTP/HTTPS, memberikan kemampuan akses jauh yang hebat untuk persekitaran pembangunan ServBay.

Senario Penggunaan

Dengan menggabungkan ServBay dan FRP, anda boleh menangani senario pembangunan berikut dengan mudah:

• Demonstrasi & Kolaborasi Jarak Jauh: Paparkan serta merta laman web atau aplikasi yang sedang anda bangun kepada ahli pasukan atau pelanggan tanpa perlu deploy ke server jauh.
• Ujian Webhook: Terima pemberitahuan Webhook daripada servis pihak ketiga (seperti GitHub, Stripe, WeChat Pay, dsb.) dan debug terus di mesin tempatan anda.
• Ujian Integrasi API: Dedahkan API backend pembangunan tempatan anda kepada pembangun front-end luar atau rakan kerjasama untuk ujian penyepaduan.
• Ujian Pembangunan Peranti Mudah Alih: Akses laman atau aplikasi ServBay tempatan pada peranti mudah alih anda untuk ujian keserasian silang peranti.
• Perkongsian Sementara: Kongsi fail atau perkhidmatan tempatan dengan pantas tanpa konfigurasi yang rumit.

Prasyarat

Sebelum mula mengkonfigurasi FRP, sila pastikan perkara berikut dipenuhi:

1. ServBay Telah Dipasang dan Berjalan: Mesin macOS anda telah berjaya memasang dan menjalankan ServBay, serta perkhidmatan tempatan (contohnya laman web) yang ingin didedahkan sudah dikonfigurasi dalam ServBay dan boleh diakses melalui browser secara tempatan.
2. Memiliki Server FRP Awam (frps): Anda memerlukan sebuah server dengan alamat IP awam, dan telah memasang serta menjalankan FRP server (frps) di atasnya. Panduan ini menfokuskan pada konfigurasi klien (frpc).
3. Nama Domain Awam (Pilihan, Digalakkan untuk HTTP/HTTPS): Jika anda ingin akses perkhidmatan melalui domain, anda perlukan domain sendiri dan boleh mengkonfigurasi DNS.
4. Klien FRP (frpc) Telah Dipasang: FRP klien tidak disertakan dalam ServBay secara lalai, jadi anda perlu memuat turun dan memasangnya secara berasingan.

Persiapan Persekitaran & Pemasangan Klien FRP

Ikuti langkah-langkah berikut untuk memasang klien FRP (frpc) pada mesin macOS tempat ServBay dipasang.

1. Muat Turun Klien FRP: Lawati halaman FRP GitHub Releases dan muat turun versi terkini pakej pemasang FRP mengikuti seni bina sistem macOS anda.

   • Untuk Apple Silicon (M1/M2/M3 dan seumpamanya), muat turun fail frp_*.darwin_arm64.tar.gz.
   • Untuk seni bina Intel, muat turun fail frp_*.darwin_amd64.tar.gz.

2. Pasang Klien FRP: Ekstrak fail yang dimuat turun, kemudian salin fail boleh laksana frpc ke direktori PATH sistem, seperti /usr/local/bin, supaya anda boleh menjalankan arahan frpc dari mana-mana terminal.

   Sila ambil perhatian, nombor versi dalam contoh perintah di bawah (0.52.3 merupakan versi baharu semasa penulisan panduan, sila rujuk nama fail anda sebenar) dan seni bina (darwin_arm64) mungkin berbeza. Sila sesuaikan mengikut fail sebenar.

   # Contoh muat turun: frp_0.52.3_darwin_arm64.tar.gz
   # Masuk ke direktori muat turun
   cd ~/Downloads
   
   # Ekstrak fail (tukar kepada nama fail sebenar anda)
   tar -zxvf frp_0.52.3_darwin_arm64.tar.gz
   
   # Masuk ke direktori hasil ekstrak (tukar kepada nama folder sebenar)
   cd frp_0.52.3_darwin_arm64
   
   # Salin fail frpc ke /usr/local/bin
   sudo cp frpc /usr/local/bin/
   
   # (Pilihan) Salin juga fail contoh frpc.toml ke lokasi seperti direktori home pengguna
   # cp frpc.toml ~/

   Masukkan kata laluan pengguna anda untuk menyempurnakan arahan sudo.

3. Sahkan Pemasangan: Buka tetingkap terminal baru, jalankan arahan berikut untuk memastikan frpc dipasang dengan betul dan sudah ada dalam PATH:

   frpc -v
   # Output dijangka: frpc version 0.52.3

   Jika anda nampak maklumat versi, pemasangan berjaya dilakukan.

Mengkonfigurasi Terowong Klien FRP

Konfigurasi klien FRP utama dilakukan melalui fail yang dipanggil frpc.toml (format TOML sangat digalakkan untuk FRP versi baharu). Anda perlu mencipta atau mengedit fail ini, untuk tetapkan bagaimana frpc menyambung ke FRP server (frps) anda serta bagaimana perkhidmatan dalam ServBay dipetakan ke internet awam.

Penjelasan Fail Konfigurasi frpc.toml

Berikut contoh struktur asas fail konfigurasi frpc.toml, memaparkan maklumat sambungan dan definisi asas untuk satu proksi:

# frpc.toml - Contoh konfigurasi klien FRP

# Bahagian [common]: konfigurasi sambungan klien ke pelayan
serverAddr = "your-frps-server.com" # Alamat IP awam atau domain FRP server anda
serverPort = 7000 # Port pelayan FRP untuk sambungan klien (lalai 7000)

# Konfigurasi pengesahan (sangat digalakkan guna token)
auth.method = "token"
auth.token = "your_authentication_token" # Token pengesahan, mesti sepadan dengan konfigurasi pelayan FRP

# Pilihan: Aktifkan TLS untuk enkripsi sambungan klien-pelayan (tingkatkan keselamatan)
# tls_enable = true

# Bahagian [[proxies]]: definisi satu atau lebih terowong proksi
[[proxies]]
name = "my-web-service" # Nama proksi, mesti unik dalam fail frpc.toml
type = "http" # Jenis proksi: http, https, tcp, udp, stcp, xtcp dll.
localIP = "127.0.0.1" # Alamat IP perkhidmatan tempatan, lalai 127.0.0.1
localPort = 80 # Port perkhidmatan tempatan (contoh: port HTTP ServBay lalai)
customDomains = ["servbay.your-domain.com"] # Domain akses awam (khusus jenis http/https). **Domain MESTI ditetapkan DNS ke IP pelayan FRP anda.**

# Konfigurasi proksi tambahan boleh ditambah sebagai bahagian [[proxies]] baru
# [[proxies]]
# ... (konfigurasi proksi lain)

Item Konfigurasi	Bahagian	Keterangan
serverAddr	[common]	IP awam atau domain pelayan FRP server (frps).
serverPort	[common]	Port pelayan FRP untuk sambungan klien, lalai 7000. Tukar ikut konfigurasi server sebenar anda.
auth.method	[common]	Kaedah pengesahan antara klien-server, biasa token. Mesti sama dengan konfigurasi pelayan.
auth.token	auth (di bawah [common])	Token pengesahan, mesti sama dengan di server. Jangan dedahkan token ini sembarangan.
tls_enable	[common]	Aktifkan sambungan terenkripsi TLS. Disarankan set ke true untuk keselamatan diganda.
[[proxies]]	Tahap root	Array bagi satu atau lebih terowong. Setiap blok [[proxies]] mendefinisikan satu aturan pemetaan tersendiri.
name	[[proxies]]	Nama proksi semasa, unik dalam fail frpc.toml yang sama. Disarankan nama bermakna (fungsi servis).
type	[[proxies]]	Jenis protokol proksi: kebiasaan http, https, tcp, udp. Pilih mengikut servis anda.
localIP	[[proxies]]	Alamat IP untuk servis tempatan, lalai 127.0.0.1. Biasanya tak perlu ubah.
localPort	[[proxies]]	Port servis tempatan. Contoh: HTTP ServBay = 80, HTTPS = 443; MySQL = 3306, PostgreSQL = 5432, dsb.
remotePort	[[proxies]]	(Untuk jenis tcp/udp sahaja) Port awam yang didedahkan server FRP. Pengguna luar akses servis menggunakan serverAddr:remotePort.
customDomains	[[proxies]]	(Jenis http/https sahaja) Domain awam. Array string, boleh set banyak domain. Semua domain ini MESTI telah resolve DNS ke IP FRP server.
subdomain	[[proxies]]	(Jenis http/https SAHAJA dan server support) Set subdomain yang akan digunakan bersama konfigurasi subdomain_host di pelayan server FRP.
[proxies.plugin]	[[proxies]]	Konfigurasi plugin seperti https2https untuk servis HTTPS tempatan.
hostHeaderRewrite	[proxies.plugin] atau [[proxies]]	Ubah header Host yang dihantar ke perkhidmatan tempatan. Sangat penting jika konfigurasi virtualhost dalam ServBay berdasarkan domain.

Contoh Konfigurasi: Pemetaan Laman HTTPS ServBay ke Domain Awam

ServBay secara lalai mengaktifkan HTTPS untuk laman web tempatan dan mengurus sijil SSL secara automatik. Untuk mendedahkan laman HTTPS tempatan ke internet awam dengan FRP, biasanya gunakan jenis proksi https dengan pilihan plugin https2https, atau proksi jenis tcp untuk redirect port 443 terus. Namun kerana virtualhost ServBay bergantung pada header Host, penggunaan jenis https dengan pilihan hostHeaderRewrite lebih digemari.

Berikut contoh pemetaan laman HTTPS tempatan (misal domain tempatan servbay.test) ke domain awam seperti test-frp.servbay.app menggunakan FRP. Sila PASTIKAN domain awam anda (cth. test-frp.servbay.app) telah resolve DNS ke IP pelayan FRP (frps.servbay.demo).

Cipta fail frpc.toml (cth., di direktori home pengguna ~/frpc.toml) dan tambah konfigurasi berikut:

# Contoh frpc.toml - Pemetaan laman HTTPS ServBay ke internet awam

# [common]: Konfigurasi sambungan ke pelayan FRP
serverAddr = "frps.servbay.demo" # Gantikan dengan alamat server FRP anda (IP/domain)
serverPort = 7000 # Gantikan dengan port server FRP

auth.method = "token"
auth.token = "servbay_demo_token" # Gantikan dengan token pengesahan server FRP anda

# Digalakkan: Enkripsi sambungan dengan TLS
tls_enable = true

# [[proxies]]: Pemetaan laman HTTPS tempatan ServBay
[[proxies]]
name = "servbay-website-https" # Nama proksi (boleh ditukar), cth. servbay-test-site
type = "https" # Jenis proksi

# Tetapkan domain awam. Pastikan ia resolve ke IP server FRP!
customDomains = ["test-frp.servbay.app"] # Tukar ke domain yang ingin anda buka

# Butiran redirect local service
localIP = "127.0.0.1" # Biasanya ServBay listen pada alamat ini
localPort = 443 # Port HTTPS ServBay default

# PERINGATAN: Tukar Host header ke domain laman web tempatan dalam ServBay
# Contoh: Web server seperti Nginx/Caddy routing berdasarkan nilai Host
hostHeaderRewrite = "servbay.test" # Gantikan dengan domain laman tempatan dalam ServBay

# Pilihan: Setting header khusus untuk kenal pasti asal permintaan
[proxies.requestHeaders.set]
x-from-where = "frp-tunnel"

Gantikan serverAddr, serverPort, auth.token, customDomains, dan hostHeaderRewrite dalam konfigurasi di atas mengikut keadaan sebenar anda.

Kenapa hostHeaderRewrite penting: ServBay mengendalikan laman web anda menggunakan pelayan web seperti Nginx atau Caddy. Pelayan ini biasanya mengarahkan permintaan ke direktori atau aplikasi laman tertentu berdasarkan nilai header Host. Permintaan yang tiba melalui FRP membawa Host header domain awam (test-frp.servbay.app) dan bukan domain tempatan (servbay.test). Jika hostHeaderRewrite tidak dikonfigurasikan, pelayan web ServBay tidak dapat mengenal laman web sasaran dan akan memberikan ralat 404 atau laman default. Oleh itu, tetapkan hostHeaderRewrite ke domain tempatan laman web ServBay sangat penting.

Menjalankan Servis Klien FRP

Selepas mencipta dan menyimpan fail konfigurasi frpc.toml, buka terminal, navigasi ke direktori fail tersebut (atau gunakan laluan penuh jika letak di home pengguna) dan jalankan arahan berikut:

# Jika frpc.toml berada di direktori semasa
frpc -c frpc.toml

# Jika frpc.toml berada di home pengguna
# frpc -c ~/frpc.toml

Arahan ini menjalankan frpc di latar hadapan dan akan cuba sambung ke server frps. Jika berjaya, anda akan nampak log menunjukkan terowong sudah sedia dan servis proksi berjalan.

Jika anda mahu frpc berjalan di latar belakang, gunakan nohup atau gunakan alat pengurusan servis macOS seperti launchctl. Contoh menggunakan nohup:

# Sekiranya frpc.toml berada di home pengguna
nohup frpc -c ~/frpc.toml &

nohup akan alihkan output log ke fail nohup.out dan jalankan proses di latar belakang. Namun, gunakan launchctl untuk pengurusan servis yang lebih rasmi di macOS (konfigurasi lebih kompleks, tidak dibincangkan di sini).

Pengesahan Servis & Diagnosa Log

Pengesahan Servis

Selepas frpc berjalan dan log menunjukkan sambungan berjaya, buka browser dan kunjungi domain awam yang anda tetapkan dalam frpc.toml (cth. https://test-frp.servbay.app). Sahkan perkara berikut:

• Laman berjaya dimuat, tiada ralat sambungan, tiada amaran sijil (jika guna HTTPS) atau masalah rangkaian lain.
• Kod status HTTP 200 atau seperti dijangka.
• Kandungan laman sama dengan yang diakses melalui https://servbay.test secara tempatan.
• Untuk HTTPS, lihat ikon kunci pada browser dan pastikan sijil SSL sah (nama domain cocok dengan domain awam anda).

Diagnosa Log

Log klien FRP sangat penting untuk mengenal pasti isu sambungan dan pemajuan (forwarding). Bila anda jalankan frpc -c frpc.toml, log akan keluar di terminal secara lalai. Anda boleh meneliti log untuk mengenal pasti sebarang ralat atau amaran.

Untuk memaparkan log debug dengan lebih terperinci semasa memulakan, jalankan:

frpc -c frpc.toml --log_level debug

Jika anda letakkan konfigurasi log_file dalam frpc.toml (contoh, log_file = "/var/log/frpc.log"), log akan ditulis ke fail tersebut. Anda boleh ikuti log masa nyata dengan:

tail -f /path/to/your/frpc.log

Penyelesaian Masalah Biasa

Jika mengalami masalah semasa mengkonfigurasi atau menggunakan FRP, rujuk jadual ralat dan solusi umum berikut:

Gejala	Penyelesaian
Gagal pengesahan sambungan FRP	Semak tetapan auth.token dan auth.method di bahagian [common] dalam frpc.toml dan pastikan sama sepenuhnya dengan konfigurasi server FRP (frps). Semak juga log di server, adakah terdapat ralat pengesahan?
Domain awam tidak dapat diakses atau masalah DNS	Sahkan domain yang ditetapkan dalam customDomains telah resolve ke IP publik FRP server. Gunakan ping your-frp-domain.com atau perkhidmatan DNS lookup untuk semak. Tunggu jika terdapat cache DNS.
Mengakses domain awam, cuma nampak halaman selamat datang FRP	Ini selalunya bermaksud domain sudah resolve ke server FRP, tapi tiada aturan pemajuan ke klien. Sahkan customDomains dan type dalam frpc.toml betul, pastikan server FRP membenarkan domain tersebut.
Port tempatan digunakan atau servis tidak berjalan	Pastikan ServBay dan perkhidmatan yang ingin dedahkan sudah berjalan dan mendengar di port yang betul. Guna lsof -i :PORT (gantikan PORT dengan nilai localPort) untuk semak.
Terowong sering putus / tidak stabil	Semak kestabilan rangkaian kedua-dua mesin ServBay dan server FRP. Cuba dalam [common] tingkatkan parameter heartbeat, contohnya heartbeat_timeout = 30 atau tambah bilangan connection pool. Semak juga log server FRP, kemungkinan ada had sumber atau masalah lain.
Mengakses HTTP dipaksa redirect ke HTTPS	Semak konfigurasi pelayan web (seperti Nginx/Caddy) dalam ServBay—adakah redirect HTTP ke HTTPS telah diaktifkan? Untuk expose HTTP, tukar type ke http dan buang plugin tidak perlu. Untuk expose HTTPS, pastikan type https dengan konfigurasi sijil betul.
Amaran sijil HTTPS di browser	Jika anda gunakan proksi jenis https dan sijil tempatan ialah self-signed/ServBay CA, browser anda mungkin beri amaran. Anda boleh install CA ServBay ke mesin klien anda, atau configure plugin seperti https2https untuk gunakan fail sijil yang lebih dipercayai. Juga boleh set sijil SSL pada pelayan FRP server itu sendiri.
Menerima ralat 404	Semak konfigurasi hostHeaderRewrite dalam frpc.toml—wajib set ke domain laman web tempatan dalam ServBay (cth. servbay.test). Jika Host header tidak cocok, pelayan web ServBay tidak tahu website mana ingin dipaparkan.
Sambungan ditolak firewall server FRP	Pastikan port serverPort (cth. 7000) dibuka pada firewall server FRP, begitu juga port service luar seperti 80 (HTTP), 443 (HTTPS), atau port remotePort untuk proksi TCP/UDP.
Firewall tempatan halang sambungan	Pastikan tiada aturan firewall pada macOS yang menghalang outbound ke serverPort FRP. Pastikan juga port ServBay tempatan (localPort) membenarkan sambungan tempatan daripada 127.0.0.1.
Log frpc tunjuk sambungan berjaya tapi servis tak dapat diakses	Kemungkinan isu di konfigurasi server FRP, atau masalah jaringan antara server dan klien. Semak log di server FRP (frps) dan pastikan mapping port/domain telah dikonfigurasi dengan betul.

Kelebihan & Cadangan Keselamatan Penggunaan FRP dalam ServBay

Menggunakan FRP dengan ServBay memberikan keanjalan dan kemudahan tinggi untuk pembangun:

• Sokongan Pelbagai Protokol: FRP menyokong HTTP, HTTPS, TCP, UDP, dsb. Bukan sahaja servis web, anda juga boleh publish database tempatan (cth. MySQL/PostgreSQL/MongoDB), Redis atau bahkan SSH.
• Konfigurasi Fleksibel: Dengan fail TOML ringkas, anda boleh tetapkan berbilang terowong bagi pelbagai servis atau laman.
• Open Source & Boleh Kawal Sendiri: FRP projek open source matang—anda kawal penuh NAT traversal ini tanpa kebergantungan pihak ketiga.
• Ciri Keselamatan: Sokongan token pengesahan, SSL/TLS (tls_enable = true), dan kawalan keselamatan dalam ServBay (urus sijil SSL, dsb.) menyediakan perlindungan data semasa transit.

Cadangan Keselamatan:

• Aktifkan Enkripsi TLS: Sangat disyorkan set tls_enable = true dalam [common] supaya sambungan klien-server terenkripsi.
• Gunakan Token Pengesahan Kuat: Guna auth.token yang kompleks dan ubah token anda secara berkala.
• Hadkan Pendedahan Perkhidmatan: Hanya dedahkan servis tempatan/kepada umum yang benar-benar diperlukan.
• Akses Domain, Bukan IP: Untuk servis HTTP/HTTPS, lebih selamat dan mudah audit jika guna domain dalam customDomains berbanding akses terus IP FRP server (jika boleh).
• Amankan Server FRP: Hadkan port terbuka, gunakan firewall dengan konfigurasi ketat.
• Pertimbangkan Kawalan Akses Tambahan: Jika server FRP support, tambah pengesahan atau whitelist IP.

Dengan semua set tetapan di atas, anda kini boleh mendedahkan perkhidmatan pembangunan tempatan dalam ServBay menerusi FRP di internet, sekaligus mempercepat aliran kerja pembangunan anda dengan mudah dan selamat.