O Uptime Kuma serve para estes cenários:

• Você tem alguns sites, APIs ou serviços de backend para ficar de olho.
• Você quer receber notificações por Telegram, e-mail ou WeCom imediatamente após uma queda.
• Você precisa de uma página de status simples para informar aos usuários quais serviços estão normais e quais estão fora do ar.
• Você não quer montar a stack relativamente pesada de Prometheus + Grafana.
• Você tem apenas uma VPS de baixa configuração e ainda quer que ela rode.

Não é muito adequado para estes cenários:

• Você precisa de análise complexa de métricas, como tendências de CPU, memória, disco ou consultas lentas.
• Você precisa armazenar dados de séries temporais por anos.
• Você precisa de permissões multilocatário, relatórios complexos e auditoria empresarial.

Meu conselho é: use o Uptime Kuma para monitorar "se o serviço está vivo" e use Prometheus/Grafana para monitorar "por que ficou lento". Não são o mesmo tipo de coisa.

O Uptime Kuma é muito leve e, para uso pessoal, não é exigente com a máquina.

O que realmente precisa de atenção é isto: é melhor não colocar o painel de monitoramento na mesma máquina que todos os serviços de negócio.

Por exemplo, se você tem apenas uma VPS e tanto o site quanto o Uptime Kuma rodam nessa máquina, quando a máquina cair, o Uptime Kuma também cai, e é claro que ele não vai conseguir te notificar. Então uma prática melhor é:

• O negócio principal na máquina A.
• O Uptime Kuma na máquina B.
• Se o orçamento for limitado, uma VPS anual barata para a máquina B já basta.

Se por enquanto você só tem uma máquina, também não é impossível implantar. Pelo menos você pode começar monitorando o domínio, o certificado, as portas e o status dos contêineres Docker. Mais tarde, quando o negócio se tornar mais importante, migre o painel de monitoramento para outra VPS.

Ambiente padrão deste artigo:

• Ubuntu 22.04 / 24.04 ou Debian 12.
• Docker e Docker Compose já instalados.
• Você tem um domínio, por exemplo status.example.com.
• As portas 80/443 estão acessíveis.
• O Caddy já está instalado, ou você está disposto a configurá-lo conforme este artigo.

Primeiro confirme que o Docker está disponível:

docker version
docker compose version

Confirme que o domínio já resolve para a VPS:

dig status.example.com +short

Se ainda não instalou o Caddy, você pode ler primeiro este artigo: Guia completo de proxy reverso com Caddy em uma VPS.

Costumo colocar esse tipo de serviço em /opt:

sudo mkdir -p /opt/uptime-kuma
sudo chown -R "$USER":"$USER" /opt/uptime-kuma
cd /opt/uptime-kuma

Crie o diretório de dados:

mkdir -p data

Os monitores, as configurações de notificação, as páginas de status e as informações de usuários do Uptime Kuma ficam todos em /app/data. Esse diretório precisa ser persistido, caso contrário os dados serão perdidos mais tarde quando você excluir contêineres ou atualizar imagens.

Crie docker-compose.yml:

nano docker-compose.yml

Escreva:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - ./data:/app/data
    ports:
      - "127.0.0.1:3001:3001"

Aqui eu deliberadamente vinculei apenas 127.0.0.1:3001, para não expor a porta 3001 diretamente à internet.

O motivo é simples: apenas as portas 80/443 ficam abertas para a internet e o Uptime Kuma fica atrás do Caddy. Assim, certificados, HTTPS e controle de acesso são mais fáceis de gerenciar.

Se você também quiser usar o Uptime Kuma para monitorar contêineres Docker na mesma VPS, precisa montar adicionalmente o socket do Docker:

services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    container_name: uptime-kuma
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "127.0.0.1:3001:3001"

Observe esta linha:

- /var/run/docker.sock:/var/run/docker.sock:ro

Sem ela, o Uptime Kuma normalmente não consegue ver os contêineres Docker do host, então você não poderá adicionar monitores do tipo Docker Container.

Mas também não monte o socket do Docker em todos os contêineres sem pensar. Ele consegue ler o status do Docker e, por si só, é um ponto de entrada altamente sensível. Só é recomendado ativá-lo quando você realmente precisar monitorar contêineres Docker, e continuar mantendo o Uptime Kuma acessível apenas via HTTPS, sem expor a porta 3001 diretamente à internet.

