Uptime Kuma em um VPS: como monitorar sites e servidores

06/09/20267 min de leitura

Tropic

Uptime Kuma em um VPS: como monitorar sites e servidores

Language: pt

Uptime Kuma: configure seu próprio monitoramento de sites em um VPS

Um site pode apresentar falhas e continuar retornando 200 OK. Um backup pode parar de ser executado sem um erro evidente. O Uptime Kuma detecta os dois problemas: verifica sites, APIs, portas e tarefas em segundo plano, e envia uma notificação quando algo dá errado.

Neste guia, veremos onde hospedar o sistema de monitoramento, qual tipo de VPS ele precisa e como instalar o Uptime Kuma 2, ativar HTTPS, conectar o Telegram e criar uma página de status.

Uptime Kuma em sete etapas

Configure um VPS pequeno separado dos projetos monitorados.
Aponte um subdomínio, como monitor.example.com, para ele.
Instale o Docker e execute o Uptime Kuma 2.
Feche a porta interna 3001 e ative o HTTPS.
Crie monitores HTTP, DNS, TCP ou push.
Configure o Telegram e, se necessário, uma página de status.
Configure atualizações e um backup externo do diretório de dados.

O que é o Uptime Kuma

O Uptime Kuma é uma ferramenta gratuita, open source e self-hosted. O painel e o histórico de verificações ficam armazenados no seu próprio servidor.

Ele monitora HTTP(S), portas TCP, ping, DNS, WebSocket, texto e JSON nas respostas, sinais push e contêineres Docker. O intervalo mínimo de verificação é de 20 segundos. Também há dezenas de canais de notificação, autenticação de dois fatores, gráficos de latência, monitoramento de certificados TLS e várias páginas de status.

Como detectar uma falha escondida atrás de `200 OK`

Uma verificação HTTP básica vê apenas o código de resposta. Porém, um servidor web pode mostrar uma página em branco ou uma tela de erro da aplicação e ainda retornar um status de sucesso.

Para um monitoramento mais preciso, use:

Keyword — procura uma frase esperada, como o nome do site ou o texto “Account dashboard”;
JSON Query — verifica um valor na resposta de uma API, por exemplo status: healthy.

Assim, o monitor confirma não apenas que a porta está acessível, mas também que a aplicação apresenta pelo menos um sinal esperado de funcionamento correto.

Monitor push para backups e tarefas cron

Um monitor push não consulta um serviço periodicamente. Em vez disso, ele espera um sinal regular do próprio serviço. Um script de backup ou uma tarefa cron chama uma URL exclusiva depois de terminar com sucesso. Se o sinal não chegar a tempo, o Uptime Kuma informa uma falha.

Isso ajuda a detectar um problema “silencioso”: o site continua funcionando, mas o backup diário não é criado há vários dias.

O que o Uptime Kuma não substitui

O Uptime Kuma acompanha principalmente disponibilidade e tempo de resposta. Para monitorar CPU, RAM, disco, logs e métricas de contêineres, complemente-o com Prometheus, Netdata, Zabbix ou outro sistema: o Kuma percebe o problema externamente, enquanto as métricas ajudam a identificar a causa.

Por que o monitoramento deve rodar em um VPS separado

Se o Uptime Kuma for instalado junto do site, uma falha no VPS, na rede ou no data center pode derrubar o projeto e o sistema de monitoramento ao mesmo tempo. A notificação talvez nunca seja enviada.

Hospede o painel em um VPS separado e, para projetos importantes, use outra localização ou outro provedor. Também é útil monitorar o próprio Kuma com um serviço externo: alguém precisa observar o sistema de monitoramento.

Requisitos do servidor para o Uptime Kuma

O projeto não define um mínimo oficial rígido de CPU e RAM. Uma configuração inicial prática para uma instalação pequena é:

1 vCPU;
1 GB de RAM;
10 GB SSD;
Ubuntu 24.04 LTS;
IPv4;
um domínio ou subdomínio para HTTPS.

Essa configuração costuma ser suficiente para algumas dezenas de verificações simples. Para centenas de monitores, retenção longa do histórico ou verificações baseadas em navegador, escolha 2 GB de RAM ou mais.

Como instalar o Uptime Kuma em um VPS

O exemplo usa Ubuntu 24.04 e o subdomínio monitor.example.com.

1. Configure o DNS e o firewall

Crie um registro DNS A apontando para o endereço IPv4 do VPS. Conecte-se por SSH e abra as portas necessárias:

ssh root@SERVER_IP
apt update && apt upgrade -y

ufw allow OpenSSH
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

Não feche a sessão SSH atual até testar uma nova conexão.

2. Instale o Docker e o Docker Compose

apt install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update
apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

docker compose version

3. Inicie o Uptime Kuma 2

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

cat > compose.yaml <<'EOF'
services:
  uptime-kuma:
    image: louislam/uptime-kuma:2
    restart: unless-stopped
    ports:
      - "127.0.0.1:3001:3001"
    volumes:
      - ./data:/app/data
EOF

docker compose up -d
docker compose ps

Use a tag :2: latest ainda aponta para a branch v1 desatualizada. O diretório /app/data deve ficar em um disco local ou em um volume Docker comum. NFS e sistemas de armazenamento sem bloqueio correto de arquivos podem corromper o banco de dados.

A porta 3001 fica acessível somente em 127.0.0.1. Um proxy reverso com HTTPS publicará o painel externamente.

4. Ative HTTPS com o Caddy

apt install -y caddy

cat > /etc/caddy/Caddyfile <<'EOF'
monitor.example.com {
    reverse_proxy 127.0.0.1:3001
}
EOF

caddy validate --config /etc/caddy/Caddyfile
systemctl reload caddy

