---
title: "Plugins betreiben"
description: "Migrationen, Plugin-Updates, Deaktivieren und Entfernen, Worker, Wartungsmodus, Zeitstempeldienst, Umgebungsvariablen, Logs und Fehlersuche"
---

Diese Seite richtet sich an Betreiber. Wie Plugins auf den Server kommen und aktiviert werden, steht unter [Plugins installieren](/plugins/installieren).

## Migrationen

Plugins legen ihre Tabellen (Präfix `plg_<id>__`) mit eigenen SQL-Migrationen an. QuickTribe führt sie aus

- beim **Aktivieren** im Plattform-Admin bzw. mit `app:plugin:enable`,
- im Dienst **`migrate`** bei jedem Start bzw. Update des Stacks – nach den Migrationen der Plattform, für alle aktivierten Plugins,
- mit **Migrationen ausführen** im Plattform-Admin oder `app:plugin:migrate` auf der Konsole.

Bringt eine neue Fassung eines Plugins eine Migration mit, die noch nicht gelaufen ist, steht das Plugin auf **Migration offen** und wird **nicht geladen** – es wirkt erst wieder, wenn die Migration gelaufen ist. So trifft neuer Code nie auf alte Tabellen.

Schlägt eine Plugin-Migration im Dienst `migrate` fehl, **startet die Plattform trotzdem**. Das Log von `migrate` zeigt dann je betroffenem Plugin eine Zeile `✘ <id>: …` mit Datei, Nummer der Anweisung und Meldung der Datenbank und darunter die Warnung „… Plugins nicht migriert – der Kern startet trotzdem; Details unter /admin/plugins.“ Nur wenn der Befehl selbst abbricht (etwa ohne Verbindung zur Datenbank), steht dort stattdessen eine Zeile `WARNUNG: Plugin-Migrationen fehlgeschlagen …`. Alle drei Fälle findet `docker compose logs migrate | grep -E '✘|nicht migriert|WARNUNG'`. Das Plugin zeigt im Plattform-Admin **Fehler** bzw. **Migration offen**. Nach dem Beheben (meist eine korrigierte Fassung des Plugins vom Anbieter):

```bash
php bin/console app:plugin:migrate --enabled            # alle aktivierten Plugins
php bin/console app:plugin:migrate mein-plugin          # ein Plugin
php bin/console app:plugin:migrate --enabled --strict   # Exit-Code 1, wenn ein Plugin scheitert (für Skripte)
```

Der Befehl verlangt genau eine Angabe: eine Plugin-ID, `--enabled` oder `--all` (alle erkannten Plugins).

Gut zu wissen:

- Eine unterbrochene Migration setzt beim nächsten Lauf nach der letzten erfolgreichen Anweisung fort.
- Ausgeführte Migrationsdateien dürfen sich nicht mehr ändern. Ändert eine neue Fassung eine schon gelaufene Datei, zeigt das Plugin **Fehler** („nach dem Ausführen geändert“) – das muss der Anbieter beheben.
- Ein Zurück auf eine ältere Fassung eines Plugins macht Migrationen nicht rückgängig. Wie bei der Plattform selbst hilft dann nur eine Datensicherung von vorher.
- `app:plugin:migrate --fresh` löscht vorher Plugin-Tabellen samt Daten – mit `--all` **alle**, mit einer Plugin-ID oder `--enabled` die Tabellen und den Migrationsstand dieser Plugins. Das ist nur für Entwicklung und Tests gedacht; in Produktion verweigert der Befehl es ohne `--force`. Nie auf einer Installation mit echten Daten verwenden.

## Ein Plugin aktualisieren

