Accesso Pubblico all’Ambiente di Sviluppo Locale ServBay con FRP (Penetrazione NAT)

FRP è uno strumento di reverse proxy ad alte prestazioni e facile da usare, ideale per esporre in maniera sicura e immediata i servizi di sviluppo locale (come siti web, API, database, ecc.) a internet pubblico. Grazie all’architettura composta da client (frpc) e server (frps), FRP consente di superare facilmente le limitazioni di rete locale realizzando un vero “tunneling” verso l’esterno.

Questa guida fornisce le istruzioni dettagliate per gli utenti di ServBay, in particolare su ambiente macOS, su come configurare e utilizzare il client FRP (frpc) per creare tunnel sicuri, così da rendere accessibili via internet i servizi web locali in esecuzione su ServBay. Questa funzionalità è essenziale per demo remote, sviluppo collaborativo, ricezione di richieste Webhook o test di API da sorgenti esterne.

Panoramica Tecnica

Il funzionamento di FRP si basa sull’instaurazione di una connessione criptata dalla macchina locale (dove gira frpc, ovvero la tua macchina con ServBay) verso un server pubblico (dove gira frps). Quando un utente esterno accede ai tuoi servizi pubblicamente, la richiesta arriva prima al server pubblico che ospita frps, il quale poi, tramite il tunnel già stabilito, reindirizza la richiesta al client frpc nella tua rete interna. frpc, a sua volta, inoltra la richiesta al servizio web locale che hai attivo su ServBay (ad esempio, il tuo sito o API). La risposta segue il percorso inverso fino all’utente.

Questo sistema permette di bypassare firewall e router della rete locale, esponendo i servizi interni all’esterno. FRP supporta diversi protocolli come TCP, UDP, HTTP, HTTPS, fornendo un potente accesso remoto agli ambienti di sviluppo ServBay.

Scenari di Utilizzo

Combinando ServBay e FRP puoi gestire agilmente diversi casi pratici di sviluppo:

• Demo remote e collaborazione: Presenta direttamente siti/app in sviluppo al team o ai clienti senza deploy su server esterni.
• Test Webhook: Ricevi notifiche da servizi di terze parti (come GitHub, Stripe o servizi di pagamento) e gestisci il debugging direttamente in locale.
• Debug API: Espone le API backend in sviluppo, consentendo test e collaborazione con i frontender o altri partner.
• Test mobile: Accedi sui dispositivi mobili ai tuoi siti/app ospitati su ServBay per verifiche di compatibilità cross-device.
• Condivisione temporanea: Condividi rapidamente file o servizi locali senza configurazioni complesse.

Prerequisiti

Prima di configurare FRP, verifica di avere:

1. ServBay installato e funzionante: ServBay è già presente e avviato su macOS, e il servizio locale che vuoi esporre (es. sito web) è correttamente configurato e accessibile dal browser in locale.
2. Un server FRP (frps) pubblico: Devi disporre di un server con IP pubblico e aver installato FRP lato server (frps). Questa guida si concentra sulla configurazione lato client (frpc).
3. Dominio pubblico (opzionale ma raccomandato per HTTP/HTTPS): Se vuoi accedere tramite dominio, possiedi un dominio ed è possibile modificarne i record DNS.
4. Client FRP (frpc) installato: Il client FRP non è incluso di default in ServBay; scaricalo e installalo manualmente.

Preparazione dell’Ambiente e Installazione Client FRP

Segui questi step per installare il client FRP (frpc) sul tuo Mac con ServBay:

1. Scarica il client FRP: Vai alla pagina delle Release di FRP su GitHub e scarica l’ultima versione compatibile con l’architettura del tuo macOS:

   • Per Apple Silicon (M1/M2/M3), scegli frp_*.darwin_arm64.tar.gz.
   • Per Intel, scegli frp_*.darwin_amd64.tar.gz.

2. Installa il client FRP: Estrai il file scaricato e copia l’eseguibile frpc in una cartella nel PATH di sistema, come /usr/local/bin, così potrai eseguirlo da qualsiasi terminale.

   Nota: i numeri di versione (0.52.3 in questo esempio) e l’architettura (darwin_arm64) potrebbero cambiare; usa il nome del file realmente scaricato.

   # Supponendo che tu abbia scaricato frp_0.52.3_darwin_arm64.tar.gz
   # Vai nella cartella dei download
   cd ~/Downloads
   
   # Estrai i file (sostituisci con il nome esatto)
   tar -zxvf frp_0.52.3_darwin_arm64.tar.gz
   
   # Accedi alla cartella estratta (sostituisci con la cartella effettiva)
   cd frp_0.52.3_darwin_arm64
   
   # Copia frpc in /usr/local/bin
   sudo cp frpc /usr/local/bin/
   
   # (Opzionale) Copia anche il file di esempio frpc.toml nella home
   # cp frpc.toml ~/

   Inserisci la tua password utente per completare il comando sudo.

