O Docker simplifica a implementação, mas introduz a sua própria classe de problemas — problemas de rede, erros de permissões, restrições de recursos e falhas de build. Diagnosticar e resolver rapidamente problemas no Docker é essencial para manter a velocidade de desenvolvimento e a estabilidade em produção. Este guia aborda problemas comuns do Docker e soluções na perspetiva de um programador sénior.
Porque é que as Competências de Troubleshooting Importam
O troubleshooting de Docker permite:
- Desenvolvimento mais rápido: Desbloquear rapidamente o seu trabalho e o da equipa
- Fiabilidade em produção: Minimizar o tempo de indisponibilidade causado por problemas de containers
- Eficiência de recursos: Identificar fugas de memória e consumidores excessivos de recursos
- Segurança: Compreender e corrigir problemas de permissões e de rede
- Otimização de custos: Evitar containers descontrolados a consumir recursos
Comandos de Diagnóstico
Verificar o Estado do Docker
# Estado do Docker daemon
sudo systemctl status docker
# Logs do Docker daemon
sudo journalctl -u docker.service
# Informação do Docker
docker info
# Versão do Docker
docker version
Diagnóstico de Containers
# Listar todos os containers
docker ps -a
# Logs do container
docker logs container_name
docker logs -f container_name # Seguir/stream
docker logs --tail 100 container_name # Últimas 100 linhas
docker logs --since 1h container_name # Última hora
# Detalhes do container
docker inspect container_name
# Utilização de recursos
docker stats
docker stats container_name --no-stream
# Processos dentro do container
docker top container_name
# Executar comandos de diagnóstico
docker exec -it container_name sh
docker exec container_name cat /etc/hosts
docker exec container_name env
Problemas Comuns e Soluções
1. O Container Não Arranca
Sintoma: O container termina imediatamente após arrancar.
# Verificar código de saída
docker ps -a --filter "name=container_name"
# Ver logs
docker logs container_name
Causas comuns:
# Código de saída 0: Processo concluído com sucesso (verifique se o comando está em foreground)
# Correção: Garanta que o processo principal corre em foreground
# Mau: CMD service nginx start
# Bom: CMD ["nginx", "-g", "daemon off;"]
# Código de saída 1: Erro da aplicação
# Verifique os logs para stack traces
# Código de saída 137: Sem memória (OOM killed)
# Aumentar o limite de memória
docker run -m 512m my-app
# Código de saída 139: Falha de segmentação
# Verifique a aplicação quanto a problemas de corrupção de memória
# Código de saída 126: Permissão negada
# Verifique as permissões de ficheiros e o utilizador
# Código de saída 127: Comando não encontrado
# Verifique se os caminhos de CMD/ENTRYPOINT estão corretos
2. Não é Possível Ligar ao Docker Daemon
Sintoma: Cannot connect to the Docker daemon at unix:///var/run/docker.sock
# Iniciar o Docker daemon
sudo systemctl start docker
# Verifique se o utilizador atual está no grupo docker
groups
# Adicionar utilizador ao grupo docker
sudo usermod -aG docker $USER
# Aplicar a alteração de grupo (ou terminar sessão/iniciar sessão)
newgrp docker
# Ou
su - $USER
3. Problemas de Rede entre Containers
Sintoma: Os containers não conseguem comunicar entre si ou com a internet.
# Verificar a configuração de rede
docker network ls
docker network inspect bridge
# Testar a resolução de DNS dentro do container
docker exec -it container_name nslookup google.com
# Testar conectividade com outro container
docker exec -it container1 ping container2
# Verificar regras de firewall
sudo firewall-cmd --list-all
Soluções:
# Containers não conseguem aceder à internet: Adicionar DNS ao daemon
# /etc/docker/daemon.json
{
"dns": ["8.8.8.8", "8.8.4.4"]
}
sudo systemctl restart docker
# Containers não conseguem comunicar entre si (CentOS/Firewalld)
sudo firewall-cmd --zone=docker --add-masquerade --permanent
sudo firewall-cmd --reload
sudo systemctl restart docker
# Criar rede personalizada para comunicação entre containers
docker network create my-network
docker run --network my-network --name container1 image1
docker run --network my-network --name container2 image2
# Agora os containers podem comunicar entre si pelo nome
4. Falhas de Build
Sintoma: docker build falha com vários erros.
# Permissão negada ao ler diretório
# Adicionar o diretório ao .dockerignore ou corrigir permissões
echo "problematic-folder" >> .dockerignore
# Contexto demasiado grande (builds lentos)
# Verifique o que está a ser enviado
du -sh .
# Adicionar ao .dockerignore:
node_modules
.git
*.log
# Não é possível encontrar pacote/dependência
# Verifique se o nome/versão do pacote está correto
# Tente fazer build sem cache
docker build --no-cache -t my-app .
# apt-get update falha
# Problema de rede ou imagem base desatualizada
# Tente uma imagem base diferente ou verifique a rede
docker build --network=host -t my-app .
5. Problemas de Permissões em Volumes
Sintoma: A aplicação não consegue ler/escrever no volume montado.
# Verificar permissões
ls -la /host/path
docker exec container_name ls -la /container/path
# Verificar o utilizador dentro do container
docker exec container_name id
# Executar o container como um utilizador específico
docker run -u $(id -u):$(id -g) -v /host:/container image
# Corrigir a propriedade no Dockerfile
RUN chown -R appuser:appuser /app
USER appuser
6. Sem Espaço em Disco
Sintoma: no space left on device
# Verificar utilização de disco
docker system df
docker system df -v
# Limpar recursos não utilizados
docker system prune
# Limpeza agressiva (remove todas as imagens não utilizadas)
docker system prune -a
# Remover todos os volumes (PERDA DE DADOS!)
docker system prune -a --volumes
# Remover imagens antigas específicas
docker images --filter "dangling=true" -q | xargs docker rmi
# Remover containers com mais de 24 h
docker container prune --filter "until=24h"
7. Utilização Elevada de Memória
Sintoma: Container a usar demasiada memória, lentidão do sistema.
# Verificar utilização de memória
docker stats
# Definir limites de memória
docker run -m 512m --memory-swap 512m my-app
# Em docker-compose.yml
services:
app:
deploy:
resources:
limits:
memory: 512M
reservations:
memory: 256M
8. Porta Já em Utilização
Sintoma: Bind for 0.0.0.0:80 failed: port is already allocated
# Descobrir o que está a usar a porta
sudo lsof -i :80
sudo netstat -tulpn | grep :80
# Encontrar o container que está a usar a porta
docker ps --filter "publish=80"
# Parar o container
docker stop container_name
# Ou usar uma porta diferente
docker run -p 8080:80 nginx
9. Falha na Resolução de DNS
Sintoma: Temporary failure resolving 'deb.debian.org' durante o build.
# Adicionar DNS ao Docker daemon
# /etc/docker/daemon.json
{
"dns": ["1.1.1.1", "8.8.8.8"]
}
sudo systemctl restart docker
# Ou fazer build com rede do host
docker build --network=host -t my-app .
10. Problemas com Certificados SSL
Sintoma: self-signed certificate in certificate chain
# Para Node.js em desenvolvimento (NÃO para produção!)
docker run -e NODE_TLS_REJECT_UNAUTHORIZED=0 my-node-app
# Instalar certificado CA personalizado no Dockerfile
COPY my-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates
Problemas no Docker Compose
Containers Não Comunicam
# Garantir que os containers estão na mesma rede
services:
web:
networks:
- app-network
db:
networks:
- app-network
networks:
app-network:
driver: bridge
Variáveis de Ambiente Não Carregam
# Verificar a localização do ficheiro .env (mesmo diretório que docker-compose.yml)
# Verificar a sintaxe das variáveis em docker-compose.yml
services:
app:
environment:
- DATABASE_URL=${DATABASE_URL} # A partir de .env
- STATIC_VALUE=hardcoded # Valor literal
Volumes Não Sincronizam
# Remover volumes e recriar
docker-compose down -v
docker-compose up -d
# Verificar o caminho de montagem do volume
docker-compose config # Mostra a configuração resolvida
Problemas Específicos da Plataforma
macOS Docker Desktop
# Sincronização lenta de ficheiros com volumes
# Usar as flags :cached ou :delegated
volumes:
- ./src:/app/src:cached
# Sem espaço em disco
# Docker Desktop -> Preferences -> Resources -> Disk
Linux com SELinux
# Permissão negada em volumes
# Adicionar a flag :z ou :Z
docker run -v /host:/container:z image
# Ou desativar o SELinux para o Docker
# Não recomendado para produção
Apple Silicon (M1/M2)
# Imagem não compatível
# Especificar plataforma
services:
app:
platform: linux/amd64
image: some-x86-only-image
Principais Conclusões
- Verifique primeiro os logs:
docker logs revela a maioria dos problemas - Inspecione tudo:
docker inspect mostra detalhes de configuração - Problemas de rede são comuns: Redes personalizadas resolvem a maioria dos problemas de conectividade
- Faça limpeza regularmente: Previna problemas de espaço em disco com
docker system prune - Os limites de recursos importam: Defina limites de memória para evitar problemas de OOM
- Permissões são complicadas: Faça corresponder o utilizador do container à propriedade dos ficheiros no host
O troubleshooting de Docker torna-se intuitivo com a prática — a maioria dos problemas enquadra-se em categorias previsíveis com soluções conhecidas.
