Guia de Resolução de Problemas do Servidor Web ServBay

O ServBay permite o uso dos servidores Caddy, NGINX e Apache como servidor web padrão, oferecendo um ambiente de desenvolvimento local flexível para você. Durante o uso, é possível se deparar com situações como site inacessível, lentidão ou retorno de erros (como erro 500 - Internal Server Error). Este guia foi elaborado para ajudá-lo a diagnosticar e solucionar falhas comuns relacionadas ao servidor web dentro do ambiente ServBay.

Usando a Ferramenta de Diagnóstico Integrada do ServBay

O ServBay oferece uma ferramenta de diagnóstico poderosa e integrada, capaz de identificar automaticamente problemas comuns de configuração e serviços. Recomendamos fortemente que, ao encontrar um problema, utilize primeiramente esta ferramenta para autoatendimento.

Abra o aplicativo ServBay e clique em Diagnóstico na barra de navegação à esquerda para acessar a interface de diagnóstico do próprio ServBay.

A ferramenta verificará o status dos principais componentes do ServBay, portas em uso, sintaxe dos arquivos de configuração e fornecerá dicas e recomendações para ajudar você a localizar rapidamente a causa do problema.

Verificando os Arquivos de Configuração do Servidor Web

Erros na configuração do servidor web são uma das principais causas de sites inacessíveis. O ServBay oferece verificadores de sintaxe específicos para cada servidor.

Verificação do Caddyfile

Use o comando validate integrado do Caddy para conferir se seu arquivo Caddyfile está correto.

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

Se a sintaxe do arquivo estiver correta, o comando retornará Valid configuration. Caso haja erros, serão exibidas mensagens específicas de acordo com o tipo de erro.

Atenção: O comando caddy validate pode gerar muitas saídas INFO ou WARN, mas geralmente se referem a informações do processo interno de carregamento do Caddy e não necessariamente indicam erro de configuração. Se ao final aparecer Valid configuration, a sintaxe está correta.

Exemplos comuns de erro no Caddyfile:

• Erro de arquivo de certificado inexistente:

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

  Erros como loading certificates: open xxxxx: no such file or directory significam que o caminho do certificado SSL especificado no seu Caddyfile está incorreto ou o arquivo não existe. Verifique se o caminho configurado para o certificado (.crt/.cer/.pem) e a chave privada (.key) está correto e se os arquivos existem no local indicado. O ServBay permite importar manualmente ou solicitar certificados SSL automaticamente via ACME; confira as configurações SSL do ServBay conforme necessário.

• Erro de caminho do diretório raiz com espaços:

  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

  O erro parsing caddyfile tokens for 'root': too many arguments costuma ocorrer quando há espaços no caminho do diretório raiz, como em root * /Applications/ServBay/www/public web, onde public web será lido como dois argumentos distintos. O correto é envolver caminhos com espaços entre aspas duplas, por exemplo: root * "/Applications/ServBay/www/public web".

  Recomendação: Para evitar esses problemas, evite usar espaços e caracteres especiais ao nomear arquivos e pastas. Use hífen - ou underline _ para separar palavras, como em public-folder ou public_dir.

• Erro em regras de Rewrite:

  Utilizar regras de reescrita copiadas diretamente do NGINX ou fora do padrão Caddy pode causar falhas na validação do Caddyfile. Consulte a documentação do módulo Rewrite do Caddy ou o guia ServBay para migrar sites do NGINX, certificando-se de que as regras estejam corretas.

Verificação da Configuração do NGINX

Use o parâmetro -t do NGINX para testar a sintaxe e validade do arquivo de configuração:

/Applications/ServBay/bin/nginx -t

Se a configuração estiver correta, você verá:

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

Se houver erros, o NGINX indicará em qual arquivo e linha o problema ocorreu. Os erros mais comuns incluem:

