Skip to Content
WonderMoney Docs
Alojamento próprio

Monitorização

Confirma que a tua instância está a funcionar e que as tarefas em segundo plano continuam a correr, com um monitor como o Uptime Kuma.

As sincronizações bancárias, as importações, as atualizações de preços e os emails agendados correm no worker, em segundo plano. Se o worker parar, a aplicação continua a abrir, por isso nada no ecrã te avisa. A API tem dois endpoints para vigiar.

Endpoints de saúde

EndpointRespondePara que serve
GET /v1/health200 sempre que o processo da API está a correrVerificações de saúde dos contentores. Nunca consulta a base de dados, por isso uma base de dados lenta não reinicia a API
GET /v1/health/ready200 quando tudo funciona, 503 quando algo falhaMonitores de disponibilidade e alertas

Ambos são públicos e não precisam de chave. /v1/health/ready verifica três coisas, em paralelo e cada uma em até 3 segundos:

VerificaçãoFalha quando
databaseO Postgres não responde a uma consulta simples
queueNão é possível ler a fila de tarefas, ou uma tarefa espera para começar há mais de HEALTH_MAX_JOB_AGE_MINUTES (60 por omissão). Os lotes de emails agendados, que se esvaziam ao longo de algumas horas de propósito, têm mais margem
workerO worker não terminou a sua tarefa de heartbeat, que corre a cada 5 minutos, nos últimos 15 minutos

Uma resposta saudável tem este aspeto:

{
  "status": "ok",
  "checks": {
    "database": { "status": "ok" },
    "queue": { "status": "ok" },
    "worker": { "status": "ok", "lastHeartbeatAt": "2026-11-07T12:00:00.000Z" }
  },
  "version": "1.2.0",
  "commit": "4f1c2e0..."
}

Quando algo falha, status é degraded, a resposta é um 503 e a verificação que falhou indica um reason curto, como timeout, unreachable, backlog ou stale_heartbeat. Os detalhes estão nos registos: docker compose logs api para a verificação, docker compose logs worker para as tarefas.

Logo depois de arrancares os contentores, worker pode falhar durante alguns segundos, até o primeiro heartbeat do worker terminar.

version e commit indicam a versão que o servidor corre. GET /v1/instance também os mostra.

Uptime Kuma

O Uptime Kuma é um monitor que alojas tu próprio e que te pode avisar por email, Telegram, ntfy e muitos outros canais. Adiciona um monitor:

  • Monitor type: HTTP(s) - Keyword
  • URL: https://money.example.com/v1/health/ready (o teu API_URL seguido de /v1/health/ready; numa instalação com um só nome de anfitrião, é o endereço da aplicação web)
  • Keyword: "status":"ok"
  • Heartbeat interval: 60 segundos

Qualquer monitor que verifique um estado 200 funciona da mesma forma. O endpoint guarda a resposta durante 5 segundos e aceita 300 pedidos a cada 15 minutos vindos do mesmo endereço, por isso consulta-o no máximo a cada 30 segundos.

Se o Uptime Kuma correr no mesmo projeto Compose, usa http://api:3001/v1/health/ready.

Contentores

docker compose ps mostra cada contentor como saudável (healthy) ou não (unhealthy). O contentor worker fica unhealthy quando o executor de tarefas parou ou não consegue chegar ao Postgres. Não deteta uma tarefa bloqueada; /v1/health/ready deteta.

On this page