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. As linhas estão em 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.
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.
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. Como um arquivo Compose se reparte num worker está em Docker Compose em produção.
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.
A API HTTP que enfileira o trabalho pode ficar no mesmo projeto. Essa forma está em API com PostgreSQL. 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.
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.
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.
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.
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 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.
A API HTTP documentada, em Infrastructure API:
GETePOST /apps/services/:id/jobslistam ou criam jobs.PUTeDELETE /apps/services/:id/jobs/:jobIdatualizam ou apagam um.POST /apps/services/:id/jobs/:jobId/runroda 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.
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.
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.
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 e o changelog de 26 de outubro.
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.
Como isso funciona na Unbroker
Tipos de serviço 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. 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 e em 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.
Checklist
- Use um worker quando o processo precisa ficar no ar e consumir uma fila durável.
- Use um job agendado quando o script começa, faz o trabalho e sai.
- Use um comando avulso para uma manutenção, com a imagem e as variáveis do serviço.
- Deixe a fila fora do worker. Use o acknowledgement, o retry e o dead-letter dessa biblioteca.
- Coloque as credenciais da fila em variáveis de runtime, não no texto do comando.
- Não crie um serviço web público só para um worker passar num health check HTTP.
- No shutdown, pare de pegar jobs, termine ou solte o que está em andamento, e feche as conexões.
- Registre IDs e categorias de erro. Deixe payloads privados fora do log.
- 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.
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.
A Unbroker tem um equivalente do Heroku Scheduler?
A página de migração do 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.