1. Erro de sintaxe: Como falta de ponto e vírgula ; ou chaves } fora de pares.
2. Erro no caminho do arquivo: Caminhos incorretos ou inexistentes em diretivas como include.
3. Conflito de porta: Quando a porta definida já está em uso por outro serviço.

Verificação da Configuração do Apache

Use o comando apachectl configtest para conferir a sintaxe da configuração do Apache:

/Applications/ServBay/bin/apachectl configtest

No caso de configuração correta, verá a mensagem Syntax OK. Se houver um erro, será exibida uma mensagem detalhada. Erros comuns no Apache incluem:

1. Falha ao carregar módulo: O módulo ativado via LoadModule não existe ou o caminho está incorreto.
2. Erro de sintaxe em .htaccess: Arquivos .htaccess com erros podem fazer todo o Apache falhar ou causar erro na pasta específica.
3. Permissões inadequadas de diretório: Diretivas como Directory ou Files com permissões (Require, Allow, Deny) restritivas podem bloquear o acesso aos arquivos do site.

Tratando o Erro 500 Internal Server Error

O erro 500 Internal Server Error é um código HTTP genérico que significa que o servidor encontrou algo inesperado e não conseguiu completar a solicitação. Na prática, geralmente indica falhas na execução de scripts back-end (como PHP, Python, Node.js etc.).

Passos Gerais de Diagnóstico

Quando encontrar um erro 500, siga estes passos:

1. Verifique o log de erro do servidor web: Este é o ponto de partida mais importante. Os logs frequentemente trazem detalhes do erro, como falhas em scripts, arquivos não encontrados ou problemas de permissão.

   • Caddy: /Applications/ServBay/var/logs/caddy/error.log
   • NGINX: /Applications/ServBay/var/logs/nginx/error.log
   • Apache: /Applications/ServBay/var/logs/apache/error.log Veja as entradas mais recentes e procure mensagens com error ou critical.

2. Verifique se o serviço back-end (ex: PHP-FPM) está rodando: Para sites em PHP, garanta que o PHP-FPM está ativo:

   ps aux | grep php-fpm

   Procure por linhas contendo php-fpm: master process ou php-fpm: pool www. Se não aparecerem, o PHP-FPM pode não estar rodando ou ter travado. Você pode iniciá-lo pela interface do ServBay ou via comando servbayctl.

3. Confira o log de erro do script back-end (PHP): Quando o log do servidor web indicar erro do FastCGI ou script, veja o log relevante:

   • PHP: /Applications/ServBay/var/logs/php/php_error.log Busque por mensagens como Fatal error, Parse error, Warning, Notice, especialmente para os scripts acessados no momento do erro. O ideal é manter o display_errors desligado em produção, mas pode ser útil ativar em desenvolvimento (geralmente configurado no php.ini).

4. Valide permissões dos arquivos e pastas: Em geral, os processos do servidor web rodam com usuários específicos (como _www) e precisam de permissões adequadas para ler arquivos e diretórios do site e, se necessário, gravar em pastas de upload ou logs.

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

   Garanta que o usuário do servidor web tenha leitura (e, se necessário, escrita) sobre os diretórios e arquivos relevantes. Ajuste com chmod e chown com cautela.

Pontos Específicos por Servidor Web para Diagnosticar Erros 500

• Caddy:

  1. Configuração FastCGI: Confira se as diretivas php_fastcgi ou reverse_proxy no Caddyfile encaminham corretamente para o endereço do PHP-FPM (usualmente 127.0.0.1:9000 ou unix:/caminho/para/php-fpm.sock).
  2. Status do PHP-FPM: Assegure-se de que a versão certa do PHP e o PHP-FPM no ServBay estejam rodando.
  3. Configuração de proxy reverso: Se utilizar reverse_proxy para outra aplicação (ex: Node.js), cheque se o endereço e a porta do back-end estão certos e se o serviço está rodando.

