Acceso Público a ServBay en entornos de desarrollo local usando FRP (Penetración de NAT)

FRP es una herramienta de proxy inverso de alto rendimiento y fácil de usar, ideal para aquellos que necesitan exponer servicios de desarrollo local (como sitios web, APIs, bases de datos, etc.) de forma segura y sencilla a Internet. Mediante su arquitectura de cliente (frpc) y servidor (frps), FRP permite la penetración de NAT de manera eficiente.

Esta guía detalla a los usuarios de ServBay, especialmente en macOS, cómo configurar y utilizar el cliente FRP (frpc) para crear túneles seguros que permitan acceder desde Internet a los servicios web locales que ejecutas en ServBay. Es fundamental para escenarios como demostraciones remotas, desarrollo colaborativo, recepción de Webhooks o pruebas de APIs externas.

Resumen Técnico del Funcionamiento

El principio central de FRP es establecer un túnel cifrado desde tu máquina local (donde se ejecuta frpc, es decir, la máquina con ServBay) hacia un servidor público (donde se ejecuta frps). Cuando usuarios externos acceden a tu servicio, las solicitudes llegan primero al servidor público con frps, el cual las reenvía por el túnel previamente establecido a tu frpc interno. Este, a su vez, redirige las solicitudes a los servicios locales de ServBay (como tu sitio web o API). Las respuestas siguen el camino inverso hasta el usuario externo.

Este mecanismo sortea restricciones de firewalls y routers internos, permitiendo así exponer servicios detrás de NAT. Además, soporta múltiples protocolos (TCP/UDP/HTTP/HTTPS), potenciando la accesibilidad remota de los entornos de desarrollo con ServBay.

Casos de Uso

Al combinar ServBay con FRP puedes cubrir fácilmente los siguientes escenarios:

• Demostraciones remotas y colaboración: Presenta tu sitio web o aplicación en desarrollo a compañeros o clientes sin necesidad de deployment en un servidor remoto.
• Pruebas de Webhooks: Recibe notificaciones desde servicios de terceros (GitHub, Stripe, pagos por WeChat, etc.) y depura su lógica directamente en local.
• Testing conjunto de APIs: Expo tu API local a desarrolladores frontend o colaboradores externos para pruebas conjuntas.
• Pruebas de desarrollo en dispositivos móviles: Accede desde dispositivos móviles a los sitios o apps locales de ServBay para pruebas de compatibilidad multiplataforma.
• Compartición temporal: Comparte rápida y temporalmente archivos o servicios locales sin complicadas configuraciones.

Requisitos Previos

Antes de comenzar la configuración de FRP, asegúrate de cumplir lo siguiente:

1. ServBay instalado y funcionando: ServBay debe estar correctamente instalado y los servicios que desees exponer deben estar accesibles en tu macOS.
2. Servidor público FRP (frps): Necesitas un servidor con IP pública donde esté desplegado y corriendo el servidor de FRP (frps). Esta guía se centra en la configuración del cliente (frpc).
3. Dominio público (opcional, recomendado para HTTP/HTTPS): Para acceder mediante un nombre de dominio, necesitas uno propio y la capacidad de gestionarlo en DNS.
4. Cliente FRP (frpc) instalado: El cliente FRP no viene incluido en ServBay, deberás descargarlo e instalarlo aparte.

Preparación del Entorno e Instalación del Cliente FRP

Sigue estos pasos para instalar el cliente FRP (frpc) en tu máquina macOS donde usas ServBay.

1. Descarga del cliente FRP: Ve a la página de lanzamientos de FRP en GitHub y descarga la versión más reciente y adecuada para la arquitectura de tu sistema:

   • Para Apple Silicon (M1/M2/M3, etc.), descarga el archivo frp_*.darwin_arm64.tar.gz.
   • Para arquitecturas Intel, descarga frp_*.darwin_amd64.tar.gz.

2. Instalación del cliente FRP: Descomprime el archivo descargado y copia el ejecutable frpc a un directorio incluido en el PATH del sistema, como /usr/local/bin, para poder ejecutarlo desde cualquier terminal.

   Ten presente que el número de versión (0.52.3 en el ejemplo) y la arquitectura (darwin_arm64) pueden variar; adapta los comandos a la versión y el archivo descargado por ti.

   # Suponiendo que has descargado frp_0.52.3_darwin_arm64.tar.gz
   # Entra en el directorio de descargas
   cd ~/Downloads
   
   # Descomprime el archivo (cambia el nombre por el de tu descarga)
   tar -zxvf frp_0.52.3_darwin_arm64.tar.gz
   
   # Entra en el directorio extraído (ajusta el nombre según corresponda)
   cd frp_0.52.3_darwin_arm64
   
   # Copia el ejecutable a /usr/local/bin
   sudo cp frpc /usr/local/bin/
   
   # (Opcional) También puedes copiar el archivo de ejemplo frpc.toml a tu carpeta personal
   # cp frpc.toml ~/

   Introduce tu contraseña de usuario para completar los comandos sudo.

