Acesso Público ao Ambiente de Desenvolvimento Local do ServBay com FRP (Furo de Firewall)

O FRP é uma ferramenta de proxy reverso de alto desempenho, fácil de usar e especialmente indicada para cenários onde é necessário expor serviços de desenvolvimento local (como sites, APIs, bancos de dados, etc.) de forma segura e prática para a internet pública. Utilizando a arquitetura cliente (frpc) e servidor (frps), o FRP possibilita o furo de firewall de forma eficiente.

Este guia fornece instruções detalhadas para usuários do ServBay, especialmente em ambientes macOS, sobre como configurar e utilizar o cliente FRP (frpc) para criar túneis seguros, permitindo que serviços web em execução no seu ServBay sejam acessíveis externamente. Isso é essencial para demonstrações remotas, desenvolvimento colaborativo, receber webhooks ou realizar testes de APIs externas.

Visão Geral do Funcionamento Técnico

O princípio central do FRP é estabelecer um túnel de comunicação criptografado entre a máquina local (onde roda o frpc, ou seja, seu Mac com ServBay) e um servidor público (onde roda o frps). Quando um usuário externo acessa seu serviço pela internet, a solicitação chega primeiro ao servidor público com frps, que então, através do túnel criado anteriormente, repassa a requisição ao seu cliente frpc na rede local. O cliente frpc encaminha então ao serviço local no ServBay (por exemplo, seu site ou API). A resposta do serviço segue o caminho inverso até o usuário externo.

Esse mecanismo permite contornar restrições impostas por firewalls e roteadores da rede interna, expondo com segurança os serviços locais para acesso público, suportando protocolos como TCP, UDP, HTTP e HTTPS — tudo isso fortalecendo o acesso remoto ao ambiente de desenvolvimento do ServBay.

Cenários de Aplicação

Combinando ServBay e FRP, você pode facilmente cobrir diversas competências do desenvolvimento moderno:

• Demonstrações Remotas e Colaborativas: Demonstre o site ou app em desenvolvimento diretamente para clientes ou equipe, sem necessidade de deploy em servidor remoto.
• Testes de Webhook: Receba notificações de webhooks de serviços externos (como GitHub, Stripe, WeChat Pay, etc.) diretamente em sua máquina, depurando lógica local.
• Integração de APIs: Exponha APIs back-end feitas localmente para testes integrados com desenvolvedores front-end ou parceiros externos.
• Testes em Dispositivos Móveis: Acesse e teste sites ou apps do ServBay diretamente em dispositivos móveis, validando compatibilidade entre plataformas.
• Compartilhamento Temporário: Compartilhe rapidamente arquivos ou serviços locais sem configuração complexa.

Pré-Requisitos

Antes de configurar o FRP, certifique-se de atender aos seguintes pontos:

1. ServBay Instalado e em Execução: Seu Mac deve estar com ServBay instalado e funcionando, e o serviço local a ser exposto (como o site) já configurado e acessível localmente via navegador.
2. Servidor FRP Público em Funcionamento (frps): É necessário um servidor com IP público, com o FRP servidor (frps) instalado, rodando e configurado. Este guia foca na configuração do cliente (frpc).
3. Domínio Público (opcional, mas recomendado para HTTP/HTTPS): Se deseja acessar via domínio, tenha um domínio próprio com DNS configurável.
4. Cliente FRP Instalado (frpc): O FRP cliente não está incluso no ServBay, é preciso baixá-lo e instalar separadamente.

Preparando o Ambiente e Instalando o Cliente FRP

Siga os passos abaixo para instalar o cliente FRP (frpc) em seu Mac com o ServBay.

1. Baixar o Cliente FRP: Visite a página de Releases do FRP no GitHub e baixe o pacote mais recente compatível com a arquitetura de seu macOS:

   • Para Apple Silicon (M1/M2/M3), baixe o arquivo frp_*.darwin_arm64.tar.gz.
   • Para Intel, baixe o arquivo frp_*.darwin_amd64.tar.gz.

2. Instalar o Cliente FRP: Extraia o arquivo baixado e copie o executável frpc para um diretório no PATH do sistema, por exemplo, /usr/local/bin, para poder rodá-lo de qualquer terminal.

   Atenção: Ajuste o número da versão (0.52.3 usado neste exemplo pode estar desatualizado) e arquitetura (darwin_arm64) conforme o nome do arquivo que você baixou.

   # Supondo que você baixou frp_0.52.3_darwin_arm64.tar.gz
   # Acesse a pasta de Downloads
   cd ~/Downloads
   
   # Extraia o arquivo (substitua pelo nome que baixou)
   tar -zxvf frp_0.52.3_darwin_arm64.tar.gz
   
   # Acesse a pasta extraída
   cd frp_0.52.3_darwin_arm64
   
   # Copie o executável frpc para /usr/local/bin
   sudo cp frpc /usr/local/bin/
   
   # (Opcional) Pode copiar o arquivo de exemplo frpc.toml para seu diretório pessoal
   # cp frpc.toml ~/

   Digite sua senha de usuário para concluir o comando sudo.

