Docker Compose: healthcheck e recuperação de serviços

--- queue_position: 22 title: "Docker Compose: healthcheck e recuperação de serviços" slug: docker-compose-healthcheck-recuperacao-servicos site_key: host-yousecure canonical: https://yousecure.io/blog/docker-compose-healthcheck-recuperacao-servicos category: docker-troubleshooting cluster: confiabilidade-docker search_intent: informacional-pratica funnel_stage: meio author: "Host You Secure Team" created_at: "2026-09-09T11:29:43-03:00" planned_scheduled_at: null status: queued-review meta_description: "Configure healthcheck no Docker Compose, diferencie processo vivo de serviço saudável e investigue reinícios com logs." excerpt: "Healthcheck bem desenhado evita que um container verde esconda uma aplicação que não responde." quick_answer: "Teste uma dependência real com timeout e retries razoáveis, use a saída do healthcheck para diagnóstico e não confunda restart automático com correção da causa." featured_image: images/22-docker-healthchecks.png featured_image_alt: "Containers conectados por um pulso de saúde e recuperação" tags: [docker, compose, healthcheck, observabilidade, troubleshooting] evidence_type: reproducible_procedure evidence_environment: Docker Compose v2 e serviço HTTP local evidence_procedure: "Adicionar healthcheck, subir a stack, consultar docker inspect e reproduzir uma falha controlada." evidence_observed_result: "O status healthy/unhealthy fica observável sem depender somente do processo PID 1." evidence_limitation: "O comando precisa existir na imagem e a rota escolhida precisa representar a saúde do serviço." information_gain: "Explica por que restart_policy não substitui healthcheck e diagnóstico." primary_cta: "Ver VPS para Docker" landing: /vps-docker-portainer-coolify --- # Docker Compose: healthcheck e recuperação de serviços ## Resposta rápida Um processo vivo não significa que a aplicação esteja pronta. `healthcheck` executa uma verificação repetível dentro do container e marca o serviço como `healthy` ou `unhealthy`. Use esse sinal para diagnóstico e orquestração; não trate reinícios como prova de que o problema foi resolvido. ## O que um bom teste deve responder Escolha uma verificação pequena e útil: uma rota `/health`, conexão a uma dependência essencial ou uma consulta simples. Não faça um teste que altere dados, dependa de um serviço externo instável ou consuma a mesma carga que a aplicação deveria atender. ## Exemplo no Compose ```yaml services: app: image: exemplo/app:stable healthcheck: test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8080/health || exit 1"] interval: 30s timeout: 5s retries: 3 start_period: 20s restart: unless-stopped ``` Se a imagem não tem `curl`, use `wget`, um binário próprio ou uma verificação compatível com a distribuição. O `start_period` dá tempo para a aplicação inicializar sem marcar falha prematuramente. ## Observe o resultado ```bash docker compose up -d docker compose ps docker inspect --format '{{json .State.Health}}' nome-do-container docker compose logs --tail=100 app ``` O histórico do healthcheck mostra código de saída e parte da saída do comando. Procure o primeiro erro, não apenas a última reinicialização. ## Falha controlada Em ambiente de teste, altere temporariamente a rota ou pare uma dependência e observe a transição para `unhealthy`. Depois restaure a condição e confirme que o serviço volta a responder. Não faça esse teste em produção sem janela, monitoramento e plano de rollback. ## Armadilhas comuns Um healthcheck que chama um endpoint autenticado pode falhar por credencial expirada. Um teste que depende de DNS público pode indicar falha da internet, não da aplicação. `restart: unless-stopped` ajuda a recuperar processo, mas não corrige migração quebrada, falta de disco ou configuração inválida. Combine o healthcheck com logs, uso de CPU/RAM, espaço em disco e alertas externos. [Uma VPS para Docker](https://yousecure.io/vps-docker-portainer-coolify) deve ter recursos e observabilidade compatíveis com os serviços que hospeda. ## Checklist - [ ] Health endpoint é barato e representativo. - [ ] Comando existe na imagem. - [ ] Timeout, retries e start period refletem o boot real. - [ ] Falhas aparecem nos logs. - [ ] Há procedimento de rollback. ## FAQ ### Healthcheck reinicia o container? Por si só, ele apenas informa o estado. A política de reinício e a ferramenta de orquestração determinam a recuperação. ### `depends_on` espera o serviço ficar saudável? O comportamento depende da versão e da condição configurada. Valide a resolução usada pelo seu Compose em vez de assumir que a ordem de inicialização garante prontidão. ## Exemplo de decisão Se a aplicação leva 90 segundos para migrar o banco, um `start_period` de 20 segundos gera um alerta falso. Se a rota `/health` responde mesmo quando a fila está parada, ela é um teste fraco para o objetivo do serviço. Registre por que cada comando foi escolhido e qual falha ele deveria detectar. Esse pequeno documento ajuda a equipe a atualizar o healthcheck quando a aplicação muda, sem transformar um indicador operacional em decoração no Compose.

Veja a infraestrutura: VPS com monitoramento e backup semanal para colocar este projeto no ar.