Guia de Solução de Problemas para Servidores Web ServBay

O ServBay oferece suporte aos servidores Caddy, NGINX e Apache como servidores web padrão, proporcionando um ambiente local de desenvolvimento flexível. Durante o uso, é possível encontrar dificuldades como site fora do ar, lentidão no carregamento ou retorno de erros (como o erro 500 Internal Server Error). Este guia tem como objetivo ajudá-lo a diagnosticar e corrigir problemas comuns relacionados aos servidores web no ambiente ServBay.

Uso da Ferramenta de Diagnóstico Interna do ServBay

O ServBay oferece uma ferramenta interna de diagnóstico de problemas que detecta automaticamente e fornece sugestões sobre os problemas mais frequentes de configuração e serviços. Recomenda-se fortemente utilizar esta ferramenta como primeiro passo na análise de qualquer problema.

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

A ferramenta verifica o status dos componentes principais do ServBay, ocupação de portas, sintaxe dos arquivos de configuração, entre outros, e apresenta dicas e sugestões para ajudar você a localizar rapidamente a origem do problema.

Lentidão ao acessar o site pela primeira vez após migrar do MAMP ou Laravel Herd

Se você mudou do MAMP ou Laravel Herd para o ServBay e percebe que, após um tempo inativo, o primeiro acesso ao site leva mais de 5 segundos para carregar, embora os acessos seguintes sejam normais. Caso volte ao estado inativo, a lentidão se repete no primeiro acesso.

Sintomas do problema

No navegador Chrome, abra as ferramentas de desenvolvedor (pressione F12 ou Cmd+Option+I), selecione a aba Network (Rede), atualize a página e clique em uma requisição para visualizar informações detalhadas em Timing (Tempo). Note que o tempo de DNS Lookup aparece em torno de 5 segundos.

(Ilustração: visualizando o tempo de DNS Lookup na aba Network das DevTools do Chrome)

Causa do problema

O MAMP e o Laravel Herd alteram forçadamente a configuração de DNS do macOS durante a instalação, criando arquivos especiais de configuração de DNS para interceptar determinados domínios (como *.test, *.local, etc.). Estes arquivos normalmente ficam no diretório /etc/resolver/.

Mesmo após a desinstalação do MAMP ou do Laravel Herd, esses arquivos de configuração de DNS podem permanecer no sistema. Ao acessar um domínio com o mesmo sufixo (como .test), o macOS tenta utilizar esses antigos resolvers para buscar o DNS, mas como o serviço de DNS do MAMP/Herd não existe mais, ocorre um timeout (tipicamente de 5 segundos), antes do sistema recorrer ao DNS padrão do sistema.

Solução

Siga os passos abaixo para eliminar completamente as configurações de DNS remanescentes do MAMP ou Laravel Herd:

1. Desinstale corretamente o MAMP ou Laravel Herd

Se ainda não fez uma desinstalação completa, utilize os procedimentos oficiais ou scripts disponibilizados:

Desinstalação do MAMP:

• Utilize a opção de desinstalação do próprio aplicativo MAMP
• Ou remova manualmente o diretório /Applications/MAMP e limpe os arquivos de configuração relacionados

Desinstalação do Laravel Herd:

# Comando oficial do Herd para desinstalação
herd uninstall

# Se o comando não estiver disponível, remova os arquivos e diretórios manualmente
rm -rf ~/Library/Application\ Support/Herd
rm -rf ~/.config/herd

2. Remova arquivos residuais do diretório /etc/resolver

Mesmo após a desinstalação apropriada, arquivos de configuração de resolvers podem permanecer em /etc/resolver/. É necessário exluí-los manualmente:

# Verifique os arquivos existentes no diretório
ls -la /etc/resolver

# Remova arquivos específicos de resolvers, por exemplo, test e local
sudo rm /etc/resolver/test
sudo rm /etc/resolver/local

