n8n Runbook-Minimum: 1 Seite, die nachts hilft (Template)

Warum ihr ein Runbook braucht

Es ist 2 Uhr nachts. Euer Handy vibriert. Der Intake-Workflow hat vor drei Stunden aufgehört zu verarbeiten. Vierzig Mandantenanfragen stecken fest.

Ihr öffnet den Laptop. Und jetzt?

Ohne Runbook macht ihr Reverse Engineering eures eigenen Systems unter Druck. Mit Runbook habt ihr einen klaren Pfad: Diagnose, Fix, Verifizieren, Dokumentieren.

Ein Runbook ist keine Dokumentation um der Dokumentation willen. Es ist der Unterschied zwischen einem 10-Minuten-Fix und 2 Stunden Panik.

Das Eine-Seite-Runbook-Template

Dieses Template deckt das Minimum für jeden Produktions-Workflow ab. Ausdrucken. Zugänglich aufbewahren. Aktualisieren wenn sich Dinge ändern.

WORKFLOW: [Name]

Zweck: [Ein Satz der beschreibt was dieser Workflow tut]

Owner: [Name] | Backup: [Name]

Zuletzt aktualisiert: [Datum]

1. HEALTH CHECK

Wie weiß ich, dass er funktioniert?

Schneller Health-Check-Befehl:

[Befehl oder URL zum Status-Check]

2. HÄUFIGE PROBLEME

Problem: Workflow führt nicht aus

1. Prüfen ob Workflow aktiv ist (Toggle in n8n)
2. Trigger prüfen (Webhook erreichbar? Schedule läuft?)
3. n8n-Service-Status prüfen
4. Server-Ressourcen prüfen (Disk, Memory)

Problem: Ausführungen schlagen fehl

1. Fehlgeschlagene Ausführung in n8n öffnen
2. Prüfen welcher Node fehlgeschlagen ist
3. Fehlermeldung prüfen
4. Häufige Ursachen:
   • API Rate Limit → Warten und Retry
   • Auth abgelaufen → Credentials erneuern
   • Datenformat geändert → Upstream-System prüfen

Problem: Langsame Verarbeitung

1. Queue-Tiefe prüfen
2. Server CPU/Memory prüfen
3. Externe API-Antwortzeiten prüfen
4. Überlegen: Ist Volumen ungewöhnlich hoch?

3. FIX-PROZEDUREN

Workflow neu starten:

1. Workflow deaktivieren (Toggle aus)
2. 10 Sekunden warten
3. Workflow aktivieren (Toggle an)
4. Mit Test-Ausführung verifizieren

Fehlgeschlagene Ausführungen wiederholen:

1. Gehe zu Executions > Failed
2. Ausführung(en) auswählen
3. Retry klicken
4. Auf Erfolg monitoren

n8n-Service neu starten:

[Befehl zum Neustart von n8n - abhängig von eurem Setup]
# Docker: docker restart n8n
# PM2: pm2 restart n8n
# Systemd: sudo systemctl restart n8n

Rollback auf vorherige Version:

1. [Ort der Versionshistorie oder Backups]
2. [Schritte zur Wiederherstellung der vorherigen Version]
3. Mit bekannt-guten Daten testen
4. 30 Minuten monitoren

4. ESKALATION

Wann eskalieren:

• Diagnose nicht möglich innerhalb 30 Minuten
• Fix erfordert Zugang den ihr nicht habt
• Impact betrifft mehrere Mandanten
• Root Cause unklar nach Fix

Eskalationskontakte:

5. NACH DEM INCIDENT

Nach jedem Incident:

• Problem behoben und verifiziert
• Root Cause identifiziert
• Runbook aktualisiert wenn nötig
• Incident geloggt in [Tracking-System]
• Stakeholder benachrichtigt wenn betroffen

Incident-Log-Ort: [URL oder Pfad]

So verwendet ihr dieses Template