Eine neue Fassung ersetzt den Plugin-Ordner. Weil PHP den Code im Betrieb zwischenspeichert (OPcache), müssen `app` und `worker` danach neu starten; offene Migrationen laufen anschließend. Wer Besucher während des Tauschs aussperren will, schaltet vorher den [Wartungsmodus](/konfiguration#wartungsmodus) ein.

**Docker Compose** (Ordner `plugins/` neben der Compose-Datei):

```bash
docker compose stop app worker
sudo rm -rf plugins/.alt-mein-plugin && sudo mv plugins/mein-plugin plugins/.alt-mein-plugin   # vorige Fassung aufheben (Ordner mit Punkt lädt QuickTribe nicht)
sudo tar -xzf ~/mein-plugin-1.1.0.tar.gz -C plugins
sudo chown -R root:root plugins/mein-plugin && sudo chmod -R u+rwX,go+rX,go-w plugins/mein-plugin
docker compose up -d
docker compose exec app php bin/console app:plugin:migrate --enabled --strict
```

**Portainer und Coolify** (Volume, Dateien über den Worker-Container; Namen wie unter [Portainer und Coolify](/plugins/installieren#portainer-und-coolify)):

```bash
chmod -R u+rwX,go+rX,go-w mein-plugin
docker exec quicktribe-worker-1 rm -rf /var/www/plugins/.neu-mein-plugin
docker cp mein-plugin quicktribe-worker-1:/var/www/plugins/.neu-mein-plugin
docker exec quicktribe-worker-1 chown -R root:root /var/www/plugins/.neu-mein-plugin
docker stop quicktribe-app-1
docker exec quicktribe-worker-1 sh -c 'cd /var/www/plugins && rm -rf .alt-mein-plugin && mv mein-plugin .alt-mein-plugin && mv .neu-mein-plugin mein-plugin'
docker restart quicktribe-worker-1
docker start quicktribe-app-1
docker exec quicktribe-app-1 php bin/console app:plugin:migrate --enabled --strict
```

**Webserver ohne Docker:**

```bash
P=/var/www/quicktribe/shared/plugins
mkdir $P/.neu && tar -xzf mein-plugin-1.1.0.tar.gz -C $P/.neu
chown -R root:root $P/.neu && chmod -R u+rwX,go+rX,go-w $P/.neu
systemctl stop quicktribe-worker quicktribe-plugin-worker
rm -rf $P/.alt-mein-plugin && mv $P/mein-plugin $P/.alt-mein-plugin && mv $P/.neu/mein-plugin $P/mein-plugin && rmdir $P/.neu
systemctl reload php8.5-fpm
systemctl start quicktribe-worker quicktribe-plugin-worker
cd /var/www/quicktribe/current && runuser -u www-data -- php bin/console app:plugin:migrate --enabled --strict
```

Danach im Plattform-Admin prüfen, ob das Plugin wieder **aktiv** ist und die neue Version zeigt. Den aufgehobenen Ordner `.alt-…` löschen Sie, sobald die neue Fassung läuft. Zurück auf die vorige Fassung geht nur, solange die neue keine Migration ausgeführt hat.

## Update der Plattform

Plugins liegen außerhalb des Images bzw. der Versionsordner und **bleiben bei einem Update von QuickTribe erhalten**; ihre Migrationen laufen im Dienst `migrate` mit. Jedes Plugin nennt im Manifest, mit welchen Versionen von QuickTribe und der Plugin-Schnittstelle es läuft (Plattform-Admin → Plugins, „Anforderungen“). Passt die neue Version nicht dazu, steht das Plugin nach dem Update auf **Fehler** und wird nicht geladen. Prüfen Sie die Anforderungen Ihrer Plugins deshalb vor einem Update und holen Sie bei Bedarf eine passende Fassung beim Anbieter. Ändern sich mit einem Update die Regeln für Plugin-Oberflächen (etwa beim [Geltungsbereich der Stile](/plugins/frontend#geltungsbereich-plugin-stile-wirken-nur-im-plugin)), bauen Sie die Plugins mit dem neuen Stand neu und spielen sie zusammen mit dem Update ein; ältere Builds zeigt die Plugin-Verwaltung mit **Stile nicht geladen – neu bauen**.

## Deaktivieren und entfernen

- **Deaktivieren** (Plattform-Admin oder `app:plugin:disable <id>`) schaltet das Plugin plattformweit aus. Seine Seiten, Menüpunkte, Felder und Reaktionen entfallen; Tabellen, Einstellungen und Dateien bleiben erhalten. Wieder aktivieren stellt alles her.
- **Entfernen:** Erst deaktivieren, dann den Ordner löschen und `app` und `worker` neu starten. Die Daten des Plugins bleiben in der Datenbank und im Speicher; im Plattform-Admin erscheint es weiter als **nicht gefunden**, solange es dort Daten oder eine Aktivierung gibt. Einen Befehl, der die Daten eines einzelnen Plugins löscht, gibt es in dieser Version nicht.

<Warning>
Speichert ein Plugin personenbezogene Daten, lassen Sie es **deaktiviert, aber installiert**, solange diese Daten existieren. Nur dann bedient QuickTribe Datenexporte und Kontolöschungen auch für dieses Plugin. Fehlt der Ordner, bleiben Löschaufträge unter Plattform-Admin → Plugins als **Offene Löschungen** stehen, bis das Plugin zurück ist.
</Warning>

## Worker

Aufträge von Plugins – wiederkehrende Jobs, einzelne Aufgaben und die Reaktionen auf Ereignisse – arbeitet der Worker in einer eigenen Warteschlange (`async_plugins`) ab. Im Container `worker` laufen dafür **zwei Prozesse** nebeneinander: einer für die Plattform (E-Mails, Push, Videos, Zeitpläne …) und einer für Plugins. Ein langer Plugin-Auftrag hält so keine E-Mails oder Erinnerungen auf. Endet einer der beiden Prozesse (planmäßig nach einer Stunde, bei 512 MB Speicher oder durch einen Absturz), startet der Container nur diesen neu – nach schnellen Abstürzen mit wachsender Wartezeit bis 60 Sekunden; der andere arbeitet weiter.

Beim Anhalten (Update, Neustart) beendet jeder Prozess erst seinen laufenden Auftrag. Die Stack-Dateien geben dem Worker dafür **bis zu fünf Minuten**, bei der Installation ohne Docker gilt dasselbe für beide systemd-Dienste (`TimeoutStopSec=300`). Ein Neustart des Workers kann deshalb einige Minuten dauern. Wird ein Auftrag trotzdem hart abgebrochen, wiederholt QuickTribe ihn nicht: Eine abgebrochene Aufgabe gilt als gescheitert (Fehler beim Plugin), ein Job läuft beim nächsten Takt wieder. Jobs prüft der Worker alle fünf Minuten auf Fälligkeit.

Bei der Installation ohne Docker übernimmt der zweite Dienst `quicktribe-plugin-worker` die Plugin-Aufträge (siehe [Webserver → Worker](/installation/webserver#11-worker)). Läuft er nicht, bleiben Jobs, Aufgaben und Reaktionen von Plugins liegen.

## Wartungsmodus

Im [Wartungsmodus](/konfiguration#wartungsmodus) verhalten sich Plugins wie die Plattform: Plugin-Seiten (`/plugins/…`, `/c/<slug>/plugins/…`) zeigen die Zugangsseite, die Plugin-Schnittstelle unter `/api/plugins/…` antwortet mit `503`. Offen bleiben nur die gebauten Dateien unter `/plugin-assets/…` (Skripte, Stile, Bilder), damit freigeschaltete Geräte die Seiten vollständig sehen. Jobs und Aufgaben laufen im Hintergrund weiter.

## Zeitstempeldienst

Manche Plugins lassen Dokumente von einer externen **Zeitstempelstelle** nach RFC 3161 bestätigen – etwa für revisionssichere Tagesabschlüsse. Das ist optional und nur nötig, wenn ein Plugin es verlangt; ohne Konfiguration bieten Plugins diese Funktion nicht an.

| Variable | Bedeutung |
| --- | --- |
| `APP_TSA_URL` | Adresse des Zeitstempeldienstes, z. B. `https://freetsa.org/tsr` |
| `APP_TSA_CA_FILE` | Pfad (im Container bzw. auf dem Server) zu einer PEM-Datei mit der Zertifikatskette des Dienstes, z. B. `/var/www/plugins/.tsa/freetsa-cacert.pem`; damit prüft QuickTribe jede Antwort |
| `APP_TSA_AUTH` | optional: Wert der Kopfzeile `Authorization` für Dienste mit Zugangsdaten (z. B. `Basic …`); leer = ohne |

Die CA-Datei ist die Grundlage jeder Prüfung. Sie gehört deshalb wie die Plugins `root` und darf für den PHP-Prozess nicht schreibbar sein – sonst ließe sich über eine Lücke in der Anwendung ein fremdes Zertifikat unterschieben, und gefälschte Zeitstempel gälten als gültig. Ein guter Platz in den Docker-Varianten ist ein Ordner `.tsa` im Plugin-Verzeichnis: Den sehen `app` und `worker`, in `app` ist er nur lesbar eingehängt, und Ordner mit Punkt lädt QuickTribe nicht als Plugin. Beispiel mit dem kostenlosen Dienst **FreeTSA**:

**Docker Compose** (im Verzeichnis mit der `docker-compose.yml`):

```bash
sudo mkdir -p plugins/.tsa
sudo curl -fsSL -o plugins/.tsa/freetsa-cacert.pem https://freetsa.org/files/cacert.pem
sudo chmod 755 plugins/.tsa && sudo chmod 644 plugins/.tsa/freetsa-cacert.pem
```

**Portainer und Coolify** (über den Worker-Container wie unter [Plugins installieren](/plugins/installieren#portainer-und-coolify)):

```bash
curl -fsSL -o freetsa-cacert.pem https://freetsa.org/files/cacert.pem && chmod 644 freetsa-cacert.pem
docker exec quicktribe-worker-1 mkdir -p /var/www/plugins/.tsa
docker cp freetsa-cacert.pem quicktribe-worker-1:/var/www/plugins/.tsa/freetsa-cacert.pem
docker exec quicktribe-worker-1 chown -R root:root /var/www/plugins/.tsa
```

Danach `APP_TSA_URL=https://freetsa.org/tsr` und `APP_TSA_CA_FILE=/var/www/plugins/.tsa/freetsa-cacert.pem` eintragen – bei Docker Compose in der `.env`, bei Portainer und Coolify in den Variablen des Stacks bzw. der Ressource – und den Stack neu ausrollen (`docker compose up -d`). Ohne Docker liegt die Datei z. B. unter `/var/www/quicktribe/shared/tsa/` (Ordner und Datei gehören `root`, Modus `755` bzw. `644`), die Variablen stehen in `shared/.env.local`. Für Dienste mit Rechtswirkung (qualifizierte Zeitstempel nach eIDAS) nennt der Anbieter Adresse, Zertifikatskette und Zugang.

- Der Server braucht ausgehenden HTTPS-Zugang zum Dienst. QuickTribe folgt keinen Weiterleitungen und wartet höchstens 10 Sekunden.
- Je Community sind 30 Zeitstempel pro Stunde möglich.
- **Behalten Sie die CA-Datei.** Mit ihr prüft QuickTribe auch ältere Zeitstempel – zum Zeitpunkt ihrer Ausstellung, also auch nach Ablauf des Zertifikats der Zeitstempelstelle. Wechselt der Dienst oder seine Zertifikatskette, hängen Sie die neuen Zertifikate an die bestehende Datei an, statt sie zu ersetzen; sonst lassen sich ältere Zeitstempel nicht mehr prüfen.

## Umgebungsvariablen

| Variable | Bedeutung |
| --- | --- |
| `APP_PLUGINS_DIR` | Verzeichnis der Plugins. In den Docker-Varianten fest `/var/www/plugins` (setzt die Stack-Datei; `app:doctor` warnt bei einem anderen Wert im Container). Ohne Docker z. B. `/var/www/quicktribe/shared/plugins` |
| `APP_PLUGINS_ALLOW_WRITABLE` | `1` schaltet die Prüfung der Dateirechte ab (Status „unsicher“ entfällt). **Nur für die Entwicklung** – in Produktion meldet `app:doctor` einen Fehler und der Plattform-Admin einen Hinweis. Standard `0` |
| `APP_TSA_URL`, `APP_TSA_CA_FILE`, `APP_TSA_AUTH` | Zeitstempeldienst, siehe [oben](#zeitstempeldienst) |
| `APP_PLUGIN_LICENSE_URL` | reserviert für eine spätere Lizenzprüfung, derzeit ohne Wirkung – leer lassen |

Alle Variablen der Installation stehen unter [Konfiguration](/konfiguration#plugins).

## Logs und Prüfung

- **Plattform-Admin → Plugins** zeigt je Plugin Status, Fehler, letzte Fehlermeldung und offene Löschungen; die Detailseite den Stand jeder Migration.
- **`app:plugin:list`** zeigt dieselbe Übersicht auf der Konsole, **`app:plugin:validate [<pfad>]`** prüft Manifest, Code, Dateirechte, Migrationen und gebaute Dateien und endet bei Fehlern mit Exit-Code 1 – gut vor dem Einspielen einer neuen Fassung.
- **`app:doctor`** enthält einen Abschnitt „Plugins“ und meldet unsichere Plugins, aktivierte Plugins mit Fehler oder offener Migration und fehlende Ordner als Fehler.
- **Logs:** Fehler von Plugins (in Endpunkten, Reaktionen auf Ereignisse, Jobs und Aufgaben) stehen im Log von `app` bzw. `worker` mit `"channel":"plugins"` und dem Namen `plugin.<id>.…`, z. B. `docker compose logs worker | grep '"channel":"plugins"'`; ohne Docker in `/var/log/php8.5-fpm.log` und im Journal von `quicktribe-plugin-worker`. Warnungen (etwa langsame Aufrufe oder Fehler, die ein Plugin im Browser meldet) schreibt die Plattform in Produktion nur zusammen mit einem Fehler desselben Aufrufs ins Log.

## Fehlersuche

| Beobachtung | Ursache und Abhilfe |
| --- | --- |
| Status **unsicher** | Eigentümer, Rechte oder Links stimmen nicht; der Grund steht daneben. Rechte wie unter [Regeln für die Dateien](/plugins/installieren#regeln-für-die-dateien) setzen. Steht „Das Plugin-Verzeichnis ist unsicher“ ganz oben, betrifft es das Verzeichnis selbst |
| Status **Migration offen** | Migrationen nachholen: Plattform-Admin → **Migrationen ausführen** oder `app:plugin:migrate --enabled` |
| Status **Fehler** | Meldung lesen: fehlerhaftes `plugin.json`, unpassende Anforderungen, fehlende Datei in `dist/`, Code lässt sich nicht laden, Migration gescheitert oder nachträglich geändert. Meist braucht es eine korrigierte Fassung vom Anbieter. **Fehlermeldung zurücksetzen** blendet eine behobene Laufzeit-Meldung aus |
| Status **nicht gefunden** | Der Ordner fehlt oder heißt anders als die Plugin-ID; Ordner wiederherstellen |
| Plugin fehlt in der Liste | Ordner liegt nicht direkt im Plugin-Verzeichnis, beginnt mit einem Punkt oder `APP_PLUGINS_DIR` zeigt woandershin (`app:doctor` nennt das Verzeichnis) |
| Aktivieren meldet „Bitte bestätige diese Aktion mit einer erneuten Anmeldung …“ | ab- und wieder anmelden, dann innerhalb von 10 Minuten aktivieren |
| Neue Fassung wirkt nicht | `app` und `worker` nicht neu gestartet (OPcache) – neu starten |
| Plugin-Seiten ohne Oberfläche, im Browser 404 für `/plugin-assets/…` | `dist/` fehlt oder ist unvollständig; ohne Docker fehlt der nginx-Block für `/plugin-assets/` |
| Plugin erscheint nicht unter Einstellungen → Plugins | Es gilt für alle Communities (dann gibt es keinen Schalter) oder ist plattformweit nicht aktiv |
| Jobs oder Aufgaben eines Plugins laufen nicht | Worker läuft nicht, bzw. ohne Docker fehlt `quicktribe-plugin-worker`; Plugin in der Community ausgeschaltet; Fehler im Plugin-Log |
| **Offene Löschungen** | Kontolöschungen, die ein Plugin noch nicht verarbeitet hat; QuickTribe versucht es stündlich erneut. Nach drei Fehlschlägen steht ein Hinweis da – Plugin-Log prüfen, Plugin wieder installieren bzw. Migrationen nachholen |
