Guía de solución de problemas de servidores web en ServBay

ServBay permite utilizar Caddy, NGINX o Apache como servidor web predeterminado, ofreciéndote un entorno de desarrollo local flexible. Durante su uso, es posible que te encuentres con situaciones donde el sitio no se carga, va lento o arroja errores (por ejemplo, error interno 500). Esta guía te ayudará a diagnosticar y solucionar problemas habituales relacionados con servidores web en el entorno ServBay.

Uso de la herramienta de diagnóstico integrada de ServBay

ServBay incluye una potente herramienta de diagnóstico capaz de detectar automáticamente problemas habituales de configuración y servicios. Se recomienda encarecidamente usar esta herramienta como primer paso ante cualquier inconveniente.

Abre la aplicación de ServBay y haz clic en Diagnóstico de fallos en la barra lateral izquierda para acceder a la interfaz integrada de diagnóstico.

Esta herramienta revisa el estado de los componentes principales, puertos ocupados y la sintaxis de archivos de configuración, proporcionando recomendaciones y sugerencias para ayudarte a localizar la causa del problema rápidamente.

Acceso lento al sitio tras migrar desde MAMP o Laravel Herd

Si migraste desde MAMP o Laravel Herd a ServBay, es probable que el primer acceso al sitio, después de un periodo de inactividad, tarde más de 5 segundos en cargar, mientras que los accesos posteriores sean rápidos. Tras otro periodo de inactividad, la lentitud vuelve a ocurrir en el primer acceso.

Síntomas del problema

En Chrome, abre las herramientas para desarrolladores (presionando F12 o Cmd+Option+I), selecciona la pestaña Network (Red), recarga la página y haz clic en tu solicitud para ver la información detallada de Timing (Tiempo). Verás que el tiempo de DNS Lookup ronda los 5 segundos.

(Ejemplo: visualizar el tiempo de DNS Lookup en la pestaña Network de las DevTools de Chrome)

Causa del problema

MAMP y Laravel Herd modifican la configuración DNS de macOS durante la instalación, creando archivos especiales en /etc/resolver/ para interceptar dominios concretos (como *.test o *.local). Incluso tras desinstalar estos programas, dichos archivos pueden permanecer en el sistema. Cuando accedes a sitios con los mismos sufijos (ejemplo: .test), macOS intenta primero resolverlos usando esos resolvers obsoletos, pero al no existir el servicio DNS de MAMP/Herd, se produce un timeout (habitualmente 5 segundos), antes de que el sistema use el DNS por defecto.

Solución

Sigue estos pasos para limpiar cualquier configuración DNS residual de MAMP o Laravel Herd:

1. Desinstala correctamente MAMP o Laravel Herd

Si aún no los desinstalaste completamente, utiliza los desinstaladores oficiales o scripts para eliminar todos los archivos:

Desinstalar MAMP:

• Usa la opción de desinstalación incluida en MAMP.
• O elimina manualmente la carpeta /Applications/MAMP y los archivos de configuración relacionados.

Desinstalar Laravel Herd:

# Comando oficial de desinstalación
herd uninstall

# Si el comando no está disponible, elimina manualmente la aplicación y sus configuraciones
rm -rf ~/Library/Application\ Support/Herd
rm -rf ~/.config/herd

2. Elimina archivos residuales en el directorio /etc/resolver

Aunque hayas desinstalado MAMP o Herd, pueden quedar archivos de configuración DNS en /etc/resolver/. Elimínalos manualmente:

# Lista los archivos en /etc/resolver
ls -la /etc/resolver

# Borra los resolvers específicos (por ejemplo, test y local)
sudo rm /etc/resolver/test
sudo rm /etc/resolver/local

# Borra también cualquier otro archivo creado por MAMP/Herd
# Ejemplo: sudo rm /etc/resolver/herd

Archivos habituales creados por MAMP/Herd:

• test - para dominios *.test
• local - para dominios *.local
• herd - específico de Laravel Herd

Nota: requiere permisos de administrador (sudo).

3. Evita usar el sufijo *.local en dominios locales

macOS utiliza .local para el servicio mDNS (Bonjour) orientado a redes locales. Si empleas este sufijo en desarrollo local, pueden aparecer:

• Conflictos DNS,
• Lentitud de acceso,
• Comportamientos de red inesperados.

Recomendación: usa sufijos alternativos para dominios de desarrollo, como:

• .test - reservado para pruebas,
• .localhost - garantiza resolución a la dirección local,
• .dev - es un TLD real, pero común en desarrollos locales,
• O el sufijo personalizado recomendado por ServBay.

4. Sobre la limpieza de la caché DNS (opcional)

Para asegurar que los cambios sean efectivos de inmediato, puedes limpiar la caché DNS del sistema:

# macOS Big Sur (11) y versiones recientes
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# macOS Catalina (10.15) y anteriores
sudo killall -HUP mDNSResponder

5. Verifica la solución

Tras la limpieza, vuelve a acceder a tu sitio ServBay:

1. Accede al sitio local desde el navegador,
2. Abre las DevTools de Chrome → Network (Red),
3. Recarga y comprueba el Timing de la solicitud,
4. Verifica que el tiempo de DNS Lookup es normal (generalmente menor a 50ms).

Siguiendo estos pasos deberías eliminar la lentitud en el primer acceso tras migrar desde MAMP o Laravel Herd. Si el problema persiste, comprueba si otros programas (como VPNs o proxies) están interfiriendo con la resolución DNS.

Revisión de los archivos de configuración del servidor web

Errores en la configuración suelen ser la causa principal de problemas con el acceso al sitio. ServBay proporciona herramientas específicas para validar la sintaxis en cada servidor.

Validación de Caddyfile

Utiliza el comando interno validate de Caddy para comprobar la configuración:

# macOS
/Applications/ServBay/bin/caddy validate -c /Applications/ServBay/etc/caddy/Caddyfile

# Windows
C:\ServBay\bin\caddy.exe validate -c C:\ServBay\etc\caddy\Caddyfile

Si todo está correcto, obtendrás Valid configuration. Si hay errores, se mostrará información relevante según el tipo de fallo.

Nota: El comando puede mostrar muchos mensajes INFO o WARN que forman parte del proceso interno, pero si finalmente ves Valid configuration, la sintaxis es válida.

Ejemplos comunes de errores en Caddyfile:

• Error de archivo de certificado inexistente:

  # Ejemplo en macOS
  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (más mensajes INFO/WARN) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open /Applications/ServBay/ssl/private/tls-certs/mail.servbay.host/mail.servbay.host.1crt: no such file or directory
  
  # Ejemplo en Windows
  2024/12/09 17:24:16.970 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  ... (más mensajes INFO/WARN) ...
  Error: loading http app module: provision http: getting tls app: loading tls app module: provision tls: loading certificates: open C:\\ServBay\\ssl\\private\\tls-certs\\mail.servbay.host\\mail.servbay.host.1crt: no such file or directory

  Si ves errores similares a loading certificates: open xxxxx: no such file or directory, significa que la ruta del certificado SSL configurado en el Caddyfile es incorrecta o el archivo no existe. Comprueba la ruta de los archivos de certificado (.crt, .cer, .pem) y clave (.key), y verifica que estén presentes. ServBay permite importar manualmente certificados o generarlos vía ACME; revisa las opciones SSL en ServBay.

• Error en la ruta de raíz del sitio (espacios en la ruta):

  # Ejemplo en macOS
  2024/12/09 17:26:37.371 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at /Applications/ServBay/etc/caddy/Caddyfile:1388
  
  # Ejemplo en Windows
  2024/12/09 17:26:37.371 INFO using config from file {"file": "C:\\ServBay\\etc\\caddy\\Caddyfile"}
  Error: adapting config using caddyfile: parsing caddyfile tokens for 'root': too many arguments; should only be a matcher and a path, at C:\\ServBay\\etc\\caddy\\Caddyfile:1388

  Este error parsing caddyfile tokens for 'root': too many arguments suele deberse a espacios en la ruta del directorio raíz, por ejemplo:

  • macOS: root * /Applications/ServBay/www/public web hará que Caddy interprete public web como dos argumentos.
  • Windows: root * C:\ServBay\www\public web genera el mismo problema.

  Solución: pon la ruta entre comillas dobles:

  • macOS: root * "/Applications/ServBay/www/public web"
  • Windows: root * "C:\ServBay\www\public web"

  Recomendación: Para evitar estos problemas, usa nombres de archivos y carpetas sin espacios ni caracteres especiales; utiliza guiones - o guiones bajos _ para separar palabras, por ejemplo public-folder o public_dir.

