Utiliser FRP pour exposer votre environnement de développement ServBay au public (tunneling réseau)

FRP est un outil de proxy inverse performant et facile à prendre en main. Il est particulièrement adapté pour exposer vos services locaux (sites web, API, bases de données, etc.) de façon sécurisée et pratique sur l’Internet public, notamment depuis un environnement de développement. Grâce à son architecture client (frpc) et serveur (frps), FRP permet d'établir facilement un tunnel sécurisé depuis le réseau local vers l’extérieur.

Ce guide détaillé explique comment configurer et utiliser le client FRP (frpc) sur macOS avec ServBay pour accéder en toute sécurité à vos services web locaux depuis Internet. C’est essentiel pour des scénarios comme les démonstrations à distance, le développement collaboratif, la réception de Webhooks ou les tests d’API externes.

Présentation technique du principe

Le fonctionnement de FRP repose sur la création d’un tunnel chiffré entre votre machine locale (où tourne frpc, donc celle avec ServBay) et un serveur distant public (où est lancé frps). Lorsqu’un utilisateur accède à vos services via Internet, il contacte d’abord le serveur public. Celui-ci redirige la requête par le tunnel sécurisé vers le client frpc sur votre machine, qui transmet alors la demande au service local (par exemple, votre site ou API). La réponse suit le chemin inverse jusqu’à l’utilisateur.

Ce mécanisme permet de contourner les limitations de pare-feu ou de routeur et d’exposer vos services locaux à l’extérieur, tout en supportant les protocoles TCP, UDP, HTTP et HTTPS. Cela offre un accès distant puissant à l’environnement de développement ServBay.

Cas d’usages

En combinant ServBay et FRP, vous pouvez répondre aisément à de nombreux besoins de développement :

• Démonstration & collaboration à distance : Présentez votre site/app local en développement à vos collègues ou clients sans déploiement complexe.
• Test de Webhooks : Recevez directement les notifications de Webhook provenant de services tiers (GitHub, Stripe, WeChat Pay, etc.) et déboguez-les localement.
• Tests d’API à plusieurs : Exposez temporairement une API locale à d’autres développeurs/bêta-testeurs externes.
• Tests mobiles : Accédez à vos sites/applications ServBay locaux depuis des appareils mobiles pour vérifier la compatibilité multi-équipements.
• Partages temporaires : Partagez rapidement des fichiers ou services locaux sans configuration fastidieuse.

Prérequis

Avant de configurer FRP, assurez-vous d’avoir :

1. Installé et lancé ServBay : Votre environnement macOS doit avoir ServBay installé et en fonctionnement, avec le site ou service à exposer accessible via navigateur localement.
2. Un serveur FRP public (frps) : Vous devez disposer d’un serveur public (avec IP accessible d’Internet) où tourne le serveur FRP (frps). Ce guide se focalise sur le client FRP (frpc).
3. Un nom de domaine public (optionnel mais recommandé pour HTTP/HTTPS) : Pour accéder à vos services via un domaine et configurer le DNS.
4. Installé le client FRP (frpc) : FRP n'est pas inclus dans ServBay et devra être téléchargé et installé séparément.

Préparation de l’environnement & installation du client FRP

Voici comment installer frpc sur votre Mac qui héberge ServBay :

1. Téléchargement du client FRP : Rendez-vous sur la page FRP Releases sur GitHub et téléchargez la dernière version adaptée à l’architecture de votre macOS.

   • Si vous avez un Mac Apple Silicon (M1/M2/M3, etc.), prenez le fichier frp_*.darwin_arm64.tar.gz.
   • Si vous êtes sur architecture Intel, choisissez frp_*.darwin_amd64.tar.gz.

2. Installation du client FRP : Décompressez l’archive téléchargée puis copiez l’exécutable frpc dans un dossier inclus dans votre PATH système, comme /usr/local/bin, pour pouvoir le lancer depuis n’importe quel terminal.

   Attention, le numéro de version (0.52.3 ici) et l’architecture (darwin_arm64) peuvent changer ; adaptez-les selon votre téléchargement.

   # Supposons que vous ayez téléchargé frp_0.52.3_darwin_arm64.tar.gz
   cd ~/Downloads
   
   # Décompression du fichier (adaptez le nom si besoin)
   tar -zxvf frp_0.52.3_darwin_arm64.tar.gz
   
   # Accédez au dossier décompressé
   cd frp_0.52.3_darwin_arm64
   
   # Copiez frpc dans /usr/local/bin
   sudo cp frpc /usr/local/bin/
   
   # (Optionnel) Copiez aussi le fichier d’exemple frpc.toml dans votre dossier utilisateur
   # cp frpc.toml ~/

   Renseignez votre mot de passe utilisateur pour le sudo si nécessaire.

