Daemons e Workers

Toda aplicação real precisa de algo rodando além do processo web: um consumidor de fila, um servidor de WebSocket, um worker em background, um relatório que roda toda madrugada. O PrimeForge cobre isso no grupo Processos de cada site. A página Workers e Jobs reúne três ferramentas complementares: o escalonamento de workers aumenta o número de processos que consomem a fila padrão (ou o Horizon), os pools de fila criam conjuntos nomeados de queue:work com opções próprias, e os daemons deixam você definir qualquer processo supervisionado que o painel mantém vivo no ambiente do site. Já a página Agendador do site cuida do que roda em horário marcado. Esta página explica cada uma e quando usar cada abordagem.

#A página Workers e Jobs

Abra Site → Processos → Workers e Jobs. A página não existe para sites do tipo HTML Estático, que não têm um runtime capaz de supervisionar processos.

No topo, cartões resumem o estado do processamento em segundo plano: o modo de processamento (Horizon, Workers de fila ou Sem fila), quantos processos estão saudáveis, os jobs pendentes, os jobs com falha e a conexão da fila em uso. Abaixo vêm as seções Processos (cada unidade do site com o estado — Rodando, Parado, Falhou… — e as ações Reiniciar e Ver logs), Filas (o tamanho de cada fila), Jobs com falha, Pools de fila adicionais e Daemons. Quando algo está errado — um worker em loop de reinício, workers comuns sobrando depois que o Horizon assumiu, uma fila configurada como sync — um aviso âmbar explica o que fazer.

O cabeçalho traz Escalar workers, Novo pool, Novo daemon, Reiniciar (reinício gracioso de todos os processos em segundo plano: cada um termina o job atual, sai e o systemd o inicia de novo) e o menu Fila, com Reprocessar falhas e Excluir falhas para a tabela de jobs com falha, Parar workers órfãos (quando o Horizon assumiu a fila e sobraram instâncias de worker comum) e Atualizar.

#Escalonamento de workers

Para sites Laravel que consomem uma fila (com ou sem Horizon), você pode ajustar quantos processos worker ficam consumindo os jobs. Mais workers significam mais jobs processados em paralelo — útil quando a fila acumula em horários de pico ou quando um job demorado segura os demais.

Você faz esse ajuste pela ação Escalar workers, no cabeçalho da página Workers e Jobs.

Os processos são adicionados ou removidos imediatamente, como instâncias systemd, e nenhum job em execução é interrompido: ao reduzir, cada worker sai depois de terminar o job que já estava processando. Aumente o número quando a sua fila estiver acumulando trabalho e o servidor tiver folga de CPU e memória. Cada worker adicional consome recursos do servidor, então acompanhe o uso em Monitoramento do servidor depois de escalar e não suba mais processos do que o servidor aguenta. Com o Horizon ligado, quem define o número de workers é a configuração do próprio Horizon (horizon.php).

O escalonamento muda a quantidade de processos de fila do próprio site, naquele servidor.

#Pools de fila

Um site Laravel pode definir até 5 pools de fila nomeados além do pool padrão (ou do Horizon), na seção Pools de fila adicionais. Cada pool é um conjunto de processos queue:work com a sua própria conexão (vazia = a QUEUE_CONNECTION do .env), a sua lista de filas em ordem de prioridade, e os seus próprios tentativas, timeout, pausa, limite de memória e tempo máximo de vida — de 1 a 10 processos cada. Clique em Novo pool, no cabeçalho da página: o modal mostra o comando gerado exato que cada processo vai executar antes de você salvar.

Use um pool quando filas diferentes precisam de tratamentos diferentes: um pool curto e numeroso para notificações, outro com --timeout alto e um único processo para relatórios pesados. Cada pool pode ser Editado, Ativado/Desativado ou Excluído sem tocar nos demais; as alterações pegam a trava de deploy daquele servidor, então uma mudança de pool nunca atropela um deploy em andamento.

#Daemons

Daemons são processos de longa duração que o PrimeForge mantém vivos no ambiente do seu site — consumidores de fila com flags específicas, servidores de WebSocket, workers em background, qualquer coisa que a sua aplicação precise rodando 24 horas por dia. O systemd (o gerenciador de processos do host) inicia cada daemon como uma unidade dedicada, o reinicia caso ele encerre e mostra o estado atual de cada um.

