Manutenção e incidentes no Uptime Kuma
A manutenção do Uptime Kuma marca um período de intervenção nos monitores selecionados por você. Durante esse período, o app suspende os alertas desses monitores e pode exibir um aviso nas páginas de status escolhidas.
Ficha e sumário da página
- Referência técnica
- Uptime Kuma 2.5.11
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
O período associado aos monitores
A manutenção reúne uma programação de horário e uma seleção de monitores. O Uptime Kuma usa essa associação para identificar os serviços que estão sob intervenção. Você pode programar a atualização de um app sem colocar todos os outros monitores da instância no mesmo estado.
O título e a descrição explicam a intervenção prevista. A configuração também permite selecionar as páginas públicas que exibem a mensagem. Os monitores afetados e as páginas que recebem o aviso são escolhas relacionadas, mas diferentes: uma define o comportamento das verificações, enquanto a outra define onde o cliente lê a comunicação.
Durante o período ativo, o monitor recebe o estado de manutenção. Na implementação da versão 2.5.11, o processamento verifica essa condição no início de cada ciclo. Quando a manutenção está ativa, o heartbeat registra esse estado e o ciclo dispensa a consulta normal de disponibilidade, por isso esse registro não comprova que o serviço respondeu normalmente.
Programação
Define o horário, o fuso e a recorrência.
Monitores
Recebem o estado de manutenção durante a janela ativa.
Notificações
Os alertas desses monitores ficam suspensos nesse período.
Página pública
Exibe a descrição nas páginas selecionadas para o aviso.
Horário, fuso e recorrência
O Uptime Kuma oferece uma janela única para uma intervenção com começo e fim definidos. Esse formato corresponde a uma atualização pontual, como a troca da versão de um app. O horário programado delimita o período de manutenção, mas não executa a atualização nem reinicia o container por você.
As opções recorrentes atendem intervenções repetidas. Você pode usar um intervalo entre execuções ou definir os dias da semana ou do mês. A expressão cron oferece outra forma de descrever essa agenda. Uma manutenção recorrente criada para uma tarefa que deixou de existir continua alterando os monitores até você revisar a programação.
O fuso horário participa da interpretação da agenda. Você pode usar o fuso do servidor ou selecionar outro para a manutenção. A mesma hora escrita com fusos diferentes corresponde a instantes diferentes, portanto o horário comunicado ao cliente precisa ser coerente com a programação configurada.
Também existe ativação e desativação manual. Esse formato atende uma intervenção cuja duração ainda não foi definida, mas exige acompanhamento até o encerramento. Enquanto a manutenção permanece ativa, a ausência de alertas desse monitor corresponde à configuração escolhida, não à confirmação de que o app está disponível.
O fim da janela e a resposta do serviço
O término da manutenção devolve o monitor ao processamento normal das verificações. A resposta seguinte depende do serviço naquele momento. Uma atualização que ultrapassa o horário programado pode produzir um estado de indisponibilidade depois do encerramento da janela.
Você distingue o fim da agenda do fim do trabalho. O Uptime Kuma acompanha a programação e os resultados dos testes, mas não sabe se uma migração de banco terminou ou se uma atualização foi validada no navegador. Essas informações precisam vir da intervenção realizada e das verificações adequadas ao app.
A configuração dos monitores também determina o que é observado na retomada. Um teste TCP pode confirmar que a porta voltou a aceitar conexões enquanto o app ainda apresenta erro numa função. A página Tipos de monitor explica o alcance de cada resultado para evitar essa equivalência.
A mensagem de incidente
O incidente publicado na página de status é um texto sobre uma ocorrência. Você informa o título e o conteúdo por uma sessão autenticada. A implementação associa o registro à página correspondente e guarda as datas de criação e atualização, para que a mensagem continue ligada à ocorrência comunicada.
Esse texto é separado do heartbeat do monitor. Uma falha detectada não produz automaticamente uma explicação sobre a causa. O monitor registra o que conseguiu testar, enquanto você escreve o que confirmou durante a investigação. Uma mensagem precisa pode informar o serviço afetado mesmo antes de a causa estar identificada.
A atualização do incidente permite acrescentar o andamento do reparo. Você pode explicar que o acesso voltou e que ainda está conferindo uma função específica, quando esse for o estado real do trabalho. O texto não precisa prometer um horário de recuperação que ainda não foi confirmado.
O que o cliente consegue interpretar
Uma manutenção comunica uma interrupção prevista e altera o comportamento dos monitores associados. Um incidente comunica uma ocorrência que merece explicação pública. Os dois recursos podem participar do mesmo atendimento, mas cada um registra uma informação diferente sobre o serviço.
Uma intervenção programada pode revelar um erro e durar além da janela inicial. Nesse caso, a mensagem publicada precisa acompanhar a situação real. Manter somente o aviso antigo faria o cliente ler um horário encerrado enquanto o serviço ainda apresenta falha.
O cache da página pública também participa da leitura. A mudança no painel pode levar algum tempo para aparecer na consulta pública, conforme a rota e a atualização do navegador. A página Páginas de status explica essa diferença entre a apresentação pública e o acompanhamento administrativo.
Ao retomar o serviço, você confere a resposta dos monitores e o funcionamento que a intervenção pretendia restaurar. A agenda registra o período planejado, os heartbeats registram os testes e o incidente registra a explicação publicada. A leitura conjunta permite relacionar a interrupção com o que foi observado e comunicado.