Guia para depurar contêineres Docker: como usar docker exec para investigar problemas

A API do ambiente de teste começou a retornar 502 de repente. Ao executar docker ps, o status do contêiner mostrava “Up 2 hours”, como se tudo estivesse funcionando normalmente. Nos logs, porém, havia apenas a mensagem seca “Connection refused”.

Esse é o tipo de situação que mais irrita: você sabe que o contêiner está em execução, mas não faz ideia do que realmente está acontecendo lá dentro. O arquivo de configuração está correto? O processo realmente iniciou? A porta está sendo escutada? Para responder a essas perguntas, é preciso “entrar” no contêiner, como quem abre uma caixa-preta para ver o que existe dentro dela.

Para ser sincero, quando comecei a usar Docker, também não sabia como “entrar” em um contêiner. Pesquisei na internet e encontrei gente recomendando docker exec, gente indicando docker attach e até quem sugerisse simplesmente reiniciar o contêiner. Depois de cometer vários erros, entendi que existe uma maneira correta de depurar contêineres.

Neste artigo, você vai aprender a usar docker exec para entrar corretamente em um contêiner e investigar problemas. Também veremos a diferença essencial entre exec e attach, o que fazer quando faltam ferramentas dentro do contêiner e algumas técnicas práticas de depuração. Depois disso, na próxima falha você não precisará recorrer imediatamente à velha solução de reiniciar tudo.

Fundamentos do docker exec: a forma correta de entrar em um contêiner

A maneira mais simples de entrar

O comando mais usado para entrar em um contêiner em execução é:

docker exec -it my-nginx bash

Há três partes importantes aqui:

• -it: é a combinação de dois parâmetros. -i mantém a entrada padrão aberta, enquanto -t aloca um terminal. Em termos simples, isso permite que você “converse” com o contêiner.
• my-nginx: é o nome do contêiner. Você também pode usar o ID, como em docker exec -it abc123def456 bash.
• bash: é o comando que será executado dentro do contêiner; neste caso, ele inicia um terminal bash.

Depois de executar o comando, o prompt muda para algo parecido com root@abc123def456:/#. Isso indica que você já “entrou” no contêiner. A partir daí, é possível executar comandos como em um servidor Linux comum.

E se o bash não existir?

Às vezes, você pode encontrar este erro:

$ docker exec -it my-alpine bash
OCI runtime exec failed: exec failed: container_linux.go:380:
starting container process caused: exec: "bash": executable file not found

Não se preocupe. Normalmente, isso acontece porque o contêiner usa um sistema extremamente enxuto, como o Alpine Linux, que inclui sh por padrão, mas não bash. Basta trocar o comando:

docker exec -it my-alpine sh

Na minha experiência, vale tentar bash primeiro e, se não funcionar, usar sh. Isso resolve cerca de 90% dos casos.

Use o ID do contêiner para ganhar flexibilidade

Muitas vezes, você pode preferir não procurar o nome do contêiner. Nesse caso, basta usar os primeiros caracteres do ID:

# Primeiro, veja o ID do contêiner
$ docker ps
CONTAINER ID   IMAGE    COMMAND                  CREATED
abc123def456   nginx    "/docker-entrypoint.…"   2 hours ago

# Entre usando o prefixo do ID; 3 ou 4 caracteres costumam bastar
$ docker exec -it abc1 bash

O Docker encontra automaticamente o ID pelo prefixo, desde que ele não corresponda a mais de um contêiner. Esse recurso é especialmente útil quando há muitos contêineres.

A forma correta de sair do contêiner

Para sair depois de entrar, digite exit ou pressione Ctrl+D:

root@abc123def456:/# exit
exit
$

O ponto principal é que, ao entrar com exec, o contêiner não para quando você sai. Isso é importante, e a próxima seção explica o motivo.

exec vs attach: não confunda mais os dois

A diferença essencial

Muitos tutoriais citam docker exec e docker attach ao mesmo tempo, mas poucos explicam claramente a diferença entre eles. Quando comecei, usei attach da maneira errada e fiz um contêiner parar sem entender por quê.