3. Verificación de instalación: Abre una nueva ventana de terminal y ejecuta:

   frpc -v
   # La salida esperada será algo como: frpc version 0.52.3

   Si ves la versión, la instalación fue un éxito.

Configuración de Túneles en el Cliente FRP

La configuración principal de FRP se realiza mediante un archivo llamado frpc.toml (FRP recomienda el formato TOML para las versiones recientes). Debes crearlo o editarlo para que frpc sepa cómo conectar con tu servidor (frps) y cómo mapear los servicios locales de ServBay a Internet.

Explicación del archivo de configuración frpc.toml

A continuación, un ejemplo básico del archivo frpc.toml que muestra cómo establecer la conexión y definir un proxy:

# frpc.toml - Ejemplo de archivo de configuracion del cliente FRP

# Sección [common]: configuración de la conexión cliente-servidor
serverAddr = "your-frps-server.com" # IP pública o dominio de tu servidor FRP
serverPort = 7000 # Puerto del servidor FRP para conexiones entrantes (por defecto 7000)

# Configuración de autenticación (se recomienda usar token)
auth.method = "token"
auth.token = "your_authentication_token" # Token que debe coincidir con la configuración del servidor

# Opcional: activa TLS para cifrado de las conexiones cliente-servidor
# tls_enable = true

# Sección [[proxies]]: define uno o varios túneles proxy
[[proxies]]
name = "my-web-service" # Nombre único para este proxy
type = "http" # Tipo de proxy: http, https, tcp, udp, stcp, xtcp, etc.
localIP = "127.0.0.1" # IP local del servicio (por defecto 127.0.0.1)
localPort = 80 # Puerto local del servicio (ej. 80 para HTTP en ServBay)
customDomains = ["servbay.your-domain.com"] # Dominio público para acceder (solo http/https). **Asegura que apunte por DNS a tu servidor FRP.**

# Puedes añadir más proxies como más bloques [[proxies]]
# [[proxies]]
# ... (configuración de otro servicio)

Parámetro	Sección	Descripción
serverAddr	[common]	Dirección IP pública o dominio del servidor FRP (frps).
serverPort	[common]	Puerto del servidor FRP (por defecto 7000). Modifícalo según tu configuración.
auth.method	[common]	Método de autenticación. Usualmente token. Debe coincidir con el servidor.
auth.token	auth (dentro de [common])	Token secreto para la autenticación con el servidor FRP. No lo compartas.
tls_enable	[common]	Habilita cifrado TLS entre cliente y servidor. Se recomienda ponerlo en true.
[[proxies]]	raíz	Array para definir uno o múltiples túneles proxy independientes.
name	[[proxies]]	Nombre único para el túnel en este archivo. Útil para identificar el servicio.
type	[[proxies]]	Tipo de protocolo (http, https, tcp, udp, etc.). Selecciona el que aplique a tu servicio local.
localIP	[[proxies]]	Dirección IP local del servicio expuesto. Por defecto, 127.0.0.1.
localPort	[[proxies]]	Puerto local del servicio (HTTP: 80, HTTPS: 443, MySQL: 3306, PostgreSQL: 5432...)
remotePort	[[proxies]]	(Sólo para tcp/udp) Puerto público a través del que se accede desde fuera (serverAddr:remotePort).
customDomains	[[proxies]]	(Sólo http/https) Array de dominios públicos. Deben estar configurados en DNS a tu servidor FRP.
subdomain	[[proxies]]	(Sólo http/https, y si el servidor lo permite) Para subdominios mediante subdomain_host en la config del servidor. Alternativa a customDomains.
[proxies.plugin]	[[proxies]]	Plugins especiales, por ejemplo, https2https para servicios HTTPS.
hostHeaderRewrite	[proxies.plugin] o [[proxies]] (según tipo/plugin)	Reescribe el header Host en las peticiones al servicio local. Fundamental para virtual hosts en ServBay. Debe coincidir con el dominio configurado en ServBay.

Ejemplo típico de configuración: Exponer un sitio HTTPS de ServBay

Por defecto, ServBay configura sitios locales usando HTTPS y gestiona certificados SSL automáticamente. Para exponer ese servicio a Internet mediante FRP, normalmente se usa el tipo de proxy https y, posiblemente, el plugin https2https, o directamente un proxy tcp en el puerto 443. Debido a que ServBay distingue los sitios virtuales por el header Host, la opción más habitual es combinar el tipo https con hostHeaderRewrite.

