O monitoramento de infraestrutura é um pilar fundamental para qualquer operação de tecnologia da informação moderna. Ferramentas como o Uptime Kuma ganharam popularidade por oferecerem uma interface amigável, leve e eficiente para verificar a disponibilidade de serviços, APIs e servidores. No entanto, ao migrar para ambientes containerizados utilizando Docker, é comum que administradores de sistemas e desenvolvedores se deparem com comportamentos inesperados. Problemas como falhas na inicialização do contêiner, impossibilidade de acesso à interface web ou erros de sincronização de dados são frequentes quando a configuração não segue as melhores práticas de persistência e rede.
Este guia técnico aborda o troubleshooting completo do Uptime Kuma em containers Docker. O objetivo é diagnosticar e resolver os principais obstáculos encontrados por profissionais de DevOps e SREs, garantindo que o monitoramento esteja sempre ativo e confiável. Abordaremos desde a validação da instalação até a resolução de conflitos de rede e persistência de dados.
1. Validação do Estado do Contêiner
O primeiro passo em qualquer troubleshooting é verificar se o contêiner está realmente rodando. Um estado "Exited" ou "Restarting" indica que há um erro crítico impedindo a execução. Utilize o comando docker ps -a para listar todos os contêineres, incluindo aqueles que estão parados.
docker ps -a
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
a1b2c3d4e5f6 louislam/uptime-kuma:1 "/init" 5 minutes ago Up 2 minutes 0.0.0.0:3001->3001/tcp uptime-kumaSe o status do seu contêiner for diferente de Up, você precisa investigar os logs para entender a causa raiz. O comando docker logs é sua principal ferramenta aqui. Adicione a flag --tail 50 para ver as últimas linhas geradas, o que facilita a leitura em meio a muito ruído.
docker logs uptime-kuma --tail 50Sintomas comuns nos logs incluem erros de permissão ao acessar o diretório de banco de dados ou falhas na inicialização do Node.js devido à falta de memória RAM disponível no host. Se você vir mensagens sobre EACCES, verifique as permissões do volume montado, conforme detalhado na seção de persistência.
2. Configuração de Persistência de Dados
A causa número um de perda de dados e falhas no Uptime Kuma é a falta de configuração adequada de volumes Docker. Por padrão, o Docker armazena os dados do contêiner em seu sistema de arquivos interno. Se o contêiner for removido ou atualizado, todas as configurações de monitoramento serão perdidas.
O Uptime Kuma armazena seus dados no diretório /app/backend/data. Para persistir esses dados, você deve mapear um diretório do host para esse caminho dentro do contêiner. A sintaxe correta no comando docker run ou no arquivo docker-compose.yml é essencial.
No arquivo docker-compose.yml, a estrutura recomendada é:
version: '3.8'
services:
uptime-kuma:
image: louislam/uptime-kuma:1
container_name: uptime-kuma
volumes:
- ./data:/app/backend/data
ports:
- "3001:3001"
restart: unless-stoppedSe você estiver utilizando comandos diretos no terminal, utilize a flag -v:
docker run -d \
--name uptime-kuma \
-v /caminho/para/seus/dados:/app/backend/data \
-p 3001:3001 \
louislam/uptime-kuma:1Dica de Troubleshooting: Se após adicionar o volume o contêiner falhar ao iniciar, verifique as permissões do diretório no host Linux. O usuário interno que roda o processo do Uptime Kuma pode não ter acesso de escrita ao diretório montado. Você pode corrigir isso alterando a propriedade do diretório:
sudo chown -R 1000:1000 /caminho/para/seus/dadosO UID 1000 é comum em imagens modernas baseadas em Alpine ou Debian não-root, mas consulte a documentação específica da imagem se o problema persistir.
3. Diagnóstico de Conflitos de Porta e Rede
Muitas vezes, o contêiner inicia corretamente, mas a interface web não é acessível no navegador. Isso geralmente ocorre por dois motivos: conflito de porta ou regras de firewall.
Conflito de Porta
O Uptime Kuma utiliza a porta 3001 por padrão. Antes de iniciar o contêiner, verifique se essa porta não está sendo usada por outro serviço no seu servidor Linux.
sudo ss -tulnp | grep 3001
# ou
netstat -tulnp | grep 3001Se alguma saída for retornada, outra aplicação já está escutando naquela porta. Você tem duas opções: parar o serviço conflitante ou mapear uma porta diferente no seu host para a porta interna do contêiner.
docker run -d \
--name uptime-kuma-alt \
-p 8080:3001 \
louislam/uptime-kuma:1Neste exemplo, você acessará o serviço via http://seu-ip:8080.
Firewall e Segurança de Rede
No Linux, ferramentas como ufw, firewalld ou iptables podem bloquear o acesso externo à porta exposta. Certifique-se de liberar a porta correspondente ao mapeamento que você definiu.
Para usuários de UFW (Ubuntu/Debian):
sudo ufw allow 3001/tcp
sudo ufw reloadPara usuários de Firewalld (CentOS/RHEL/Fedora):
sudo firewall-cmd --permanent --add-port=3001/tcp
sudo firewall-cmd --reload4. Problemas com Acesso HTTPS e Reverse Proxy
Em ambientes de produção, é altamente recomendável colocar o Uptime Kuma atrás de um reverse proxy como Nginx ou Traefik, especialmente para habilitar HTTPS. Sem HTTPS, alguns tipos de monitoramento (como webhooks sensíveis) podem falhar devido a políticas de segurança do navegador ou do servidor alvo.
Se você configura o Uptime Kuma para usar HTTPS internamente através do proxy, mas não configurou corretamente as variáveis de ambiente, o sistema pode gerar links mistos ou falhar no handshake TLS.
O Uptime Kuma suporta a configuração de cabeçalhos de proxy via variáveis de ambiente. Se seu reverse proxy estiver em um container Docker separado na mesma rede, você precisa garantir que o contêiner do Kuma saiba que está atrás de um proxy.
environment:
- UPTIME_KUMA_WEBSOCKET_MAX_BUFFER_TIME=300000
- UPTIME_KUMA_WEBSOCKET_PING_INTERVAL=5000No entanto, o problema mais comum não é técnico, mas de configuração do proxy. Ao configurar o Nginx para servir o Uptime Kuma, você deve garantir que o suporte a WebSockets esteja habilitado, pois o Kuma usa WebSockets para atualizações em tempo real do status.
location / {
proxy_pass http://localhost:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}A ausência das linhas proxy_set_header Upgrade e Connection "upgrade" fará com que o dashboard carregue, mas os status não se atualizarão automaticamente, exigindo recarregamento manual da página.
5. Troubleshooting de Monitoramento Falso-Positivo
Um cenário frustrante comum é o Uptime Kuma marcar um serviço como "Down" quando ele está funcionando perfeitamente. Isso requer uma abordagem sistemática para isolar a falha.
Verificação de DNS no Contêiner
Os contêineres Docker possuem seu próprio resolver de DNS. Se o host tiver configurações DNS complexas ou privadas (como zonas internas da AWS, Azure ou um DNS local), o contêiner pode não conseguir resolvê-las.
Para diagnosticar, acesse o shell do contêiner:
docker exec -it uptime-kuma shDentro do contêiner, tente pingar o serviço monitorado ou usar ferramentas de diagnóstico como nslookup ou curl.
nslookup google.com
curl -I https://google.comSe o DNS falhar dentro do contêiner, você pode precisar configurar os servidores DNS no arquivo /etc/docker/daemon.json do host ou passar as opções de rede corretamente no docker-compose:
services:
uptime-kuma:
dns:
- 8.8.8.8
- 1.1.1.1Falhas de TLS/SSL
O Uptime Kuma valida certificados SSL por padrão. Se o serviço monitorado tiver um certificado autoassinado, expirado ou com uma cadeia de certificação incompleta, o monitoramento falhará.
Nas configurações do monitor no painel do Uptime Kuma, existe uma opção para "Ignore TLS/SSL Errors". Use-a com cautela apenas para testes ou em ambientes internos onde a segurança da cadeia de certificados não é crítica. Em produção, prefira corrigir o certificado do serviço alvo.
Timeouts
Serviços lentos podem ser marcados como down se o tempo de resposta exceder o limite configurado. Verifique a configuração de Timeout em cada monitor. O padrão é geralmente 5 segundos, mas para APIs complexas ou sistemas legados, aumentar esse valor para 10 ou 20 segundos pode evitar alertas falsos.
6. Manutenção e Backups Automáticos
Um sistema de monitoramento sem backup é um risco operacional. O Uptime Kuma não possui uma funcionalidade nativa de agendamento de backups robusta integrada ao core, mas isso pode ser facilmente contornado com scripts shell ou tarefas cron do host.
A estratégia mais simples é copiar o diretório de dados periodicamente. Como os dados são armazenados em um SQLite local (database.sqlite), garantir a integridade desse arquivo é crucial.
Crie um script simples de backup:
#!/bin/bash
BACKUP_DIR="/backups/uptime-kuma"
DATE=$(date +%F)
docker cp uptime-kuma:/app/backend/data/database.sqlite $BACKUP_DIR/db-$DATE.sqliteAgende este script via crontab para rodar diariamente. Isso garante que, em caso de corrupção do banco de dados ou falha no disco, você possa restaurar o estado anterior do monitoramento.
7. Atualização Segura da Imagem
Manter o Uptime Kuma atualizado é vital para correções de segurança e novas funcionalidades. A atualização em ambientes Docker deve ser feita com cuidado para não perder dados ou configurações.
- Pare o contêiner existente:
docker stop uptime-kuma- Remova o contêiner antigo (os dados estão salvos no volume, não se preocupe):
docker rm uptime-kuma- Puxe a nova imagem:
docker pull louislam/uptime-kuma:1- Rode o novo contêiner com a mesma configuração de volumes e portas:
docker run -d \
--name uptime-kuma \
-v /caminho/para/seus/dados:/app/backend/data \
-p 3001:3001 \
louislam/uptime-kuma:1Após a atualização, verifique os logs imediatamente para garantir que nenhuma migração de banco de dados falhou. Em versões muito antigas para versões muito novas, pode ser necessário verificar a documentação da release notes para possíveis breaking changes na configuração.
Conclusão
O troubleshooting do Uptime Kuma em containers Docker envolve principalmente a compreensão de como o Docker gerencia volumes, redes e processos. A maioria dos problemas relatados por usuários — desde falhas de inicialização até atualizações manuais — pode ser resolvida seguindo uma lógica estruturada: verificar logs, validar persistência de dados, assegurar conectividade de rede e revisar configurações de proxy.
Ao implementar as práticas descritas neste tutorial, profissionais de TI podem garantir que seu sistema de monitoramento seja resiliente, seguro e fácil de manter. A observabilidade não começa apenas com a coleta de métricas, mas com a infraestrutura sólida que sustenta essas ferramentas. Utilize este guia como referência rápida sempre que encontrar anomalias no ambiente de monitoramento.