• NGINX:

  1. Diretiva fastcgi_pass: Verifique se esta instrução em nginx.conf (ou no arquivo da aplicação) aponta para o local correto do serviço PHP-FPM.
  2. client_max_body_size: Para upload de arquivos grandes, aumente este limite caso necessário.
  3. Diretiva try_files: Certifique-se de que leva ao arquivo de índice ou repassa corretamente ao FastCGI.

• Apache:

  1. Módulo mod_rewrite: Se .htaccess usa reescrita de URL, verifique se o mod_rewrite está habilitado.
  2. Revisão do arquivo .htaccess: Qualquer erro neste arquivo pode causar erro 500. Confira sintaxe, especialmente em regras do tipo RewriteRule.
  3. Configuração AllowOverride: No arquivo de configuração do Apache, permita o uso de diretivas do .htaccess para o diretório relevante (geralmente como All ou, pelo menos, incluindo FileInfo e Limit).

Gerenciamento de Serviços

Após ajustar arquivos ou resolver problemas de serviço, normalmente é necessário reiniciar os servidores para que as mudanças tenham efeito.

Reiniciando Serviços

Execute o comando servbayctl restart para reiniciar o serviço desejado:

# Reiniciar o serviço Caddy
servbayctl restart caddy -all

# Reiniciar o serviço NGINX
servbayctl restart nginx -all

# Reiniciar o serviço Apache
servbayctl restart apache -all

O argumento -all garante que todos os serviços relacionados ao servidor web (ex: FastCGI junto à reinicialização do Caddy/NGINX/Apache) também sejam reiniciados quando aplicável.

Conferindo o Status do Serviço

Use o comando servbayctl status para ver o status atual do serviço:

# Verificar status do Caddy
servbayctl status caddy -all

# Verificar status do NGINX
servbayctl status nginx -all

# Verificar status do Apache
servbayctl status apache -all

A saída mostrará se o serviço está running (em execução), stopped (parado) ou em outro estado. Isso ajuda a verificar se o serviço iniciou corretamente.

Passos Avançados de Diagnóstico

Se nenhuma das opções acima resolver o problema, siga alguns passos mais avançados:

1. Analise com ferramentas do navegador: Abra as ferramentas para desenvolvedores (geralmente F12), acesse as abas Console e Network. Confira erros de JavaScript no frontend, códigos de status HTTP detalhados, cabeçalhos e corpo das respostas para identificar se o erro está do lado do back-end ou do lado do cliente.
2. Use o comando curl -v: No terminal, execute curl -v seu-site.servbay.demo para acessar o site. O parâmetro -v mostra o detalhamento das requisições/respostas, cabeçalhos e informações SSL/TLS, facilitando o diagnóstico de problemas de conexão/protocolo. Substitua seu-site.servbay.demo pelo domínio real do seu ambiente no ServBay.
3. Desative temporariamente o firewall: Firewalls locais (como o nativo do macOS ou antivírus) podem bloquear acessos. Desative o firewall local por um curto período para testar e, se resolver, ajuste as regras para permitir as portas usadas pelo ServBay (geralmente 80, 443, etc.).
4. Teste em outros navegadores/dispositivos: Acesse o site em navegadores diferentes ou em outro computador/dispositivo para descartar problemas de cache ou configurações específicas do equipamento.
5. Cheque configurações do DNS local ou arquivo hosts: Se estiver usando um domínio customizado (diferente de localhost ou IP), confira o arquivo /etc/hosts ou suas configurações DNS locais para garantir que o domínio aponta para 127.0.0.1 ou ::1.

Conclusão

Falhas em servidores web são desafios comuns no desenvolvimento local. Seguindo um roteiro de verificação da sintaxe dos arquivos de configuração, análise de logs, checagem do status dos serviços e validação de permissões, é possível resolver a maioria dos problemas rapidamente. As ferramentas integradas de diagnóstico e a linha de comando servbayctl do ServBay são grandes aliadas nesse processo. Se encontrar dificuldades mais avançadas, não hesite em consultar a documentação detalhada do ServBay ou contatar o suporte técnico.