Supongamos que tienes un sitio en ServBay bajo el dominio local servbay.test y quieres exponerlo en Internet en test-frp.servbay.app, que apunta por DNS al servidor público FRP (frps.servbay.demo). El archivo frpc.toml se vería así (ajusta los valores según tu caso):

# Ejemplo de frpc.toml para exponer sitio HTTPS de ServBay

# [common]: Conexión con el servidor FRP
serverAddr = "frps.servbay.demo" # Cambia por la IP o dominio de tu servidor FRP
serverPort = 7000 # Cambia por el puerto del servidor FRP

auth.method = "token"
auth.token = "servbay_demo_token" # Cambia por tu token real configurado en el servidor

# Recomendado: activa cifrado TLS
tls_enable = true

# [[proxies]]: proxy para el sitio HTTPS de ServBay
[[proxies]]
name = "servbay-website-https" # Nombre del proxy, puede ser p. ej. servbay-test-site
type = "https" # Tipo HTTPS

# Configura el dominio público y asegúrate que apunte a tu servidor FRP
customDomains = ["test-frp.servbay.app"] # Cambia por tu dominio real

# Redirección local a ServBay
localIP = "127.0.0.1"
localPort = 443 # Puerto HTTPS por defecto de ServBay

# Esencial: reescribe el header Host al dominio local del sitio en ServBay
# Así los servidores web de ServBay (Nginx/Caddy) identifican correctamente la página.
hostHeaderRewrite = "servbay.test" # Cambia por tu dominio local real en ServBay

# Opcional: añade un header custom para reconocer la procedencia desde el túnel FRP
[proxies.requestHeaders.set]
x-from-where = "frp-tunnel"

Recuerda adaptar los parámetros serverAddr, serverPort, auth.token, customDomains y hostHeaderRewrite según tu entorno.

Importancia de hostHeaderRewrite: ServBay usa servidores como Nginx o Caddy para gestionar múltiples sitios. Normalmente, estos determinan la web a mostrar según el header Host de la petición. Sin la reescritura, las peticiones llegarían con el dominio público (test-frp.servbay.app) y no tu dominio local (servbay.test), por lo que el servidor no podría asociarla correctamente, resultando en errores 404 o mostrando la web por defecto. Por eso, hostHeaderRewrite es clave para el correcto enrutamiento de tu sitio en ServBay.

Arranque del servicio cliente FRP

Después de guardar el archivo frpc.toml, abre la terminal, navega a la carpeta donde está (si está en ~, puedes llamarlo desde cualquier parte especificando la ruta absoluta) y arranca el cliente FRP así:

# Si tu frpc.toml está en el directorio actual
frpc -c frpc.toml

# Si está en tu carpeta personal
# frpc -c ~/frpc.toml

Esto ejecutará frpc en foreground e intentará conectar con el servidor FRP. Si todo va bien, verás logs indicando la creación del túnel y el inicio del proxy.

Para ejecutarlo en segundo plano, puedes usar nohup o utilidades como launchctl (típico de macOS). Por ejemplo, con nohup:

# Suponiendo que tu frpc.toml está en tu carpeta personal
nohup frpc -c ~/frpc.toml &

Esto redirigirá el output a nohup.out y ejecutará en segundo plano. Ten en cuenta que launchctl es la forma más estándar en macOS para servicios persistentes, aunque su configuración es más avanzada y escapa a esta guía.

Verificación del Servicio y Diagnóstico de Logs

Verificación del Servicio