Inicie o serviço:

docker compose up -d

Verifique o status:

docker compose ps
docker compose logs -f --tail=100

Teste localmente:

curl -I http://127.0.0.1:3001

Se houver resposta, o contêiner já está em execução.

Edite o Caddyfile:

sudo nano /etc/caddy/Caddyfile

Adicione:

status.example.com {
    encode zstd gzip

    header {
        X-Content-Type-Options nosniff
        Referrer-Policy strict-origin-when-cross-origin
    }

    reverse_proxy 127.0.0.1:3001
}

Verifique a configuração e recarregue:

sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Abra no navegador:

https://status.example.com

O primeiro acesso vai pedir para você criar uma conta de administrador. Não use uma senha fraca; o painel de monitoramento normalmente armazena tokens de canais de notificação, endereços Webhook e informações de serviços, e ser escaneado é bastante problemático.

Após fazer login, clique em Add New Monitor e comece pelo monitoramento de sites.

Configuração comum:

• Monitor Type: HTTP(s)
• Friendly Name: Site principal
• URL: https://example.com
• Heartbeat Interval: 60 segundos ou 120 segundos
• Retries: 2-3 vezes
• Accepted Status Codes: 200-299

Eu geralmente não defino o intervalo muito curto. Muitas VPS pequenas, rotas baratas e redes internacionais oscilam ocasionalmente, e isso é normal. Se você configurar para verificar a cada 20 segundos, no final pode acabar se assustando sozinho.

Uma configuração mais estável é:

间隔：60 秒
重试：3 次
失败后再通知

Assim é possível filtrar algumas oscilações breves de rede.

Não adicione 100 monitores de uma vez; primeiro fique de olho no que realmente é importante.

Recomenda-se começar por estas categorias:

O que eu mais uso é HTTP(s) + Keyword. Porque alguns sites podem retornar 200 mesmo quando estão apresentando erros. Por exemplo, o framework da aplicação mostra uma página de erro, o código de status HTTP está normal, mas o conteúdo da página já não é o que você quer.

Nesse caso você pode definir um Keyword:

必须包含：网站标题、品牌名、某个固定文字

Se a página não contiver mais essa palavra, o Uptime Kuma vai determinar como anormal.

Se você quiser adicionar monitoramento de Docker Container, primeiro confirme que o Compose acima montou /var/run/docker.sock. Caso contrário, quando você selecionar o tipo Docker no Uptime Kuma, muito provavelmente não conseguirá conectar ao daemon do Docker.

O Telegram é um dos métodos de notificação que mais recomendo: rápido, gratuito e simples de configurar.

O processo geral:

1. Encontre @BotFather para criar um Bot.
2. Obtenha o Bot Token.
3. Envie uma mensagem para o Bot.
4. Obtenha o Chat ID.
5. Adicione uma notificação do Telegram no Uptime Kuma.

Se você não sabe como obter o Chat ID, pode acessar:

https://api.telegram.org/bot你的TOKEN/getUpdates

Encontre chat.id nele.

No Uptime Kuma, vá em:

Settings -> Notifications -> Setup Notification

Selecione Telegram, preencha o Bot Token e o Chat ID, e então clique em Test.

Depois que o teste for bem-sucedido, lembre-se de definir este canal de notificação como padrão, ou vinculá-lo manualmente aos monitores importantes.

As notificações por e-mail são boas como reserva. Às vezes o sistema do celular silencia o Telegram, mas o e-mail pelo menos deixa um registro.

Configuração SMTP comum:

Host: smtp.example.com
Port: 587
Security: STARTTLS
Username: [email protected]
Password: 邮箱授权码
From: [email protected]

Atenção a algumas armadilhas:

• Muitos provedores de e-mail não permitem usar a senha de login; use uma senha específica de aplicativo.
• O provedor da VPS pode restringir a porta 25; prefira 587 ou 465.
• É melhor configurar SPF, DKIM e DMARC para a caixa de envio, caso contrário é fácil cair no spam.
• Não coloque a senha da sua caixa de e-mail pessoal principal.

Se for apenas para uso pessoal, Telegram + e-mail já é suficiente. Em cenários empresariais, você pode conectar também Slack, Discord, Webhook, WeCom etc.

A página de status do Uptime Kuma é muito prática. Por exemplo, se você tem alguns serviços:

• Site oficial
• API
• Site de documentação
• Site de downloads
• Painel de administração

Você pode criar uma página pública:

https://status.example.com/status/main

Depois que usuários ou clientes abrirem, eles podem ver quais serviços estão normais e quais estão fora do ar.

No entanto, não recomendo tornar públicos todos os serviços internos. A página de status deve incluir apenas o que os usuários precisam saber, como o site oficial, a API e o serviço de downloads. Não exponha bancos de dados, Redis ou painéis de administração internos; não há necessidade de mostrar sua estrutura interna para os outros.

Muitas pessoas esquecem esse ponto.

Se o Uptime Kuma só monitora os outros, ninguém vai saber quando ele mesmo cair. Uma forma mais confiável é:

• Usar outro serviço de monitoramento gratuito para monitorar status.example.com.
• Ou encontrar outra VPS de baixo custo para rodar um segundo Kuma, monitorando um ao outro.
• Ou usar um serviço de terceiros como reserva, como Better Stack, Healthchecks, UptimeRobot etc.

Projetos pessoais não precisam ser complicados demais, mas pelo menos você deve saber um fato: o monitoramento de ponto único só consegue descobrir os problemas dos outros, não o problema da sua própria queda total.

Os dados do Uptime Kuma ficam em /opt/uptime-kuma/data. Basta fazer backup desse diretório.

O backup mais simples:

cd /opt/uptime-kuma
mkdir -p /opt/backups/uptime-kuma

tar czf /opt/backups/uptime-kuma/uptime-kuma-$(date +%F-%H%M).tar.gz data

Se você já usa restic, rclone ou armazenamento de objetos para backups, basta adicionar esse diretório à lista de backups.

Recomenda-se fazer backup pelo menos de:

• data/kuma.db
• data/upload/
• Todo o /opt/uptime-kuma/data

Ao restaurar, pare o serviço primeiro:

cd /opt/uptime-kuma
docker compose down
mv data data.broken.$(date +%F-%H%M)
tar xzf /opt/backups/uptime-kuma/uptime-kuma-你的日期.tar.gz

docker compose up -d

Após restaurar, verifique: se os monitores ainda estão lá, se os canais de notificação podem ser testados e se o link da página de status está normal.

Faça backup antes de atualizar:

cd /opt/uptime-kuma
tar czf /opt/backups/uptime-kuma/before-upgrade-$(date +%F-%H%M).tar.gz data docker-compose.yml

Baixe a nova imagem e reinicie:

docker compose pull
docker compose up -d

Verifique os logs:

docker compose logs -f --tail=100

Se você não quiser acompanhar sempre a versão mais recente, pode fixar a versão da imagem. Para projetos pessoais, louislam/uptime-kuma:2 é mais tranquilo; em ambientes de produção, é mais recomendável atualizar primeiro em uma máquina de teste.

Antes do uso formal, recomenda-se confirmar:

• O diretório data está persistido.
• A porta 3001 está vinculada apenas a 127.0.0.1.
• O domínio usa HTTPS.
• A senha do administrador é suficientemente forte.
• Pelo menos um canal de notificação instantânea está configurado.
• Os monitores importantes estão vinculados a notificações.
• Se você quiser monitorar contêineres Docker, /var/run/docker.sock está montado.
• A página de status não expõe serviços internos.
• O diretório de dados está incluído nos backups.
• Um teste de notificação foi feito.
• Um simulado de restauração foi feito.

O Uptime Kuma é mais adequado para o "monitoramento de primeira camada": o site não abre, a API caiu, a porta não responde, o certificado está prestes a expirar, a palavra-chave desapareceu; ele consegue te avisar rapidamente.

Mas ele não é onipotente. Ele te diz "o serviço tem um problema", mas não necessariamente "por que há um problema". Se você também quiser ver métricas de CPU, memória, disco e contêineres, pode adicionar Prometheus + Grafana; se for apenas um projeto pessoal, o site de uma equipe pequena ou alguns aplicativos auto-hospedados, o Uptime Kuma já é suficiente.

Meu próprio hábito é: adicionar primeiro os serviços importantes ao Uptime Kuma, pelo menos garantindo que alguém seja avisado quando houver uma queda; quando o serviço se tornar mais complexo, adicionar depois logs, métricas e rastreamento. Não faça o sistema de monitoramento ser mais complexo que o negócio desde o início.