Udostępnienie środowiska ServBay na publiczny internet przy pomocy FRP (tunelowanie sieci lokalnej)

FRP to wydajne i łatwe w użyciu narzędzie reverse proxy, wyjątkowo przydatne w sytuacjach, gdy chcesz bezpiecznie oraz wygodnie udostępnić usługi uruchomione lokalnie (np. stronę, API, bazę danych) publicznie. Dzięki architekturze klient-serwer (frpc/frps), FRP efektywnie realizuje tzw. "tunelowanie sieci lokalnej".

Ten przewodnik krok po kroku wyjaśnia użytkownikom ServBay — szczególnie na macOS — jak skonfigurować i używać klienta FRP (frpc), by tworzyć bezpieczne tunele, dzięki którym lokalne usługi webowe uruchomione w ServBay będą dostępne publicznie. To nieocenione np. do zdalnych prezentacji, pracy zespołowej, odbierania webhooków czy testów API z zewnątrz.

Podstawy technologii

Kluczowa idea FRP to zestawienie szyfrowanego tunelu między maszyną wewnątrz sieci lokalnej (z uruchomionym frpc, czyli twoim komputerem z ServBay) a publicznym serwerem (z instalacją frps). Gdy ktoś z internetu próbuje uzyskać dostęp do twoich usług, początkowo trafia na publiczny serwer frps. Serwer ten przekierowuje ruch przez ustanowiony tunel do frpc na twoim komputerze, który z kolei przekazuje żądanie do lokalnie działającego serwisu (np. strony lub API). Odpowiedź wraca tą samą ścieżką do użytkownika zewnętrznego.

FRP omija w ten sposób ograniczenia zapór sieciowych oraz routerów, pozwalając na udostępnienie usług lokalnych na zewnątrz. Obsługuje różne protokoły (TCP/UDP/HTTP/HTTPS), znacząco poszerzając możliwości zdalnego dostępu do środowiska ServBay.

Przykładowe zastosowania

Integracja ServBay z FRP sprawdza się w codziennej pracy dewelopera zwłaszcza w takich scenariuszach, jak:

• Zdalne prezentacje i praca zespołowa: Bez deployowania na serwer, możesz zaprezentować tworzoną stronę lub aplikację współpracownikom czy klientom.
• Testy webhooków: Lokalnie nasłuchuj i debuguj powiadomienia webhook (np. z GitHub, Stripe, WeChat Pay i innych).
• Wspólne testy API: Udostępnij lokalne API frontendowcom albo partnerom do integracji i testowania.
• Testowanie na urządzeniach mobilnych: Przeglądaj lokalnie tworzoną stronę czy aplikację ServBay bezpośrednio na telefonie, testując kompatybilność.
• Tymczasowe udostępnianie: W prosty sposób podziel się plikiem lub usługą lokalną bez skomplikowanej konfiguracji.

Wymagania wstępne

Zanim przystąpisz do konfiguracji FRP, upewnij się, że:

1. ServBay jest zainstalowany i działa: Twój Mac (macOS) ma poprawnie zainstalowany i uruchomiony ServBay, a usługi które chcesz udostępnić (np. strona) są skonfigurowane i dostępne lokalnie przez przeglądarkę.
2. Masz publiczny serwer FRP (frps): Potrzebujesz serwera z publicznym adresem IP oraz zainstalowanym i działającym FRP po stronie serwera (frps). Ten przewodnik skupia się na stronie klienta (frpc).
3. Domena publiczna (opcjonalnie, ale zalecana dla HTTP/HTTPS): Jeśli planujesz dostęp przez domenę, musisz mieć zarejestrowaną własną domenę i możliwość ustawiania rekordów DNS.
4. Zainstalowany klient FRP (frpc): Domyślnie nie jest on dostarczany z ServBay — trzeba pobrać i zainstalować osobno.

Przygotowanie środowiska i instalacja FRP Client

Oto kroki, które poprowadzą cię przez instalację klienta FRP (frpc) na Macu z ServBay:

1. Pobierz klienta FRP: Odwiedź stronę wydań FRP na GitHubie i pobierz NAJNOWSZY plik dla odpowiedniej architektury macOS.

   • Dla Apple Silicon (M1/M2/M3 itd.): pobierz frp_*.darwin_arm64.tar.gz.
   • Dla Intela: pobierz frp_*.darwin_amd64.tar.gz.