Se o DNS apontar para o VPS, o Caddy solicitará automaticamente um certificado TLS e fará o proxy das conexões WebSocket. Hospede o painel na raiz do domínio ou subdomínio: um endereço como example.com/kuma não é compatível.

5. Crie a conta de administrador

Acesse https://monitor.example.com, crie uma conta com uma senha longa e exclusiva e ative a autenticação de dois fatores.

Como adicionar o primeiro monitor

Clique em Add New Monitor e selecione HTTP(s):

Informe um nome e a URL completa.
Defina o intervalo, por exemplo, 60 segundos.
Adicione duas tentativas para lidar com falhas ocasionais de rede.
Selecione um canal de notificação.
Salve o monitor e confirme que as verificações bem-sucedidas começam a aparecer.

Para o site principal, as verificações HTTP e Keyword são úteis. Para uma API, use um endpoint de saúde e JSON Query. Não exponha bancos de dados ou portas administrativas à internet apenas para monitoramento; use uma rede confiável ou VPN.

Exemplo de monitor push para um backup

Depois de criar um monitor Push, adicione sua URL exclusiva ao final do script:

backup-command && \
  curl -fsS "https://monitor.example.com/api/push/SECRET_TOKEN?status=up&msg=backup-ok"

A requisição só é executada depois que o backup termina com sucesso. Trate o token push como uma senha: quem souber a URL poderá enviar um sinal falso.

Como conectar o Telegram

Crie um bot pelo @BotFather, envie uma mensagem para ele e abra Settings → Notifications → Telegram. Informe o Bot Token e o Chat ID, clique em Test e associe o canal aos seus monitores. Para serviços críticos, adicione um segundo canal, como e-mail.

Como criar uma página de status

Em Status Pages, você pode agrupar monitores, mostrar o status atual e o histórico de disponibilidade, associar um domínio e informar manutenções programadas por meio de Maintenance. Não publique endereços IP internos ou URLs técnicas: os clientes precisam apenas de componentes como “Website”, “API”, “Account dashboard” e “Payments”.

Como atualizar e fazer backup do Uptime Kuma

Antes de uma atualização importante, pare o contêiner e salve o diretório de dados:

cd /opt/uptime-kuma
docker compose down

tar -czf /root/uptime-kuma-$(date +%F).tar.gz \
  data compose.yaml

docker compose up -d

Mova o arquivo para outro dispositivo ou armazenamento externo. Uma cópia no mesmo VPS não protege contra a exclusão do servidor ou falha do disco.

Para uma atualização normal:

cd /opt/uptime-kuma
docker compose pull
docker compose up -d --force-recreate

Após a inicialização, verifique docker compose ps, abra o painel e envie uma notificação de teste.

Qual VPS escolher para o Uptime Kuma

Uma instalação pequena precisa apenas de um VPS Linux com 1 vCPU e 1 GB de RAM. A independência é mais importante que o desempenho bruto: o monitor precisa continuar funcionando quando o projeto principal estiver indisponível.

Você pode hospedar o Uptime Kuma em um VPS da tropic.host quando os serviços monitorados estiverem em outra plataforma ou em um nó independente. Ubuntu, Docker e um IP estático permitem iniciar o painel rapidamente, enquanto os recursos podem ser ampliados com o crescimento do número de verificações.

Se a produção já estiver na mesma infraestrutura, escolha outro nó ou adicione um monitor externo. Separar os domínios de falha é mais útil do que acrescentar outro núcleo de CPU.

Erros comuns

Erro	Por que é um problema	Abordagem melhor
O monitoramento roda junto do projeto	Uma falha compartilhada derruba o serviço e as notificações	Use um VPS ou local separado
A porta `3001` está exposta publicamente	O painel fica acessível sem proxy reverso ou HTTPS	Vincule a porta a `127.0.0.1`
Apenas o código de status `200` é verificado	Um erro da aplicação pode parecer sucesso	Adicione Keyword ou JSON Query
A tag `latest` é usada	Ela aponta para a branch v1 desatualizada	Use `louislam/uptime-kuma:2`
O backup fica no mesmo VPS	Ele desaparecerá junto com o servidor	Copie o diretório `data` para outro local

Resumo

O Uptime Kuma transforma um VPS pequeno em seu próprio centro de monitoramento de sites, APIs, DNS, portas, certificados e tarefas em segundo plano. Keyword ajuda a detectar uma página quebrada, JSON Query encontra uma resposta incorreta da API e Push revela um backup ou cron interrompido.

Para uma configuração confiável, hospede o monitoramento separado da produção, feche a porta 3001, ative HTTPS e 2FA e configure dois canais de notificação. Depois, faça um backup externo do diretório de dados e uma verificação independente do próprio Uptime Kuma.

FAQ

O Uptime Kuma é gratuito?

Sim. O projeto é open source e distribuído sob a licença MIT. Você paga apenas pela infraestrutura, pelo domínio e pelos backups externos.

Quanta RAM o Uptime Kuma precisa?

Para uma instalação pequena, 1 GB de RAM é um bom ponto de partida. Para centenas de verificações, retenção longa do histórico ou Browser Engine, reserve 2 GB ou mais.

Posso instalar o Uptime Kuma sem Docker?

Sim, usando Node.js e PM2. No entanto, o Docker Compose costuma ser mais fácil de atualizar, migrar e restaurar em um VPS.

Posso usar o Uptime Kuma sem um domínio?

Tecnicamente, sim — por meio do endereço IP ou de um túnel SSH. Para acesso permanente pela internet, um subdomínio com HTTPS é mais seguro.

O Uptime Kuma mostra o uso de CPU, RAM e disco?

Não como um sistema completo de métricas do servidor. Para monitorar recursos, complemente-o com Prometheus, Netdata, Zabbix ou outra ferramenta especializada.

Voltar ao Blog