3. Verificando Instalação: Abra um novo terminal, rode o comando abaixo para verificar se o frpc foi instalado corretamente e adicionado ao PATH:

   frpc -v
   # Saída esperada: frpc version 0.52.3

   Se visualizar a versão, a instalação foi bem-sucedida.

Configurando o Túnel no Cliente FRP

A configuração do FRP é feita em um arquivo chamado frpc.toml (o formato TOML é recomendado para as versões mais recentes). Nele você define como o frpc se conecta ao FRP servidor (frps) e quais serviços locais do ServBay serão expostos externamente.

Explicando o Arquivo frpc.toml

Veja um exemplo básico de estrutura do frpc.toml, com informações essenciais de conexão e exemplo de configuração de túnel:

# frpc.toml - Exemplo de configuração do cliente FRP

# [common]: Configuração de conexão do cliente com o servidor
serverAddr = "your-frps-server.com" # IP público ou domínio do servidor FRP
serverPort = 7000 # Porta do servidor FRP para conexão do cliente (padrão: 7000)

# Autenticação (recomendado usar token)
auth.method = "token"
auth.token = "your_authentication_token" # Token idêntico ao configurado no servidor FRP (frps)

# Opcional: ativa criptografia TLS entre cliente e servidor para maior segurança
# tls_enable = true

# [[proxies]]: Definição de uma ou mais configurações de túnel
[[proxies]]
name = "my-web-service" # Nome único do proxy neste arquivo
type = "http" # Tipo do proxy: http, https, tcp, udp, stcp, xtcp, etc.
localIP = "127.0.0.1" # IP local do serviço, padrão é 127.0.0.1
localPort = 80 # Porta do serviço local (por exemplo, 80 para HTTP do ServBay)
customDomains = ["servbay.your-domain.com"] # Domínio para acesso externo HTTP/S. Deve apontar via DNS para o IP do servidor FRP.

# Pode adicionar mais [[proxies]] para outros serviços
# [[proxies]]
# ... (configuração de outro serviço)

Parâmetro	Seção	Descrição
serverAddr	[common]	IP público ou domínio do servidor FRP (frps).
serverPort	[common]	Porta do servidor FRP para conexões. Padrão 7000. Ajuste conforme sua configuração.
auth.method	[common]	Método de autenticação do cliente. Mais comum: token. Deve ser igual ao do servidor.
auth.token	auth (em [common])	Token de autenticação igual ao configurado no servidor. Mantenha segredado.
tls_enable	[common]	Ativa conexão criptografada TLS entre cliente e servidor. Recomendado definir como true.
[[proxies]]	Nível raiz	Define configurações de um ou mais túneis. Cada bloco [[proxies]] representa um mapeamento independente.
name	[[proxies]]	Nome exclusivo do túnel neste arquivo. Sugira nomes que facilitem a identificação.
type	[[proxies]]	Tipo de protocolo do proxy: http, https, tcp, udp, etc. Escolha conforme o serviço local.
localIP	[[proxies]]	IP do serviço local. Normalmente 127.0.0.1.
localPort	[[proxies]]	Porta do serviço local. Por exemplo, HTTP do ServBay usa 80; HTTPS, 443; MySQL, 3306; PostgreSQL, 5432, etc.
remotePort	[[proxies]]	(Em tcp/udp apenas) Porta exposta externamente para conexão pública, acessível via serverAddr:remotePort.
customDomains	[[proxies]]	(Apenas para http/https) Lista de domínios que serão acessados pelo público via DNS apontando ao servidor FRP. Deve ser array.
subdomain	[[proxies]]	(HTTP/HTTPS, com subdomain_host no servidor) Especifique um subdomínio, resultando em subdomain.subdomain_host no acesso externo.
[proxies.plugin]	[[proxies]]	Configuração de plugins, por exemplo https2https para tratar HTTPS local.
hostHeaderRewrite	[proxies.plugin] ou [[proxies]]	Reescreve o header Host das requisições para o domínio esperado pelo servidor web do ServBay. Abolutamente necessário para sites configurados por nome de host.

Exemplo Típico: Mapeando um Site HTTPS do ServBay

Por padrão, o ServBay configura seus sites locais com HTTPS e gerencia SSL automaticamente. Para expor esse serviço HTTPS via FRP, recomenda-se usar o proxy do tipo https com ou sem o plugin https2https — ou, alternativamente, o proxy de tipo tcp para a porta 443. No entanto, como o ServBay utiliza virtual hosts com base no header Host, o tipo https combinado com hostHeaderRewrite é o mais prático.