De forma simples:

• docker exec: inicia um novo processo dentro do contêiner, como se abrisse uma nova janela.
• docker attach: conecta-se ao processo principal do contêiner, o PID 1, como se espelhasse uma tela que já está aberta.

Parece abstrato? Veja um exemplo.

Imagine que você execute docker attach my-nginx para se conectar a um contêiner Nginx e depois pressione Ctrl+C ou digite exit para sair. O que acontece? O processo principal do contêiner, o Nginx, recebe o sinal de encerramento e todo o contêiner para. Se isso acontecer em produção, você provavelmente terá uma conversa nada agradável com seu chefe.

Por outro lado, com docker exec -it my-nginx bash, você inicia um processo bash independente. Encerrar esse bash não afeta o processo principal do Nginx, e o contêiner continua funcionando normalmente.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Quando usar exec e quando usar attach?

Minha recomendação é simples: em 99% dos casos, use exec.

Attach só é realmente útil quando você precisa interagir diretamente com o processo principal do contêiner, por exemplo:

• O contêiner executa um programa interativo, como o REPL do Python.
• Você precisa acompanhar a saída do processo principal em tempo real.
• Vários terminais precisam ver o mesmo conteúdo de forma sincronizada, como em um compartilhamento de tela.

Sinceramente, essas situações são raras. Na maior parte do tempo, você só quer entrar no contêiner para examinar arquivos, ajustar configurações ou executar comandos. Para isso, exec é seguro e prático.

Uma tabela para memorizar a diferença

Agora ficou claro por que insisto tanto no uso de exec. Attach foi criado para acompanhar a saída do contêiner, não para a depuração cotidiana.

O que fazer quando faltam ferramentas no contêiner

Por que parece que não há comando algum no contêiner?

Você finalmente entrou no contêiner e tentou editar um arquivo de configuração com vim, mas recebeu:

root@abc123:/# vim /etc/nginx/nginx.conf
bash: vim: command not found

Depois tentou testar uma API com curl:

root@abc123:/# curl localhost:8080
bash: curl: command not found

Às vezes, nem ping está disponível. Na primeira vez que isso aconteceu comigo, fiquei desesperado: como depurar um ambiente que não tem ferramenta nenhuma?

Na verdade, isso segue a filosofia das imagens Docker: instale apenas o necessário e evite todo o resto. Uma imagem completa do Ubuntu pode ocupar centenas de MB, enquanto uma imagem Alpine tem apenas cerca de 5 MB. Como isso é possível? Removendo todas as ferramentas consideradas “desnecessárias”, incluindo vim, curl e ping, que talvez pareçam óbvias para você.

Instale ferramentas temporariamente em uma emergência

Nessa situação, você pode instalar temporariamente o que precisa. Use o gerenciador de pacotes adequado ao sistema do contêiner.

Sistemas Debian/Ubuntu (apt/apt-get):

# Primeiro, atualize a lista de pacotes
apt-get update

# Instale ferramentas comuns
apt-get install -y vim curl wget net-tools

# Se precisar de ferramentas de diagnóstico de rede
apt-get install -y iputils-ping dnsutils

Sistemas CentOS/RedHat (yum):

yum install -y vim curl wget

Sistemas Alpine (apk):

apk update
apk add vim curl bash

Como descobrir qual sistema o contêiner usa?

Se você não souber qual é o sistema do contêiner, há duas maneiras simples de verificar:

# Método 1: consulte o arquivo de identificação da distribuição
cat /etc/os-release

# Método 2: veja qual gerenciador de pacotes existe
which apt-get   # Se existir, provavelmente é Debian/Ubuntu
which yum      # Se existir, provavelmente é CentOS/RedHat
which apk      # Se existir, provavelmente é Alpine

Eu costumo tentar diretamente apt-get update. Se falhar, parto para outro gerenciador. Isso não vai estragar o contêiner.

Isso é seguro?

Há alguns cuidados ao instalar ferramentas temporariamente:

Ambiente de desenvolvimento: pode instalar sem grandes preocupações. Quando o contêiner de teste reiniciar, ele será restaurado e as ferramentas instaladas desaparecerão.

