Criar e executar tarefas cron (Cron Jobs) no cPanel

Uma tarefa cron executa um comando com a frequência que configurar. Serve para agendar ações como processar uma fila, gerar um relatório ou lançar a manutenção de uma aplicação.

Embora possam ser geridas a partir do terminal (comando crontab), a secção Cron Jobs do cPanel facilita a configuração através de uma interface simples.

Email para notificações

É o endereço para o qual o cron envia a saída padrão e os erros que o comando produzir. Se a tarefa não gerar saída, não receberá uma mensagem a confirmar cada execução.

Adicionar novas tarefas

Em cPanel > Cron Jobs, utilize Add New Cron Job. Escolha uma frequência habitual ou preencha minuto, hora, dia do mês, mês e dia da semana. Introduza depois o comando e guarde.

Em comando indicamos aquilo que queremos executar. Por exemplo, se tivermos um ficheiro cron.php em public_html que realiza tarefas de manutenção, devemos indicar:

cd /home/usuario_cpanel/public_html && /opt/alt/php83/usr/bin/php cron.php >> /home/usuario_cpanel/cron.php.log 2>&1

O exemplo utiliza o PHP 8.3: verifique se essa versão existe e é compatível. Use sempre o caminho completo do PHP da sua aplicação: /usr/local/bin/php ou simplesmente php podem ser outra versão, com outras extensões. cd fixa o diretório de trabalho para os scripts que usam caminhos relativos; && evita executá-los a partir de outra pasta se a mudança falhar. O exemplo guarda a saída num registo para não perder os erros. Reveja e faça a rotação desse ficheiro. Se não quiser nem registo nem emails, termine o comando em >/dev/null 2>&1: a saída é descartada. É útil em tarefas executadas a cada poucos minutos, que encheriam a caixa de correio de avisos, mas também oculta qualquer falha da tarefa.

Executar um URL a partir do cron

Quando uma aplicação disponibiliza um URL de tarefas, pode pedi-lo com curl:

curl --fail --silent --show-error --max-time 300 https://tudominio.com/ruta-de-cron

Durante os primeiros testes, conserve a saída de diagnóstico e verifique o resultado da tarefa na aplicação. O email contém a saída, não necessariamente o código de retorno. Quando confirmar que funciona, pode guardá-la num registo privado. Crie antes a pasta de destino com as permissões adequadas:

curl --fail --silent --show-error --max-time 300 https://tudominio.com/ruta-de-cron >> /home/usuario_cpanel/logs/cron-url.log 2>&1

É preferível executar diretamente o comando PHP ou CLI da aplicação, quando existir, porque evita DNS, SSL e um pedido web completo. Não inclua palavras-passe ou tokens permanentes num URL que possa ficar guardado em históricos e registos.

Escolha um intervalo superior ao tempo máximo de execução. Se uma chamada demorar cinco minutos e agendar outra a cada minuto, as tarefas podem sobrepor-se e esgotar processos. A própria aplicação deve implementar um bloqueio quando não admitir execuções simultâneas.

Tarefas cron atuais

Em Current Cron Jobs temos uma lista das tarefas cron adicionadas, para as poder editar ou eliminar conforme necessário.

Verificar o agendamento

Estas horas correspondem ao ambiente de cron do servidor; confirme o seu fuso horário antes de agendar uma ação ligada a uma hora local. No cPanel, preencha esses campos em separado: não acrescente os cinco campos à caixa Command.

Depois de guardar, verifique a execução seguinte através do seu registo ou do resultado esperado. Um teste manual bem-sucedido não demonstra que o cron tenha o mesmo ambiente: normalmente não carrega o .bashrc, as variáveis do seu terminal nem o NVM. Use caminhos absolutos e configure explicitamente o que o script precisar.

Evitar execuções simultâneas

Se o comando for executado em primeiro plano e o flock estiver disponível, pode manter um bloqueio durante toda a sua execução:

/usr/bin/flock -n /home/usuario_cpanel/tarea.lock /opt/alt/php83/usr/bin/php /home/usuario_cpanel/apps/mi-proyecto/tarea.php

Verifique os caminhos e que a aplicação não depende de outro diretório de trabalho. O bloqueio é libertado quando o comando termina; não cobre trabalhos que este lance em segundo plano nem processos remotos que continuem depois de uma chamada HTTP. Se não conseguir o bloqueio, -n omite essa execução: verifique se esse comportamento serve para a sua tarefa.

Eliminar uma entrada do cron impede execuções futuras, mas não para uma que já esteja em curso. Se a tarefa realizar cobranças, envios ou alterações de dados, reveja o seu estado antes de a repetir após um timeout.

Workers de filas: cron ou processos persistentes

Um worker de filas lançado a partir do cron tem de terminar quando já não houver trabalho e não se juntar ao do minuto seguinte. Por exemplo, para o Laravel, a cada minuto:

cd /home/usuario_cpanel/apps/mi-proyecto && /usr/bin/flock -n /home/usuario_cpanel/.cola-mi-proyecto.lock /opt/alt/php84/usr/bin/php artisan queue:work --stop-when-empty --max-time=300

Processa o que estiver pendente e termina; se o anterior ainda estiver a trabalhar, flock -n omite essa execução. Os trabalhos esperam no máximo um minuto. No Laravel também o pode lançar a partir do scheduler, como explicamos em Instalar o Laravel.

Não use o cron para deixar um worker em execução com & ou nohup: ninguém o vigia, por isso, se cair, não volta, e sem bloqueio soma-se outro a cada minuto.

Nos planos Avanza, Max e Elastic, os processos persistentes mantêm sempre em execução um worker de filas, o Horizon ou um comando próprio, e voltam a arrancá-lo se cair. Se os usar, verá nas suas tarefas cron uma linha que termina em # hostsuar-procesos: é o vigilante que os verifica a cada minuto. Não a edite nem a apague; é gerida a partir de Ferramentas > Processos.

Uma linha com schedule:run que termina em # hostsuar-deploy- e um número é o scheduler de uma aplicação Laravel que o Deploy+ agendou ao publicá-la. Essa é sua: pode alterá-la ou apagá-la como qualquer outra.