Cronjob on wt-modules

Verwendung

Mon, 01 Jan 0001 00:00:00 +0000

Job erstellen

Steuerungspanel → Cron Job Scheduler → Neuer Job:

Feld	Bedeutung
Name (Slug)	technischer Bezeichner, `a-z 0-9 _ -`. Nur-lesen für durch Module angebotene Jobs (deren `<module>:<name>`-Schlüssel ist fix); editierbar für selbst erstellte Jobs.
Titel	menschenlesbarer Name
Trigger	ein oder mehrere Zeit-Trigger (Cron-Zeitpläne) und/oder Ereignis-Trigger — der Job feuert, wenn irgendein Trigger feuert. Mindestens einer ist erforderlich.
Cron-Ausdruck	(Zeit-Trigger) Standard-5-Feld-Cron oder ein Makro (`@daily`, `@weekly`, …). Zeiten sind UTC.
Ereignisname	(Ereignis-Trigger) das Ereignis, auf das dieser Job reagiert. Slug oder `<domain>:slug`, max. 64 Zeichen.
Befehl	ein `modules_v4/<module>/cli/<script>.php`-Pfad oder ein erlaubter Core-Befehl.
Argumente	nur einfache Optionen/Werte (z.B. `--limit=5000`), max. 10 Tokens
Timeout	30 - 3600 s
Bei Fehler benachrichtigen	Opt-in: Admin-Konten bei Job-Fehlern benachrichtigen

Verfügbare Ereignisnamen und Befehle werden als Datalists bereitgestellt, um die Dateneingabe zu erleichtern.

Der Tick

Mon, 01 Jan 0001 00:00:00 +0000

Der Tick ist das Herz des Moduls: einmal pro Minute prüft er alle aktivierten Jobs, entscheidet, was fällig ist, und führt es aus. Weder das webtrees-Core noch das Betriebssystem planen selbst — sie starten nur tick.php .

flowchart TD
 subgraph Triggers["`⏱ Auslöser *(once per minute)*`"]
 CRON["`🕑 OS cron / systemd<br/>*every minute*`"]
 WATCH["`👁 watch-Daemon<br/>*(in-module)*`"]
 end

 subgraph Guard["🛡 Guard"]
 TP["`📄 cli/tick.php · **cron:tick**<br/>*guard(): 403 over HTTP*`"]
 OFF{"`⚠ site offline?<br/>*data/offline.txt*`"}
 BOOT["`🚀 boot()<br/>*webtrees + DB*`"]
 end

 subgraph Selection["🔎 Arbeit auswählen"]
 TIME["`📅 time-based jobs<br/>**next_run_at due** *(UTC)*`"]
 CE[("`📦 cj_event<br/>*Event-Warteschlange*`")]
 DRAIN["`🧮 drain queue<br/>*coalesced · 60 s budget*`"]
 end

 subgraph Execution["`⚙ Ausführung *(isolated child)*`"]
 RUN["`🧪 JobRunner<br/>**proc_open**`"]
 LIM["`⏲ timeout 30–3600 s<br/>last **64 KB** · exit code`"]
 end

 subgraph Storage["💾 Speicherung"]
 CJRUN[("`cj_run<br/>*Laufverlauf*`")]
 MARK["`🏷 tick.last<br/>*stale > 300 s → tick_stale*`"]
 end

 CRON --> Guard
 WATCH --> Guard
 TP --> OFF
 OFF -->|"offline"| SKIP["⏭ Tick überspringen"]
 OFF -->|"online"| BOOT
 BOOT --> TIME
 BOOT --> DRAIN
 CE --> DRAIN
 TIME --> Execution
 DRAIN --> Execution
 RUN --> LIM
 LIM --> CJRUN
 BOOT --> MARK

 classDef sourceStyle fill:#e3f2fd,stroke:#1565C0,stroke-width:2px
 classDef queueStyle fill:#fff3e0,stroke:#E65100,stroke-width:2px
 classDef tickStyle fill:#e8f5e9,stroke:#2E7D32,stroke-width:2px
 classDef execStyle fill:#fce4ec,stroke:#C2185B,stroke-width:2px
 classDef storageStyle fill:#f5f5f5,stroke:#616161,stroke-width:1px

 class CRON,WATCH sourceStyle
 class OFF,CE queueStyle
 class TP,TIME,DRAIN tickStyle
 class RUN,LIM execStyle
 class CJRUN,MARK,SKIP storageStyle

Was einen Tick startet

Einen Trigger wählen (einmalig):

CLI-Skripte

Mon, 01 Jan 0001 00:00:00 +0000

Skripte

php modules_v4/cronjob/cli/tick.php # alle fälligen Jobs ausführen
php modules_v4/cronjob/cli/tick.php --dry-run # anzeigen, was ausgeführt würde
php modules_v4/cronjob/cli/tick.php --job=<name> # einen bestimmten Job jetzt ausführen
php modules_v4/cronjob/cli/tick.php --strict # Exit 1 wenn ein Job fehlgeschlagen ist
php modules_v4/cronjob/cli/tick.php --full-output # vollständige Job-Ausgabe echo (Debugging!)
php modules_v4/cronjob/cli/watch.php # Watch-Daemon starten

Exit-Codes: 0 = Tick lief (Job-Fehler werden in der DB protokolliert), 1 = Umgebungsproblem oder (mit --strict) mindestens ein Job fehlgeschlagen.

Log-Hygiene: stdout trägt nur Summary-Zeilen. Die vollständige Job-Ausgabe liegt in der Ausführungshistorie (nur Admin). --full-output niemals in einen weltlesbaren Ort umleiten.

Sicherheit

Mon, 01 Jan 0001 00:00:00 +0000

Nie eine Shell. Befehle werden via proc_open mit einem argv-Array ausgeführt.
Befehls-Whitelist. Modulskripte müssen modules_v4/<module>/cli/<script>.php entsprechen, existieren und sich in einem modules_v4/<module>/cli/-Verzeichnis auflösen. Core-Befehle sind auf die Read-only/Export-Allowlist beschränkt.
Argument-Validierung. Jedes Argument-Token muss eine einfache Option oder ein Wert sein — keine Shell-Metazeichen, keine Leerzeichen in Tokens, max. 10 Tokens.
Arbeitsverzeichnisse. Modulskripte laufen vom webtrees-Root; Core-Befehle laufen von data/.
Keine sensiblen Daten in stdout. Der Tick gibt nur Zusammenfassungen aus; die vollständige Ausgabe bleibt in der Ausführungshistorie (admin-only).
UI-Aktionen sind alle als *Admin* benannt (nur Admin, CSRF-geschützt).
Notaus-Schalter: Modul deaktivieren — der Tick tut dann nichts.
Der Tick ist Single-Instance (flock), und der Kindprozess eines Jobs wird nach dem Timeout hart getötet (SIGKILL).
Bündelung von Ereigniswarteschlangen. Eine Flut identischer Ereignisse wird zusammengeführt zu einem Joblauf.
Webhook-Token nur im Header. Das Token wird ausschließlich im X-Cronjob-Token-Header gesendet.