tutorial: Por que containers somem no Portainer e como parar de vez

15 min de leitura  ·  Guia técnico

containers somem no Portainer quando o painel perde a conexão com o endpoint Docker, quando o socket do Docker não está montado corretamente, quando há filtros ativos na interface ou quando o container foi parado, recriado ou removido fora do Portainer. A correção começa confirmando pelo terminal se o Docker ainda enxerga os containers e, depois, ajustando endpoint, volume persistente e permissões antes de atualizar ou recriar o Portainer.

Pré-requisitos

• Acesso SSH ao servidor onde o Docker está instalado, preferencialmente com usuário root ou usuário com permissão sudo.
• Docker já instalado e em execução no host, seja em Ubuntu 24.04 LTS, Debian 12, Rocky Linux 9 ou AlmaLinux 9.
• Nome do container do Portainer ou acesso ao comando docker para localizar o container atual.
• Conhecimento básico sobre volumes Docker, principalmente o volume persistente usado pelo Portainer para salvar configurações.
• Antes de qualquer alteração, confirme o acesso ao servidor. Se precisar revisar a conexão, veja Acessando servidores VPS Linux da AviraHost.

Por que containers somem no Portainer mesmo existindo no Docker

containers somem no Portainer com frequência quando a interface deixa de representar o estado real do Docker host. O ponto mais importante é separar duas situações: containers invisíveis no painel e containers realmente removidos do Docker. Ao rodar a verificação pelo terminal, você verá se o problema está no Portainer ou se a aplicação deixou de existir no host.

Comece listando todos os containers, incluindo os parados. Esse comando não altera nada no servidor e é a forma mais segura de diagnosticar se o Portainer apenas não está exibindo os containers Docker.

docker ps -a

Output esperado:
CONTAINER ID   IMAGE                    COMMAND        STATUS                      NAMES
a1b2c3d4e5f6   portainer/portainer-ce   "/portainer"   Up                          portainer
b2c3d4e5f6g7   nginx                    "nginx -g..."  Exited (0)                  site-nginx
c3d4e5f6g7h8   mysql                    "docker..."    Up                          banco-mysql

Se o container aparece em docker ps -a, mas não aparece no Portainer, o painel está com problema de visualização, endpoint, permissão ou filtro. Se ele não aparece no terminal, investigue remoção manual, recriação por Compose, limpeza com prune ou uso de outro host Docker. Em ambientes com múltiplos servidores, também é comum abrir o endpoint errado e concluir que os containers sumiram, quando na verdade eles estão em outro host.

1. Confirme se o Docker mostra os containers com docker ps -a.
2. Verifique se o Portainer está rodando e com o volume de dados preservado.
3. Confira se o socket /var/run/docker.sock foi montado no container do Portainer.
4. Revise filtros de status, stack, namespace ou endpoint dentro da interface.
5. Evite comandos destrutivos antes de identificar volumes, redes e containers em uso.

Como verificar o endpoint Docker no Portainer sem perder dados

endpoint Docker desconectado no Portainer é uma das causas mais comuns quando o painel abre normalmente, mas não lista containers. O Portainer depende de uma conexão com o Docker local ou remoto; se essa conexão falha, a interface pode parecer vazia ou mostrar erro ao carregar recursos.

No terminal, confirme se o container do Portainer está ativo. Ao rodar este comando, você verá o estado atual do painel e o nome exato do container, que pode variar conforme a instalação.

docker ps --filter "name=portainer"

Output esperado:
CONTAINER ID   IMAGE                    STATUS         PORTS                    NAMES
a1b2c3d4e5f6   portainer/portainer-ce   Up             0.0.0.0:9443->9443/tcp   portainer

Depois, inspecione se o socket do Docker está montado. Sem esse socket, o Portainer pode iniciar, mas não consegue conversar corretamente com o Docker local.

docker inspect portainer --format '{{json .Mounts}}'

Output esperado:
[{"Type":"volume","Name":"portainer_data","Destination":"/data"},{"Type":"bind","Source":"/var/run/docker.sock","Destination":"/var/run/docker.sock"}]

O resultado esperado deve conter o volume de dados em /data e o bind mount do socket em /var/run/docker.sock. Se o socket não aparecer, o Portainer foi criado sem a montagem necessária para gerenciar o Docker local. Nesse caso, recriar apenas o container do Portainer com o volume correto costuma resolver a visibilidade, desde que você não remova o volume persistente.