2. Zainstaluj klienta FRP: Rozpakuj pobrany plik i skopiuj plik wykonywalny frpc do katalogu znajdującego się w PATH — np. /usr/local/bin. Dzięki temu polecenie frpc będzie dostępne w każdym terminalu.

   Uwaga: Numer wersji (0.52.3 na moment pisania artykułu) i architektura (darwin_arm64) mogą się zmieniać — wpisz odpowiednie dla swojego przypadku.

   # Zakładamy, że pobrałeś plik frp_0.52.3_darwin_arm64.tar.gz
   # Przejdź do katalogu z pobranym plikiem
   cd ~/Downloads
   
   # Rozpakuj archiwum
   tar -zxvf frp_0.52.3_darwin_arm64.tar.gz
   
   # Wejdź do rozpakowanego folderu
   cd frp_0.52.3_darwin_arm64
   
   # Skopiuj 'frpc' do /usr/local/bin
   sudo cp frpc /usr/local/bin/
   
   # (Opcjonalnie) możesz też skopiować przykładowy plik frpc.toml do katalogu domowego
   # cp frpc.toml ~/

   Podaj swoje hasło użytkownika, żeby zakończyć polecenie sudo.

3. Zweryfikuj instalację: Otwórz nowy terminal i wpisz polecenie, by upewnić się, że frpc zainstalowano poprawnie:

   frpc -v
   # Oczekiwany wynik: frpc version 0.52.3

   Jeśli widzisz numer wersji, instalacja przebiegła pomyślnie.

Konfiguracja tunelu FRP Client

Konfigurację klienta zapisuje się w pliku frpc.toml (zalecanym formatem jest TOML). Musisz utworzyć lub edytować ten plik, by określić jak frpc połączy się z serwerem FRP (frps) i które usługi lokalne ServBay mają być wystawione na zewnątrz.

Omówienie pliku konfiguracyjnego frpc.toml

Poniżej podstawowy schemat pliku frpc.toml, pokazujący jak ustawić dane połączenia i podstawowy tunel proxy:

# frpc.toml — przykładowa konfiguracja klienta FRP

# Sekcja [common]: ustawienia połączenia klienta z serwerem
serverAddr = "your-frps-server.com" # Publiczny adres IP lub domena twojego FRP serwera
serverPort = 7000 # Port serwera FRP dla klienta (domyślnie 7000)

# Uwierzytelnianie (zalecane: token)
auth.method = "token"
auth.token = "your_authentication_token" # Klucz zgodny z konfiguracją serwera FRP

# Opcjonalnie: włącz TLS by zaszyfrować połączenie klient-serwer
# tls_enable = true

# Sekcja [[proxies]]: definiowanie jednego lub więcej tuneli proxy
[[proxies]]
name = "my-web-service" # Unikatowa nazwa proxy w ramach pliku
type = "http" # Typ proxy: http, https, tcp, udp, stcp, xtcp
localIP = "127.0.0.1" # IP usługi lokalnej (zwykle 127.0.0.1)
localPort = 80 # Port usługi lokalnej (np. domyślny dla HTTP w ServBay)
customDomains = ["servbay.your-domain.com"] # Domena zewnętrzna (dla typów http/https). MUSI być skierowana przez DNS na IP twojego FRP serwera.

# Kolejne konfiguracje tuneli możesz dodać jako kolejne sekcje [[proxies]]
# [[proxies]]
# ... (definicja kolejnego tunelu)