3. Verifica l’installazione: Apri un nuovo terminale ed esegui:

   frpc -v
   # Output atteso: frpc version 0.52.3

   Se vedi la versione, l’installazione è completata con successo.

Configurazione del Tunnel Client FRP

La configurazione del client FRP si effettua tramite il file frpc.toml (il formato TOML è ora raccomandato). Dovrai creare/modificare questo file per specificare come frpc si connette al server FRP (frps) e quali servizi ServBay vuoi esporre.

Dettaglio del file di configurazione frpc.toml

Ecco un esempio base della struttura di frpc.toml che include i parametri per la connessione e la definizione di un tunnel proxy:

# frpc.toml - Esempio di configurazione client FRP

# Sezione [common]: parametri di connessione verso il server FRP
serverAddr = "your-frps-server.com" # IP pubblico o dominio del tuo server FRP
serverPort = 7000 # Porta di ascolto per le connessioni client (default 7000)

# Autenticazione (si raccomanda l’uso di token)
auth.method = "token"
auth.token = "your_authentication_token" # Secret condiviso col server FRP

# Opzionale: abilita la connessione TLS criptata per maggiore sicurezza
# tls_enable = true

# Sezione [[proxies]]: definizione di uno o più tunnel proxy
[[proxies]]
name = "my-web-service" # Nome univoco del proxy nel file frpc.toml
type = "http" # Tipo di proxy: http, https, tcp, udp, stcp, xtcp ecc.
localIP = "127.0.0.1" # IP locale del servizio da esporre (default 127.0.0.1)
localPort = 80 # Porta locale del servizio (es. porta HTTP predefinita ServBay)
customDomains = ["servbay.your-domain.com"] # Dominio pubblico per accesso esterno (solo http/https). **Assicurati che il DNS punti all’IP del server FRP**

# Puoi aggiungere altre regole [[proxies]] per altri servizi
# [[proxies]]
# ... (altra configurazione tunnel)

Parametro	Sezione	Descrizione
serverAddr	[common]	IP pubblico o dominio del server FRP (frps).
serverPort	[common]	Porta d’ascolto delle connessioni client dal server FRP (default 7000). Modifica in base alla configurazione effettiva lato server.
auth.method	[common]	Metodo di autenticazione del client verso il server, tipicamente token. Deve corrispondere alla configurazione lato server.
auth.token	[common] → auth	Secret di autenticazione condiviso col server. Non divulgare.
tls_enable	[common]	Attiva la connessione criptata TLS tra client e server. Consigliata.
[[proxies]]	livello radice	Array di regole proxy. Ogni blocco [[proxies]] configura un mapping individuale.
name	[[proxies]]	Nome del tunnel proxy, unico nel file. Scegli nomi descrittivi.
type	[[proxies]]	Protocollo proxy: http, https, tcp, udp. Scegli quello adatto al tuo servizio locale.
localIP	[[proxies]]	Indirizzo IP locale da esporre. Di default 127.0.0.1.
localPort	[[proxies]]	Porta locale del servizio. Es. HTTP di ServBay 80, HTTPS 443, MySQL 3306, PostgreSQL 5432, ecc.
remotePort	[[proxies]]	(Solo proxy tcp/udp) Porta pubblica esposta dal server FRP. Gli utenti esterni accedono tramite serverAddr:remotePort.
customDomains	[[proxies]]	(Solo proxy http/https) Domeni usati per accedere al servizio. Array di stringhe, supporta più domìni. DNS deve puntare all’IP del server.
subdomain	[[proxies]]	(Solo per http/https se abilitato lato server) Sottodominio. Se configurato, l’indirizzo pubblico sarà subdomain.subdomain_host.
[proxies.plugin]	[[proxies]]	Configurazione plugin specifici, es. https2https per gestire servizi HTTPS locali.
hostHeaderRewrite	[proxies.plugin] o [[proxies]] (a seconda del tipo/plugin)	Riscrive il campo Host della richiesta inoltrata. Fondamentale per la gestione dei virtual host in ServBay. Imposta il dominio locale giusto.

Esempio tipico: Mapping di un sito HTTPS su ServBay

Per default, ServBay configura automaticamente siti locali con HTTPS e gestisce i certificati SSL. Se vuoi esporre tale sito tramite FRP, si consiglia di usare il proxy https e il plugin hostHeaderRewrite, o altrimenti il proxy tcp per inoltrare la porta 443. In ServBay, il virtual hosting dipende dall’header Host, quindi si raccomanda la modalità https con hostHeaderRewrite.