Exemplo de configuração para publicar um site HTTPS local do ServBay (por exemplo, domínio local servbay.test) em um domínio externo (como test-frp.servbay.app). Garanta que o domínio externo (como test-frp.servbay.app) já aponte via DNS (CNAME ou A) para o IP público do servidor FRP (frps.servbay.demo).

Crie um arquivo chamado frpc.toml (por exemplo, em seu diretório pessoal: ~/frpc.toml) e insira:

# Exemplo de frpc.toml - Mapeando site HTTPS do ServBay

# [common]: configurações do servidor FRP
serverAddr = "frps.servbay.demo" # Altere para o endereço do seu servidor FRP
serverPort = 7000 # Ajuste para a porta do seu servidor FRP

auth.method = "token"
auth.token = "servbay_demo_token" # Substitua pelo seu token

# Recomenda-se ativar criptografia TLS
tls_enable = true

# [[proxies]]: Mapeando site local HTTPS do ServBay
[[proxies]]
name = "servbay-website-https" # Nome do proxy, pode personalizar
type = "https" # Tipo HTTPS

# Domínio público externo já apontando via DNS ao servidor FRP
customDomains = ["test-frp.servbay.app"] # Substitua pelo seu domínio

# Detalhes do serviço local ServBay
localIP = "127.0.0.1" # ServBay normalmente escuta em localhost
localPort = 443 # Porta HTTPS padrão do ServBay

# Importante: Reescreva o cabeçalho Host para corresponder ao domínio local configurado no ServBay
hostHeaderRewrite = "servbay.test" # Substitua pelo domínio que configurou no ServBay

# Opcional: Adicione um cabeçalho personalizado ao encaminhar requisições
[proxies.requestHeaders.set]
x-from-where = "frp-tunnel"

Substitua os parâmetros serverAddr, serverPort, auth.token, customDomains e hostHeaderRewrite conforme seu ambiente.

Por que usar o hostHeaderRewrite:
O ServBay utiliza servidores web (como Nginx ou Caddy) que selecionam o site correto com base no valor do header Host. Quando uma requisição passa pelo túnel FRP, o Host será o domínio público (test-frp.servbay.app), mas o ServBay espera o domínio local (servbay.test). Sem o hostHeaderRewrite, o servidor web local pode retornar erro 404 ou mostrar um site padrão por não identificar o alvo corretamente. Por isso, configurar este parâmetro é essencial.

Iniciando o Cliente FRP

Após criar e salvar seu frpc.toml, abra o terminal, acesse o diretório contendo o arquivo (ou aponte via caminho completo se estiver fora do diretório atual, como em ~/frpc.toml), e execute:

# Se o frpc.toml estiver na pasta atual
frpc -c frpc.toml

# Se estiver em outro local (ex: diretório pessoal)
# frpc -c ~/frpc.toml

Este comando executa o frpc em primeiro plano e tenta conectar ao servidor frps. Com sucesso, verá logs informando que o túnel está ativo e o serviço foi proxyado.

Desejando executar o frpc em segundo plano, utilize o comando nohup ou gerencie via utilitários do macOS como launchctl (mais avançado). Por exemplo, com nohup:

# Supondo frpc.toml no diretório pessoal
nohup frpc -c ~/frpc.toml &

O nohup redireciona a saída para o arquivo nohup.out e mantém o processo rodando em background. launchctl é mais avaliado para execução em serviço, mas demanda configuração além do escopo deste guia.

Verificação do Serviço e Diagnóstico de Logs

Verificando o Serviço

