Uptime Kuma¶
O Uptime Kuma é a ferramenta de monitoramento da VPS. Ele verifica serviços, domínios e endpoints e registra disponibilidade, tempo de resposta e incidentes.
Nesta VPS, ele é uma ferramenta administrativa não essencial e pode permanecer desligado durante o quiet_mode.
Informações desta VPS¶
| Item | Valor |
|---|---|
| Stack | /opt/stacks/infra/compose.yml |
| Serviço Compose | uptime-kuma |
| Container | infra-uptime-kuma-1 |
| Imagem configurada | louislam/uptime-kuma:latest |
| Versão registrada | 1.23.17 |
| Domínio | https://status.cloud.hometecseg.com |
| Porta interna | 3001 |
| Rede Docker | proxy |
| Volume | infra_kuma-data |
| Diretório no container | /app/data |
| Banco de dados | SQLite |
| Versão do SQLite registrada | 3.41.1 |
| Operação contínua | Não obrigatória |
Modo econômico
O Uptime Kuma pode aparecer como parado porque é desligado propositalmente pelo script quiet_mode.sh. Isso não significa necessariamente falha.
Estado atual¶
Ver o estado do serviço¶
Ver somente containers em execução¶
Ver containers ativos ou parados¶
Ver o estado detalhado¶
docker inspect infra-uptime-kuma-1 \
--format 'Status={{.State.Status}} ExitCode={{.State.ExitCode}} FinishedAt={{.State.FinishedAt}} OOMKilled={{.State.OOMKilled}}'
Ver o healthcheck¶
Iniciar e parar¶
Iniciar o Uptime Kuma¶
Caso o container não exista:
Parar o Uptime Kuma¶
Reiniciar o Uptime Kuma¶
Recriar o container¶
Confirmar o estado após iniciar¶
Acesso¶
Endereço:
Testar o domínio¶
Verificar o DNS¶
Ver detalhes da conexão HTTPS¶
Serviço desligado
O domínio ficará indisponível enquanto o Uptime Kuma estiver parado pelo modo econômico.
Logs¶
Ver os últimos 100 registros¶
Acompanhar os logs em tempo real¶
Procurar erros¶
Procurar avisos¶
Ver informações de versão¶
docker logs infra-uptime-kuma-1 2>&1 \
| grep -Ei "Version:|SQLite Version:|database version" \
| tail -10
Versão¶
Ver a versão registrada nos logs¶
Mostrar somente o número da versão¶
docker logs infra-uptime-kuma-1 2>&1 \
| grep "Version:" \
| tail -1 \
| sed -E 's/.*Version:[[:space:]]*//'
Ver a imagem configurada¶
Ver a imagem associada ao container¶
Ver o identificador da imagem utilizada¶
Versões disponíveis¶
A instalação atual pertence à linha antiga:
A linha recomendada atualmente é a versão principal 2.
A imagem oficial recomendada é:
A atualização da versão 1 para a versão 2 é uma migração de versão principal e pode conter mudanças incompatíveis. Por isso, ela exige backup e leitura da documentação de migração antes da execução. :contentReference[oaicite:0]{index=0}
Migração principal
Não substitua simplesmente latest por 2 sem backup. A mudança da versão 1 para a 2 deve ser tratada como migração planejada, não como um alegre docker pull disparado no escuro.
Verificar atualização disponível¶
Baixar a imagem da linha 2¶
Esse comando baixa a imagem, mas não altera o container atual.
Ver o identificador da imagem baixada¶
Ver o identificador da imagem usada pelo container¶
Comparar automaticamente¶
CONTAINER_IMAGE="$(docker inspect infra-uptime-kuma-1 --format '{{.Image}}')" &&
NEW_IMAGE="$(docker image inspect louislam/uptime-kuma:2 --format '{{.Id}}')" &&
if [ "$CONTAINER_IMAGE" = "$NEW_IMAGE" ]; then
echo "O container já utiliza a imagem baixada."
else
echo "Existe uma imagem diferente da usada pelo container."
fi
Volume persistente¶
Ver as montagens¶
docker inspect infra-uptime-kuma-1 \
--format '{{range .Mounts}}{{println .Type "|" .Name "|" .Source "|" .Destination}}{{end}}'
Inspecionar o volume¶
Ver o espaço utilizado¶
Listar os arquivos persistentes¶
Localizar o banco SQLite¶
Não editar diretamente
Não altere manualmente o banco SQLite do Uptime Kuma enquanto o container estiver ativo. O caminho mais curto entre curiosidade e corrupção costuma ser um editor de texto aberto no arquivo errado.
Backup¶
Criar diretório de backup¶
Parar o Uptime Kuma antes do backup¶
Criar backup compactado do volume¶
docker run --rm \
-v infra_kuma-data:/source:ro \
-v /opt/backups/uptime-kuma:/backup \
alpine \
tar -czf "/backup/uptime-kuma-data-$(date +%Y%m%d-%H%M%S).tar.gz" \
-C /source .
Iniciar novamente¶
Listar os backups¶
Verificar o conteúdo do backup¶
Restauração¶
Operação destrutiva
A restauração substitui os dados existentes. Preserve um backup do estado atual antes de continuar.
Parar o serviço¶
Criar backup de segurança do estado atual¶
docker run --rm \
-v infra_kuma-data:/source:ro \
-v /opt/backups/uptime-kuma:/backup \
alpine \
tar -czf "/backup/uptime-kuma-before-restore-$(date +%Y%m%d-%H%M%S).tar.gz" \
-C /source .
Limpar o volume atual¶
docker run --rm \
-v infra_kuma-data:/data \
alpine \
sh -c 'rm -rf /data/* /data/.[!.]* /data/..?*'
Restaurar o backup¶
docker run --rm \
-v infra_kuma-data:/data \
-v /opt/backups/uptime-kuma:/backup:ro \
alpine \
tar -xzf /backup/NOME_DO_BACKUP.tar.gz \
-C /data
Iniciar novamente¶
Verificar os logs¶
Migração da versão 1 para a 2¶
O procedimento oficial para Docker utiliza a imagem:
e preserva o mesmo volume montado em /app/data. :contentReference[oaicite:1]{index=1}
Criar backup antes da migração¶
docker run --rm \
-v infra_kuma-data:/source:ro \
-v /opt/backups/uptime-kuma:/backup \
alpine \
tar -czf "/backup/uptime-kuma-v1-pre-migration-$(date +%Y%m%d-%H%M%S).tar.gz" \
-C /source .
Criar backup do Compose¶
cp /opt/stacks/infra/compose.yml \
/opt/backups/uptime-kuma/compose-pre-v2-$(date +%Y%m%d-%H%M%S).yml
Alterar a imagem no Compose¶
No arquivo:
Substituir:
por:
Validar o Compose¶
Baixar a nova imagem¶
Recriar somente o Uptime Kuma¶
Acompanhar a migração¶
Verificar o estado¶
Confirmar a versão¶
Testar o domínio¶
Não interromper a migração
Durante a primeira inicialização, o Uptime Kuma pode atualizar o banco. Não encerre o container enquanto essa migração estiver ocorrendo.
Rollback da migração¶
Caso a versão 2 não funcione, o rollback deve restaurar:
- o Compose anterior;
- o backup do volume criado antes da migração.
Parar o serviço¶
Restaurar o Compose anterior¶
Limpar e restaurar o volume¶
docker run --rm \
-v infra_kuma-data:/data \
alpine \
sh -c 'rm -rf /data/* /data/.[!.]* /data/..?*'
docker run --rm \
-v infra_kuma-data:/data \
-v /opt/backups/uptime-kuma:/backup:ro \
alpine \
tar -xzf /backup/NOME_DO_BACKUP_V1.tar.gz \
-C /data
Recriar a versão anterior¶
Atualização pelo script¶
Existe um script dedicado:
Ele será analisado e documentado posteriormente na página de scripts.
Visualizar o script¶
Verificar permissões¶
Não executar sem revisão
O script pode ter sido criado para a versão 1 e usar a tag latest. Ele precisa ser revisado antes da migração para a versão 2.
Healthcheck¶
O container possui o seguinte teste:
Configuração registrada:
| Item | Valor |
|---|---|
| Intervalo | 60 segundos |
| Timeout | 30 segundos |
| Período inicial | 180 segundos |
| Tentativas | 5 |
Ver o healthcheck configurado¶
Ver o resultado atual¶
Traefik¶
Ver as labels¶
Verificar a rede proxy¶
Confirmar as redes do container¶
Ver logs do Traefik¶
Troubleshooting¶
Uptime Kuma aparece como parado¶
Verificar:
Se foi parado pelo modo econômico:
Caso o container não exista:
Código de saída 137¶
O código 137 normalmente significa que o processo recebeu SIGKILL.
Nesta VPS, isso pode ocorrer durante o desligamento planejado pelo quiet_mode. Ainda assim, confirme se houve falta de memória:
docker inspect infra-uptime-kuma-1 \
--format 'ExitCode={{.State.ExitCode}} OOMKilled={{.State.OOMKilled}} Error={{printf "%q" .State.Error}}'
Verificar mensagens do kernel:
Serviço inicia como unhealthy¶
Erro 404¶
Erro 502 ou Gateway Timeout¶
A porta interna esperada é:
Banco SQLite bloqueado¶
Procurar:
Verificar uso de disco:
Verificar permissões:
Interface abre, mas não atualiza¶
O Uptime Kuma utiliza WebSocket. O proxy reverso precisa aceitar conexões persistentes e os cabeçalhos de upgrade. :contentReference[oaicite:2]{index=2}
Verificar:
Boas práticas¶
- Manter o Uptime Kuma desligado quando o monitoramento não for necessário.
- Fazer backup antes da migração para a versão 2.
- Usar uma tag de versão principal, como
:2, em vez delatest. - Não remover o volume
infra_kuma-data. - Não editar diretamente o banco SQLite.
- Não publicar diretamente a porta
3001. - Verificar logs e healthcheck após atualizações.
- Testar a restauração dos backups.
- Revisar o script
update_kuma.shantes de utilizá-lo.