Guía de solución de problemas del servidor web en ServBay

ServBay permite utilizar Caddy, NGINX o Apache como servidores web predeterminados, brindándote un entorno de desarrollo local flexible. Durante su uso, puedes encontrarte con problemas como sitios web inaccesibles, carga lenta u errores (por ejemplo, error interno 500 del servidor). Esta guía te ayudará a diagnosticar y resolver los fallos más comunes relacionados con los servidores web en ServBay.

Uso de la herramienta de diagnóstico integrada de ServBay

ServBay proporciona una poderosa herramienta de diagnóstico integrada que detecta y muestra automáticamente problemas comunes de configuración y servicios. Se recomienda encarecidamente usar primero esta herramienta para una autocomprobación cuando surja algún 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 propia de diagnóstico de ServBay.

La herramienta revisa el estado de los componentes principales de ServBay, los puertos en uso, la sintaxis de archivos de configuración y ofrece sugerencias para ayudarte a localizar rápidamente el problema.

Verificación de archivos de configuración del servidor web

Los errores en los archivos de configuración del servidor web son una causa frecuente de sitios inaccesibles. ServBay proporciona herramientas de comprobación sintáctica específicas para cada servidor web.

Comprobación de Caddyfile

Usa el comando validate incorporado de Caddy para verificar que tu archivo de configuración Caddyfile sea correcto.

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

Si la sintaxis es correcta, el comando mostrará Valid configuration. En caso de errores, ofrecerá mensajes explicativos según el tipo de fallo encontrado.

Nota: El comando caddy validate puede generar muchos mensajes INFO o WARN, normalmente relacionados con el proceso interno de carga de Caddy. Estos no siempre significan errores de configuración: si al final ves Valid configuration, la sintaxis es válida.

Ejemplos comunes de errores en Caddyfile:

• Error: archivo de certificado no existe:

  2024/12/09 17:24:16.970 INFO using config from file {"file": "/Applications/ServBay/etc/caddy/Caddyfile"}
  ... (otros 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

  Si aparece un error como loading certificates: open xxxxx: no such file or directory, significa que la ruta del certificado SSL especificada en el Caddyfile es incorrecta o el archivo no existe. Revisa las rutas de certificados (.crt/.cer/.pem) y claves privadas (.key) en la configuración de tu sitio y asegúrate de que existen en esa ubicación. ServBay permite importar certificados manualmente o usar ACME para obtenerlos automáticamente; revisa la configuración de SSL de ServBay.

• Error de ruta de directorio raíz (con espacios):

  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

  El error parsing caddyfile tokens for 'root': too many arguments normalmente se debe a la presencia de espacios en la ruta del directorio raíz del sitio. Por ejemplo, en root * /Applications/ServBay/www/public web, public web se interpreta como dos argumentos. La solución es encerrar la ruta con espacios entre comillas dobles ", por ejemplo: root * "/Applications/ServBay/www/public web".

  Recomendación: Para prevenir estos errores, evita utilizar espacios y caracteres especiales en los nombres de archivos y directorios. Usa guiones - o guiones bajos _ para separar palabras, por ejemplo, public-folder o public_dir.

• Error en regla de Rewrite:

  Utilizar reglas de reescritura (Rewrite) que no siguen la sintaxis de Caddy, por ejemplo, copiar reglas desde NGINX directamente, puede provocar fallos de validación. Consulta la documentación del módulo Rewrite de Caddy o la guía de migración de sitios desde NGINX a ServBay para asegurar que la sintaxis sea la correcta.

Comprobación de configuración de NGINX

Utiliza el parámetro -t de NGINX para testear la sintaxis y validez de los archivos de configuración.

/Applications/ServBay/bin/nginx -t

Si es correcto, verás:

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

En caso de error, NGINX indicará el archivo y la línea donde está el problema. Errores comunes incluyen:

1. Errores de sintaxis: Como falta de punto y coma ;, llaves } no coincidentes, etc.
2. Errores de ruta de archivo: En directivas include o similares, rutas incorrectas/no existentes.
3. Conflicto de puertos: El puerto configurado ya está en uso por otra aplicación.