Ecco un esempio di mapping di un sito HTTPS configurato su ServBay (con dominio locale servbay.test) su un dominio pubblico (test-frp.servbay.app) tramite FRP. Assicurati che il dominio pubblico puntato da DNS (CNAME o A) all’IP del server FRP (frps.servbay.demo).

Crea un file chiamato frpc.toml (ad es. nella home ~/frpc.toml) e inserisci:

# Esempio frpc.toml - Mapping sito HTTPS su ServBay

# [common]: parametri di connessione server FRP
serverAddr = "frps.servbay.demo" # Sostituisci con il tuo indirizzo server FRP
serverPort = 7000 # Sostituisci con la porta effettiva

auth.method = "token"
auth.token = "servbay_demo_token" # Sostituisci con il token configurato sul server

# Raccomandato: Abilita TLS lato client-server
tls_enable = true

# [[proxies]]: mapping del sito HTTPS locale ServBay
[[proxies]]
name = "servbay-website-https" # Nome personalizzabile
type = "https" # Tipo proxy

# Dominio pubblico esposto. Deve essere già risolto verso l’IP server FRP
customDomains = ["test-frp.servbay.app"] # Sostituisci con il dominio pubblico desiderato

# Parametri inoltro richieste al servizio locale ServBay
localIP = "127.0.0.1"
localPort = 443 # HTTPS default ServBay

# Importante: riscrivi l’header Host per match con il dominio locale ServBay
# Fondamentale per la gestione dei virtual host da parte di Nginx/Caddy
hostHeaderRewrite = "servbay.test" # Sostituisci con il dominio locale giusto

# Opzionale: aggiungi header personalizzato per identificare il tunnel FRP
[proxies.requestHeaders.set]
x-from-where = "frp-tunnel"

Sostituisci serverAddr, serverPort, auth.token, customDomains e hostHeaderRewrite secondo la tua situazione reale.

Perché è cruciale hostHeaderRewrite: ServBay gestisce i siti web tramite server come Nginx o Caddy, che smistano le richieste basandosi sull’header Host. Quando la richiesta arriva a ServBay tramite tunnel FRP, il campo Host riflette il dominio pubblico (es. test-frp.servbay.app) e non il dominio locale (servbay.test), quindi il server web non riconosce correttamente il sito e può restituire errore 404 o una pagina di default. Impostare hostHeaderRewrite con il valore del dominio locale ServBay risolve questo problema.

Avvio del client FRP

Dopo aver salvato il file frpc.toml, apri il terminale e posizionati nella cartella dove risiede il file (se è nella home ~/frpc.toml, puoi specificarlo dal percorso completo). Avvia quindi FRP con:

# Se frpc.toml è nella directory corrente
frpc -c frpc.toml

# Se invece è nella home
# frpc -c ~/frpc.toml

FRP verrà eseguito in foreground e tenterà la connessione al server frps. Se tutto è corretto vedrai i log che confermano la creazione del tunnel e l’attivazione del proxy.

Se vuoi far girare frpc in background, puoi usare nohup oppure strumenti nativi come launchctl su macOS:

# Avvio in background del client FRP
nohup frpc -c ~/frpc.toml &

Con nohup il log sarà rediretto su nohup.out e il processo rimarrà in background. Per una gestione professionale dei servizi in macOS, launchctl è preferibile ma fuori scope in questa guida.

Verifica del Servizio e Analisi Log

Test del servizio