• Error en reglas de reescritura (Rewrite):

  Si copias reglas de NGINX directamente al Caddyfile, existe riesgo de fallos de sintaxis. Revisa la documentación del módulo de reescritura de Caddy y consulta la guía de migración de NGINX a ServBay para asegurarte de usar la sintaxis correcta.

Verificación de configuración NGINX

Usa el parámetro -t de NGINX para testear la sintaxis y validez del archivo de configuración:

# macOS
/Applications/ServBay/bin/nginx -t

# Windows
C:\ServBay\bin\nginx.exe -t

Si la configuración es válida:

# macOS
nginx: the configuration file /Applications/ServBay/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /Applications/ServBay/etc/nginx/nginx.conf test is successful

# Windows
nginx: the configuration file C:\ServBay\etc\nginx\nginx.conf syntax is ok
nginx: configuration file C:\ServBay\etc\nginx\nginx.conf test is successful

Si hay errores, NGINX indicará la ubicación y número de línea del fallo. Los errores típicos incluyen:

1. Errores de sintaxis: Falta de punto y coma ;, llaves } mal cerradas, etc.
2. Errores de ruta de archivo: Las rutas en include u otras directivas no existen o son incorrectas.
3. Conflicto de puertos: El puerto configurado está ocupado por otro programa.

Chequeo de configuración Apache

Usa apachectl configtest para validar la sintaxis del archivo de configuración de Apache:

# macOS
/Applications/ServBay/bin/apachectl configtest

# Windows
C:\ServBay\bin\httpd.exe -t

Una configuración válida arroja Syntax OK. En caso de error, se muestra una descripción del problema. Algunas causas habituales:

1. Carga fallida de módulos: Un módulo requerido con LoadModule no existe o la ruta es incorrecta.
2. Errores en archivos .htaccess: Sintaxis incorrecta en el .htaccess puede impedir el acceso al sitio o causar que falle el chequeo global de configuración.
3. Permisos mal configurados: Las directivas Directory o Files con ajustes como Require, Allow o Deny pueden bloquear el acceso a archivos si están mal establecidas.

Solución de errores internos 500

El error 500 (Internal Server Error) es un estado genérico que indica que el servidor tuvo un problema inesperado al procesar la solicitud, usualmente producido por fallos en scripts de backend (PHP, Python, Node.js, etc.).

Pasos generales de diagnóstico

Ante un error 500, sigue estos pasos:

1. Revisa los logs de error del servidor web: Es el punto de partida para identificar la causa. Los logs incluyen detalles sobre errores de scripts, archivos ausentes, problemas de permisos, etc.

   macOS:

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log

   Windows:

   • Caddy: C:\ServBay\var\logs\caddy\error.log
   • NGINX: C:\ServBay\var\logs\nginx\error.log
   • Apache: C:\ServBay\var\logs\apache\error.log

   Busca las entradas más recientes, prestando atención a términos como error o critical.

2. Verifica que el servicio de backend (como PHP-FPM) esté en ejecución: Si tu sitio depende de PHP, asegúrate de que PHP-FPM esté activo.

   ps aux | grep php-fpm

   Busca líneas con php-fpm: master process o php-fpm: pool www. Si no aparecen, el servicio no está iniciado o se ha caído. Usa la interfaz de ServBay o el comando servbayctl para arrancar PHP.

3. Examina los logs de errores del backend (como PHP): Si los logs del servidor apuntan a errores FastCGI o scripts, revisa el log propio del lenguaje.

   Ubicación del log PHP:

   • macOS: /Applications/ServBay/var/logs/php/php_error.log
   • Windows: C:\ServBay\var\logs\php\php_error.log

   Identifica entradas como Fatal error, Parse error, Warning, Notice, relacionadas con el script que estás visitando. Asegúrate de que la opción display_errors esté desactivada en producción y activada solo en desarrollo para ver más detalles (puedes configurarlo en el php.ini).

4. Verifica permisos en archivos y carpetas: El proceso del servidor web generalmente usa un usuario específico y requiere permisos suficientes para leer archivos y directorios del sitio, y escribir en carpetas de subida o logs.

   macOS:

   ls -la /Applications/ServBay/www/your-site/

   Asegúrate de que el usuario del servidor web (como _www) tenga permisos de lectura (y escritura, si corresponde). Utiliza chmod y chown para ajustar permisos y propietarios.

   Windows:

   dir C:\ServBay\www\your-site

   Confirma que el usuario que ejecuta ServBay tenga permisos de acceso suficientes mediante la pestaña de seguridad en las propiedades de la carpeta.

