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:
bash
# 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
1
2
3
4
5
6
2
3
4
5
6
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:
bash
# 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
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
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:
bash
# macOS Big Sur (11) y versiones recientes
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
# macOS Catalina (10.15) y anteriores
sudo killall -HUP mDNSResponder
1
2
3
4
5
2
3
4
5
5. Verifica la solución
Tras la limpieza, vuelve a acceder a tu sitio ServBay:
- Accede al sitio local desde el navegador,
- Abre las DevTools de Chrome → Network (Red),
- Recarga y comprueba el Timing de la solicitud,
- 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:
bash
# 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
1
2
3
4
5
2
3
4
5
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:
bash# 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
1
2
3
4
5
6
7
8
9Si 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):
bash# 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
1
2
3
4
5
6
7Este 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 interpretepublic 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 ejemplopublic-folder
opublic_dir
.- macOS:
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:
bash
# macOS
/Applications/ServBay/bin/nginx -t
# Windows
C:\ServBay\bin\nginx.exe -t
1
2
3
4
5
2
3
4
5
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
1
2
3
4
5
6
7
2
3
4
5
6
7
Si hay errores, NGINX indicará la ubicación y número de línea del fallo. Los errores típicos incluyen:
- Errores de sintaxis: Falta de punto y coma
;
, llaves}
mal cerradas, etc. - Errores de ruta de archivo: Las rutas en
include
u otras directivas no existen o son incorrectas. - 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:
bash
# macOS
/Applications/ServBay/bin/apachectl configtest
# Windows
C:\ServBay\bin\httpd.exe -t
1
2
3
4
5
2
3
4
5
Una configuración válida arroja Syntax OK
. En caso de error, se muestra una descripción del problema. Algunas causas habituales:
- Carga fallida de módulos: Un módulo requerido con
LoadModule
no existe o la ruta es incorrecta. - 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. - Permisos mal configurados: Las directivas
Directory
oFiles
con ajustes comoRequire
,Allow
oDeny
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:
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
ocritical
.- Caddy:
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.
bashps aux | grep php-fpm
1Busca líneas con
php-fpm: master process
ophp-fpm: pool www
. Si no aparecen, el servicio no está iniciado o se ha caído. Usa la interfaz de ServBay o el comandoservbayctl
para arrancar PHP.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óndisplay_errors
esté desactivada en producción y activada solo en desarrollo para ver más detalles (puedes configurarlo en elphp.ini
).- macOS:
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:
bashls -la /Applications/ServBay/www/your-site/
1Asegúrate de que el usuario del servidor web (como
_www
) tenga permisos de lectura (y escritura, si corresponde). Utilizachmod
ychown
para ajustar permisos y propietarios.Windows:
cmddir C:\ServBay\www\your-site
1Confirma 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:
- Configuración de FastCGI: Verifica que las directivas
php_fastcgi
oreverse_proxy
en Caddyfile apunten correctamente al servicio PHP-FPM (127.0.0.1:9000
ounix:/path/to/php-fpm.sock
). - Estado del PHP-FPM: Corrobora que la versión de PHP seleccionada y el servicio PHP-FPM estén activos en ServBay.
- Configuración de reverse proxy: Si usas
reverse_proxy
hacia backend (como Node.js), revisa dirección, puerto y estado del servicio.
- Configuración de FastCGI: Verifica que las directivas
NGINX:
- Directiva
fastcgi_pass
: Comprueba quefastcgi_pass
en elnginx.conf
o en la config del sitio apunta correctamente al PHP-FPM. - 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. - Directiva
try_files
: Confirma quetry_files
esté correctamente configurada para encontrar el índice o reenviar la solicitud a FastCGI según corresponda.
- Directiva
Apache:
- Módulo
mod_rewrite
: Si usas.htaccess
para reescritura de URLs, asegura quemod_rewrite
esté habilitado. - Contenido del .htaccess: Una instrucción incorrecta puede causar error 500. Verifica la sintaxis y reglas en el archivo.
- Configuración de
AllowOverride
: En el archivo principal de configuración, asegúrate de que la directivaAllowOverride
permita que las reglas de.htaccess
surtan efecto (comúnmenteAll
o los valores necesarios comoFileInfo
yLimit
).
- Módulo
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
:
bash
# Reiniciar Caddy
servbayctl restart caddy -all
# Reiniciar NGINX
servbayctl restart nginx -all
# Reiniciar Apache
servbayctl restart apache -all
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
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:
bash
# Estado de Caddy
servbayctl status caddy -all
# Estado de NGINX
servbayctl status nginx -all
# Estado de Apache
servbayctl status apache -all
1
2
3
4
5
6
7
8
2
3
4
5
6
7
8
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:
- Herramientas de desarrollador del navegador: Abre las DevTools (F12), revisa las pestañas
Console
yNetwork
para identificar errores de JavaScript o códigos de respuesta y encabezados que informen si el fallo está en el frontend o backend. - Usa el comando
curl -v
: Ejecutacurl -v tu-sitio.servbay.demo
desde la terminal para analizar el proceso de solicitud y respuesta (incluyendo headers, información SSL/TLS, etc.). Sustituyetu-sitio.servbay.demo
por el dominio real de tu proyecto en ServBay. - 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).
- Prueba el sitio en otro navegador/dispositivo: Así descartarás caché o configuración específica del equipo o navegador.
- 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 a127.0.0.1
o::1
.- macOS:
/etc/hosts
- Windows:
C:\Windows\System32\drivers\etc\hosts
- macOS:
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.