Guia de Troubleshooting Comum¶

Mesmo com uma configuração cuidadosa e automatizada, problemas podem (e irão!) surgir no seu servidor doméstico. Saber como diagnosticar e resolver esses problemas é uma habilidade essencial. Este guia oferece um ponto de partida com ferramentas, técnicas e soluções para alguns dos cenários de erro mais comuns que você pode encontrar.

Ferramentas Essenciais de Diagnóstico¶

Familiarize-se com estas ferramentas. Elas serão suas melhores amigas durante o troubleshooting:

Logs de Containers Docker:
- Via Portainer: A maneira mais fácil de visualizar logs de containers individuais.
  1. Acesse o Portainer (https://portainer.{{ base_domain }}).
  2. Navegue até o endpoint Docker correto (e.g., local para core-services-vm).
  3. Vá para "Containers", selecione o container problemático.
  4. Clique no ícone de "Logs" (📄).
  5. Use as opções para filtrar por data/hora, habilitar auto-refresh, ou definir o número de linhas a serem exibidas.
- Via Linha de Comando (na VM onde o Docker roda, e.g., core-services-vm):
```
# Ver todos os logs de um container
docker logs <nome_do_container_ou_id>

# Seguir os logs em tempo real (útil para ver o que acontece ao iniciar)
docker logs -f <nome_do_container_ou_id>

# Ver as últimas N linhas (e.g., 100)
docker logs --tail 100 <nome_do_container_ou_id>

# Ver logs com timestamps
docker logs -t <nome_do_container_ou_id>
```
Dashboard e Logs do Traefik:
- Dashboard Traefik: Acessível em https://traefik.{{ base_domain }} (protegido por Authelia).
  - Routers: Verifique se o roteador para o seu serviço problemático existe, está ativo (verde), e se a regra (Rule) corresponde ao hostname esperado.
  - Services: Verifique se o serviço backend associado ao roteador está saudável e aponta para o(s) container(es) correto(s) e a porta interna correta.
  - Middlewares: Verifique se os middlewares esperados (e.g., Authelia, headers) estão aplicados ao roteador e se não há erros neles.
  - Entrypoints: Confirme se seus entrypoints (web, websecure) estão ativos.
- Logs do Traefik: Acesse os logs do container traefik via Portainer ou docker logs traefik.
  - Procure por erros ao processar labels Docker, obter certificados SSL/TLS da Let's Encrypt, ou ao tentar se conectar aos serviços backend. Aumentar o nível de log do Traefik para DEBUG (no traefik.yml e reiniciar Traefik) pode fornecer mais detalhes.
Logs do Authelia:
- Acesse os logs do container authelia via Portainer ou docker logs authelia.
- Crucial para diagnosticar problemas de login, falhas de 2FA, ou erros em regras de controle de acesso. Aumentar o nível de log no configuration.yml do Authelia também pode ajudar.
Logs do Sistema (Host Proxmox e VMs): Conecte-se via SSH ao host ou VM relevante.
- journalctl (Systemd Journal):
```
journalctl -xe # Mostra os últimos logs com explicações de erros
journalctl -f # Segue os logs do sistema em tempo real
journalctl -u nome_do_servico.service # Logs de um serviço systemd específico (e.g., sshd, nfs-kernel-server, ollama)
journalctl -p err # Mostra apenas logs com prioridade de erro ou superior
```
- dmesg: Mostra mensagens do buffer do kernel. Útil para problemas de hardware, drivers, ou erros de baixo nível.
```
dmesg
dmesg | grep -i error # Filtra por erros
```
- Logs Tradicionais em /var/log/:
  - /var/log/syslog ou /var/log/messages: Logs gerais do sistema.
  - /var/log/auth.log: Logs de autenticação (logins SSH, sudo).
  - /var/log/kern.log: Logs do kernel.
  - Logs específicos de aplicações instaladas nativamente.
Ferramentas de Rede (Execute na sua máquina de controle, ou dentro de uma VM/container para testes específicos):
- ping <hostname_ou_IP>: Testa a conectividade de rede básica (ICMP).
- nslookup <hostname> ou dig <hostname>: Verifica a resolução DNS. Essencial para ver se meuservico.{{ base_domain }} está resolvendo para IPs da Cloudflare.
- curl -vL <URL>: Faz uma requisição HTTP/S e mostra detalhes verbosos da conexão, incluindo headers HTTP, códigos de status e redirecionamentos. Extremamente útil para testar Traefik, Authelia e o serviço backend.
  - Exemplo: curl -vL https://nextcloud.{{ base_domain }}
- traceroute <hostname_ou_IP> (Linux/macOS) ou tracert <hostname_ou_IP> (Windows): Mostra o caminho (saltos de rede) que os pacotes levam para alcançar um destino.
- mtr <hostname_ou_IP>: Combina ping e traceroute, fornecendo uma visão contínua da qualidade da conexão em cada salto.
- ss -tulnp (Linux) ou netstat -tulnp: Mostra quais portas estão abertas e escutando em um sistema e quais processos as estão usando. Útil para verificar se um serviço está escutando na porta esperada dentro de uma VM ou container.
Browser Developer Tools (Geralmente F12 no seu navegador web):
- Aba Network: Inspecione todas as requisições HTTP/S feitas pela página web do seu serviço. Verifique:
  - Códigos de Status (200 OK, 3xx Redirecionamentos, 4xx Erros do Cliente, 5xx Erros do Servidor).
  - Headers da Requisição e da Resposta.
  - Tempos de carregamento de cada recurso.
  - Se algum recurso (CSS, JS, imagem) está falhando ao carregar.
- Aba Console: Verifique por erros JavaScript que podem estar quebrando a funcionalidade da interface do usuário de um serviço web.
- Aba Application (ou Storage): Inspecione cookies, local storage, session storage. Útil para depurar problemas de sessão com Authelia ou a própria aplicação.

Problemas Comuns e Estratégias de Solução¶

1. Serviço Web Inacessível Externamente (`https://meuservico.{{ base_domain }}`)¶

Sintomas Comuns: Erro "Site não pode ser alcançado" no navegador, timeout, erro 5xx da Cloudflare (e.g., 502 Bad Gateway, 503 Service Unavailable), erro 404 "Not Found" do Traefik, página de login do Authelia não aparece ou dá erro.
Checklist de Diagnóstico (Siga a ordem do fluxo de tráfego):
1. DNS Público (Cloudflare):
  - O subdomínio (meuservico) está configurado corretamente no seu painel DNS da Cloudflare?
  - Se usa CNAME, ele aponta para o hostname correto do seu Cloudflare Tunnel (e.g., UUID.cfargotunnel.com)?
  - Se usa Ingress Rules/Public Hostnames no Zero Trust Dashboard, a regra para meuservico.{{ base_domain }} existe e aponta para o serviço http://traefik:80?
  - O "Proxy status" (nuvem laranja) está habilitado para o registro DNS?
  - Use uma ferramenta online de DNS lookup (ou nslookup meuservico.{{ base_domain }} na sua máquina) para verificar se ele resolve para endereços IP da Cloudflare.
2. Cloudflare Tunnel (cloudflared Agent):
  - O container cloudflared está rodando na core-services-vm? Verifique no Portainer.
  - Examine os logs do cloudflared: docker logs cloudflared. Procure por:
    - Erros de conexão com a Cloudflare ("Connection refused", "failed to connect to an edge").
    - Erros ao encaminhar para o Traefik (se estiver usando --url http://traefik:80, ele deve conseguir resolver traefik).
  - No dashboard Cloudflare Zero Trust (Access -> Tunnels), verifique o status do seu túnel. Deve estar "Healthy".
3. Traefik (Proxy Reverso):
  - O container traefik está rodando na core-services-vm?
  - Acesse o Dashboard do Traefik (https://traefik.{{ base_domain }} - você precisará autenticar com Authelia).
    - Routers: O roteador para meuservico.{{ base_domain }} existe e está com status verde? A Rule está correta (Host(\meuservico.{{ base_domain }}`))? OsEntryPoints(websecure`) estão corretos?
    - Services: O serviço backend associado ao roteador está saudável? Ele aponta para o(s) container(es) correto(s) do meuservico e para a porta interna correta que o meuservico escuta?
    - Middlewares: Os middlewares aplicados ao roteador (e.g., authelia@docker, securityHeaders@file) estão corretos e sem erros?
  - Verifique as labels Docker do container meuservico no seu docker-compose.yml. Estão corretas quanto ao nome do host, entrypoint, nome do serviço Traefik, e a porta interna do container (loadbalancer.server.port)?
  - Examine os logs do Traefik (docker logs traefik) para erros específicos relacionados a este serviço, problemas com certificados SSL, ou falhas ao conectar ao backend.
4. Authelia (se o serviço estiver protegido por ele):
  - O container authelia e seu banco de dados (authelia_db) estão rodando?
  - Você consegue acessar o portal Authelia (https://auth.{{ base_domain }})?
  - Examine os logs do Authelia (docker logs authelia) para erros de autenticação, problemas com as regras de acesso (access_control no configuration.yml), ou falhas de conexão com o banco de dados.
  - A configuração do middleware authelia@docker no Traefik (definida no docker-compose.yml do Authelia) está correta?
5. Container do Serviço de Destino (meuservico):
  - O container meuservico está rodando na core-services-vm (ou ai-desktop-vm se aplicável)?
  - Ele está conectado à rede Docker correta (geralmente proxy se exposto via Traefik)?
  - O serviço dentro do container está realmente escutando na porta interna que o Traefik espera (e.g., se Traefik está configurado para encaminhar para a porta 8000 do container, o serviço dentro do container deve estar escutando em 0.0.0.0:8000 ou :::8000)?
    - Use docker exec -it <nome_do_container_meuservico> ss -tulnp (ou netstat -tulnp) dentro do container para verificar as portas em escuta.
  - Examine os logs do container meuservico para quaisquer erros de inicialização, falhas ao processar requisições, ou problemas de configuração interna.
6. Firewalls (Menos Provável se Outros Serviços Funcionam):
  - O UFW na core-services-vm está permitindo tráfego de entrada nas portas 80 e 443 (para Traefik)? (Isso já deve ter sido configurado pelo Ansible).
  - O PVE Firewall no host Proxmox não deve estar bloqueando tráfego entre a internet e a core-services-vm se o Cloudflare Tunnel estiver funcionando, pois o túnel é uma conexão de saída.

2. Container Não Inicia ou Fica em Loop de Crash (Status "Restarting")¶

Sintomas: O container aparece como "Stopped", "Created", ou fica alternando entre "Starting" e "Restarting" no Portainer.
Principal Ferramenta de Diagnóstico:
1. docker logs <nome_do_container_ou_id>: Esta é a primeira e mais importante etapa. Os logs do container quase sempre indicam o motivo exato da falha ou do crash. Execute este comando na VM onde o container deveria estar rodando.
Causas Comuns e Soluções:
- Erro de Configuração no docker-compose.yml ou Variáveis de Ambiente:
  - Uma variável de ambiente obrigatória está faltando ou tem um valor incorreto?
  - Um caminho de volume mapeado está incorreto ou o diretório de origem não existe/não tem permissões?
- Problemas de Permissão nos Volumes Mapeados:
  - O usuário/UID com o qual o processo principal dentro do container roda (definido pela imagem Docker ou pelas variáveis PUID/PGID no compose) não tem permissão para ler/escrever nos diretórios NFS mapeados?
  - Lembre-se que nossos exports NFS usam all_squash para anonuid={{ docker_puid }} e anongid={{ docker_pgid }}. Garanta que o PUID/PGID no seu compose corresponda a estes valores e que os diretórios no NFS tenham o dockeruser:dockergroup como proprietário/grupo na VM.
  - Verifique as permissões nos diretórios NFS dentro da VM (e.g., ls -ld /mnt/pve_data_zfs/docker-volumes/meuservico/config).
- Porta Já em Uso (se o container tenta mapear uma porta diretamente no host da VM):
  - Se o docker-compose.yml tem uma seção ports: (e.g., -p 8080:80) e a porta 8080 na VM já está sendo usada por outro processo ou container, o novo container falhará ao iniciar.
  - Use sudo ss -tulnp | grep <numero_da_porta> na VM para ver qual processo está usando a porta.
- Recursos Insuficientes na VM:
  - A VM tem RAM ou CPU livre suficiente para o container iniciar e rodar? (Menos comum para uma falha de inicialização imediata, mas pode causar crashes se o container tentar alocar muita memória rapidamente). Verifique o uso de recursos na VM.
- Dependências Não Satisfeitas (Outros Containers):
  - Se o container depende de outro serviço (e.g., um banco de dados) e esse serviço não está rodando ou não está acessível, o container dependente pode falhar ao iniciar.
  - Use depends_on com condition: service_healthy no docker-compose.yml para ajudar com a ordem de inicialização, mas o container principal ainda precisa estar funcional.
- Arquivo de Configuração Interno Corrompido ou Inválido:
  - Se o container iniciou uma vez, criou arquivos de configuração em seu volume, e depois esses arquivos foram corrompidos ou editados incorretamente, ele pode falhar ao reiniciar. Verifique os logs para mensagens sobre falha ao ler/parsear arquivos de configuração.
- Imagem Docker Incorreta ou Corrompida:
  - Raramente, a imagem Docker baixada pode estar corrompida. Tente remover a imagem local (docker rmi <imagem>) e deixar o Docker Compose baixá-la novamente.
  - Verifique se a tag da imagem especificada no docker-compose.yml realmente existe no registro.

3. Problemas com Volumes NFS (Persistência de Dados)¶

Sintomas: Containers não conseguem ler ou escrever em seus volumes persistentes, os dados não são salvos entre reinícios do container, erros de "Permission denied" ou "Read-only file system" nos logs do container relacionados a caminhos de volume.
Checklist de Diagnóstico:
1. Servidor NFS no Host Proxmox:
  - O serviço nfs-kernel-server está rodando no host Proxmox? Verifique com sudo systemctl status nfs-kernel-server.
  - O arquivo /etc/exports no host Proxmox está correto?
    - Os caminhos dos datasets ZFS (e.g., /data/docker-volumes) estão corretos?
    - O CIDR da sua rede de VMs ({{ vm_nfs_allowed_clients_cidr }}) está correto e permite acesso aos IPs das suas VMs?
    - As opções de exportação (rw,sync,no_subtree_check,all_squash,anonuid={{ docker_puid }},anongid={{ docker_pgid }}) estão definidas como esperado?
  - Após qualquer mudança no /etc/exports, você executou sudo exportfs -rav no host Proxmox para aplicar as mudanças?
2. Cliente NFS na VM (e.g., core-services-vm):
  - O pacote nfs-common está instalado? (Deveria estar, via role common).
  - Os compartilhamentos NFS do host Proxmox estão montados corretamente na VM? Verifique com:
```
df -hT | grep nfs
mount | grep nfs
```
    Você deve ver seus datasets (e.g., /data/docker-volumes) montados em /mnt/pve_data_zfs/docker-volumes (ou seu {{ vm_nfs_mount_base_path }}).
  - O arquivo /etc/fstab na VM contém as entradas corretas para montar os compartilhamentos NFS automaticamente no boot, com as opções corretas (e.g., rw,sync,hard,intr,bg,noatime,nodiratime,rsize=1048576,wsize=1048576,vers=4.2)?
  - Você consegue listar, criar e deletar arquivos (como root ou como {{ vm_ansible_user_name }}) nos pontos de montagem NFS dentro da VM? Exemplo: ls -l /mnt/pve_data_zfs/docker-volumes/ sudo touch /mnt/pve_data_zfs/docker-volumes/testfile && sudo rm /mnt/pve_data_zfs/docker-volumes/testfile
3. Permissões de Arquivo/Diretório nos Volumes NFS (Dentro da VM):
  - Quais são as permissões e o proprietário/grupo dos diretórios que são mapeados para os containers (e.g., /mnt/pve_data_zfs/docker-volumes/nextcloud/config)? Use ls -ld /caminho/para/diretorio_do_volume na VM.
  - Devido às opções all_squash, anonuid={{ docker_puid }}, anongid={{ docker_pgid }} no export NFS, os arquivos e diretórios criados pela VM no montado NFS (ou pelo host Proxmox diretamente nos datasets) devem aparecer na VM como pertencentes ao UID/GID especificados por anonuid/anongid (que são {{ docker_puid }} e {{ docker_pgid }}).
  - O PUID e PGID definidos nas variáveis de ambiente do seu container Docker correspondem a esses valores?
4. Firewall:
  - O firewall no host Proxmox (PVE Firewall) está permitindo tráfego NFS (porta TCP/UDP 2049, e possivelmente portas para rpcbind/portmapper se usar NFSv3 ou inferior) vindo dos IPs das suas VMs?
  - O firewall UFW na VM não deve bloquear o tráfego NFS de saída para o host Proxmox (a política de saída padrão é allow).
5. Logs do Kernel/Sistema (em ambas as máquinas):
  - Verifique dmesg e journalctl no host Proxmox e na VM por erros relacionados a NFS (e.g., "mount.nfs: access denied by server", "Stale file handle").

4. Problemas de Autenticação com Authelia¶

Sintomas: Redirecionamentos inesperados para o portal Authelia, erros na página de login do Authelia (e.g., "Invalid credentials", "Internal Server Error"), falha no segundo fator (2FA), acesso negado a um serviço mesmo após login bem-sucedido.
Checklist de Diagnóstico:
1. Logs do Authelia: docker logs authelia na core-services-vm. Este é o primeiro lugar para procurar. Aumente o nível de log no configuration.yml do Authelia se precisar de mais detalhes.
2. Configuração do Authelia (authelia/config/configuration.yml):
  - jwt_secret e session.secret: Estão definidos, são complexos e são os mesmos que Authelia está usando? (Se você os define via variáveis de ambiente no compose, certifique-se que estão sendo passados corretamente).
  - session.domain: Está configurado para o seu domínio pai (e.g., {{ base_domain }}), e NÃO para um subdomínio como auth.{{ base_domain }}? Isso é crucial para que o cookie de sessão funcione em todos os seus subdomínios.
  - storage (PostgreSQL): A configuração do banco de dados (host authelia_db, usuário, senha, nome do DB) está correta e o container authelia_db está rodando e saudável?
  - access_control.rules: As regras estão definidas como você espera? A default_policy está correta? As regras para domínios específicos e a regra bypass para auth.{{ base_domain }} estão presentes e corretas?
  - notifier (SMTP): Se configurado, está correto? Problemas aqui podem impedir o reset de senha.
3. Conectividade com o Banco de Dados PostgreSQL do Authelia:
  - O container authelia consegue alcançar o container authelia_db na rede internal_services?
  - Verifique os logs do authelia_db também.
4. Cookies do Navegador:
  - Tente limpar os cookies do seu navegador para o seu {{ base_domain }} e para auth.{{ base_domain }} e tente logar novamente.
  - Use as Developer Tools do navegador (F12 -> Aba Application/Storage -> Cookies) para inspecionar o cookie de sessão do Authelia (geralmente chamado homelab_authelia_session ou o que você definiu em session.name). Ele está sendo definido para o domínio correto?
5. Sincronia de Relógio:
  - Certifique-se de que o relógio na core-services-vm (e, portanto, nos containers) está sincronizado corretamente com um servidor NTP. Desvios significativos de tempo podem afetar a validação de códigos TOTP para 2FA.
6. Configuração do Middleware authelia@docker no Traefik:
  - No docker-compose.yml da stack Authelia (Seção 5.3), a definição do middleware traefik.http.middlewares.authelia.forwardauth.address está correta, apontando para http://authelia:9091/api/verify...?
  - Os serviços que você quer proteger no Traefik estão referenciando este middleware corretamente (e.g., middlewares: "authelia@docker")?

5. Problemas com Certificados SSL/TLS (Let's Encrypt via Traefik)¶

Sintomas: Avisos de certificado inválido, expirado, ou "não confiável" no navegador ao acessar seus serviços HTTPS. Erros de "SSL handshake failed".
Checklist de Diagnóstico:
1. Logs do Traefik: docker logs traefik. Procure por mensagens de erro contendo "ACME", "Let's Encrypt", "TLS certificate", ou "challenge". Aumentar o nível de log do Traefik para DEBUG pode fornecer informações muito detalhadas sobre o processo de obtenção de certificados.
2. Configuração do Resolvedor ACME no traefik.yml (Config Estática):
  - O email para Let's Encrypt está correto?
  - O storage para o acme.json (e.g., /data/acme.json dentro do container Traefik) está correto e o container Traefik tem permissão de escrita nesse caminho no volume NFS? (Verifique as permissões do diretório traefik/data no NFS).
  - Para o dnsChallenge com provider: "cloudflare":
    - A variável de ambiente CF_DNS_API_TOKEN está sendo passada corretamente para o container Traefik (verifique o docker-compose.yml da stack core e o .env carregado)?
    - O token API da Cloudflare que você gerou é válido e tem as permissões corretas (geralmente "Zone:DNS:Edit" para o seu {{ base_domain }})?
3. Arquivo acme.json:
  - Localização: {{ vm_nfs_mount_base_path }}/{{ zfs_docker_volumes_dataset_name }}/traefik/data/acme.json na core-services-vm.
  - Verifique o conteúdo (é um arquivo JSON). Ele contém entradas para seus domínios e os certificados? Há mensagens de erro dentro dele?
  - Não Edite acme.json Manualmente
    A edição manual deste arquivo pode corrompê-lo. Se você suspeitar que ele está corrompido e o Traefik não consegue obter/renovar certificados:
    1. Pare o container Traefik.
    2. Faça um backup do acme.json atual (e.g., renomeie para acme.json.bak).
    3. Delete o acme.json original (ou deixe o diretório traefik/data vazio se não houver outros arquivos importantes lá).
    4. Inicie o container Traefik. Ele tentará obter novos certificados para todos os seus roteadores configurados com Let's Encrypt.
    Limites de Taxa da Let's Encrypt
    Se você deletar o acme.json e forçar o Traefik a obter muitos certificados repetidamente em um curto período, você pode atingir os limites de taxa da Let's Encrypt (e.g., para "Certificates per Registered Domain" ou "Failed Validation limit"). Se isso acontecer, você terá que esperar (geralmente uma hora ou até uma semana para alguns limites) antes de tentar novamente.
4. Propagação de DNS: Para o desafio DNS-01, Traefik (via API da Cloudflare) precisa criar um registro TXT temporário no DNS do seu domínio. Este registro precisa ser publicamente resolúvel pelos servidores da Let's Encrypt para que o desafio seja bem-sucedido. Se sua propagação de DNS for excepcionalmente lenta (raro com Cloudflare), ou se houver problemas com a API da Cloudflare, o desafio pode falhar.
5. Roteadores Traefik: Os roteadores para seus serviços HTTPS no Traefik (definidos por labels Docker ou File Provider) estão configurados corretamente com tls: true (geralmente implícito com entrypoints: "websecure") e tls.certresolver: "letsencrypt"?

Lembre-se que o troubleshooting é frequentemente um processo de eliminação. Comece com os logs, formule hipóteses sobre a causa raiz e teste-as sistematicamente. Anote o que você tentou e os resultados para não repetir os mesmos passos ou se perder.