Diagnóstico específico de error 500 por tipo de servidor web

• Caddy:

  1. Configuración de FastCGI: Verifica que las directivas php_fastcgi o reverse_proxy en Caddyfile apunten correctamente al servicio PHP-FPM (127.0.0.1:9000 o unix:/path/to/php-fpm.sock).
  2. Estado del PHP-FPM: Corrobora que la versión de PHP seleccionada y el servicio PHP-FPM estén activos en ServBay.
  3. Configuración de reverse proxy: Si usas reverse_proxy hacia backend (como Node.js), revisa dirección, puerto y estado del servicio.

• NGINX:

  1. Directiva fastcgi_pass: Comprueba que fastcgi_pass en el nginx.conf o en la config del sitio apunta correctamente al PHP-FPM.
  2. Parámetro client_max_body_size: Si intentas subir archivos grandes y obtienes error 500, puede que el límite de tamaño sea demasiado bajo.
  3. Directiva try_files: Confirma que try_files esté correctamente configurada para encontrar el índice o reenviar la solicitud a FastCGI según corresponda.

• Apache:

  1. Módulo mod_rewrite: Si usas .htaccess para reescritura de URLs, asegura que mod_rewrite esté habilitado.
  2. Contenido del .htaccess: Una instrucción incorrecta puede causar error 500. Verifica la sintaxis y reglas en el archivo.
  3. Configuración de AllowOverride: En el archivo principal de configuración, asegúrate de que la directiva AllowOverride permita que las reglas de .htaccess surtan efecto (comúnmente All o los valores necesarios como FileInfo y Limit).

Gestión de servicios

Después de modificar configuraciones o solucionar problemas del backend, suele ser necesario reiniciar los servidores o servicios para que los cambios tengan efecto.

Reiniciar servicios

Para reiniciar el servidor web, usa el comando servbayctl restart:

# Reiniciar Caddy
servbayctl restart caddy -all

# Reiniciar NGINX
servbayctl restart nginx -all

# Reiniciar Apache
servbayctl restart apache -all

El parámetro -all también reiniciará servicios asociados, como PHP-FPM si está configurado.

Ver el estado de los servicios

Para comprobar el estado actual de los servicios, usa:

# Estado de Caddy
servbayctl status caddy -all

# Estado de NGINX
servbayctl status nginx -all

# Estado de Apache
servbayctl status apache -all

Verás si el servicio está running (activo), stopped (detenido) u otro estado, lo que te ayudará a confirmar que se ha arrancado correctamente.

Pasos avanzados de solución de problemas

Si los puntos anteriores no resuelven el problema, prueba estos pasos adicionales:

1. Herramientas de desarrollador del navegador: Abre las DevTools (F12), revisa las pestañas Console y Network para identificar errores de JavaScript o códigos de respuesta y encabezados que informen si el fallo está en el frontend o backend.
2. Usa el comando curl -v: Ejecuta curl -v tu-sitio.servbay.demo desde la terminal para analizar el proceso de solicitud y respuesta (incluyendo headers, información SSL/TLS, etc.). Sustituye tu-sitio.servbay.demo por el dominio real de tu proyecto en ServBay.
3. Prueba desactivar temporalmente el firewall: Algunos firewalls locales o softwares de seguridad podrían bloquear conexiones. Desactívalo temporalmente y verifica si el problema desaparece; si es así, ajusta las reglas para permitir los puertos que usa ServBay (como 80 o 443).
4. Prueba el sitio en otro navegador/dispositivo: Así descartarás caché o configuración específica del equipo o navegador.
5. Comprueba configuración local de DNS o hosts: Si utilizas dominios personalizados (no localhost o IP), revisa el archivo hosts para asegurar que el dominio resuelve a 127.0.0.1 o ::1.
   • macOS: /etc/hosts
   • Windows: C:\Windows\System32\drivers\etc\hosts

Resumen

Los problemas con servidores web son habituales en entornos de desarrollo local. Siguiendo un proceso metódico: revisa la sintaxis de la configuración, analiza los logs de errores, verifica el estado de los servicios y confirma los permisos de los archivos. La herramienta de diagnóstico de ServBay junto con el comando servbayctl te serán de gran ayuda. Ante situaciones complejas, consulta la documentación avanzada de ServBay o contacta al equipo de soporte técnico para asistencia especializada.