Parametr	Sekcja	Opis
serverAddr	[common]	Publiczny adres IP lub domena serwera FRP (frps).
serverPort	[common]	Port serwera FRP na potrzeby połączenia klienta; domyślnie 7000. Ustaw odpowiedni do twojej konfiguracji.
auth.method	[common]	Metoda uwierzytelniania; zazwyczaj token. Musi być zgodna z serwerem.
auth.token	auth (w [common])	Sekretny token — wpisz taki sam jak na serwerze. Trzymaj w tajemnicy!
tls_enable	[common]	Czy szyfrować tunel klient-serwer TLS-em. Zalecane ustawienie true.
[[proxies]]	root	Zbiór jednego lub kilku tuneli proxy. Każda sekcja [[proxies]] to oddzielny tunel.
name	[[proxies]]	Nazwa tunelu/proxy — musi być niepowtarzalna w jednym pliku; warto nazwą wskazać przeznaczenie usługi.
type	[[proxies]]	Typ protokołu: http, https, tcp, udp itd. Ustaw odpowiedni do lokalnej usługi.
localIP	[[proxies]]	Lokalny adres IP. Przeważnie zostaw 127.0.0.1.
localPort	[[proxies]]	Port lokalnej usługi; np. 80 dla HTTP, 443 dla HTTPS, 3306 dla MySQL i 5432 dla PostgreSQL.
remotePort	[[proxies]]	(dla tcp/udp) Port na serwerze FRP udostępniany na świat (użytkownicy łączą się przez serverAddr:remotePort).
customDomains	[[proxies]]	(dla http/https) Domena(y), przez które usługa ma być osiągalna. MUSISZ ustawić odpowiedni rekord DNS na IP FRP.
subdomain	[[proxies]]	(dla http/https, przy wsparciu serwera) Możesz ustawić subdomenę, jeśli serwer obsługuje subdomain_host.
[proxies.plugin]	[[proxies]]	Konfiguracja wtyczek, np. https2https do lokalnych serwisów HTTPS.
hostHeaderRewrite	[proxies.plugin] albo [[proxies]]	Przepisanie nagłówka Host w żądaniach do lokalnego serwera — kluczowe dla wirtualnych hostów ServBay.

Typowa konfiguracja: wystawianie strony HTTPS ServBay

ServBay domyślnie konfiguruje strony WWW jako HTTPS i zarządza certyfikatami. Przy wystawianiu przez FRP najlepiej użyć typu https plus opcjonalnie pluginu https2https, albo przekierować port 443 przez tcp. Ponieważ ServBay (Nginx/Caddy) rozpoznaje strony po nagłówku Host, najwygodniej użyć typu https i ustawić hostHeaderRewrite.

Poniżej przykładowa konfiguracja wystawiająca lokalną stronę HTTPS na zewnętrzną domenę. Upewnij się, że domena publiczna (np. test-frp.servbay.app) jest skierowana (CNAME lub A) na adres twojego serwera FRP (frps.servbay.demo).

Utwórz plik frpc.toml (np. ~/frpc.toml) o zawartości:

# frpc.toml — przykład mapowania strony HTTPS ServBay

# [common]: ustawienia serwera FRP
serverAddr = "frps.servbay.demo" # Twój adres serwera (IP/domena)
serverPort = 7000 # Port serwera FRP

auth.method = "token"
auth.token = "servbay_demo_token" # Token zgodny z serwerem FRP

# Zalecane: włącz szyfrowanie TLS
tls_enable = true

# [[proxies]]: tunel dla strony HTTPS ServBay
[[proxies]]
name = "servbay-website-https" # Nazwa proxy, np. servbay-test-site
type = "https" # Typ: HTTPS

# Skonfiguruj domenę publiczną — musi wskazywać na serwer FRP
customDomains = ["test-frp.servbay.app"] # Twoja domena

# Szczegóły przekierowania do lokalnej usługi
localIP = "127.0.0.1" # Typowa adresacja ServBay
localPort = 443 # HTTPS — domyślnie 443

# Kluczowe! Zmień nagłówek Host na domenę ServBay
# Nginx/Caddy w ServBay wybiera aplikację na podstawie Host.
hostHeaderRewrite = "servbay.test" # Domena strony w ServBay (zmień!)

# Opcjonalnie: własne nagłówki dodane do żądania
[proxies.requestHeaders.set]
x-from-where = "frp-tunnel"

W powyższym przykładzie zmień parametry serverAddr, serverPort, auth.token, customDomains, hostHeaderRewrite na odpowiadające twojej sytuacji.