3. Vérification de l’installation : Ouvrez un nouveau terminal puis tapez :

   frpc -v
   # Vous devriez voir une réponse du style : frpc version 0.52.3

   Si la version s’affiche, l’installation est réussie.

Configuration du tunnel client FRP

La configuration de FRP côté client se fait principalement dans un fichier frpc.toml (le format TOML est recommandé désormais). Ce fichier indique à frpc comment se connecter à votre serveur FRP (frps) et quels services ServBay exposer.

Détail du fichier de configuration frpc.toml

Voici un exemple minimal de structure du fichier, avec les informations de connexion et une règle simple de proxy :

# frpc.toml - Exemple de configuration du client FRP

# [common] : paramètres de connexion client ↔ serveur
serverAddr = "your-frps-server.com" # Adresse IP publique ou nom de domaine du serveur FRP
serverPort = 7000 # Port d'écoute sur le serveur FRP (par défaut 7000)

# Authentification (recommandé : token)
auth.method = "token"
auth.token = "your_authentication_token" # La clé d’authentification, doit matcher la configuration du serveur

# Option : Activez le chiffrement TLS pour plus de sécurité
# tls_enable = true

# [[proxies]] : une ou plusieurs règles de tunnel/proxy
[[proxies]]
name = "my-web-service" # Nom unique du proxy (dans ce fichier)
type = "http" # Type : http, https, tcp, udp, stcp, xtcp, etc.
localIP = "127.0.0.1" # Adresse de votre service local (généralement 127.0.0.1)
localPort = 80 # Port local du service (ex : 80 pour le HTTP ServBay)
customDomains = ["servbay.your-domain.com"] # Domaines d’accès public (HTTP/HTTPS). Doit pointer (DNS) vers votre serveur FRP.

# Ajoutez d’autres blocs [[proxies]] pour d’autres services si nécessaire
# [[proxies]]
# ...

Clé de configuration	Bloc	Description
serverAddr	[common]	IP ou domaine du serveur FRP (frps).
serverPort	[common]	Port d’écoute sur le serveur FRP (par défaut 7000). Adaptez si besoin.
auth.method	[common]	Méthode d’authentification, en général token. Doit être identique sur le serveur et le client.
auth.token	auth (dans [common])	Clé d’auth, à ne jamais divulguer, doit être identique côté serveur.
tls_enable	[common]	Chiffrer le tunnel avec TLS (true conseillé pour plus de sécurité).
[[proxies]]	Racine	Tableau (liste) de tunnels/proxy. Chaque bloc définit une règle d’exposition différente.
name	[[proxies]]	Nom unique du tunnel/proxy dans ce fichier. Choisissez un nom en rapport avec le service exposé.
type	[[proxies]]	Type de proxy (http, https, tcp, udp, etc.), selon le service que vous exposez.
localIP	[[proxies]]	IP locale sur laquelle votre service écoute. Généralement 127.0.0.1 sauf cas spécial.
localPort	[[proxies]]	Port du service local (80 : HTTP, 443 : HTTPS, 3306 : MySQL, etc.).
remotePort	[[proxies]]	(Pour type tcp/udp) Port exposé côté serveur FRP.
customDomains	[[proxies]]	(Type http/https) Domaine(s) par lequel on accède au service depuis Internet. Cette liste doit pointer (DNS) vers votre serveur FRP.
subdomain	[[proxies]]	(http/https, si serveur supporte) Indique le sous-domaine à utiliser si subdomain_host est configuré côté serveur. Alternatif à customDomains.
[proxies.plugin]	[[proxies]]	Pour des plugins particuliers (ex : https2https etc.).
hostHeaderRewrite	[proxies.plugin] ou [[proxies]]	Permet de réécrire le header Host lors de la redirection. Crucial si ServBay utilise cette info pour des hôtes virtuels.

Exemple typique : exposer un site HTTPS ServBay

