Guida alla configurazione del servizio di reverse proxy frp in ServBay

frp (Fast Reverse Proxy) è un'applicazione ad alte prestazioni per reverse proxy che consente di rendere visibili in modo sicuro i servizi di rete locali su Internet. ServBay integra la funzionalità di client frp (frpc), permettendoti di collegarti al tuo server frp (frps) auto-ospitato e di accedere ai siti web locali gestiti in ServBay tramite domini personalizzati. Questo metodo ti offre il pieno controllo sul server tunnel.

Questa guida fornisce istruzioni dettagliate su come configurare il client frp in ServBay e collegarlo al proprio server frps.

Panoramica

A differenza di altri servizi tunnel gestiti disponibili in ServBay, l'uso di frp richiede di aver già installato e configurato un server frps su una propria macchina. ServBay funge da client frpc; si occupa di inoltrare il traffico dal tuo sito locale, attraverso il server frps, su Internet. Questo modello è indicato per gli sviluppatori che desiderano il massimo controllo e personalizzazione sul sistema di tunneling.

Scenari di utilizzo

• Controllo totale sul server tunnel: Puoi gestire completamente la configurazione, la sicurezza e le prestazioni del server frps.
• Utilizzo di domini e SSL personalizzati: Configura facilmente qualsiasi dominio di tua proprietà per i tuoi progetti locali ed integra i certificati SSL ACME gestiti da ServBay.
• Configurazioni di rete avanzate: frp supporta diversi tipi di proxy e impostazioni avanzate, per esigenze complesse.
• Deployment privato: Ideale se non vuoi dipendere da servizi tunnel di terze parti.

Prerequisiti

1. ServBay installato: Verifica che ServBay sia correttamente installato e funzionante sul tuo sistema macOS.
2. Server frps self-hosted:
   • Necessiti di un server accessibile pubblicamente su cui hai installato e avviato il servizio frps.
   • Prendi nota dell'indirizzo IP pubblico o del dominio del server frps.
   • Annota il bindPort (porta per la comunicazione tra client e server frp) e il token (token di autenticazione) specificati nel file di configurazione di frps (frps.toml o frps.ini).
3. Dominio e configurazione DNS:
   • Serve un dominio pubblico (es. your-frp-server.com) con relativo record A che punti all'IP pubblico del server frps. Userai questo dominio per l’accesso ai tuoi siti in locale.
4. Certificato ACME SSL in ServBay:
   • Per rendere accessibile il dominio esterno tramite HTTPS, richiedi anticipatamente un certificato SSL ACME per tale dominio usando la funzione SSL Certificates di ServBay. Ad esempio, se vuoi usare project.your-frp-server.com, ottieni un certificato per tale dominio.
5. Domini secondari multipli e certificati SSL:
   • Se vuoi usare più sottodomini senza dover configurare molteplici record A, puoi utilizzare il carattere jolly *: aggiungi un record A per *.your-frp-server.com che punti all'IP pubblico del server frps. Richiedi un certificato ACME wildcard tramite ServBay includendo il dominio di secondo livello e il wildcard nella richiesta (es. scrivi your-frp-server.com, *.your-frp-server.com nel campo Domain, con il wildcard come ultimo ed i domini separati da virgola). Poi potrai aggiungere liberamente nuovi sottodomini in ServBay senza modificare i record DNS, riutilizzando lo stesso certificato SSL.
   • In questo modo, puoi facilmente offrire accesso esterno usando domini come company-project.your-frp-server.com, personal.your-frp-server.com, customer-1.your-frp-server.com direttamente da ServBay, senza impostare più record A e condividendo lo stesso certificato SSL.

Procedura operativa

1. Installa il pacchetto frp in ServBay

1. Apri l'applicazione ServBay.
2. Dal menu laterale, seleziona Software package (Pacchetti).
3. Cerca frp nell’elenco pacchetti.
4. Premi il pulsante di installazione accanto a frp.
5. Dopo l’installazione, il tentativo di avvio di frp potrebbe fallire perché la configurazione non è ancora stata completata: è normale.

2. Prepara il tuo server frps e la configurazione

Devi installare e avviare frps manualmente sul tuo server pubblico. ServBay può generare per te un template base di frps.toml (per versioni frp recenti) per velocizzare la configurazione:

