Solução de Problemas: Diagnóstico Rápido de Erros Comuns em Containers Docker

Os containers Docker são projetados para serem resilientes, mas falhas na inicialização são uma parte inevitável do ciclo de vida do desenvolvimento. Quando um container é encerrado subitamente, entender rapidamente a causa raiz é fundamental para manter a velocidade de implantação. Essas falhas são frequentemente crípticas, marcadas apenas por um código de saída diferente de zero.

Este guia fornece metodologias de solução de problemas com a ajuda de especialistas, utilizando o kit de ferramentas de comandos essenciais do Docker. Abordaremos um processo de diagnóstico estruturado, aproveitando docker ps, docker logs e docker inspect para identificar e resolver rapidamente os problemas de inicialização de container mais frequentes, permitindo que você supere a adivinhação e aplique correções acionáveis.

Fase 1: Triagem Inicial e Avaliação de Estado

A primeira etapa no diagnóstico de qualquer falha de container é determinar seu estado atual e recente. O comando padrão docker ps mostra apenas containers em execução, o que é inútil quando um container é encerrado imediatamente após a inicialização.

Usando `docker ps -a` para Encontrar Falhas

O comando crucial para a triagem inicial é docker ps -a (listar todos os containers, em execução ou parados). Isso permite visualizar o status, o código de saída e a idade do container parado.

$ docker ps -a
CONTAINER ID   IMAGE          COMMAND                CREATED          STATUS                    PORTS     NAMES
2d3f4b5c6e7a   my-app:latest  "/usr/bin/start.sh"    5 minutes ago    Exited (127) 3 minutes ago          web-service
d8c9a0b1c2d3   nginx:latest   "nginx -g 'daemon..."  10 minutes ago   Up 8 minutes              80/tcp    active-proxy

Indicadores de Status Chave:

Exited (0): O container foi encerrado de forma limpa e intencional (muitas vezes após a conclusão de um trabalho em lote). O diagnóstico geralmente é mínimo.
Exited (Diferente de Zero): Ocorreu uma falha. Códigos comuns diferentes de zero (1, 126, 127) indicam problemas graves, como o travamento de um processo, um arquivo não encontrado ou erros de permissão.
Created: O container foi criado, mas nunca iniciado, ou a inicialização falhou muito rapidamente para que o status fosse atualizado.

Fase 2: Aprofundando com Logs do Container

Uma vez que você tenha o ID ou o nome do container, a ferramenta mais valiosa para o diagnóstico é o mecanismo de registro (logging). O Docker captura os fluxos de saída padrão (stdout) e erro padrão (stderr) do processo principal do container.

Recuperando Logs Históricos

Use o comando docker logs para recuperar toda a saída capturada do container com falha. Essa saída geralmente contém a mensagem de erro exata (por exemplo, rastreamento de pilha, erro de configuração ou aviso de arquivo ausente) que fez o container parar.

# Recuperar logs para o container com falha
$ docker logs web-service

# --- Exemplo de Saída de Log ---
Padronizando ambiente...
Erro: Arquivo de configuração não encontrado em /etc/app/config.json
Falha na inicialização da aplicação. Saindo.

Dicas Avançadas de Filtragem de Logs:

Opção de Comando	Propósito	Exemplo
`-f, --follow`	Transmitir logs em tempo real (útil se o container iniciar e travar rapidamente).	`docker logs -f web-service`
`--tail N`	Exibir apenas as últimas N linhas de logs.	`docker logs --tail 50 web-service`
`-t, --timestamps`	Mostrar carimbos de data/hora para cada entrada de log (útil para correlacionar eventos).	`docker logs -t web-service`
`--since`	Mostrar logs gerados após um período ou duração específica (por exemplo, `1h`, `15m`).	`docker logs --since 15m web-service`

Melhor Prática: Sempre verifique os logs imediatamente após uma falha. Se os logs estiverem vazios, a falha ocorreu antes que o processo principal da aplicação pudesse iniciar, muitas vezes indicando um problema com a própria configuração ENTRYPOINT ou CMD do Docker.

Fase 3: Analisando Estado e Configuração com `docker inspect`

Quando os logs são insuficientes (por exemplo, mostrando um erro genérico ou nada), você precisa analisar a configuração interna e o ambiente de execução do container.

Revisando o Objeto de Estado Completo

docker inspect fornece um objeto JSON abrangente detalhando tudo sobre o container, desde configurações de rede até limites de recursos e, crucialmente, o estado final e a mensagem de erro.

$ docker inspect web-service

Concentre-se nos seguintes caminhos JSON chave na saída:

1. Informações de Estado

Esta seção contém as informações detalhadas de saída, incluindo o horário da falha e quaisquer mensagens de erro em nível de sistema (se aplicável).

