O Uptime Kuma é um monitor open source e auto-hospedado para verificações HTTP(S), TCP, ping, DNS, WebSocket e outras. Num VPS separado, continua a verificar quando o seu servidor de produção falha, em vez de desaparecer com ele.
Esta configuração do Uptime Kuma num VPS instala a v2 com Docker Compose, mantém a porta 3001 em loopback, acrescenta HTTPS através do Caddy, encaminha os alertas para o Telegram, Discord e Slack e publica uma página de estado.
Pré-requisitos e o que vai precisar
- Um VPS com pelo menos 1 vCPU, 1 GB de RAM e 10 GB de armazenamento SSD local
- Ubuntu 24.04 LTS ou outra versão atual do Ubuntu suportada pelo Docker
- Docker Engine e Docker Compose instalados no VPS
- Um domínio ou subdomínio a apontar para o VPS através de um registo A (algo como status.example.com)
- Acesso SSH e à-vontade básico com a linha de comandos
Se ainda não tiver o Docker instalado, siga o guia de instalação do Docker para Ubuntu. Instala o Docker Engine e o plugin Compose usado mais abaixo.
Porque é que o VPS de monitorização tem de estar separado do que vigia
A produção e a monitorização no mesmo servidor partilham o mesmo domínio de falha. Se esse servidor parar, desaparecem ao mesmo tempo a aplicação e o sistema responsável por enviar o alerta.
Duas disposições práticas melhoram isto:
- Mesmo fornecedor, localização diferente. Coloque a produção e a monitorização em hosts separados, em localizações diferentes. Isto reduz a exposição a uma falha de um único servidor ou de um único datacenter, mas não protege contra todos os incidentes de rede ou de plano de controlo que afetem o fornecedor inteiro.
- Um fornecedor completamente diferente. Alojar o monitor noutro sítio acrescenta proteção contra incidentes que afetem o fornecedor inteiro. Em troca, fica com mais uma conta, mais uma fatura e mais uma superfície operacional para gerir.
Uma única instância do Uptime Kuma continua sem vigilância exterior. Acrescente uma verificação HTTP(S) externa à sua página de estado pública. O plano gratuito do UptimeRobot inclui atualmente 50 monitores com intervalos de cinco minutos. Isto não torna o Uptime Kuma de alta disponibilidade, mas avisa-o quando o próprio monitor desaparece.
A mesma regra vale para as páginas de estado públicas: aquilo que lhe conta sobre a falha não pode partilhar o domínio de falha com aquilo que falha.
Construa num VPS Linux com acesso root, NVMe e o poder do AMD EPYC.
Ver planos LinuxDimensionar o VPS
O Uptime Kuma não tem uma fórmula fiável entre número de monitores e RAM, porque a carga muda com o tipo de monitor, o intervalo, as definições de repetição e a retenção do histórico. Verificações simples de HTTP(S), TCP, ping e DNS são mais leves do que as verificações Browser Engine, que executam o Chromium.
Para um conjunto pequeno de verificações básicas, comece com 1 vCPU, 1 GB de RAM e armazenamento SSD local. Acompanhe o uso real com docker stats uptime-kuma e o crescimento da base de dados com du -sh /opt/uptime-kuma/data. Acrescente memória quando o uso se mantiver alto, quando o contentor reportar um OOM kill, ou quando começar a usar verificações Browser Engine.
A imagem v2 completa inclui o Chromium e um MariaDB integrado; a documentação das tags do Docker explica a diferença entre as imagens full e slim.
Instalar o Uptime Kuma com Docker Compose
Guarde este ficheiro como docker-compose.yml em /opt/uptime-kuma/:
services:
uptime-kuma:
image: louislam/uptime-kuma:2
container_name: uptime-kuma
restart: unless-stopped
ports:
# Bind to localhost only. The reverse proxy will expose it on 443.
- "127.0.0.1:3001:3001"
volumes:
- ./data:/app/data
Três linhas merecem destaque:
- image: louislam/uptime-kuma:2 fixa a versão principal. A tag :2 segue a linha estável 2.x. Não use :latest.
- 127.0.0.1:3001:3001 liga o contentor apenas ao localhost. A internet pública nunca deve chegar diretamente à porta 3001. É o proxy inverso que detém o certificado TLS e o nome de host público.
- O volume de dados guarda a base de dados, a configuração dos monitores e o histórico. Mantenha-o em armazenamento local, porque a documentação de instalação do Uptime Kuma avisa que sistemas de ficheiros sem bloqueio POSIX fiável, incluindo muitas configurações NFS, podem corromper o SQLite. Pare a stack antes de fazer uma cópia ao nível do sistema de ficheiros.
Coloque-o a correr e verifique:
sudo install -d -o "$USER" -g "$USER" /opt/uptime-kuma
cd /opt/uptime-kuma
# Paste the docker-compose.yml file above.
sudo docker compose up -d
sudo docker compose ps
Saída esperada de docker compose ps:
NAME IMAGE STATUS PORTS
uptime-kuma louislam/uptime-kuma:2 Up (healthy) 127.0.0.1:3001->3001/tcp
Para chegar ao painel pela primeira vez, não abra a porta 3001 à internet, nem por instantes. Use um túnel SSH:
ssh -L 3001:127.0.0.1:3001 [email protected]
Abra http://localhost:3001 no navegador, crie a conta de administrador, defina uma palavra-passe forte e feche o túnel. A partir daqui o painel chega-lhe por HTTPS através do proxy inverso.
Se não precisa de fazer o Compose à mão, também oferecemos o Uptime Kuma como aplicação de um clique. A página atual da aplicação indica a v1, pelo que não corresponde à instalação v2 deste guia. Siga o caminho manual com Compose se precisar mesmo da v2.
Proxy inverso e TLS
Não exponha o Uptime Kuma diretamente. Coloque um proxy inverso à frente para tratar do TLS, do encaminhamento correto dos URL e de um único ponto de entrada público. Dois caminhos.
Caddy. Se o Caddy ainda não estiver instalado, siga os passos oficiais do pacote para Ubuntu. Com o Caddy a correr como serviço do host, o Caddyfile abaixo encaminha para o Uptime Kuma em loopback e trata da emissão e renovação do certificado automaticamente.
Dica: quando o VPS de monitorização só aloja o Uptime Kuma, use o Caddy. O Caddyfile tem três linhas e o Caddy trata sozinho da emissão e renovação do certificado. Sem Certbot e sem um temporizador de renovação à parte para vigiar às 4 da manhã.
Guarde isto como /etc/caddy/Caddyfile:
status.example.com {
reverse_proxy 127.0.0.1:3001
}
Recarregue o Caddy:
sudo systemctl reload caddy
Verifique:
curl -I https://status.example.com
Deve receber uma resposta 2xx ou 3xx bem-sucedida com um certificado válido. Se a ligação falhar, confirme que o registo A ou AAAA do domínio aponta para este VPS, que as portas 80 e 443 estão acessíveis e que o Caddy consegue ligar-se a ambas. Isto faz parte dos requisitos de HTTPS automático do Caddy.
Nginx Proxy Manager. Se o NPM correr diretamente no host, acrescente um Proxy Host para status.example.com, encaminhe-o para 127.0.0.1 na porta 3001, peça um certificado Let's Encrypt e ative o Websockets Support. Se o NPM correr em Docker, 127.0.0.1 aponta para o próprio contentor do NPM. Nesse caso, ligue o NPM e o Uptime Kuma à mesma rede Docker e encaminhe o proxy host para uptime-kuma na porta 3001.
Encaminhamento de notificações: Telegram, Discord, Slack
O Uptime Kuma consegue encaminhar o mesmo evento de monitor para vários canais de notificação. Configure cada fornecedor uma vez e depois associe um ou mais canais a um monitor consoante quem precisa do alerta.
As notificações configuram-se globalmente em Definições > Notificações e depois atribuem-se a cada monitor. Cada monitor pode disparar um ou vários canais. O mesmo alerta pode chegar ao Telegram do engenheiro de piquete, ao Slack da equipa e ao email para o registo de auditoria, tudo a partir de um único evento.
Telegram
- No Telegram, envie mensagem a @BotFather e execute /newbot. Escolha um nome e um nome de utilizador. O BotFather responde com um token de bot. Guarde-o.
- Envie qualquer mensagem ao seu novo bot. Depois abra https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates num navegador. Procure o campo chat.id: é esse o seu ID de chat.
- No Uptime Kuma: Definições > Notificações > Configurar notificação > Telegram. Cole o token do bot e o ID de chat. Clique em Teste. Confirme que o bot envia o alerta de teste.
- Se a mensagem de teste não chegar, verifique se o token do bot e o ID de chat estão corretos e confirme que a firewall do VPS permite HTTPS de saída para api.telegram.org.
Discord
- Abra o servidor de Discord onde quer os alertas. Clique com o botão direito no canal pretendido e depois Editar canal > Integrações > Webhooks > Novo webhook. Dê-lhe um nome (algo como «Uptime Kuma»), escolha o canal e copie o URL do webhook.
- No Uptime Kuma: Definições > Notificações > Configurar notificação > Discord. Cole o URL do webhook. Opcionalmente, defina também o nome de utilizador e o avatar.
- Clique Teste. Confirme que o webhook publica o alerta de teste no canal.
Slack
- No Slack, crie um Incoming Webhook para o canal onde quer os alertas. O Slack devolve um URL de webhook com o formato https://hooks.slack.com/services/T.../B.../....
- No Uptime Kuma: Definições > Notificações > Configurar notificação > Slack. Cole o URL do webhook. Opcionalmente, configure também o ícone e a substituição de canal.
- Clique Teste.
Assim que todos os testes passarem, edite cada monitor e selecione os canais de notificação que deve usar. Defina Max Retries (tentativas máximas) e Retry Interval (intervalo entre tentativas) de forma a que uma falha breve não dispare logo um alerta.
A página de estado integrada (e quando lhe ficará curta)
O Uptime Kuma inclui páginas de estado públicas com slugs personalizados, monitores agrupados, domínios próprios, publicações de incidentes e mensagens de manutenção agendada. Também pode publicar várias páginas de estado a partir de uma só instância, para serviços ou públicos diferentes.
A limitação maior está na comunicação com os clientes. Neste momento os visitantes não conseguem subscrever atualizações por email diretamente a partir de uma página de estado, e essa página pública continua a fazer parte da mesma aplicação Uptime Kuma do painel do operador. A auto-subscrição dos visitantes continua registada como um pedido de funcionalidade em aberto.
Se precisar de subscrições de clientes ou de um sistema de estado separado do painel de monitorização, o Kener é uma alternativa. O nosso artigo sobre a stack de monitorização auto-hospedada explica como as duas ferramentas se podem combinar.
Problemas comuns
As notificações falham em silêncio quando a firewall do VPS bloqueia o HTTPS de saída. Sintoma: o botão Test funciona nuns canais e noutros não. Correção: confirme que as ligações HTTPS de saída são permitidas e que curl -I https://api.telegram.org tem êxito a partir do VPS.
O navegador mostra «ERR_TOO_MANY_REDIRECTS» depois de ativar o proxy. Procure redirecionamentos duplicados de HTTP para HTTPS no Caddy, no Nginx Proxy Manager ou num CDN à frente. O Uptime Kuma deve continuar a servir HTTP na porta 3001 enquanto o proxy inverso público termina o TLS. Se ativar os cabeçalhos de proxy fidedigno, o caminho atual é Definições > Reverse Proxy > Cabeçalhos HTTP > Trust Proxy.
O contentor reinicia de poucos em poucos minutos. Verifique se o contentor foi terminado por falta de memória e depois acompanhe o consumo atual com docker stats uptime-kuma. Se o contentor levou OOM kill ou a memória se mantém perto do limite do VPS, acrescente RAM, reduza as verificações pesadas ou aumente os respetivos intervalos.
A página de estado funciona em localhost mas não através do nome de host público. Confirme que o proxy inverso encaminha o caminho raiz sem alterações, preserva o cabeçalho Host e suporta WebSockets. O Uptime Kuma não suporta instalação num subdiretório, por isso use um domínio ou subdomínio dedicado em vez de um caminho como example.com/uptime-kuma.
Para terminar
O Uptime Kuma num VPS separado dá-lhe controlo sobre as verificações, o encaminhamento dos alertas e a página de estado pública, mas também fica com as atualizações, as cópias de segurança, os patches do sistema e a vigilância externa do próprio monitor. Escolha um VPS numa localização diferente da produção, instale a v2 com Docker Compose ou use a aplicação de um clique depois de confirmar a versão indicada, ponha o Caddy à frente e ligue os canais que a sua equipa realmente acompanha.
Perguntas frequentes
De quanta RAM precisa o Uptime Kuma?
O Uptime Kuma não tem uma fórmula fiável entre número de monitores e RAM, porque o consumo muda com o tipo de monitor, o intervalo de verificação, as definições de repetição, a retenção do histórico e o uso do Browser Engine. Para um conjunto pequeno de verificações básicas, comece com 1 GB de RAM e acompanhe o consumo real com docker stats uptime-kuma. Acrescente memória se o consumo se mantiver perto do limite ou se o contentor levar OOM kill.
Devo correr o Uptime Kuma no mesmo servidor da minha aplicação?
Não. Se a ferramenta de monitorização e a aplicação partilharem servidor, uma falha põe as duas offline ao mesmo tempo e perde os alertas justamente quando mais precisa deles. Corra o Uptime Kuma num VPS separado, de preferência noutro datacenter.
O Uptime Kuma consegue enviar alertas para o Telegram, Discord e Slack?
Sim. O Telegram, o Discord e o Slack são serviços de notificação integrados, a par do email, dos webhooks genéricos, do PagerDuty, do ntfy, do Mattermost e de muitos outros. O Telegram usa um token de bot e um ID de chat, enquanto o Discord e o Slack usam URL de webhook. Pode associar vários canais de notificação ao mesmo monitor.
Qual é a diferença entre o Uptime Kuma e o UptimeRobot?
O Uptime Kuma é auto-hospedado, por isso é você que gere o servidor, as atualizações, as cópias de segurança e o encaminhamento dos alertas. Suporta intervalos de verificação até 20 segundos. O UptimeRobot é SaaS alojado, e o seu plano gratuito atual inclui 50 monitores com verificações de cinco em cinco minutos. Escolha o Uptime Kuma se quiser controlo, ou o UptimeRobot se não quiser operar o servidor de monitorização.
O Uptime Kuma tem uma página de estado pública?
Sim. Pode escolher que monitores ficam visíveis, agrupá-los, publicar várias páginas de estado, associá-las a domínios próprios e agendar mensagens de manutenção. A auto-subscrição por email dos visitantes não vem incluída, por isso use uma ferramenta de páginas de estado voltada para clientes quando estes precisarem de subscrever atualizações.