1. In ServBay, vai su Tunnel -> frp.

2. Individua e clicca l'icona a discesa o di espansione accanto a frp server config (frps.toml). ServBay mostrerà un esempio di frps.toml simile al seguente:

   # Il file di configurazione frps generato automaticamente da ServBay
   # è pensato per l'utilizzo diretto sul server.
   # Modifica i parametri secondo le tue esigenze.
   bindPort = 12345
   auth.method = "token"
   auth.token = "myserverpassword"
   
   vhostHTTPPort = 80
   vhostHTTPSPort = 443
   
   log.to = "/tmp/frps.log"
   log.level = "info"
   log.maxDays = 3
   log.disablePrintColor = true
   
   # Per le versioni più recenti di frps (ad esempio 0.52.0+), usa webServer.port, webServer.addr, webServer.user, webServer.password per la Dashboard
   # webServer.port = 7500
   # webServer.addr = "0.0.0.0"
   # webServer.user = "admin"
   # webServer.password = "admin_password"

3. Note chiave sulle impostazioni:

   • bindPort: Porta per la comunicazione tra frpc e frps. Assicurati che sia aperta nel firewall del server. Si raccomanda fortemente di proteggere l’accesso a questa porta con regole firewall (ad es. consentendo solo IP specifici).
   • auth.method = "token" e auth.token: Per autenticazione client. Modifica il valore con una password robusta.
   • vhostHTTPPort = 80 e vhostHTTPSPort = 443: Porte usate da frps per le richieste HTTP e HTTPS ai virtual host.
     • [Fondamentale] ServBay è ottimizzato per scenari in cui il server frps usa direttamente le porte 80 e 443 rispettivamente come vhostHTTPPort e vhostHTTPSPort. Così ServBay può trasmettere senza soluzione di continuità i certificati SSL ACME locali a frps per l’uso dai client.
     • Se, per qualsiasi ragione, il server frps non può usare direttamente le porte 80/443 (ad esempio già impegnate), sarà necessario configurare un ulteriore reverse proxy (Nginx o Caddy) davanti a frps che ascolti sulle porte pubbliche 80/443 e inoltri il traffico alle porte effettive di frps. In questo caso, i certificati SSL saranno gestiti dal reverse proxy e non più da ServBay.
   • log.to: Percorso file di log di frps.
   • Opzioni Dashboard (come webServer.port): Optional, per l’accesso all’interfaccia web di frps.

4. Copia questa configurazione sul tuo server, salvala come frps.toml (o frps.ini, se preferisci/necessario in base alla versione) e personalizza i parametri secondo le tue esigenze.

5. Avvia il servizio frps sul server.

3. Configurare il client frp in ServBay

Torna all’app ServBay e compila i parametri di connessione del client frp:

1. Vai su Tunnel -> frp.

2. Inserisci i dati del tuo server frps:

   • Server Address (Indirizzo server): Inserisci il dominio o l’indirizzo IP pubblico del tuo server frps (es: my.test.frp.server.host).
   • Server Port (Porta server): Inserisci il valore bindPort impostato in frps.toml (es: 12345).
   • Auth Token (Token autorizzazione): Inserisci il valore auth.token settato in frps.toml (es: myserverpassword).

3. Configura le regole di mapping dei tunnel:

   • Local Domain (Sito locale): Dal menu a tendina, seleziona il sito ServBay che vuoi esporre tramite frp su Internet (es: servbay.demo).
   • External Domain (Dominio esterno): Inserisci il dominio pubblico che i visitatori useranno per accedere al sito locale (es: test.ks.do). Il record DNS A di questo dominio deve già puntare all’IP del server frps.
     • Nota importante: A differenza delle altre configurazioni Tunnel disponibili in ServBay (come Ngrok, Cloudflared), qui va inserito il dominio completo.
   • ACME Certificates (Certificato ACME): Dal menu a tendina, seleziona il certificato ACME già richiesto in ServBay per il dominio inserito (es: il certificato di test.ks.do).
     • Nota: Se vuoi rendere disponibile il dominio esterno in HTTPS, seleziona il certificato corretto in questa sezione. ServBay trasmetterà il certificato a frpc, che – collegandosi a frps – lo utilizzerà per rispondere alle richieste HTTPS. Non è quindi necessario configurare SSL manualmente su frps per questo dominio; ServBay lo gestisce automaticamente.