Atenção: não remova volumes antes de identificar o que cada um armazena. O volume do Portainer guarda configurações do painel, endpoints e preferências; volumes de bancos, aplicações e sites podem conter dados de produção.

Como recriar o Portainer preservando o volume persistente

volume persistente do Portainer é o que impede perda de configuração ao remover e criar novamente o container do painel. Remover o container do Portainer não deve apagar automaticamente seus containers Docker, mas remover volumes sem revisão pode causar perda de dados importantes.

Primeiro, liste os volumes e localize o volume usado pelo Portainer. Em instalações comuns, ele pode se chamar portainer_data, mas confirme no seu servidor antes de agir.

docker volume ls

Output esperado:
DRIVER    VOLUME NAME
local     portainer_data
local     mysql_data
local     app_uploads

Se precisar recriar o Portainer, pare e remova somente o container do Portainer. Esse procedimento não remove o volume, desde que você não use comandos com remoção de volumes.

docker stop portainer
docker rm portainer

Output esperado:
portainer
portainer

Agora crie o container novamente montando o socket Docker e preservando o volume existente. Ajuste as portas apenas se sua instalação usa outro padrão.

docker run -d \
  --name portainer \
  --restart=always \
  -p 9443:9443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce

Output esperado:
ID longo do novo container criado

Depois, confirme se o Portainer voltou a subir e se o Docker continua mostrando os containers da aplicação. Essa dupla verificação evita confundir falha de painel com perda real de containers.

docker ps --filter "name=portainer"
docker ps -a

Output esperado:
portainer com STATUS Up
lista de containers ativos e parados do host Docker

Se você usa Docker para hospedar sites, bancos e aplicações, mantenha um inventário simples com nome do container, imagem, portas, volumes e rede. Esse inventário ajuda muito quando a interface do Portainer deixa de carregar ou quando um container é recriado por outro processo.

Como identificar filtros e containers parados no Portainer

containers parados no Portainer podem dar a impressão de desaparecimento quando a interface está filtrando apenas recursos ativos. Isso é especialmente comum depois de reinicialização do servidor, falha da aplicação ou alteração em uma stack Docker Compose.

Use o terminal para comparar containers ativos e todos os containers. Ao rodar os dois comandos, você verá a diferença entre o que está em execução e o que existe no host.

docker ps
docker ps -a

Output esperado:
docker ps mostra apenas containers em execução
docker ps -a mostra containers em execução e parados

Se um container aparece apenas em docker ps -a, ele não sumiu: ele está parado. Nesse caso, veja o motivo da parada com logs e inspeção. O log costuma mostrar erro de inicialização, falha de conexão com banco, porta ocupada ou arquivo de configuração inválido.

docker logs --tail=80 nome-do-container

Output esperado:
linhas recentes do log da aplicação, incluindo mensagens de erro ou inicialização

Também vale conferir o código de saída e o estado do container. Ao executar o comando abaixo, você verá se ele está parado, reiniciando ou se encerrou com erro.

docker inspect nome-do-container --format 'Status={{.State.Status}} ExitCode={{.State.ExitCode}} Error={{.State.Error}}'

Output esperado:
Status=exited ExitCode=0 Error=
ou
Status=exited ExitCode=1 Error=mensagem de erro

No Portainer, revise filtros de ambiente, stack, status e busca por nome. Se você usa múltiplos endpoints, confirme no canto do ambiente se está olhando para o Docker host correto. Em servidores com Nginx, bancos e aplicações separadas por redes Docker, a organização por stack ajuda, mas também pode esconder recursos se a visualização estiver limitada.

Como evitar que containers desapareçam após atualização ou limpeza

backup de containers Docker não significa apenas copiar o container em si, e sim preservar os dados importantes em volumes, arquivos de Compose e variáveis de ambiente. O Portainer facilita a gestão, mas a segurança operacional depende de você saber onde estão volumes, redes, portas e arquivos usados pelas aplicações.

Antes de atualizar o Portainer ou limpar recursos, gere uma visão geral dos containers e volumes. Esses comandos são seguros para consulta e ajudam a registrar o estado atual do ambiente.

docker ps -a --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"
docker volume ls
docker network ls

Output esperado:
tabela com nomes, imagens, status e portas
lista de volumes Docker
lista de redes Docker

Atenção: comandos como docker system prune, docker volume prune e remoção de stacks podem excluir recursos não utilizados ou volumes dependendo das opções usadas. Em produção, nunca execute limpeza sem revisar o que será removido.