# Remova também outros arquivos criados pelo MAMP/Herd, se existirem
# Exemplo: sudo rm /etc/resolver/herd

Arquivos comuns criados pelo MAMP/Herd incluem:

• test - utilizado por domínios *.test
• local - utilizado por domínios *.local
• herd - específico do Laravel Herd

Atenção: É necessário permissão de administrador (sudo) para excluir estes arquivos.

3. Evite usar o sufixo *.local

O sufixo de domínio *.local é reservado pelo macOS para serviços de mDNS de rede local (Bonjour). Utilizá-lo para ambientes de desenvolvimento pode resultar em:

• Conflitos de resolução DNS
• Lentidão no acesso
• Comportamentos inesperados de rede

Recomendação: Utilize outros sufixos para seus domínios locais, por exemplo:

• .test - reservado para fins de teste
• .localhost - garante resolução para o endereço de loopback local
• .dev - é um TLD real, mas comum em ambientes de desenvolvimento local
• Ou implemente o sufixo personalizado recomendado pelo ServBay

4. Limpe o cache de DNS (opcional)

Após realizar os procedimentos acima, limpe o cache de DNS do sistema para que as alterações tenham efeito imediato:

# Para macOS Big Sur (11) e posteriores
sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

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

5. Verifique se a correção funcionou

Após a limpeza, acesse novamente o site no ServBay:

1. Abra o navegador e acesse o site local
2. Abra o DevTools do Chrome → aba Network (Rede)
3. Atualize a página e confira os Timing (Tempo) da requisição
4. Confirme se o tempo do DNS Lookup está abaixo de 50ms

Realizando estes passos, você irá eliminar a lentidão do primeiro acesso após migrar do MAMP ou Laravel Herd. Se o problema persistir, verifique se outros softwares de terceiros (como VPN, proxies) estão interferindo na resolução de DNS.

Verificação dos arquivos de configuração dos servidores web

Erros nos arquivos de configuração são uma das causas mais comuns de sites fora do ar. O ServBay fornece ferramentas dedicadas para checagem de sintaxe de cada servidor.

Checando o Caddyfile

Use o comando validate do próprio Caddy para verificar a sintaxe do Caddyfile:

# 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

Se estiver tudo correto, o comando retorna Valid configuration. Caso haja problemas, são exibidas mensagens específicas de erro.

Observação: O comando caddy validate pode mostrar várias mensagens do tipo INFO ou WARN, geralmente referentes aos processos internos de carregamento do Caddy. Não se preocupe, desde que a saída final seja Valid configuration.

Exemplos comuns de erros no Caddyfile:

• Erro de certificado não encontrado:

  # Exemplo macOS
  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
  
  # Exemplo Windows
  2024/12/09 17:24:16.970 INFO using config from file {"file": "C:\\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 C:\\ServBay\\ssl\\private\\tls-certs\\mail.servbay.host\\mail.servbay.host.1crt: no such file or directory

  Se aparecer algo como loading certificates: open xxxxx: no such file or directory, significa que o caminho dos arquivos de certificado SSL informados no Caddyfile está incorreto ou os arquivos não existem. Verifique se os arquivos de certificado (.crt, .cer, .pem) e chave privada (.key) estão corretos e presentes no local definido. O ServBay permite importar manualmente ou solicitar certificados SSL automaticamente via ACME; confira as configurações SSL no aplicativo.

• Erro de caminho raiz do site (com espaço):

  # Exemplo 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
  
  # Exemplo 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

  O erro parsing caddyfile tokens for 'root': too many arguments normalmente ocorre quando o caminho da pasta raiz do site contém espaços. Por exemplo:

  • macOS: root * /Applications/ServBay/www/public web — public web é interpretado como dois argumentos separados
  • Windows: root * C:\ServBay\www\public web — idem acima

  Solução: utilize aspas duplas " para envolver o caminho com espaço:

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

  Dica: Para evitar este tipo de erro, prefira nomes de arquivos e pastas sem espaços ou caracteres especiais. Use - ou _ para separar palavras, por exemplo: public-folder ou public_dir.

• Erro em regras de Rewrite:

  Utilizar regras de rewrite copiadas diretamente do NGINX (ou mal formatadas) no Caddyfile pode causar falha na validação. Consulte a documentação do módulo Rewrite do Caddy ou o guia do ServBay para migração de sites do NGINX e ajuste a sintaxe adequadamente.

Checando a configuração do NGINX

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

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

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

Se estiver correto, a saída será:

# 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

Caso contrário, o NGINX apontará a linha exata do erro. Problemas de configuração comuns:

1. Erros de sintaxe: Falta de ponto e vírgula ;, chaves } não correspondentes, etc.
2. Caminho de arquivos incorretos: include e outras diretivas apontando para arquivos/pastas inexistentes.
3. Conflito de porta: Porta de escuta já em uso por outro processo.