Dopo aver avviato frpc e aver visto dai log che la connessione è stabilita, apri il browser e visita il dominio pubblico configurato (es. https://test-frp.servbay.app). Controlla quanto segue:

• La pagina si carica senza errori di connessione, TLS o di altro tipo.
• Ricevi codice HTTP 200 o quelli previsti dal servizio.
• Il contenuto della pagina coincide con l’accesso locale su https://servbay.test.
• Se è HTTPS, controlla che appaia il lucchetto nella barra degli indirizzi, a indicare che il certificato SSL è valido (emesso per il tuo dominio pubblico).

Analisi e monitoraggio dei log

I log del client FRP sono fondamentali per il debugging. Lanciando frpc -c frpc.toml, i log appaiono sul terminale. Consulta l’output per errori o warning.

Per dettagli maggiori durante la risoluzione problemi, avvia il client in modalità debug:

frpc -c frpc.toml --log_level debug

Se nel file frpc.toml è specificato il parametro log_file (es. log_file = "/var/log/frpc.log"), i messaggi verranno salvati in quel file. Monitora il log in tempo reale con:

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

Troubleshooting – Risoluzione dei Problemi Comuni

Ecco le problematiche più frequenti e le relative soluzioni:

Problema	Soluzione
Autenticazione con il server FRP fallita	Verifica che auth.token e auth.method in [common] corrispondano esattamente a quelli configurati sul server FRP (frps). Consulta anche il log lato server per eventuali errori di autenticazione.
Dominio pubblico non accessibile o DNS errato	Assicurati che il dominio in customDomains abbia un record DNS (CNAME/A) puntato all’IP pubblico del server FRP. Usa ping tuodominio.com o strumenti online per verificarne la risoluzione. Aspetta il refresh DNS.
Il dominio pubblico mostra la welcome page di FRP	Il dominio risolve correttamente, ma il server FRP non inoltra la richiesta al client. Verifica che il nome in customDomains e il tipo sia http/https. Controlla le regole lato server.
Porta locale non disponibile o servizio non avviato	Verifica che ServBay sia attivo e il servizio sia in ascolto sulla porta configurata in localPort di frpc.toml. Usa lsof -i :PORT per controllare la porta.
Tunnel instabile o disconnessioni frequenti	Controlla la connettività sia della macchina ServBay che del server FRP. Puoi aumentare heartbeat_timeout = 30 in [common] e regolare pool_count. Analizza i log lato server per errori o limiti di risorse.
La navigazione HTTP forza il redirect su HTTPS	Verifica che la configurazione di Nginx/Caddy in ServBay non forzi il redirect HTTP→HTTPS se vuoi esporre HTTP. Se necessario, imposta il tipo tunnel su http e rimuovi plugin superflui.
Warning certificato HTTPS nel browser	Se usi un certificato CA privata (ad es. generato da ServBay), i browser potrebbero mostrare warning. Per eliminare l’avviso, importa la CA ServBay sul dispositivo. In alternativa, configura plugin/FRP server con un certificato valido.
Errore 404 sul dominio esposto	Verifica che hostHeaderRewrite sia impostato correttamente col dominio locale configurato in ServBay (es. servbay.test), in modo che il webserver riconosca la virtual host giusta.
Firewall del server FRP blocca la connessione	Assicurati che il firewall del server FRP abbia aperte sia la porta serverPort (default 7000) che le porte pubbliche usate dai servizi (HTTP 80, HTTPS 443 o altre).
Firewall locale blocca la connessione	Verifica che la macchina ServBay consenta connessioni in uscita sul serverPort di FRP e non blocchi i servizi in ascolto su localPort da 127.0.0.1.
Log client FRP: connessione riuscita ma servizio non raggiungibile	Potrebbe trattarsi di un problema lato server FRP o di routing di rete. Controlla i log lato server (frps) e verifica la presenza delle regole corrette.

Vantaggi della Soluzione FRP in Ambiente ServBay e Consigli di Sicurezza

Utilizzare FRP insieme a ServBay offre massima flessibilità e rapidità agli sviluppatori:

• Supporto multi-protocollo: FRP gestisce HTTP, HTTPS, TCP, UDP — puoi esporre in modo sicuro anche database locali (MySQL, PostgreSQL, MongoDB), Redis, SSH e altro.
• Configurazione versatile: Il formato TOML permette mapping multipli in modo semplice, così esponi in un colpo solo vari siti/servizi ServBay.
• Open source e personalizzabile: FRP è open source e sotto il tuo pieno controllo, senza dipendere da piattaforme di terzi.
• Sicurezza robusta: FRP supporta token di autenticazione e tunneling criptato TLS (tls_enable = true), garantendo la sicurezza dei dati. Con gli strumenti di gestione SSL di ServBay, costruisci un ambiente ancora più sicuro.

Consigli di sicurezza:

• Attiva TLS: Imposta tls_enable = true in [common] per criptare la connessione client-server.
• Usa un token forte: Imposta un auth.token complesso e difficile da indovinare; cambia periodicamente il secret.
• Esporre solo il necessario: Rendi pubblici solo i servizi indispensabili.
• Preferisci domini pubblici ai soli IP: Per HTTP/HTTPS, usa customDomains per un accesso sicuro via dominio (evita l’accesso diretto tramite IP).
• Sicurezza lato server FRP: Tieni il server FRP sicuro, esponi solo le porte indispensabili e imposta regole firewall efficaci.
• Valuta il controllo accessi: Se supportato dal server FRP, imposta restrizioni per IP o altri sistemi di controllo avanzato.

Seguendo i passaggi e i suggerimenti descritti, potrai esporre i tuoi servizi locali ServBay tramite FRP su internet pubblico, ottimizzando il flusso di sviluppo e collaborazione.