Dlaczego hostHeaderRewrite jest istotny?
ServBay korzysta z serwerów typu Nginx/Caddy, które podstawiają aplikację na podstawie nagłówka Host. FRP domyślnie przekazuje nagłówek z domeną publiczną (test-frp.servbay.app), natomiast ServBay rozpoznaje lokalną stronę po innej domenie (servbay.test). Brak przepisania skutkuje błędem 404 lub inną stroną domyślną. Dlatego musisz ustawić hostHeaderRewrite na domenę lokalną danej strony.

Uruchomienie klienta FRP

Gdy zapiszesz plik frpc.toml, uruchom terminal, przejdź do katalogu z plikiem (lub podaj ścieżkę bezwzględną) i odpal klienta:

# Gdy plik jest w bieżącym folderze
frpc -c frpc.toml

# Albo, jeśli w katalogu domowym
# frpc -c ~/frpc.toml

Polecenie uruchamia frpc w trybie pierwszoplanowym i łączy z frps. Po pomyślnym zestawieniu tunelu zobaczysz odpowiednie logi o aktywnych proxy.

Aby uruchomić frpc w tle, możesz użyć nohup lub narzędzi systemowych macOS (np. launchctl). Dla prostoty:

# Plik w katalogu domowym
nohup frpc -c ~/frpc.toml &

Wynik zostanie wtedy zapisany do nohup.out, a proces przejdzie w tło. Zarządzanie przez launchctl jest bardziej zaawansowane (nie objęte tym artykułem).

Weryfikacja usługi i diagnostyka logów

Weryfikacja