Par défaut, ServBay configure vos sites locaux en HTTPS et gère les certificats SSL. Pour exposer un service HTTPS local via FRP, il est conseillé d’utiliser le type https et, si nécessaire, le plugin https2https ou simplement hostHeaderRewrite. Comme ServBay utilise l’en-tête Host pour le routage de ses vhosts, il faut impérativement réécrire ce header lors du proxy.

Exemple : exposer un site local ServBay (ex. servbay.test) sur un domaine public (ex. test-frp.servbay.app). Assurez-vous que le domaine public (DNS) pointe bien vers votre serveur FRP (frps.servbay.demo).

Créez un fichier nommé frpc.toml (par exemple dans ~/frpc.toml), puis ajoutez :

# Exemple de frpc.toml – Exposer un site HTTPS ServBay

# [common] : paramètres de connexion au serveur FRP
serverAddr = "frps.servbay.demo" # Votre serveur FRP (IP/Domaine)
serverPort = 7000 # Port du serveur FRP

auth.method = "token"
auth.token = "servbay_demo_token" # Token identique à celui du serveur FRP

# Conseil : activez le chiffrement TLS
tls_enable = true

# [[proxies]] : proxy pour le site HTTPS local
[[proxies]]
name = "servbay-website-https" # Nom du proxy, ex : servbay-test-site
type = "https" # Type HTTPS

# Configuration du domaine public d’accès. Ce domaine doit pointer (DNS) vers votre serveur FRP.
customDomains = ["test-frp.servbay.app"] # Remplacez par votre domaine public désiré

# Détails de la redirection vers ServBay local
localIP = "127.0.0.1"
localPort = 443 # Port HTTPS de ServBay

# Important : réécriture du Host pour le domaine local de ServBay
# Le serveur web (Nginx/Caddy) utilise l’en-tête Host pour distinguer ses vhosts.
hostHeaderRewrite = "servbay.test" # Remplacez par le domaine local de ServBay

# Optionnel : ajouter un header custom pour identifier l’origine de la requête côté backend
[proxies.requestHeaders.set]
x-from-where = "frp-tunnel"

Modifiez les champs serverAddr, serverPort, auth.token, customDomains, hostHeaderRewrite selon vos besoins.

Pourquoi hostHeaderRewrite est-il fondamental ? ServBay gère des sites locaux via son serveur web (Nginx ou Caddy), qui différencie les sites à partir de l’en-tête Host. Si la requête provenant d’Internet via FRP contient comme Host le domaine public (test-frp.servbay.app) au lieu de votre domaine ServBay (servbay.test), le site local ne sera pas reconnu (404 ou mauvais site). La directive hostHeaderRewrite est donc essentielle pour router la bonne requête sur le bon vhost.

Démarrer le client FRP

Après avoir créé et adapté votre frpc.toml, ouvrez un terminal, placez-vous dans le dossier du fichier (ou spécifiez le chemin complet), puis lancez :

# Si le fichier est dans le dossier courant
frpc -c frpc.toml

# Sinon, par exemple depuis le dossier utilisateur
# frpc -c ~/frpc.toml

Cette commande démarre frpc au premier plan et établit le tunnel. Observez le log en temps réel ; la connexion au serveur FRP doit s’établir sans erreur.

Pour exécuter frpc en arrière-plan, utilisez la commande nohup (ou configurez un service launchctl sur macOS pour un fonctionnement plus robuste) :

# Exemple : fichier dans le dossier utilisateur
nohup frpc -c ~/frpc.toml &

Le log sera alors écrit dans nohup.out. Pour une gestion plus élaborée sur macOS, la création d’un agent launchctl est recommandée (non couvert ici).

Vérification et diagnostic

Tester l’accès au service exposé