4. Aggiunta di altri tunnel:

   • Se hai bisogno di mappare più siti locali o più domini esterni, clicca il pulsante + a lato della riga per aggiungere nuove configurazioni tunnel.

4. Salva la configurazione e avvia il servizio frp

1. Dopo aver completato la configurazione, clicca il pulsante Salva in basso a destra.
2. ServBay salverà la configurazione di frpc e proverà ad avviare il servizio frp.
3. Controlla lo stato indicato dalla spia accanto a frp nella lista Tunnel. Se tutto è corretto e la connessione frpc->frps riesce, la spia diventerà verde, segnalando il servizio attivo.
4. Verifica accesso:
   • Ora dovresti poter accedere al sito locale dall’esterno tramite il dominio configurato (es: https://test.ks.do).
   • Clicca sull'icona di copia o sull'icona browser accanto al dominio esterno per testare l’accesso.

Avvertenze

• Deployment e gestione server frps: Sei pienamente responsabile dell’installazione, configurazione, sicurezza e manutenzione del tuo server frps.
• Sicurezza della bindPort di frps: Usa un auth.token forte e preferibilmente limita l’accesso alla porta bindPort tramite firewall su IP/IP range specifici.
• Scelta delle porte vhostHTTPPort e vhostHTTPSPort:
  • Consigliato far ascoltare direttamente a frps le porte 80 e 443 come vhost, così si sfrutta la trasmissione trasparente del certificato SSL ACME di ServBay.
  • Se frps usa porte vhost diverse da 80/443, dovrai configurare un reverse proxy (Nginx/Caddy) che ascolti sulle porte pubbliche 80/443 e rigiri il traffico sulle porte frps; in questo caso sarà il reverse proxy a gestire l’SSL.
• Necessità del certificato ACME: Se desideri accesso HTTPS, richiedilo in ServBay e selezionalo nella configurazione frp.
• Propagazione DNS: Assicurati che il record A del dominio esterno punti all’IP del server frps e sia propagato correttamente su Internet.

FAQ (Domande frequenti)

• D: Il servizio frp su ServBay non si avvia e la spia è rossa o arancione: cosa posso fare?
  • R: Verifica che in ServBay i parametri Server Address, Server Port e Auth Token coincidano esattamente con bindPort e auth.token su frps.toml. Verifica che il server frps sia effettivamente in esecuzione e la porta sia raggiungibile dal tuo Mac (controlla eventuali firewall). Consulta i log di frp su ServBay per dettagli sugli errori.
• D: Riesco ad accedere con il dominio esterno ma solo in HTTP (non HTTPS)?
  • R: Assicurati di aver selezionato il certificato ACME nel campo corrispondente della configurazione frp in ServBay, e che in frps.toml la variabile vhostHTTPSPort sia impostata correttamente (idealmente su 443).
• D: Il mio server frps deve usare porte vhost diverse da 80/443, come posso gestire l’SSL?
  • R: In tal caso, installa davanti a frps un reverse proxy (come Nginx o Caddy) che ascolti su 80/443, si occupi dell’SSL (puoi gestirlo autonomamente, senza ServBay) e inoltri il traffico alle porte effettive di frps. In questo scenario, il campo ACME Certificates di ServBay non verrà più utilizzato direttamente per SSL pubblico, perché il certificato verrà gestito dal reverse proxy sul server.
• D: Il file frps.toml generato da ServBay è diverso dal mio frps.ini?
  • R: Il formato delle configurazioni di frp sta migrando progressivamente da .ini a .toml. ServBay offre un template .toml. Se usi una versione frps vecchia o preferisci .ini, consulta la documentazione ufficiale frp e adatta la configurazione. I parametri fondamentali sono equivalenti.

Riepilogo

ServBay integra un potente client frp fornendo agli sviluppatori macOS una soluzione di tunneling altamente personalizzabile e controllabile. Grazie al deployment autonomo di un server frps, unite alle comode opzioni di configurazione frpc e gestione certificati ACME SSL in ServBay, puoi esporre in maniera sicura e flessibile i tuoi siti di sviluppo locale su Internet. Presta sempre la massima attenzione alla configurazione di frps e frpc, in particolare in merito alle porte e alla sicurezza, per garantire stabilità ed affidabilità del servizio.