Você gerencia os daemons na seção Daemons da página Workers e Jobs do site.

#Criar um daemon

Clique em Novo daemon e preencha:

Você pode ter até 5 daemons por site. A lista mostra um selo de status ao vivo para cada um (Executando / Parado / Fatal…), com as ações Reiniciar, Editar, Excluir e Ver logs — esta abre o journal daquela unidade em uma aba própria da página de Logs, sem misturar com os logs do site inteiro.

Fila, Horizon, agendador e Reverb já têm controles próprios em Workers e Jobs e em Serviços — um daemon com o mesmo comando consumiria a mesma fila duas vezes. Toda operação que muda a configuração de daemons — criar, editar, ligar/desligar ou remover — re-renderiza as unidades systemd do site e as recarrega (daemon-reload + restart) para aplicar a nova configuração. É uma reinicialização rápida, e o modal avisa antes.

#Exemplos de comandos

php artisan queue:work redis --queue=payments --timeout=300
node websocket-server.js
sh -c "python worker.py >> storage/logs/worker.log 2>&1"

Repare no último exemplo: como o comando é executado diretamente (sem shell), qualquer redirecionamento (>>), pipe (|) ou encadeamento (&&) precisa ser envolvido em sh -c "...".

Se o Agent daquele servidor for anterior ao suporte a daemons ou a pools, a página exibe um aviso âmbar — eles passam a funcionar após a próxima atualização do Agent do servidor.

#Agendador do site

A página Site → Processos → Agendador lista as tarefas agendadas (cron) daquele site — as mesmas tarefas que aparecem, junto com as do host, no Agendador do servidor. Ela existe para todos os tipos de site, exceto HTML Estático, e exige o papel Developer ou acima.

A coluna Origem separa dois tipos de tarefa:

• Instalada — o agendador do Laravel (schedule:run), que o painel mantém sozinho quando o Agendador está ligado na página Serviços do site. Ela não é editada aqui; se o agendador do Laravel estiver desligado, a página avisa e aponta para Serviços.
• Personalizada — tarefas que você cria. Clique em Nova tarefa, dê um nome, o comando (por exemplo php artisan app:relatorio-diario, com caminhos relativos à raiz do app), o fuso horário, o timeout, Sem sobreposição e a frequência (presets de minuto a mês, ou uma expressão cron personalizada). O comando roda como o usuário Linux do site, na release ativa — não há usuário a escolher.

Cada tarefa traz Executar agora, Saída (a saída da última execução), Editar, Excluir e Monitorar com heartbeat / Parar heartbeat: com o heartbeat ligado, o painel espera um ping depois de cada execução e abre um incidente quando ele não chega — veja Heartbeats. Os detalhes de todos os campos estão em Monitoramento, Agendador e Firewall.

#Daemon, pool, escalonamento ou agendador — qual usar?

As quatro ferramentas rodam trabalho fora do processo web, mas resolvem problemas diferentes:

• Use o escalonamento de workers quando você só quer mais capacidade para a fila padrão do Laravel. É o caminho direto para processar mais jobs por segundo, sem escrever comando nenhum.
• Use um pool de fila quando o que muda não é a quantidade, e sim como aquela fila deve ser consumida: outra conexão, outro --timeout, outro limite de memória. O painel monta o queue:work para você e supervisiona cada processo.
• Use um daemon quando você precisa de um processo personalizado que fica sempre de pé e que o painel não gerencia por padrão: um servidor de WebSocket próprio, um worker escrito em outra linguagem, um consumidor de eventos. Você controla o comando exato, o diretório e a quantidade de cópias.
• Use o Agendador do site quando o trabalho tem hora marcada e termina: um relatório diário, uma limpeza semanal, uma sincronização a cada 15 minutos.

Na prática, elas convivem: você escala os workers da fila principal, cria pools para as filas que pedem tratamento próprio, adiciona daemons para os processos especializados e agenda o que precisa rodar em horário fixo.

#Próximos passos

• Deploys e Rollback — como o código chega ao servidor e reinicia os processos
• Configuração de Sites — Comandos, Logs e Heartbeats do site
• Modo de Pânico — tirar um site do ar sem parar os processos do site (nem os daemons)