Como Executar Tarefas em Segundo Plano numa Aplicação Web: Filas, Agendadores e Cron

Para executar tarefas em segundo plano numa aplicação web, separe primeiro o trabalho em dois tipos. As tarefas disparadas (enviar um email de boas-vindas, processar um upload) podem ser guardadas numa fila de tarefas, muitas vezes uma tabela na base de dados, e tratadas por um worker com novas tentativas. As tarefas agendadas (um relatório noturno, lembretes de 15 em 15 minutos) precisam de algo que dispare num horário: a funcionalidade de cron do alojamento, ou um agendador externo que chama um endpoint protegido na sua app. Torne sempre as tarefas seguras para correr duas vezes, registe as falhas e nunca dependa de um temporizador dentro de um servidor que pode adormecer ou reiniciar.

Este guia explica as opções, quando se aplica cada uma e como configurá-las com um criador de apps com IA, incluindo em alojamentos que escalam para zero.

O que conta como tarefa em segundo plano

Tudo o que é lento, pouco fiável ou desnecessário para a resposta imediata do utilizador:

• Envio de emails, notificações e recibos
• Redimensionar imagens, transcodificar vídeo, gerar PDFs
• Chamar APIs lentas de terceiros, incluindo modelos de IA em tarefas longas
• Importar ou sincronizar dados de outro sistema
• Limpezas noturnas, relatórios e lembretes

Fazer isto dentro do pedido torna as páginas lentas e frágeis: se o fornecedor de email estiver em baixo, o registo do utilizador falha. Passá-lo para segundo plano significa que o utilizador recebe uma resposta imediata e a tarefa pode ser repetida.

As opções

Não há uma resposta única. Uma app pequena precisa muitas vezes apenas de uma fila em base de dados mais um agendador externo.

Porque é que os alojamentos que escalam para zero mudam o cenário

Muitas plataformas modernas põem a sua app em repouso quando ninguém a usa e acordam-na no pedido seguinte. Isso poupa dinheiro, mas um servidor em repouso não executa código: os temporizadores não disparam e os workers não fazem polling. Nestas plataformas, o trabalho agendado tem de começar com um pedido recebido, e a fonte mais fácil desse pedido é um agendador externo. Cada chamada acorda a app (e muitas vezes a base de dados), por isso chamar a cada minuto custa mais do que chamar a cada 15 minutos. Escolha o horário mais espaçado que satisfaça a necessidade.

Padrão 1: uma fila de tarefas em base de dados

Para tarefas disparadas:

1. Crie uma tabela jobs: tipo, payload (JSON), estado (pending, running, done, failed), tentativas, run_after, last_error, datas.
2. Quando algo acontece, insira uma linha de tarefa na mesma transação da alteração que a causou, para que ambas tenham sucesso ou falhem juntas.
3. Um worker escolhe as tarefas devidas, marca-as como running, faz o trabalho e marca-as como done.
4. Em caso de falha, aumente attempts, defina um run_after mais tarde (por exemplo 1, 5 e depois 30 minutos) e guarde o erro. Ao atingir um máximo, marque-a como failed e alerte alguém.

Se mais do que um worker puder correr em simultâneo, as tarefas têm de ser reclamadas de forma segura. No Postgres, SELECT ... FOR UPDATE SKIP LOCKED permite que cada worker reclame linhas diferentes sem colisões.

O que executa o worker? Num servidor sempre ligado, um ciclo num processo separado. Num alojamento que escala para zero, o endpoint agendado do Padrão 2 pode processar um lote de tarefas devidas em cada chamada.

Padrão 2: um agendador externo a chamar a sua app

Para tarefas agendadas:

1. Acrescente um endpoint como POST /api/cron/send-reminders.
2. Proteja-o: exija um token secreto num cabeçalho, guardado como segredo nos dois lados, e recuse tudo o resto.
3. Torne-o idempotente: correr duas vezes no mesmo minuto não pode enviar dois lembretes. Registe o que já foi enviado.
4. Mantenha cada chamada curta: processe um lote (por exemplo 100 itens) e deixe a chamada seguinte tratar do resto.
5. Aponte um agendador para ele.

Escolhas de agendador:

• Fluxos agendados do GitHub Actions. Gratuitos dentro dos limites de utilização do GitHub. Em setembro de 2026, a documentação do GitHub indica que o intervalo mínimo é de uma vez a cada 5 minutos, que as execuções podem sofrer atrasos em horas de muita carga (sobretudo no início de cada hora), que os agendamentos usam UTC por omissão, e que os fluxos agendados num repositório público são desativados após 60 dias sem atividade no repositório.
• Serviços de cron alojados. Existem muitos serviços cuja única função é chamar um URL segundo um horário. Verifique a fiabilidade, o intervalo mínimo e os alertas antes de depender de um.
• O agendador do seu fornecedor de nuvem. Se já usa um grande fornecedor de nuvem, terá um agendador gerido que pode chamar um endpoint HTTPS.
• Um serviço alojado de tarefas ou fluxos. Combinam agendamento, filas e novas tentativas, e chamam os seus endpoints em cada passo. Compare preços e limites no site de cada fornecedor.