Após rodar o frpc e conferir nos logs que a conexão foi estabelecida, abra o navegador e acesse o domínio público configurado (https://test-frp.servbay.app). Atente-se para:

• O navegador deve carregar a página sem erros de conexão, de certificado SSL (se usando HTTPS) ou outros problemas de rede.
• Deve retornar HTTP 200 ou outros códigos esperados.
• O conteúdo da página deve ser idêntico ao acesso local via ServBay (https://servbay.test).
• Se estiver usando HTTPS, verifique se o navegador exibe o cadeado e confirma o certificado válido (emitido pelo seu domínio).

Logs e Diagnóstico

Os logs do FRP cliente são fundamentais para solucionar falhas de conexão ou proxy. Ao rodar frpc -c frpc.toml, os logs aparecem no terminal padrão. Fique atento a mensagens de erro ou alerta.

Para iniciar o frpc já em modo de debug (logs detalhados):

frpc -c frpc.toml --log_level debug

Caso tenha configurado o parâmetro log_file no seu frpc.toml (ex.: log_file = "/var/log/frpc.log"), os logs serão gravados neste arquivo. Utilize tail -f /caminho/do/seu/frpc.log para monitoramento em tempo real.

Solução de Problemas Comuns

Caso enfrente dificuldades ao configurar ou usar o FRP, consulte o quadro abaixo para soluções básicas:

Sintoma	Solução
Falha de autenticação no servidor FRP	Confirme se auth.token e auth.method em [common] do frpc.toml são idênticos à configuração do servidor FRP. Revise também os logs do servidor quanto a erros de autenticação.
Domínio público não acessível ou DNS incorreto	Certifique-se que os domínios especificados em customDomains apontam corretamente via DNS (CNAME/A) para o servidor FRP. Use ping seu-dominio-frp.com ou ferramentas de DNS online para confirmar. Espere o tempo de propagação do DNS.
Domínio retorna página de boas-vindas do FRP	Isso indica que o domínio aponta para o servidor FRP, mas não há proxy correspondente ativo. Verifique se o nome em customDomains e o type (http/https) batem com o seu acesso e se o servidor permite tal domínio.
Porta local ocupada ou serviço inativo	Confirme que o ServBay está rodando e o serviço local está ativo na porta definida em localPort. Use lsof -i :PORTA (substitua PORTA pelo valor) para checagem de ocupação das portas locais.
Túnel desconecta ou é instável	Verifique a estabilidade da conexão de rede do Mac e do servidor FRP. Ajuste parâmetros de heartbeat, como heartbeat_timeout = 30, ou aumente o pool_count no [common]. Analise logs do frps e recursos do servidor.
Acesso HTTP redireciona para HTTPS	Revise a configuração do servidor web do site no ServBay. Se precisa expor HTTP puro, use type http e remova plugins desnecessários. Para HTTPS, utilize type https e forneça as configurações de certificado corretas (ou utilize plugins segundo a necessidade).
Erro de certificado HTTPS (aviso do navegador)	Ao acessar com https tunnel, se o site local ServBay usa certificado autoassinado, seu navegador pode alertar sobre confiança. Isto é esperado. Se deseja confiança, instale o CA do ServBay no computador cliente. Outra opção é tratar os certificados via plugin do FRP ou configurar SSL válido no servidor FRP.
Retorno HTTP 404 no acesso	Verifique se hostHeaderRewrite está correto e corresponde ao domínio local do ServBay. Host inadequado impede o servidor web de identificar o site.
Firewall do servidor FRP bloqueando	Libere a porta serverPort (padrão 7000) e as portas dos serviços publicados (ex.: 80, 443, ou outros remotos) no firewall do servidor FRP.
Firewall local bloqueando	O Mac precisa permitir conexões de saída para o serverPort do FRP. Verifique se não há regra bloqueando conexões do próprio Mac, principalmente na porta local (localPort) para 127.0.0.1.
FRP cliente loga conexão mas não acessa	Pode ser configuração incorreta/existente no servidor FRP, ou problema de rede entre servidor e cliente. Revise os logs do frps do outro lado para identificar erros ou políticas de encaminhamento ausentes.

Vantagens e Dicas de Segurança da Solução FRP para ServBay

Integrar FRP ao ServBay traz flexibilidade e praticidade para desenvolvedores:

• Suporte a Vários Protocolos: FRP trabalha com HTTP, HTTPS, TCP, UDP e muito mais. Assim, pode expor bancos de dados locais (MySQL, PostgreSQL, MongoDB), Redis ou até SSH via ServBay.
• Configuração Flexível: Configure múltiplos túneis facilmente via arquivos TOML, expondo vários sites ou serviços em paralelo.
• Projeto Open Source e Controlável: FRP é maduro e de código aberto, oferecendo controle total sobre o furo de firewall, eliminando a dependência de terceiros.
• Segurança: Suporta autenticação por token e túneis criptografados TLS (tls_enable = true), protegendo seus dados em trânsito. Somado à gestão de SSL do próprio ServBay, alcança um ambiente de desenvolvimento seguro.

Dicas de Segurança:

• Ative o TLS: Em [common], sempre defina tls_enable = true para garantir a criptografia.
• Utilize Tokens Fortes: Gere um auth.token forte e de difícil adivinhação. Troque regularmente.
• Exponha Apenas o Necessário: Publique somente os serviços realmente requeridos externamente.
• Prefira domínios públicos: Ao invés do IP, acesse HTTP/HTTPS usando domínios em customDomains, conforme disponível.
• Mantenha o servidor FRP seguro: Libere apenas as portas necessárias, utilize firewall e boas práticas.
• Considere Controle de Acesso: Se suportado, restrinja por IP ou use regras avançadas no servidor FRP.

Seguindo estas recomendações, você conseguirá expor serviços de desenvolvimento locais do ServBay de maneira segura e eficiente via FRP, otimizando seus fluxos de trabalho de desenvolvimento.