Comprobación de configuración de Apache

Utiliza el comando apachectl configtest para comprobar la sintaxis del archivo de configuración de Apache.

/Applications/ServBay/bin/apachectl configtest

Si es correcto, verás Syntax OK. Si hay errores, aparecerán mensajes detallados. Errores comunes de configuración en Apache:

1. Carga de módulos fallida: El módulo activado (LoadModule) no existe o la ruta es incorrecta.
2. Errores de sintaxis en .htaccess: Archivos .htaccess en tu sitio con errores pueden provocar que falle toda la configuración o errores en directorios concretos.
3. Permisos de directorio incorrectos: Las directivas Directory o Files pueden restringir el acceso a archivos del sitio si no están bien configuradas (Require, Allow, Deny).

Solución de errores 500 interno del servidor

El error 500 Internal Server Error es un código HTTP habitual que indica que el servidor encontró una situación inesperada al procesar una petición. En aplicaciones web, esto suele significar que un script backend (PHP, Python, Node.js, etc.) falló durante la ejecución.

Pasos generales de diagnóstico

Cuando veas un error 500, sigue estos pasos:

1. Revisa los logs de errores del servidor web: Es el primer paso. Encontrarás detalles específicos como fallos de scripts, archivos inexistentes o problemas de permisos.

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log Consulta las últimas líneas en busca de palabras clave como error o critical.

2. Comprueba que el backend (por ejemplo, PHP-FPM) esté corriendo: Si tu sitio usa PHP, asegúrate de que el servicio PHP-FPM esté activo.

   ps aux | grep php-fpm

   Busca líneas con php-fpm: master process o php-fpm: pool www. Si no aparece ningún proceso, significa que PHP-FPM no está iniciado o está caído. Puedes arrancarlo desde la interfaz de ServBay o usando el comando servbayctl.

3. Revisa los logs de errores del backend (por ejemplo, PHP): Si los logs de tu servidor indican un error FastCGI o de script backend, revisa los logs del lenguaje correspondiente.

   • PHP: /Applications/ServBay/var/logs/php/php_error.log Busca mensajes como Fatal error, Parse error, Warning o Notice, especialmente relacionados con el script que intentabas ejecutar. Asegúrate de que display_errors está desactivado en producción, aunque en desarrollo puedes activarlo temporalmente para obtener más detalles (esto se configura en el php.ini).

4. Comprueba permisos de archivos y directorios: El proceso del servidor web (usualmente el usuario _www) necesita permisos suficientes para leer los archivos y directorios del sitio, así como escribir en carpetas de subida o de logs.

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

   Asegúrate de que el usuario correspondiente tiene acceso de lectura a la raíz del sitio y sus subdirectorios. Si necesitas subir archivos o escribir logs, se requiere permiso de escritura. Usa chmod y chown con precaución para ajustar estos permisos.

Puntos clave para los errores 500 según el servidor web

• Caddy:

  1. Configuración FastCGI: Verifica que los comandos php_fastcgi o reverse_proxy en Caddyfile apunten a la dirección correcta de PHP-FPM (normalmente 127.0.0.1:9000 o unix:/ruta/a/php-fpm.sock).
  2. Estado de PHP-FPM: Comprueba que la versión PHP elegida y el servicio PHP-FPM están activos en ServBay.
  3. Configuración de reverse proxy: Si usas reverse_proxy para gestionar otros backends (como Node.js), revisa que la dirección y el puerto sean correctos y que el backend esté operativo.

• NGINX:

  1. Directiva fastcgi_pass: Revisa en nginx.conf o en la configuración del sitio que fastcgi_pass apunte correctamente a PHP-FPM.
  2. client_max_body_size: Si ocurre un error 500 al subir archivos grandes, probablemente este valor sea demasiado bajo y limite el tamaño del cuerpo de la petición.
  3. Directiva try_files: Verifica que esté correctamente configurada para encontrar el archivo índice adecuado o reenviar la petición a FastCGI.