Checando configuração Apache

Use o comando apachectl configtest para validar sintaxe dos arquivos de configuração Apache:

# macOS
/Applications/ServBay/bin/apachectl configtest

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

Se tudo estiver correto, a saída será Syntax OK. Se houver erros, o comando exibirá detalhes para correção. Erros frequentes:

1. Falha ao carregar módulos: Diretiva LoadModule apontando para módulo inexistente ou caminho errado.
2. Erros em arquivos .htaccess: Sintaxe errada no .htaccess pode causar falhas na configuração ou resultar em erro em diretórios específicos.
3. Permissões de diretório inadequadas: Diretrizes como Directory, Files, com configurações de permissão (Require, Allow, Deny) bloqueando acesso aos arquivos do site.

Lidando com Erro 500 Internal Server Error

O erro 500 é um status HTTP genérico e indica que o servidor encontrou uma situação inesperada ao processar a requisição. Na prática, costuma apontar falha na execução de scripts backend (PHP, Python, Node.js, etc.).

Passos gerais para análise

Ao se deparar com erro 500, siga estas etapas:

1. Verifique o log de erros do servidor: Esta é a primeira fonte para encontrar detalhes de erro — como problemas de script, arquivo ausente ou permissões.

   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

   Procure entradas recentes contendo termos como error ou critical.

2. Verifique se o serviço backend (ex: PHP-FPM) está rodando: Se o site depende de PHP, confirme que o PHP-FPM está ativo.

   ps aux | grep php-fpm

   Procure linhas com php-fpm: master process ou php-fpm: pool www. Se não houver processo, o serviço está parado ou caiu; reinicie via interface gráfica ou comando servbayctl.

3. Consulte o log de erros do script backend (ex: PHP): Mensagens de erro do tipo FastCGI ou direto de scripts PHP são registradas no log do PHP.

   Localização dos logs PHP:

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

   Busque por termos como Fatal error, Parse error, Warning, Notice, em especial relacionados ao script acessado. Em ambiente de produção, o display_errors deve estar desativado, mas você pode ativá-lo temporariamente em desenvolvimento via php.ini.

4. Cheque as permissões de arquivos e pastas: O processo do servidor web roda sob usuário específico e precisa ter permissão para ler arquivos do site e gravar em pastas de upload ou logs.

   macOS:

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

   Certifique-se que o usuário do servidor web (ex: _www) tem permissão de leitura na raiz e subpastas, e permissão de escrita para uploads/logs. Use chmod e chown conforme necessário.

   Windows:

   dir C:\ServBay\www\seu-site

   No Windows, garanta que sua conta de usuário tem permissões de acesso ao diretório do site; ajuste via propriedades de segurança do arquivo.

Pontos de atenção por servidor quanto ao erro 500

• Caddy:

  1. Configuração FastCGI: Verifique se a diretiva php_fastcgi ou reverse_proxy aponta para o endereço de escuta do PHP-FPM (127.0.0.1:9000 ou unix:/caminho/php-fpm.sock).
  2. Status do PHP-FPM: Confirme que a versão e o serviço PHP-FPM selecionado no ServBay estão funcionando.
  3. Proxy reverso: Se usa reverse_proxy para backend (Node.js, etc), revise endereço, porta e o funcionamento do serviço backend.