...
"State": {
    "Status": "exited",
    "Running": false,
    "Paused": false,
    "Restarting": false,
    "OOMKilled": false, 
    "Dead": false,
    "Pid": 0,
    "ExitCode": 127,
    "Error": "", // Frequentemente vazio, mas pode conter mensagens de nível de kernel
    "StartedAt": "2023-10-26T14:30:00.123456789Z",
    "FinishedAt": "2023-10-26T14:30:00.223456789Z"
},
...

2. Ponto de Entrada e Comando

Se o container saiu com o código 127 (comando não encontrado) ou 126 (comando não executável), verifique o Path e os Args nas seções Config ou State para garantir que o processo principal esteja especificado corretamente e que o caminho exista na imagem.

...
"Config": {
    "Entrypoint": [
        "/usr/bin/start.sh"
    ],
    "Cmd": [
        "--mode=production"
    ],
...

3. Montagens e Volumes

Se a aplicação falhou devido a arquivos ausentes ou erros de permissão, verifique a seção Mounts para confirmar que os volumes do host foram mapeados corretamente, estão acessíveis e possuem as permissões necessárias.

Fase 4: Cenários Comuns de Falha na Inicialização e Resoluções

Ao combinar dados de logs e inspeção, você pode categorizar a falha e aplicar uma correção direcionada.

Cenário 1: Porta Já Alocada (Erro de Bind)

Isso ocorre quando a porta do host que você está tentando mapear (-p 8080:80) já está em uso por outro processo (seja outro container ou um processo em execução na máquina host).

Diagnóstico: O container geralmente falha ao iniciar imediatamente, ou os logs mostram um erro como bind: address already in use.

Resolução:
1. Pare o processo ou container em conflito.
2. Altere o mapeamento da porta do host (por exemplo, -p 8081:80).

Cenário 2: Comando Não Encontrado (Código de Saída 127)

Isso significa que o runtime do Docker não conseguiu executar o comando especificado na diretiva ENTRYPOINT ou CMD.

Diagnóstico: Verifique docker logs (que pode estar vazio) e confirme a seção Config usando docker inspect.

Resolução:
1. Certifique-se de que o caminho do executável esteja correto (por exemplo, /usr/local/bin/app, e não apenas app).
2. Verifique se o executável existe na imagem. Você pode precisar executar um container de depuração temporário para examinar o sistema de arquivos da imagem:

# Execute temporariamente a imagem, substituindo o comando com falha
$ docker run -it --entrypoint /bin/bash my-app:latest
# Agora dentro do container, verifique: ls -l /usr/bin/start.sh

Cenário 3: Permissão Negada (Código de Saída 126 ou Erros de Volume)

Normalmente ocorre quando o usuário do container não tem permissão para acessar um arquivo, diretório ou ponto de montagem de volume necessário.

Diagnóstico: Os logs mostram erros como Permission denied (Permissão negada) ou cannot open file (não é possível abrir o arquivo).

Resolução:
1. Permissões de Volume: Se estiver usando montagens de host (-v /host/data:/container/data), certifique-se de que a pasta do host tenha permissões de leitura/gravação para o ID do usuário sob o qual o container é executado (geralmente UID 1000 ou root).
2. Permissões de Ponto de Entrada: Certifique-se de que o script especificado em ENTRYPOINT tenha o sinalizador executável definido no Dockerfile (RUN chmod +x /path/to/script).

Cenário 4: Falta de Memória (OOMKilled)

Esta é uma falha em nível de sistema em que o kernel termina o processo principal do container devido ao consumo excessivo de memória.

Diagnóstico: Verifique docker ps -a para STATUS Exited (137) ou execute docker inspect [id] e procure o campo "OOMKilled": true no objeto State.

Resolução:
1. Aumente o limite de memória do container usando a flag -m (por exemplo, --memory 2g).
2. Otimize a aplicação para reduzir o uso de memória.

Resumo e Próximos Passos

A solução de problemas eficiente do Docker depende de uma abordagem estruturada: comece com docker ps -a para avaliar a falha, use docker logs como sua principal ferramenta de investigação e reserve docker inspect para questões mais profundas de configuração e ambiente. Ao entender o significado dos códigos de saída e saber onde procurar no estado do container, você pode reduzir drasticamente o tempo gasto resolvendo falhas comuns de inicialização.

Ações Adicionais:

Se o problema estiver relacionado à imagem, reconstrua a imagem com etapas de depuração temporárias (por exemplo, exibindo variáveis de ambiente) incluídas no Dockerfile.
Se os logs forem escassos, altere temporariamente a inicialização do container para usar bash ou sh para navegar manualmente no sistema de arquivos e testar comandos dentro do ambiente.