Para visualizar o impacto de uma limpeza geral sem apagar volumes manualmente, use primeiro comandos de listagem e evite flags agressivas. Se a aplicação foi criada por Docker Compose, mantenha o arquivo Compose salvo fora do container e documente o diretório em que ele fica.

docker compose ls

Output esperado:
NAME                STATUS              CONFIG FILES
meu-projeto          running             /opt/meu-projeto/docker-compose.yml

Se você administra vários sites e serviços no mesmo servidor, também vale revisar boas práticas gerais de otimização e organização em Dicas de Otimização de Servidores Linux. Para Docker, a regra prática é simples: Portainer pode ser recriado; volumes de aplicação e arquivos de configuração precisam ser preservados.

Problemas comuns e como resolver

Sintoma: containers aparecem no terminal, mas não no Portainer

Causa: o endpoint Docker pode estar desconectado, o socket /var/run/docker.sock pode não estar montado ou a interface pode estar filtrando recursos. Solução: confirme com docker ps -a, inspecione os mounts do container Portainer e reconecte o endpoint local sem remover o volume de dados.

Sintoma: Portainer abre, mas mostra ambiente vazio

Causa: você pode estar acessando o endpoint errado, especialmente em ambientes com mais de um Docker host. Também pode haver falha de permissão no socket Docker. Solução: valide o host via SSH, compare o resultado do terminal com a interface e recrie o Portainer com o bind mount correto para /var/run/docker.sock.

Sintoma: container sumiu depois de uma limpeza Docker

Causa: comandos de limpeza podem remover containers parados, imagens não usadas, redes ou volumes, dependendo do comando executado. Solução: verifique histórico de comandos, liste volumes restantes com docker volume ls e restaure a aplicação a partir do Compose, backup de volume ou configuração documentada.

Sintoma: container aparece parado e não volta a iniciar

Causa: a aplicação pode estar encerrando por erro interno, porta ocupada, variável ausente ou dependência indisponível. Solução: leia os logs com docker logs --tail=80 nome-do-container, confira o código de saída com docker inspect e corrija a causa antes de tentar reiniciar repetidamente.

Perguntas frequentes sobre containers somem no Portainer

Por que meus containers não aparecem no Portainer?

Containers podem não aparecer no Portainer quando o endpoint Docker está desconectado, o socket do Docker não foi montado corretamente ou há filtros ativos na interface. Também é comum confundir containers parados com containers removidos, por isso confirme pelo terminal com docker ps -a.

Como reconectar o Docker ao Portainer sem perder containers?

A reconexão deve ser feita verificando o endpoint local do Docker e mantendo o volume persistente do Portainer intacto. Se o volume de dados do Portainer for removido, as configurações do painel podem ser perdidas, embora os containers Docker ainda possam existir no host.

Portainer removido apaga meus containers Docker?

Remover apenas o container do Portainer não apaga automaticamente os containers gerenciados pelo Docker. O risco maior está em remover volumes, redes ou executar comandos destrutivos como docker system prune sem revisar o que será excluído.

Qual comando confirma se o container existe fora do Portainer?

Use docker ps -a para listar containers ativos e parados diretamente no host Docker. Se o container aparecer nesse comando, o problema está na visualização, endpoint ou configuração do Portainer, e não necessariamente na remoção do container.

É seguro atualizar o Portainer em servidor de produção?

É seguro quando você preserva o volume de dados do Portainer e valida os containers existentes antes da atualização. Antes de alterar a versão, registre o nome do volume, confira o endpoint Docker e evite remover volumes usados em produção.

Conclusão

• Antes de mexer no Portainer, rode docker ps -a para confirmar se os containers ainda existem no Docker host.
• Preserve o volume de dados do Portainer e verifique a montagem do socket Docker antes de recriar ou atualizar o painel.
• Evite limpezas destrutivas sem revisar containers, volumes, redes e arquivos Docker Compose usados em produção.

Leia também

• Passo a passo para fazer backup e restaurar containers Docker
• Entenda o Traefik não iniciando: o que verificar e como resolver
• Entenda Docker no Ubuntu 24.04: instale e configure do zero

Precisa de ajuda com Portainer e Docker?

Ambientes com Docker, Portainer, Nginx e aplicações em produção exigem organização de volumes, redes e backups para reduzir falhas operacionais. Um servidor VPS bem dimensionado facilita esse controle e dá mais previsibilidade para hospedar seus containers.

Conheça os planos de Servidor VPS da AviraHost