• NGINX:

  1. Diretiva fastcgi_pass: No nginx.conf ou arquivo de configuração do site, confira se está apontando corretamente para PHP-FPM.
  2. Diretiva client_max_body_size: Uploads grandes podem causar erro 500 se o tamanho permitido for pequeno.
  3. Diretiva try_files: Veja se está configurada corretamente para buscar o arquivo certo ou encaminhar via FastCGI.

• Apache:

  1. Módulo mod_rewrite: Se utiliza .htaccess para reescrita de URL, garanta que o módulo está ativo.
  2. Conteúdo do arquivo .htaccess: Erros de sintaxe podem causar erro 500 imediatamente. Revise RewriteRule e semelhantes.
  3. Diretiva AllowOverride: Veja se está habilitada (normalmente All, ou pelo menos FileInfo, Limit), permitindo que instruções do .htaccess tenham efeito.

Gerenciamento de Serviços

Após modificar configurações ou corrigir problemas backend, é necessário reiniciar o servidor web ou serviços afetados para aplicar mudanças.

Reiniciando serviços

Utilize o comando servbayctl restart para reiniciar o servidor selecionado:

# Reiniciar Caddy
servbayctl restart caddy -all

# Reiniciar NGINX
servbayctl restart nginx -all

# Reiniciar Apache
servbayctl restart apache -all

O parâmetro -all reinicia também serviços relacionados, como PHP-FPM para servidores configurados com FastCGI.

Consultando o status dos serviços

Use o comando servbayctl status para verificar o status do serviço:

# Status do Caddy
servbayctl status caddy -all

# Status do NGINX
servbayctl status nginx -all

# Status do Apache
servbayctl status apache -all

A saída mostra se o serviço está running (em execução), stopped (parado) ou outro status, facilitando o diagnóstico de inicialização.

Passos avançados para troubleshooting

Caso os procedimentos acima não resolvam, tente aplicações mais aprofundadas:

1. Ferramentas de desenvolvedor do navegador: Abra o DevTools do navegador (F12), nas abas Console e Network. Veja eventuais erros JavaScript, códigos de resposta HTTP, headers e corpo de resposta — isso ajuda a saber se o problema está no frontend ou backend.
2. Use o comando curl -v: No terminal, rode curl -v seu-site.servbay.demo; o parâmetro -v detalha todo o request/response, incluindo headers e informações SSL/TLS — útil para diagnosticar problemas de conexão ou protocolo. Substitua seu-site.servbay.demo pelo domínio real usado no ServBay.
3. Teste desativando o firewall temporariamente: Um firewall local (macOS ou softwares de terceiros) pode bloquear conexões. Desative temporariamente para testar; se resolver, configure o firewall para liberar portas usadas pelo ServBay (ex: 80, 443).
4. Teste em outros navegadores/dispositivos: Tente acessar o site em diferentes browsers ou devices; assim, você exclui problemas de cache ou configurações específicas.
5. Cheque a resolução DNS local ou arquivo hosts: Usando domínios personalizados (não localhost ou IP), verifique se estão resolvendo para 127.0.0.1 ou ::1 no arquivo hosts.
   • macOS: /etc/hosts
   • Windows: C:\Windows\System32\drivers\etc\hosts

Conclusão

Problemas de servidor web são comuns em ambientes de desenvolvimento local. Com análise sistemática dos arquivos de configuração, logs de erro, status dos serviços e permissões de arquivos, é possível resolver a maioria dos casos. Use a ferramenta de diagnóstico do ServBay e o comando servbayctl como aliados. Se o problema for complexo, consulte a documentação detalhada do ServBay ou entre em contato com o suporte técnico para auxílio especializado.