Padrão 3: deixe o fornecedor tratar

Por vezes, a melhor tarefa em segundo plano é nenhuma:

• Pagamentos. A Stripe volta a tentar as cobranças de subscrições falhadas e envia webhooks; você reage em vez de fazer polling. Veja o que é um webhook.
• Email. Os fornecedores põem a entrega em fila e repetem-na depois de lhes entregar a mensagem.
• Trabalho de IA em lote. A OpenAI e a Anthropic oferecem APIs em lote para pedidos não urgentes, que submete e recolhe mais tarde.

Prompts para o seu criador de apps com IA

Para uma fila:

Adiciona uma fila de tarefas em segundo plano usando uma tabela jobs na nossa base de dados (tipo, payload JSON, estado, tentativas, run_after, last_error). Quando um utilizador se regista, insere uma tarefa send_welcome_email na mesma transação, em vez de enviar o email de imediato. Acrescenta uma função processJobs(limit) que reclama as tarefas devidas com SELECT ... FOR UPDATE SKIP LOCKED, as executa e repete as falhas após 1, 5 e 30 minutos, marcando-as como failed após 4 tentativas.

Para um disparo agendado:

Adiciona POST /api/cron/tick protegido por um token bearer do segredo CRON_SECRET; recusa qualquer pedido sem ele. Cada chamada executa processJobs(100) e envia os lembretes de marcações previstos para as próximas 24 horas que ainda não foram enviados, registando os lembretes enviados para que nada seja enviado duas vezes. Devolve um resumo JSON do que correu. Depois escreve um fluxo do GitHub Actions que chame este endpoint a cada 15 minutos, lendo o URL e o token dos segredos do repositório.

Erros comuns

• Confiar no setInterval. Para em silêncio quando o servidor adormece ou reinicia, e duplica-se quando correm duas cópias.
• Um endpoint de cron sem proteção. Qualquer pessoa que o encontre pode disparar as suas tarefas, ou a sua fatura de email.
• Tarefas que não são idempotentes. As novas tentativas e as chamadas duplicadas do agendador vão acontecer. Desenhe para isso.
• Falhas sem visibilidade. Uma tarefa que falha em silêncio durante uma semana é pior do que uma que falha de forma ruidosa. Registe os erros e alerte em falhas repetidas.
• Execuções longas num só pedido. Os pedidos expiram. Processe em lotes.
• Agendar com demasiada frequência. Cada chamada num alojamento que escala para zero acorda e fatura a app. Ajuste o intervalo à necessidade real.
• Fusos horários. "9h" significa coisas diferentes para o seu agendador (muitas vezes UTC) e para os utilizadores. Guarde as horas em UTC e converta por utilizador.
• Segredos no ficheiro do fluxo. Guarde os tokens no cofre de segredos do agendador. Veja como manter as chaves de API seguras.

Lista de verificação

• Trabalho lento retirado dos pedidos dos utilizadores
• Tarefas guardadas de forma durável, e não apenas em memória
• Novas tentativas com atrasos crescentes e um máximo
• Cada tarefa segura para correr duas vezes
• Endpoint agendado protegido por um token secreto
• Cada execução processa um lote limitado
• Tarefas falhadas visíveis, com alertas
• Intervalo de agendamento escolhido tendo em conta o custo de alojamento
• Horas guardadas em UTC

Tarefas em segundo plano no Mythex

A documentação do Mythex não descreve tarefas agendadas ou cron, e as apps publicadas e as suas bases de dados entram em repouso quando estão inativas e acordam no pedido seguinte (veja Limites de alojamento). Por isso, não dependa de temporizadores dentro da app. A abordagem que funciona é a descrita acima: peça ao agente uma tabela de tarefas e um endpoint protegido por token, e depois aponte um agendador externo para o URL publicado. Guarde o token como segredo do projeto, e lembre-se de que cada acordar gasta créditos pelo tempo em que a app e a base de dados estiveram ativas, por isso escolha um intervalo sensato. Se a sua app precisar de um backend de API para isto, a receita Backend de API REST é um bom ponto de partida, e como criar uma API REST explica como desenhar os endpoints. Se o núcleo do seu produto forem processos permanentes, como workers ou bots, uma plataforma feita para processos persistentes pode ser mais adequada.

Perguntas