# Workers em segundo plano e cron: quando rodar um consumidor e quando agendar um comando

Passo a passo: adicione um serviço Worker para um consumidor de fila que fica no ar, ou um job na aba Jobs para um cron que sai. Os dois exigem Pro.

Canonical URL: https://unbroker.cloud/pt/blog/background-workers-cron-jobs
Published: 2026-11-08
Reviewed: 2026-11-16
Author: Timoteo Borgobello

## A resposta curta

São três execuções, e nenhuma substitui as outras.

Um worker é um processo sem HTTP de entrada. Ele fica no ar e consome uma fila durável. Um job agendado é um comando com cron: nome, cron, comando e fuso, e cada execução fica em **Executions**. Um comando avulso roda uma vez, com a imagem e as variáveis daquele serviço.

A fila não é o worker. Um script que processa um item e sai é um job agendado ou um comando avulso, não um worker. Serviços Worker, comandos avulsos e jobs agendados exigem Pro. A landing é [workers em segundo plano](https://unbroker.cloud/solutions/background-worker). As linhas estão em [Plans](https://docs.unbroker.cloud/billing/plans).

## Três formas de rodar trabalho que não é um request HTTP

| | Worker | Job agendado | Comando avulso |
| --- | --- | --- | --- |
| O que é | Um processo longo, sem HTTP de entrada | Um comando com uma expressão cron | Um comando, uma vez |
| Quando cabe | E-mails, uploads, indexação, um consumidor que espera | Um script que começa, faz o trabalho e sai num horário | Manutenção que você roda uma vez |
| O que fica no ar | O processo, enquanto espera trabalho | Nada entre execuções | Nada depois da execução |
| O que dispara | O comando de start do serviço | O horário, ou uma execução manual em Jobs | Você, pela aba Jobs ou pela API |
| Plano | Pro. Não está no Free | Pro. Não está no Free | Pro. Não está no Free |

O guia do worker marca o corte: um comando de start como `node worker.mjs` precisa ficar no ar enquanto espera. Um script que processa um item e sai usa um fluxo agendado ou avulso. O guia é [Deploy a background worker](https://docs.unbroker.cloud/guides/background-worker).

## Quando você precisa de um worker em segundo plano

Escolha um worker quando o processo consome jobs e não atende HTTP. Enviar e-mail, processar uploads e indexar são os exemplos desse guia.

No Cloud, adicione um serviço e escolha a categoria **Worker**. Conecte o repositório, revise o comando de build e defina o comando de start. Coloque as credenciais da fila e as variáveis do banco na configuração de runtime. Como essas variáveis são agrupadas está em [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets).

Não crie um serviço web público só para um processo sem listener passar num health check HTTP. Esse modo de falha está em [Depurar um deploy que falhou](https://unbroker.cloud/pt/blog/debug-failed-deployment). Como um arquivo Compose se reparte num worker está em [Docker Compose em produção](https://unbroker.cloud/pt/blog/docker-compose-to-production).

Para um build de contêiner, escolha **Dockerfile** em **Build & deploy** e informe um caminho relativo ao diretório raiz. `ENTRYPOINT` ou `CMD` sobe o worker. Deixe o diretório raiz vazio quando o Dockerfile precisa do repositório inteiro como contexto de build. Workers com Dockerfile ainda rodam sem URL pública, sem serviço de entrada e sem sonda de readiness HTTP.

Faça o deploy e leia o log de runtime. Enfileire um job de teste que não seja de produção e acompanhe até um resultado durável. Um processo no ar não prova que conseguiu autenticar na fila ou terminar o trabalho.

No shutdown, pare de pegar jobs novos, termine ou solte o que está em andamento, e feche as conexões com a fila e com o banco. Use uma idempotency key quando uma segunda execução cobraria, enviaria ou escreveria duas vezes. Mande falhas repetidas para o dead-letter da fila, ou para outro registro durável de falha. Registre IDs de job e categorias de erro, não payloads com dados privados.

Acompanhe a idade da fila, o backlog e os jobs concluídos, junto com CPU e memória. Uma CPU quieta pode ser falta de trabalho, ou o worker ter perdido a conexão com a fila. Os workers rodam uma réplica, então a concorrência fica dentro do consumidor, no orçamento de memória e nos limites dos sistemas que ele chama. Logs da plataforma e gráficos de recursos estão em [Logs, métricas e alertas](https://unbroker.cloud/pt/blog/logs-metrics-alerts).

A API HTTP que enfileira o trabalho pode ficar no mesmo projeto. Essa forma está em [API com PostgreSQL](https://unbroker.cloud/solutions/api-with-postgres). Um trabalho que precisa sobreviver a um restart não fica no processo web. Numa app FastAPI, o corte entre `BackgroundTasks` e um worker está em [FastAPI em produção](https://unbroker.cloud/pt/blog/fastapi-in-production).

## A fila não é o worker

A Unbroker roda o consumidor. Acknowledgement, retry e visibility timeout são da biblioteca de fila que você roda. Um loop sobre um array em memória não é entrega durável.

O check local do guia é concreto. Enfileire um job com um ID da aplicação. Confirme só depois do sucesso. Interrompa o processamento e verifique que a fila consegue reentregar o trabalho que não foi confirmado. Repita o mesmo job e verifique que ele não duplica um pagamento, um e-mail ou outro efeito sensível.

O Redis pode ser essa fila. Cache, sessões e filas são outra decisão: [Redis gerenciado](https://unbroker.cloud/pt/blog/managed-redis-cache-queues).

O Beacon é mensagem em tempo real. Ele entrega no máximo uma vez. Mensagens publicadas enquanto um cliente está desconectado não são reenviadas. Para um trabalho que precisa rodar exatamente uma vez, use uma fila durável. O Beacon pode avisar um cliente depois que esse resultado foi gravado. A nota é [Beacon reliability](https://docs.unbroker.cloud/beacon/reliability).

## Quando um cron cabe melhor

Use um job agendado quando o programa começa, faz o trabalho e sai. Um rebuild noturno, um relatório ou uma limpeza que não está esperando uma fila cabem aqui. O horário não substitui uma fila durável, e o worker não substitui o horário.

Cada serviço tem uma aba **Jobs**. Um job agendado tem um nome, uma expressão cron, um comando e um fuso. A saída de cada execução fica em **Executions**. A aba pode disparar um job salvo. A nota de release é o [changelog de 1 de agosto](https://unbroker.cloud/changelog/2026-08-01-jobs-terminal-pre-deploy).

Os comandos exigem que o serviço esteja rodando. A aba Jobs diz para iniciar o serviço antes de executar comandos. A [página de migração do Heroku](https://unbroker.cloud/pt/migrar/heroku) diz a mesma regra para jobs agendados, e diz que as entradas do Scheduler não são importadas. O mapa de uma linha `worker` do Procfile, do processo release e de uma entrada do Scheduler está em [Procfile do Heroku, linha a linha](https://unbroker.cloud/pt/blog/heroku-procfile-to-services).

A API HTTP documentada, em [Infrastructure API](https://docs.unbroker.cloud/api/infrastructure):

- `GET` e `POST /apps/services/:id/jobs` listam ou criam jobs.
- `PUT` e `DELETE /apps/services/:id/jobs/:jobId` atualizam ou apagam um.
- `POST /apps/services/:id/jobs/:jobId/run` roda um job agora.

As páginas publicadas do `ubctl` não documentam um comando de jobs. `ubctl apps backups schedule` aceita `--cron` para um backup de volume. Esse horário não é a aba Jobs. A referência é [Storage commands](https://docs.unbroker.cloud/cli/storage).

A documentação não diz quanto uma execução agendada pode durar, nem o que acontece se duas execuções se sobrepõem. Esta página não acrescenta nenhuma das duas regras.

## Comandos avulsos para manutenção

Um comando avulso roda uma vez, com a imagem e as variáveis do serviço. Na aba Jobs o painel se chama **One-off command**, com um campo de comando e um botão **Run**. A API é `POST /apps/services/:id/commands`. Vale a mesma regra do serviço rodando.

Em 8 de outubro de 2026 o terminal interativo do navegador foi removido. Comandos avulsos e jobs agendados continuaram. Uma execução manual cria um evento de activity com a pessoa que lançou e o serviço. O texto do comando fica no registro da execução. Ele não é copiado para o feed de activity de toda a organização. A nota é [comandos auditados](https://unbroker.cloud/changelog/2026-10-08-audited-commands).

Use um comando avulso para uma manutenção que você quer uma vez. Use um job agendado quando esse comando precisa se repetir. Use o comando pre-deploy quando uma migração precisa terminar antes de a versão nova ir ao ar. Esse passo de release está em [Migrações de banco no deploy](https://unbroker.cloud/pt/blog/database-migrations-on-deploy).

## O que não misturar com isso

Um comando pre-deploy roda uma vez a partir da imagem nova, antes de essa versão ir ao ar. Rollbacks não rodam esse comando de novo. O exemplo do changelog é `npm run db:migrate`. Comandos de migração exigem Pro. A documentação não diz o que um pre-deploy que falhou faz com a versão que já está no ar.

Um comando post-deploy é outro gancho. Ele roda depois que o deployment está live, numa cópia avulsa da imagem nova, com as variáveis daquele serviço, por no máximo 10 minutos. A saída é acrescentada ao log do deployment. Se o comando falha, o deployment continua `live` e nada é revertido. O comando não roda quando o próprio deploy falha. Ele não monta um volume persistente. Coloque segredos em variáveis, não no texto do comando. O changelog de 26 de outubro diz que comandos post-deploy exigem um plano pago e não estão disponíveis para serviços de imagem.

Esse limite de 10 minutos é o comando post-deploy. A documentação não o declara para um job agendado nem para um comando avulso na aba Jobs. As fontes são [Deployments](https://docs.unbroker.cloud/cli/deployments) e o [changelog de 26 de outubro](https://unbroker.cloud/changelog/2026-10-26-post-deploy-command).

O Beacon não é a fila. **Serverless** não é um jeito de rodar um worker. Serverless reduz a zero um contêiner HTTP ocioso e o acorda no próximo request. Ele suporta serviços HTTP de repositório público e de upload estático, com uma réplica fixa. Imagens, workers, builds com Dockerfile, volumes persistentes, rede privada e autoscaling não são suportados. A seção é [Service types](https://docs.unbroker.cloud/apps/services#serverless).

## Como isso funciona na Unbroker

<aside class="plan-box">
<p><strong>Na Unbroker.</strong> Adicione um serviço na categoria Worker. Ele roda uma réplica, não tem URL pública e não pode ser marcado como privado. Workers com Dockerfile não têm sonda de readiness HTTP. Jobs agendados e comandos avulsos ficam na aba Jobs de cada serviço. Workers, comandos avulsos e jobs agendados exigem Pro. Serverless não se aplica a workers.</p>
</aside>

[Tipos de serviço](https://docs.unbroker.cloud/apps/services) descreve um worker como um processo sem tráfego HTTP de entrada, útil para filas, processamento agendado, indexação e jobs assíncronos. O guia do worker ainda traça o limite: um script que processa um item e sai é um job agendado ou avulso, não esse processo longo. Um worker já não tem Service nem URL pública, então não pode ser marcado como privado.

Serviços de imagem, workers e qualquer serviço com volume persistente rodam sempre uma réplica. Serviços de repositório e de upload são os que podem rodar várias réplicas, inclusive autoscaling. Esse controle está em [Autoscaling de réplicas](https://unbroker.cloud/pt/blog/replica-autoscaling). Ele não acrescenta uma segunda réplica a um worker.

O Pro custa $25 por mês, com $25 de crédito de uso. O crédito reinicia a cada ciclo de cobrança, não acumula e não tem valor em dinheiro. Se o uso elegível fica abaixo do crédito, a cobrança do mês continua sendo o preço do plano. O runtime do worker, e a fila ou o banco, entram cada um no uso. A página de planos não publica um preço separado para um worker. No Pro, os limites de CPU e memória são configuráveis. As linhas atuais estão em [preços](https://unbroker.cloud/pt/precos) e em [Plans](https://docs.unbroker.cloud/billing/plans). As mesmas linhas de capacidade aparecem como Contract no Enterprise, que é um acordo separado.

Não há um comando `ubctl` documentado para esses jobs. As rotas HTTP acima são a automação documentada. Criar um token de API exige Pro. O que um token pode fazer começa em [Agentes de código](https://unbroker.cloud/agents).

## Checklist

1. Use um worker quando o processo precisa ficar no ar e consumir uma fila durável.
2. Use um job agendado quando o script começa, faz o trabalho e sai.
3. Use um comando avulso para uma manutenção, com a imagem e as variáveis do serviço.
4. Deixe a fila fora do worker. Use o acknowledgement, o retry e o dead-letter dessa biblioteca.
5. Coloque as credenciais da fila em variáveis de runtime, não no texto do comando.
6. Não crie um serviço web público só para um worker passar num health check HTTP.
7. No shutdown, pare de pegar jobs, termine ou solte o que está em andamento, e feche as conexões.
8. Registre IDs e categorias de erro. Deixe payloads privados fora do log.
9. Use o Pro para workers, comandos avulsos e jobs agendados. Deixe o Serverless fora do worker.

## Perguntas frequentes

### Como rodar um worker em segundo plano num PaaS?

Na Unbroker, adicione um serviço e selecione a categoria Worker. Conecte o repositório, revise o comando de build e defina um comando de start que permanece no ar, por exemplo `node worker.mjs`. As credenciais da fila entram na configuração de runtime. Faça o deploy e acompanhe um job de teste no log de runtime. Um worker é um processo sem HTTP de entrada; fica no ar e consome uma fila durável. Serviços Worker exigem Pro e rodam uma réplica. Um script que processa um item e sai é um job agendado ou um comando avulso, não um worker. A fonte é o [guia do worker](https://docs.unbroker.cloud/guides/background-worker).

### Qual é a diferença entre um worker em segundo plano e um cron job?

Um worker é um processo longo, sem HTTP de entrada. O comando de start fica no ar e consome uma fila, por exemplo node worker.mjs. Um job agendado é um comando com nome, uma expressão cron e um fuso, na aba Jobs. A saída de cada execução fica em Executions. Um script que processa um item e sai é um job agendado ou um comando avulso, não um worker. A fonte é o [guia do worker](https://docs.unbroker.cloud/guides/background-worker).

### A Unbroker tem um equivalente do Heroku Scheduler?

A [página de migração do Heroku](https://unbroker.cloud/pt/migrar/heroku) chama os scheduled jobs de equivalente mais próximo do Heroku Scheduler: um comando com nome, uma expressão cron e um fuso, num serviço que está rodando. As entradas do Scheduler não são importadas. Comandos avulsos ficam separados, e não são uma agenda. Esta página não compara preços.

### Serviços Worker exigem Pro?

Sim. A tabela de planos lista serviços Worker como indisponíveis no Free e disponíveis no Pro. O Pro custa $25 por mês, com $25 de crédito de uso. O crédito reinicia a cada ciclo e não acumula. Se o uso elegível fica abaixo do crédito, a cobrança do mês continua sendo o preço do plano.

### Quantas réplicas um worker pode rodar?

Uma. Tipos de serviço diz que serviços de imagem, workers e qualquer serviço com volume persistente rodam sempre uma réplica. A concorrência fica dentro do consumidor, no orçamento de memória dele e nos limites do que ele chama.

### Posso dar a um worker uma URL pública ou um health check HTTP?

Não. Um worker não pode ser marcado como privado, porque já não tem Service nem URL pública. Workers com Dockerfile rodam sem URL pública, sem serviço de entrada e sem sonda de readiness HTTP. Não crie um serviço web público só para um processo sem listener passar num health check HTTP.

### A fila fica dentro do processo do worker?

Não. O worker e a fila durável são peças separadas. Acknowledgement, retry, visibility timeout e dead-letter são da biblioteca de fila que você roda. Um loop sobre um array em memória não é entrega durável. O Redis pode ser a fila. O Beacon não.

### Como rodar um job agendado na Unbroker?

Abra a aba Jobs do serviço. Um job agendado tem um nome, uma expressão cron, um comando e um fuso. A saída fica em Executions. A aba pode disparar um job salvo enquanto o serviço está rodando. A API HTTP lista e cria jobs em GET e POST /apps/services/:id/jobs, atualiza ou apaga um em PUT e DELETE /apps/services/:id/jobs/:jobId, e roda um agora em POST /apps/services/:id/jobs/:jobId/run. As páginas publicadas do ubctl não documentam um comando de jobs.

### O que aconteceu com o terminal interativo do navegador?

Ele foi removido em 8 de outubro de 2026. Comandos avulsos e jobs agendados continuam. Uma execução manual cria um evento de activity com a pessoa que lançou e o serviço. O texto do comando fica no registro da execução. Ele não é copiado para o feed de activity de toda a organização.

### Comandos avulsos e jobs agendados estão no Free?

Não. A tabela de planos lista comandos avulsos e jobs agendados como indisponíveis no Free e disponíveis no Pro. A mesma tabela lista serviços Worker como indisponíveis no Free.

### O Beacon é uma fila de jobs?

Não. O Beacon entrega mensagens em tempo real no máximo uma vez. Mensagens publicadas enquanto um cliente está desconectado não são reenviadas. Para um trabalho que precisa rodar exatamente uma vez, use uma fila durável. O Beacon pode avisar um cliente depois que esse resultado foi gravado.

### Devo rodar o cron dentro do processo web?

Um comando que começa, faz o trabalho e sai fica na aba Jobs, como job agendado ou como comando avulso. Um processo que fica no ar e consome uma fila fica num worker. Um timer dentro do processo HTTP não é nenhuma dessas execuções documentadas. A documentação não diz o que acontece se duas execuções agendadas se cruzam, então esta página também não diz.

## Related reading

- [Workers em segundo plano](https://unbroker.cloud/solutions/background-worker)
- [Redis gerenciado](https://unbroker.cloud/pt/blog/managed-redis-cache-queues)
- [Migrações de banco no deploy](https://unbroker.cloud/pt/blog/database-migrations-on-deploy)
- [Logs, métricas e alertas](https://unbroker.cloud/pt/blog/logs-metrics-alerts)
- [Variáveis de ambiente e segredos](https://unbroker.cloud/pt/blog/environment-variables-and-secrets)
- [Docker Compose em produção](https://unbroker.cloud/pt/blog/docker-compose-to-production)
- [FastAPI em produção](https://unbroker.cloud/pt/blog/fastapi-in-production)
- [Autoscaling de réplicas](https://unbroker.cloud/pt/blog/replica-autoscaling)
- [Preços](https://unbroker.cloud/pt/precos)
- [Procfile do Heroku, linha a linha](https://unbroker.cloud/pt/blog/heroku-procfile-to-services)