Po starcie frpc i zalogowaniu się, przetestuj serwis w przeglądarce pod wskazaną domeną publiczną (np. https://test-frp.servbay.app) i sprawdź:

• Strona ładuje się bez błędów sieci ani błędów certyfikatu.
• Otrzymujesz kod HTTP 200 lub przewidywany.
• Treść odpowiada tej z lokalnego dostępu pod adresem https://servbay.test.
• Dla HTTPS: sprawdź czy przeglądarka pokazuje kłódkę i certyfikat jest ważny (tzn. wystawiony na twoją domenę publiczną).

Logi i diagnostyka

Logi FRP są kluczowe w diagnostyce połączeń i przekierowań. Domyślnie po uruchomieniu frpc -c frpc.toml trafiają do terminala.

Dla szerszej diagnostyki możesz dodać szczegółowe logi (debug):

frpc -c frpc.toml --log_level debug

Możesz również zapisać logi do pliku przez parametr log_file (np. log_file = "/var/log/frpc.log") w pliku frpc.toml, a następnie śledzić je np. przez:
tail -f /ścieżka/do/frpc.log

Najczęstsze problemy i ich rozwiązania

Jeśli coś pójdzie nie tak, poniżej znajdziesz popularne przypadki i propozycje działań:

Objaw	Rozwiązanie
Błąd uwierzytelniania FRP	Sprawdź, czy token (auth.token) i metoda (auth.method) w [common] zgadzają się z serwerem FRP (frps). Zajrzyj do logów po stronie serwera pod kątem prób błędnego logowania.
Brak dostępu do domeny publicznej lub błędy DNS	Sprawdź, czy domena w customDomains wskazuje przez DNS (CNAME/A) na IP twojego serwera FRP. Pomocne polecenia: ping twoja-domena-frp.com lub narzędzia online do sprawdzania DNS-u. Odczekaj aż zaktualizują się cache DNS.
Strona powitalna FRP przy wejściu przez domenę	To znaczy, że domena jest ustawiona na FRP, ale serwer FRP nie przekierowuje jej do twojego klienta. Sprawdź, czy wpis w customDomains jest literalnie zgodny z wpisywaną domeną i czy type to http lub https. Skontroluj konfigurację serwera pod kątem obsługi domeny.
Zajęty port lokalny lub niedziałający serwis	Sprawdź czy ServBay działa, a usługa faktycznie nasłuchuje na ustalonym porcie (localPort w frpc.toml). Polecenie lsof -i :PORT (zamień PORT na odpowiedni) pokaże które procesy korzystają z portu.
Zrywanie tunelu, kiepska stabilność	Oceń stabilność sieci maszyny z ServBay oraz samego serwera FRP. Możesz wydłużyć timeout w [common] (np. heartbeat_timeout = 30) lub zwiększyć pool_count. Zwróć uwagę na wydajność serwera, zasoby oraz możliwe limity.
Przymusowe przekierowanie HTTP→HTTPS	Zweryfikuj, czy serwer webowy w ServBay (Nginx/Caddy) nie wymusza przekierowań na HTTPS. Jeśli chcesz wystawić HTTP, ustaw type = http i skasuj niepotrzebne pluginy. Dla HTTPS: wybierz type = https oraz ustaw prawidłowe ścieżki certyfikatów lub plugin.
Błędy certyfikatu SSL (ostrzeżenia przeglądarki)	Jeśli używasz tunelu https, a ServBay generuje certyfikaty własne lub CA, możesz zobaczyć ostrzeżenia o niezaufanym certyfikacie — to normalne. Możesz zainstalować CA ServBay, używać pluginu (https2http/https2https) i wskazać certyfikat ServBay, lub posiadać legalny certyfikat na FRP serwerze. Przy tunelu typu https i hostHeaderRewrite — certyfikaty są obsługiwane przez ServBay, a poziom zaufania zależy od statusu lokalnego certyfikatu.
Zwroty 404	Upewnij się, że nagłówek hostHeaderRewrite w frpc.toml ustawiony jest na domenę lokalną skonfigurowaną w ServBay, np. servbay.test. W przeciwnym razie serwer www ServBay nie rozpozna strony.
Firewall na serwerze FRP	Sprawdź, czy na serwerze FRP są otwarte porty serverPort (domyślnie 7000) oraz porty usług (np. 80, 443, własne z remotePort).
Firewall na komputerze lokalnym	Na komputerze Mac upewnij się, że nie zablokowano połączeń wychodzących klienta frpc z portem serwera FRP oraz że nie ograniczono dostępu do portu ServBay (localPort) dla połączeń z 127.0.0.1.
Logi klientów pokazują połączenie OK, ale usługi niedostępne	Sprawdź konfigurację po stronie serwera FRP, logi tamtejsze pod kątem błędów lub prób połączenia. Upewnij się, że serwer przekierowuje odpowiednie porty/domeny.

Zalety integracji FRP z ServBay i zalecenia bezpieczeństwa

Połączenie FRP z ServBay da ci elastyczność i wygodę pracy:

• Wsparcie wielu protokołów: HTTP, HTTPS, TCP, UDP — udostępnisz nie tylko strony, ale też np. lokalne bazy (MySQL/PostgreSQL/MongoDB), Redis, SSH itd.
• Elastyczna konfiguracja: W prostym pliku TOML umieścisz wiele tuneli/proxy dla różnych stron i usług ServBay.
• Open source & pełna kontrola: FRP to dojrzały projekt open source. Masz pełną kontrolę nad swoim tunelem, bez polegania na dostawcach zewnętrznych.
• Bezpieczeństwo: FRP obsługuje tokeny uwierzytelniające oraz tunelowanie TLS (tls_enable = true). To chroni twoje dane w drodze, a w połączeniu z własnym zarządzaniem certyfikatami SSL ServBay — budujesz naprawdę bezpieczne środowisko testowe lub demo.

Praktyczne porady bezpieczeństwa:

• Włącz szyfrowanie TLS: W sekcji [common] zawsze ustaw tls_enable = true, by tunelować ruch przez SSL/TLS.
• Stosuj silne tokeny: Używaj trudnych do odgadnięcia i regularnie wymienianych wartości auth.token.
• Minimalizuj wystawione usługi: Udostępniaj tylko te lokalne serwisy/porty, do których chcesz mieć dostęp z zewnątrz.
• Preferuj domenę nad IP: Dla usług HTTP/HTTPS zawsze korzystaj z customDomains (domena), nie publicznego IP FRP (gdy to możliwe).
• Zadbaj o bezpieczeństwo serwera FRP: Otwórz tylko wymagane porty, skonfiguruj firewall wg potrzeb.
• Rozważ kontrolę dostępu: Jeśli serwer FRP wspiera, ograniczaj dostęp np. po wybranych adresach IP.

Po wykonaniu tych kroków z powodzeniem wystawisz swoje lokalne serwisy z ServBay przez FRP do internetu — co radykalnie poprawi wygodę pracy zespołowej, testów czy prezentacji!