Après démarrage de frpc (et confirmation de la connexion), ouvrez votre navigateur et allez sur le domaine public configuré (ex. https://test-frp.servbay.app). Vérifiez :

• Que la page charge sans erreur réseau ni erreur de certificat (pour HTTPS).
• Que vous obtenez un HTTP 200 ou le statut attendu.
• Que le contenu correspond à votre accès local (ex. https://servbay.test).
• Pour le HTTPS : vérifiez que le cadenas de sécurité du navigateur s’affiche, et que le certificat SSL est bien valide (émis pour votre domaine public).

Diagnostic via les logs

Les logs du client FRP sont essentiels pour déceler les soucis de connexion ou de redirection. Par défaut, ils s’affichent dans le terminal. Pour augmenter leur niveau de détail (utile pour le débogage) :

frpc -c frpc.toml --log_level debug

Si dans frpc.toml vous avez paramétré un chemin de log (log_file = "/var/log/frpc.log"), vous pouvez suivre ce log en direct :

tail -f /chemin/vers/votre/frpc.log

Résolution des problèmes courants

En cas de problème lors de la configuration ou de l’utilisation de FRP, consultez cette table de dépannage :

Symptôme	Solution
Échec d’authentification	Vérifiez que les champs auth.token et auth.method dans [common] de frpc.toml correspondent exactement à ceux du serveur FRP (frps). Consultez aussi les logs serveur.
Domaine public inaccessible ou non résolu	Vérifiez que le champ customDomains de frpc.toml pointe bien (DNS CNAME ou A) vers le serveur FRP public. Testez avec ping votredomaine.fr. Patientez le temps du cache DNS.
FRP affiche la page d’accueil à la place du service	Le domaine pointe bien vers le serveur FRP, mais il n’y a pas de règle correspondante sur le serveur ou le client. Vérifiez l’exactitude de customDomains et du type (http/https).
Port local occupé ou service inactif	Vérifiez que ServBay tourne et que le service local est bien lancé sur le port indiqué. Utilisez lsof -i :PORT pour vérifier quel programme utilise le port.
Tunnel instable ou déconnexions fréquentes	Contrôlez la stabilité réseau côté Mac et côté serveur FRP. Vous pouvez ajuster des paramètres dans [common], comme heartbeat_timeout = 30 ou pool_count.
Redirection forcée HTTPS	Vérifiez la config du serveur web local (Nginx/Caddy) pour voir si HTTP est redirigé vers HTTPS. Pour exposer HTTP, utilisez type = "http". Pour HTTPS, configurez correctement les certificats ou les plugins nécessaires.
Avertissement certificat HTTPS	Si ServBay utilise un certificat auto-signé ou un CA interne, votre navigateur peut avertir. Installez le CA de confiance, utilisez les plugins FRP adaptés ou un certificat public légitime.
Erreur 404	Vérifiez que hostHeaderRewrite correspond exactement au domaine configuré pour le vhost ServBay local (ex. servbay.test).
Pare-feu du serveur bloque la connexion	Ouvrez les ports nécessaires (par défaut 7000, et ceux exposés) sur le pare-feu du serveur FRP.
Pare-feu local bloque la connexion	Assurez-vous que votre Mac n’a pas de règle bloquant le port serverPort en sortie, ni le port de vos services en local (généralement, macOS autorise par défaut).
Tunnel FRP ouvert mais accès impossible	Cela peut venir d’une mauvaise configuration côté serveur FRP ou d’un problème de routage réseau. Inspectez les logs côté serveur pour détecter l’origine du souci.

Avantages de la solution FRP avec ServBay & conseils de sécurité

Associer FRP à ServBay procure souplesse et efficacité aux développeurs :

• Support multi-protocoles : HTTP, HTTPS, TCP, UDP… Exposez aussi vos bases de données (MySQL, PostgreSQL, MongoDB), Redis, SSH, etc.
• Configuration flexible : Ajoutez facilement plusieurs tunnels dans un seul fichier TOML.
• Contrôle & open source : FRP est libre et mature ; votre service est sous contrôle total, sans dépendance à un prestataire tiers.
• Sécurité : Prise en charge du token d’authentification, du chiffrement TLS (tls_enable = true),… À combiner avec la gestion SSL de ServBay pour une sécurité maximale.

Recommandations de sécurité :

• Chiffrez toujours les connexions FRP (TLS) : Ajoutez tls_enable = true dans [common] pour garantir la confidentialité du tunnel.
• Utilisez un token fort et changez-le régulièrement : Le champ auth.token doit être long et difficile à deviner.
• N’exposez que l’indispensable : Limitez au strict nécessaire les services locaux mis à disposition sur le net.
• Privilégiez l’usage de noms de domaine pour le HTTP/HTTPS : Configurez customDomains et évitez l’accès direct par IP et port si possible.
• Sécurisez votre serveur FRP : Ouvrez uniquement les ports requis, mettez en place des règles de pare-feu.
• Envisagez des contrôles d’accès avancés : Limitez les accès à certaines IP si c’est supporté par votre FRP serveur.

En suivant ces étapes, vous pourrez exposer efficacement et en toute sécurité vos environnements ServBay locaux grâce à FRP, simplifiant grandement vos processus de développement et de collaboration.