Scheduled Tasks: What the Once-per-Minute cron:run Does

On the admin “Scheduled Tasks” page, you can see each task’s frequency, next run time, and latest result, but many people don’t know: these times are only for display; what actually makes tasks run is cron:run, executed once per minute on the server. This article explains exactly what it does and when it doesn’t take effect.

1. Prerequisite: the Once-per-Minute cron:run

Scheduled tasks are not automatically triggered by web pages based on time. The server needs to execute the following once per minute:

* * * * * /usr/bin/php /var/www/kingcms/x1/bin/kingcms cron:run >> /var/www/kingcms/x1/data/cron.log 2>&1

crontab, systemd timer, the BT Panel “Scheduled Tasks”, a shared hosting control panel, or Windows Task Scheduler all work; set the interval to 1 minute. The same cron:run run executes in sequence: scheduled tasks registered by enabled modules, automatic backups, database maintenance, update checks, language pack supplementary translation, demo sandbox cleanup, the admin task queue, and custom tasks that are due. data/cron.lock ensures only one runs at a time; if the previous run has not finished, the current run exits immediately.

If cron:run is not configured, the page still shows frequencies and next run times, but tasks will not execute when due; if the scheduler has not run for more than 10 minutes, a yellow warning bar appears at the top of the “Data Backup” page. The executing user must also have write permission on data/; otherwise lock files, logs, and backups cannot be created.

2. System Tasks

System tasks are fixed tasks registered by the core and enabled modules. They cannot be created, edited, or deleted; you can only click “Run Now”:

• Module scheduled tasks: every minute; the name shows the module name;
• Automatic backup: daily at 03:15 (can be changed to every Monday or disabled);
• Database maintenance: runs VACUUM every Sunday at 03:45 (time can be changed or it can be disabled);
• Update check: every 6 hours; only checks, does not upgrade automatically;
• Language pack supplementary translation: every minute; after AI service is configured, fills in missing language entries;
• Demo sandbox cleanup and admin task queue: every minute.

Tasks disabled in settings show “Disabled”, and their next run time shows “—”. Clicking “Run Now” executes once immediately within the current request and does not change the original frequency; tasks with due-time checks that have already run in the current period return immediately.

3. Custom Tasks: Let AI Work on a Schedule

Custom tasks pass a prompt to the AI assistant for execution at a fixed time, suitable for regularly writing article drafts and organizing content. The prerequisite is to first configure a service under “Settings → AI & API → AI Service” and confirm it is available.

When creating one, fill in four fields: task name (up to 100 characters), what the AI should do (complete instructions, clearly stating the topic, format, and save location), frequency (daily or weekly), and run time (site time zone, default 09:00). After saving, you can edit, pause, resume, delete, or run it immediately.

Note these execution rules: the task runs as the creator, and after it finishes it automatically confirms the pending operations generated by this run, so changes are written directly to the website; the creator must still be an enabled administrator, otherwise the task fails; only one result summary is kept each time (the first 120 characters of the assistant’s reply), and it is overwritten on the next run; frequencies are only daily and weekly—hourly is not available.

4. It Cannot Be Used as a Shell

The Scheduled Tasks page only lists fixed system tasks and AI custom tasks; you cannot create Shell command or script tasks here. If you need to run other commands on the server on a schedule, write them directly in the system crontab, BT Panel, or another scheduler—do not hand them to cron:run.

5. Troubleshooting Order

1. Check whether the server executes cron:run every minute;
2. Check whether the executing user has write permission on data/;
3. Check whether “Last Run” on the “Data Backup” page is updated;
4. If a custom task fails, check “Latest Run Result”: an unconfigured AI service or a disabled creator will be recorded here;
5. If you are still unsure, manually run php x1/bin/kingcms cron:run and check the terminal output.

Summary

The core of scheduled tasks is not the admin page, but that once-per-minute cron:run on the server. Configure it properly, grant sufficient permissions on data/, and distinguish between system tasks and custom tasks; only then will scheduled backups, translation, push, and drafting happen as expected.