Schritt 1: Jetzt ausfüllen

Nicht auf einen Incident warten. Das Template heute für jeden Produktions-Workflow ausfüllen. Die 30 Minuten die ihr jetzt investiert, sparen Stunden während eines Notfalls.

Schritt 2: Zugänglich aufbewahren

• Kopie fürs Büro ausdrucken
• Im Shared Drive speichern
• Vom Monitoring-Dashboard verlinken
• In On-Call-Dokumentation aufnehmen

Schritt 3: Testen

Fire Drill durchführen:

1. Tut so als wäre der Workflow down
2. Dem Runbook folgen
3. Notieren wo Anweisungen unklar sind
4. Entsprechend aktualisieren

Schritt 4: Pflegen

Quartalsweise reviewen:

• Sind Kontakte noch korrekt?
• Haben sich Prozeduren geändert?
• Gibt es neue häufige Probleme?

Nach jedem Incident aktualisieren:

• Hat das Runbook geholfen?
• Was hat gefehlt?
• Was kann hinzugefügt werden um nächstes Mal zu verhindern?

Häufige Runbook-Fehler

Fehler 1: Zu viel Detail

Ein Runbook ist keine vollständige Dokumentation. Es sind Notfall-Anweisungen. Auf eine Seite beschränken. Zu detaillierten Docs verlinken wenn nötig.

Fehler 2: Veraltete Informationen

Falsche Kontaktinfos oder veraltete Prozeduren sind schlimmer als keine. Regelmäßig reviewen.

Fehler 3: Setzt Wissen voraus

Für die Person schreiben die um 2 Uhr nachts einspringt und diesen Workflow nie gesehen hat. Abkürzungen ausschreiben. Exakte Befehle angeben.

Fehler 4: Nicht getestet

Ein Runbook das nie benutzt wurde wird versagen wenn es gebraucht wird. Mit Fire Drill testen.

Fehler 5: Nicht zugänglich

Ein perfektes Runbook in einem Ordner den niemand finden kann ist nutzlos. Mehrere Zugangspunkte: ausgedruckt, digital, vom Monitoring verlinkt.

Beispiel: Mandanten-Intake-Workflow Runbook

WORKFLOW: Mandanten-Intake-Routing-v2

Zweck: Routet neue Mandantenanfragen vom Webformular zum passenden Anwalt basierend auf Rechtsgebiet und Dringlichkeit.

Owner: Sarah K. | Backup: Mike T.

Zuletzt aktualisiert: 2024-01-15

1. HEALTH CHECK

Schneller Check: https://n8n.internal/workflow/5/executions

2. HÄUFIGE PROBLEME

Webhook empfängt keine Daten:
Prüfen: Sendet das Formular an korrekte URL?
Prüfen: Erlaubt Firewall eingehenden Traffic?
Test: Test-Formular absenden, prüfen ob Ausführung erscheint

CRM-Verbindung schlägt fehl:
Prüfen: API-Credentials im n8n Credential Store
Prüfen: CRM-System-Statusseite
Fix: OAuth-Token erneuern wenn abgelaufen

Routing inkorrekt:
Prüfen: Rechtsgebiet-Mapping im Set-Node
Prüfen: Hat Formular neue Rechtsgebiete hinzugefügt?
Fix: Mapping aktualisieren, mit Sample-Daten testen

3. ESKALATION

Diese eine Seite handhabt 90% der Mitten-in-der-Nacht-Probleme.

Nächster Schritt

1. Dieses Template herunterladen/kopieren
2. Für euren kritischsten Workflow ausfüllen
3. Mit dem Team teilen
4. Fire Drill für nächste Woche planen

Der beste Zeitpunkt ein Runbook zu schreiben war vor eurem ersten Incident. Der zweitbeste Zeitpunkt ist jetzt.

Leitfaden: n8n-Betrieb für Kanzleien

Passend:
n8n Versionierung und Releases