Ambiente de produção: faça isso apenas em uma investigação urgente. Depois de resolver o problema, adicione as ferramentas necessárias ao Dockerfile e reconstrua a imagem.

Há dois motivos para isso:

1. Segurança: os pacotes instalados temporariamente podem conter vulnerabilidades.
2. Reprodutibilidade: quando o contêiner reiniciar, as ferramentas desaparecerão e você terá de instalá-las de novo.

Solução de longo prazo: instale no Dockerfile

Se você precisa dessas ferramentas com frequência, o melhor é instalá-las durante o build da imagem:

FROM nginx:latest

# Instale ferramentas comuns de depuração
RUN apt-get update && apt-get install -y \
    vim \
    curl \
    wget \
    net-tools \
    iputils-ping \
 && rm -rf /var/lib/apt/lists/*  # Limpe o cache para reduzir o tamanho da imagem

# Outras configurações...

Repare no rm -rf /var/lib/apt/lists/* ao final. Essa é uma boa prática que reduz bastante o tamanho da imagem.

Uma dica prática

Se você só quer consultar rapidamente o conteúdo de um arquivo de configuração, não precisa de vim. cat ou less resolvem, e esses dois comandos existem em quase todos os contêineres:

# Exiba o arquivo completo
cat /etc/nginx/nginx.conf

# Exiba o arquivo por páginas, útil para arquivos longos
less /etc/nginx/nginx.conf  # Pressione q para sair

# Exiba apenas as primeiras linhas
head -n 20 /etc/nginx/nginx.conf

Se você precisa alterar o arquivo e não há vim, pode fazer uma substituição direta com sed. Não é tão intuitivo quanto o vim, mas funciona em uma emergência:

# Troque listen 80 por listen 8080
sed -i 's/listen 80/listen 8080/g' /etc/nginx/nginx.conf

Como entrar no contêiner como um usuário específico

Por que definir um usuário?

Às vezes, você entra no contêiner e encontra esta situação:

root@abc123:/app# cat /var/log/app.log
cat: /var/log/app.log: Permission denied

Ou tenta alterar a permissão de um arquivo:

root@abc123:/app# chmod 644 config.yaml
chmod: changing permissions of 'config.yaml': Operation not permitted

O prompt mostra root, então por que ainda falta permissão? Normalmente, isso acontece porque o contêiner foi configurado para executar como um usuário não root, o que é uma boa prática recomendada em produção, e o usuário padrão do exec herdou essa configuração.

Entre como root

Nesse caso, indique explicitamente que deseja entrar como root:

docker exec -it --user root my-app bash

Ou use a forma abreviada:

docker exec -it -u root my-app bash

Agora você terá privilégios reais de root e poderá consultar qualquer arquivo e alterar qualquer configuração.

Entre com um UID específico

Em alguns casos, você pode precisar usar um ID de usuário específico. Por exemplo, se o usuário da aplicação dentro do contêiner tiver UID 1000:

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

# Entre com o UID 1000
docker exec -it --user 1000 my-app bash

# Também é possível informar o nome, se esse usuário existir no contêiner
docker exec -it --user appuser my-app bash

# Informe usuário e grupo no formato usuário:grupo
docker exec -it --user 1000:1000 my-app bash

Isso é especialmente útil para depurar problemas de permissão. Se você suspeitar que a aplicação não consegue gravar em um diretório, entre com o mesmo usuário da aplicação e teste:

# Entre como o usuário da aplicação
docker exec -it --user appuser my-app bash

# Tente criar um arquivo no diretório de dados
appuser@abc123:/app$ touch /data/test.txt
touch: cannot touch '/data/test.txt': Permission denied

# Pronto: o problema de permissão foi confirmado

Quando são necessários privilégios de root?

Na minha experiência, estes casos geralmente exigem root:

1. Alterar configurações do sistema: diversos arquivos em /etc/.
2. Instalar pacotes: apt-get, yum e outros gerenciadores exigem root.
3. Consultar logs do sistema: usuários comuns não podem ler muitos arquivos em /var/log/.
4. Ajustar permissões de arquivos: operações como chmod e chown.
5. Depurar problemas de rede: ferramentas como tcpdump e netstat normalmente exigem root.

Mas lembre-se: se não precisar de root, não use root. Isso vale especialmente em produção. Depois de fazer uma alteração como root, registre-a e reverta permissões excessivas para não deixar uma brecha de segurança.

Um alerta de segurança

Embora seja possível entrar no contêiner como root, alguns cuidados são necessários.

Ambiente de teste:

• Você pode usar root sem grandes problemas. O contêiner será restaurado quando reiniciar.

Ambiente de produção:

• Entrar apenas para inspecionar algo → OK.
• Alterar temporariamente uma configuração em uma emergência → tolerável, mas registre exatamente o que foi alterado.
• Compilar código ou instalar software diretamente no contêiner → não faça isso. Essas mudanças devem estar no Dockerfile.

Por quê? Porque o conceito de contêineres segue a ideia de “infraestrutura imutável”. Tudo o que você alterar em um contêiner em execução desaparecerá quando ele reiniciar. As mudanças reais devem ficar no Dockerfile para que o ambiente seja reproduzível.

Existe ainda outro risco: em algumas configurações, o root do contêiner e o root do host podem compartilhar o mesmo UID 0. Embora haja isolamento por namespaces, uma configuração incorreta pode permitir que o root do contêiner afete o host. Esse é outro motivo para executar contêineres com usuários não root em produção.

Técnicas práticas e cenários comuns

Execute um único comando sem abrir um shell interativo

Muitas vezes, não é necessário permanecer dentro do contêiner. Você só quer executar um comando e ver o resultado. Nesse caso, não use o parâmetro -it:

# Liste o conteúdo do diretório
docker exec my-nginx ls -la /etc/nginx/

# Consulte o arquivo de configuração
docker exec my-nginx cat /etc/nginx/nginx.conf

# Verifique os processos
docker exec my-nginx ps aux

# Veja quais portas estão em escuta
docker exec my-nginx netstat -tlnp

# Teste a conectividade de rede
docker exec my-nginx curl -I localhost:80

Essa abordagem é especialmente útil em scripts ou para consultar rapidamente um valor. Por exemplo, costumo verificar assim se uma aplicação está respondendo:

# Script de verificação de integridade
if docker exec my-app curl -f http://localhost:8080/health; then
  echo "App is healthy"
else
  echo "App is down!"
fi

Fluxo padrão para depurar um contêiner

Quando encontro um problema em um contêiner, geralmente sigo este processo:

1. Primeiro, veja o status do contêiner

docker ps -a  # Veja se o contêiner está em execução

2. Consulte os logs em busca de pistas

docker logs my-app --tail 100  # Veja as 100 linhas mais recentes
docker logs my-app -f          # Acompanhe os logs em tempo real, como tail -f

3. Verifique os processos dentro do contêiner

docker exec my-app ps aux

Confira se os processos esperados foram iniciados. Em um contêiner Nginx, por exemplo, devem aparecer os processos master e worker do nginx.

4. Verifique as portas em escuta

docker exec my-app netstat -tlnp
# Ou, se netstat não estiver disponível
docker exec my-app ss -tlnp

Confirme se a aplicação está escutando a porta correta.

5. Teste se o serviço está disponível

# Teste de dentro do contêiner
docker exec my-app curl localhost:8080

# Se curl não estiver disponível, use telnet para testar a porta
docker exec my-app telnet localhost 8080

6. Consulte os arquivos de configuração

docker exec my-app cat /etc/nginx/nginx.conf
docker exec my-app cat /app/config.yaml

Confira se a configuração corresponde ao esperado.

7. Verifique o espaço em disco

docker exec my-app df -h

Às vezes, o problema é simplesmente falta de espaço no contêiner, o que impede a aplicação de gravar arquivos.

Combinações úteis de comandos de depuração

Verifique as variáveis de ambiente:

docker exec my-app env | grep DATABASE

Isso ajuda a confirmar se a configuração de conexão com o banco de dados está correta.

Procure um arquivo específico:

docker exec my-app find /app -name "*.log"

Veja as permissões dos arquivos:

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

docker exec my-app ls -la /app/

Esse comando é muito útil para investigar problemas de permissão.

Monitore os recursos do contêiner em tempo real:

docker stats my-app

Esse comando não usa exec; ele é executado diretamente no host. A saída mostra em tempo real o uso de CPU, memória, rede e I/O.

Execute operações em vários contêineres

Se você precisa verificar vários contêineres, pode combinar os comandos em um script shell:

# Verifique o uso de memória de todos os contêineres em execução
for container in $(docker ps -q); do
  echo "Container: $container"
  docker exec $container free -h
  echo "---"
done

Depure problemas de rede

Verifique a conectividade entre contêineres:

# No contêiner A, envie ping para o contêiner B
docker exec containerA ping containerB

# Teste se o contêiner consegue acessar a internet
docker exec my-app ping -c 3 google.com

# Verifique a resolução DNS
docker exec my-app nslookup google.com

Veja o IP do contêiner:

docker inspect my-app | grep IPAddress
# Ou entre no contêiner e consulte o endereço
docker exec my-app ip addr show

O que fazer se o contêiner reiniciar sem parar?

Às vezes, o contêiner inicia e encerra imediatamente, sem dar tempo para executar exec. Nesse caso, há duas opções.

Método 1: substitua o comando de inicialização

# Mantenha o contêiner em execução sem chamar o CMD original
docker run -it --name debug-app my-app-image sh

Assim, o contêiner permanece no shell e não executa o script de inicialização original, dando tempo para investigar o problema.

Método 2: examine o contêiner encerrado

# Inicie um contêiner que já foi encerrado
docker start my-app

# Consulte os logs imediatamente
docker logs my-app

# Se o contêiner ainda estiver ativo, entre rapidamente com exec
docker exec -it my-app bash

Aprendi as técnicas desta seção aos poucos, resolvendo problemas reais. No começo, depurar contêineres Docker pode parecer confuso, mas depois que esses comandos se tornam familiares, a investigação fica muito mais rápida.

Conclusão

Depois de tantos detalhes, os pontos centrais da depuração de contêineres Docker se resumem a estes:

Usar docker exec para entrar no contêiner é a opção mais segura, pois sair da sessão não afeta a execução. Memorize este comando: docker exec -it nome-do-contêiner bash. Se bash não funcionar, tente sh.

Não confunda exec com attach. Attach se conecta ao processo principal e pode parar o contêiner quando você sai. A menos que saiba exatamente o que está fazendo, prefira exec.

Não se assuste se faltarem ferramentas. Você pode instalá-las temporariamente com apt-get, yum ou apk. Lembre-se, porém, de que isso é apenas uma solução de emergência; no longo prazo, as ferramentas devem ser adicionadas ao Dockerfile.

Quando precisar de privilégios de root, use o parâmetro --user root. Tenha cuidado em produção, registre as mudanças e leve-as para a imagem assim que possível.

Siga um processo de depuração: primeiro veja os logs, depois verifique os processos, confira a configuração e, por fim, teste a rede. Essa ordem resolve a maioria dos problemas.

Na próxima vez que um contêiner apresentar falha, não corra para reiniciá-lo. Entre e investigue. Muitos problemas têm causas simples, como uma configuração incorreta, permissões inadequadas ou conflito de portas. Quando você domina exec, depurar contêineres deixa de ser tão complicado.

Para terminar, aqui está um checklist que você pode seguir quando encontrar um problema:

Checklist de depuração do contêiner:

• O contêiner está em execução? (docker ps)
• Há erros nos logs? (docker logs)
• Todos os processos iniciaram? (docker exec ps aux)
• As portas estão sendo escutadas corretamente? (docker exec netstat -tlnp)
• O arquivo de configuração está correto? (docker exec cat config)
• Há espaço suficiente em disco? (docker exec df -h)
• A rede está funcionando? (docker exec curl/ping)