Tras arrancar frpc, y una vez superada la conexión, abre el navegador y accede al dominio público que configuraste en frpc.toml (p.ej. https://test-frp.servbay.app). Comprueba lo siguiente:

• La página carga correctamente, sin errores de conexión, aviso de certificados (si usas HTTPS) u otros problemas de red.
• El código de estado HTTP es 200 o el esperado.
• El contenido corresponde al acceso local en ServBay (p.ej. https://servbay.test).
• En caso de HTTPS, el navegador muestra el candado seguro y el certificado SSL es válido (emitido para tu dominio público).

Diagnóstico de Logs

Los logs de frpc son esenciales para depuración. Por defecto, ejecutando frpc -c frpc.toml, se muestran por terminal. Fíjate en errores o advertencias.

Puedes aumentar el detalle de los logs ejecutando en modo debug así:

frpc -c frpc.toml --log_level debug

Si tu archivo frpc.toml incluye el parámetro log_file (p.ej. log_file = "/var/log/frpc.log"), los logs se escribirán en el archivo indicado, el cual puedes monitorizar con tail -f /ruta/tu/frpc.log.

Solución de Problemas Comunes

Si te encuentras con problemas durante la configuración o uso de FRP, revisa estas causas y soluciones:

Problema	Solución
Fallo de autenticación con el servidor FRP	Verifica que auth.token y auth.method en la sección [common] de frpc.toml coincidan exactamente con la configuración de frps. Consulta los logs de ambos lados.
El dominio público no resuelve o no es accesible	Asegúrate de que el dominio en customDomains apunte vía DNS CNAME o A a la IP pública del servidor FRP. Usa ping o herramientas de DNS para comprobar la resolución.
El dominio muestra la página de bienvenida de FRP	Suele indicar que el dominio apunta bien, pero no hay configuración que lo enrute. Revisa que customDomains y type estén correctos y el servidor permita ese dominio.
Puerto local en uso o servicio no iniciado	Confirma que ServBay y el servicio estén activos en el puerto especificado. Usa lsof -i :PUERTO para verificar si hay procesos escuchando.
El túnel se cae o es inestable	Comprueba la estabilidad de red de tu Mac y del servidor FRP. Ajusta parámetros como heartbeat_timeout = 30 (en [common]) o incrementa pool_count si procede.
Navegador redirige HTTP a HTTPS	Consulta la config del servidor web de ServBay. Si solo quieres HTTP, asegúrate que el proxy es http y no se fuerzan redirecciones. Para HTTPS, revisa certificados/plugin.
Error de certificado HTTPS	Si el sitio de ServBay usa un CA autofirmado, el navegador puede advertir de un certificado no confiable. Instala el CA de ServBay en tu máquina, o usa un plugin como https2https, o configura el FRPS con un certificado válido. Recuerda: usando https y hostHeaderRewrite, el navegador depende del certificado del sitio local en ServBay.
Error 404 al acceder	Revisa que el hostHeaderRewrite esté correctamente puesto con el dominio local usado en ServBay; si no, el servidor web no encontrará el sitio objetivo.
El firewall del servidor FRP bloquea conexiones	Abre el puerto serverPort (por defecto 7000), además de los puertos de los servicios (HTTP 80, HTTPS 443, otros proxy TCP/UDP).
El firewall local bloquea conexiones	Comprueba que tu Mac no bloquea conexiones salientes al serverPort de FRP, ni conexiones locales de frpc a los puertos de ServBay (localPort).
frpc indica conexión exitosa pero el acceso falla	Puede ser por configuración incorrecta en el servidor FRP o problemas de red entre servidor y cliente. Consulta los logs de frps y revisa mapeos de puertos/dominios.

Ventajas y Recomendaciones de Seguridad al Usar FRP con ServBay

La combinación de FRP y ServBay otorga gran flexibilidad al desarrollo:

• Soporte multiprotocolo: FRP permite exponer HTTP, HTTPS, TCP, UDP, etc. No solo sitios web; puedes exponer también bases de datos (MySQL, PostgreSQL, MongoDB), Redis, SSH y más.
• Configuración sencilla: Añade múltiples túneles/proxy editando solo un archivo TOML, facilitando el acceso externo a varios servicios de ServBay.
• Open Source y control total: FRP es un proyecto maduro, de código abierto, por lo que controlas completamente tu infraestructura de penetración de NAT, sin depender de terceros.
• Seguridad: FRP soporta tokens de autenticación y túneles cifrados con TLS (tls_enable = true), asegurando la privacidad de tus datos. Junto a la gestión integral de SSL en ServBay, el entorno de desarrollo puede ser aún más seguro.

Recomendaciones de seguridad:

• Activa siempre TLS (cifrado): Se recomienda invariablemente definir tls_enable = true en [common] del frpc.toml.
• Usa tokens fuertes: Elige un token complejo, difícil de adivinar y cámbialo regularmente.
• Expón solo lo necesario: Solo publica los servicios y puertos imprescindibles para acceso externo.
• Utiliza dominios públicos siempre que puedas: Para servicios HTTP/HTTPS, prefiere nombres de dominio (customDomains) sobre dirección IP directa.
• Protege el servidor FRP: Mantén tu servidor FRP seguro, abre solo los puertos necesarios y configura bien el firewall.
• Evalúa controles de acceso avanzados: Si es posible, configura restricciones de acceso adicionales en el servidor FRP, como limitaciones por dirección IP.

Siguiendo estas indicaciones y pasos, podrás exponer correctamente tu entorno local de desarrollo en ServBay a Internet usando FRP, facilitando y optimizando tu flujo de trabajo como desarrollador.