• Apache:

  1. Módulo mod_rewrite: Si usas archivos .htaccess para reescrituras de URL, asegúrate de que el módulo mod_rewrite esté habilitado.
  2. Contenido del archivo .htaccess: Las instrucciones incorrectas en .htaccess provocan errores 500. Revisa la sintaxis, especialmente las reglas RewriteRule.
  3. Valor de AllowOverride: Revisa que, en la configuración del directorio aplicado, AllowOverride esté permitido (All o incluyendo al menos FileInfo y Limit) para que las reglas de .htaccess tengan efecto.

Gestión de servicios

Tras modificar archivos de configuración o resolver problemas de backend, normalmente tendrás que reiniciar el servidor web o servicios relacionados para que los cambios se apliquen.

Reinicio de servicios

Usa el comando servbayctl restart para reiniciar el servidor web de tu elección.

# Reiniciar servicio Caddy
servbayctl restart caddy -all

# Reiniciar servicio NGINX
servbayctl restart nginx -all

# Reiniciar servicio Apache
servbayctl restart apache -all

El parámetro -all intentará reiniciar también los servicios relacionados, por ejemplo, reiniciando PHP-FPM junto al servidor web correspondiente si está configurado con FastCGI.

Consulta del estado de los servicios

Utiliza el comando servbayctl status para conocer el estado actual de los servicios.

# Ver estado de Caddy
servbayctl status caddy -all

# Ver estado de NGINX
servbayctl status nginx -all

# Ver estado de Apache
servbayctl status apache -all

El resultado mostrará si los servicios están en estado running (en ejecución), stopped (detenidos) u otro estado. Esto te ayudará a ver si arrancaron correctamente.

Pasos avanzados para diagnóstico

Si los métodos anteriores no resuelven el problema, prueba estos pasos adicionales:

1. Revisa las herramientas de desarrollador del navegador: Abre las devtools del navegador (usualmente pulsando F12) y accede a las pestañas Console y Network. Busca errores JavaScript en el frontend, códigos de estado de las peticiones, cabeceras y cuerpo de las respuestas. Esto ayuda a identificar si el problema está en el frontend o backend.
2. Utiliza el comando curl -v: Ejecuta en terminal curl -v your-website.servbay.demo. El parámetro -v mostrará detalles de la petición y respuesta, cabeceras, y negociaciones SSL/TLS, lo que permite identificar problemas de conexión o protocolo. Sustituye your-website.servbay.demo por tu dominio real en ServBay.
3. Desactiva temporalmente el firewall: El firewall local (como el propio de macOS) o software de seguridad pueden bloquear conexiones entrantes. Desactiva el firewall temporalmente y, si así se soluciona el problema, revisa las reglas para permitir los puertos usados por ServBay (por ejemplo, 80, 443).
4. Prueba en distintos navegadores/dispositivos: Accede al sitio web desde navegadores o dispositivos alternativos para descartar cuestiones de caché o configuraciones específicas del navegador/dispositivo.
5. Verifica la resolución DNS local o el archivo hosts: Si usas un dominio personalizado (no localhost ni IP directa), revisa el archivo /etc/hosts o tu configuración DNS local y asegúrate de que el dominio apunta a 127.0.0.1 o ::1.

Resumen

Los fallos en el servidor web son un reto común en el desarrollo local. La mayoría de los problemas pueden resolverse comprobando sistemáticamente la sintaxis de los archivos de configuración, revisando los registros de errores, asegurando que los servicios estén activos y verificando los permisos de archivos. Las herramientas integradas de diagnóstico de ServBay y la línea de comandos servbayctl son aliados clave en este proceso. Si el problema se complica, consulta la documentación avanzada de ServBay o contacta con el soporte técnico para obtener ayuda.