PKR-Lab

30070 - n8n — Low-Code-Automatisierung

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/30070-n8n.md

n8n — Low-Code-Automatisierung

Cluster: TECH · Ordner argocd/apps/tech/n8n/ · URL https://n8n.prod.homeserver. kubectl-Befehle in diesem Doc gelten für den TECH-Cluster (Zugriff je Cluster).

n8n ist ein selbst gehosteter Workflow-Automatisierer (Open-Source-Alternative
zu Zapier/Make). Über eine visuelle Oberfläche lassen sich Dienste verknüpfen,
z. B.:


Architektur

n8n.prod.homeserver  →  Traefik  →  n8n (Port 5678)
                                   └── PVC: data (5 Gi, local-path, Node homeserver)

Erster Start

n8n ist nach dem Deploy unter https://n8n.prod.homeserver erreichbar. Beim
ersten Öffnen wird ein Owner-Account angelegt. Das Konto sollte ein starkes
Passwort und 2FA (TOTP, Einstellungen → Persönlich) haben, denn wer
Workflows bearbeiten darf, führt über Code- und Execute-Command-Nodes Befehle im
Pod aus (siehe Sicherheit).


Webhook-Authentifizierung

Die Webhooks, die Tickets oder Benachrichtigungen auslösen, prüfen einen
Header. Der Webhook-Node steht auf Authentication: Header Auth, das
Credential (Typ „Header Auth“, Name Authorization, Wert Bearer <Token>)
liegt in der n8n-Datenbank und nicht im Repo. Ohne gültigen Header antwortet
n8n mit 403.

Webhook Credential in n8n Sender Token beim Sender
/webhook/alamos-einsatz (GET und POST) Webhook alamos-einsatz alamos-relay Schlüssel n8nToken im SealedSecret alamos-relay-secrets
/webhook/banana-pi-down Webhook banana-pi-down Alertmanager (Receiver n8n-banana-pi-down) SealedSecret n8n-webhook-token im Namespace monitoring, gemountet unter /etc/vm/secrets/n8n-webhook-token/token
/webhook/nightly-worker-update Webhook nightly-worker-update nightly-worker-wake.sh auf dem homeserver Vault-Variable vault_n8n_nightly_webhook_token, Datei /etc/nightly-worker-wake/n8n-auth-header

Jede Quelle hat ein eigenes Token, damit eine Rotation nur einen Sender betrifft.
Nach einem Workflow-Import in eine neue Instanz muss das Credential einmal
angelegt und im Webhook-Node ausgewählt werden.

Nicht abgesichert sind bewusst /webhook/instagram-bild (Meta holt das Bild
öffentlich ab, Exact-Match und ^[0-9a-f]{32}$) und /webhook/isc-news
(Aufrufer ist eine externe Website, bewusst offen).

Rotation eines Tokens: neues Token erzeugen (openssl rand -hex 24), beim
Sender hinterlegen (siehe Tabelle) und das n8n-Credential mit
Bearer <neues Token> überschreiben. Bis beide Seiten stimmen, antwortet n8n
mit 403. Das Skript des Nightly-Wake schreibt dann nur eine Journal-Warnung,
für Relay und Alertmanager gilt: Reihenfolge Sender zuerst nicht möglich, weil
der Header-Wert gleich sein muss. Rotation daher zu einer ruhigen Zeit.


Zugang zu ntfy

Alle HTTP-Nodes, die an ntfy senden (zammad-tickets-verarbeiten, email-to-whatsapp-kanal, isc-news-veroeffentlichen, instagram-post-per-mail, isc-urkunden-melden), nutzen das n8n-Credential ntfy-publisher (Typ „Header Auth“, Name Authorization, Wert Bearer <publisher_token>). Das Credential liegt in der n8n-Datenbank und nicht im Repo. Nach dem Import eines Workflows in eine neue Instanz muss es einmal angelegt und in den ntfy-Nodes ausgewählt werden, sonst scheitern sie mit 401/403, sobald ntfy auth-default-access: deny-all hat. Token, Nutzer und Rotation: 10010.


Benachrichtigungsmail an Peter Kretzer

Sechs Workflows schicken zusätzlich zu Zammad oder ntfy eine Mail an [email protected]. Absender ist [email protected], die letzte Zeile jeder Mail ist die Kennung ID-IT-xi8klGKdh8 (dieselbe wie am Ende der KI-Signatur). Empfänger, Absender und Kennung stehen im jeweiligen Mail-bauen-Node.

Workflow Auslöser der Mail Mail-Nodes Inhalt
zammad-tickets-verarbeiten KI-Antwort wurde in Zammad gespeichert (Mail-Entwurf oder interne Notiz) KI-Mail bauen, KI-Mail senden Ticketnummer, Titel, Link, Art der Ablage, Antwort ohne Signatur, interne Hinweise
alamos-einsatz-to-zammad Einsatzalarm angekommen (kein Test-Call, kein Duplikat) Alarm-Mail bauen, Alarm-Mail senden Betreff und Rohdaten des Alarms wie im Ticket
banana-pi-down-to-zammad Alertmanager meldet den Alarmmonitor als nicht erreichbar Ausfall-Mail bauen, Ausfall-Mail senden Text des Tickets samt letzten Metriken
infotafel-herunterfahren Donnerstag 19:15, Erfolg oder Fehler Protokoll-Mail bauen, Protokoll-Mail senden Meldung wie auf ntfy
mdm-auftrag-per-mail Auftrag per Mail oder Formular abgearbeitet, auch bei ungültigem Auftrag Zusammenfassung-Mail bauen, Zusammenfassung-Mail senden Zusammenfassung, was gemacht wurde, mit Problemen
EDV-Kretzer – Status-Hinweis schalten (nur in n8n, nicht im Repo) Formular abgeschickt, parallel zum GitHub-Aufruf Status-Mail bauen, Status-Mail senden Aktion, Bereiche, Text, Gültigkeit

Credential: SMTP Netcup Automations (Typ SMTP, Postfach [email protected], Netcup-Server) in n8n angelegt und den Nodes … Mail senden zugewiesen. Nach einem Import in eine neue Instanz muss sie neu zugewiesen werden, Credential-IDs werden nicht übernommen. Dieselbe Credential-Art nutzt ISC-Urkunden melden.

Verhalten:


Publish: zentrale Meldung und Morgenbericht

Der Workflow publish-benachrichtigung („Publish: Benachrichtigung“) ist der gemeinsame Ausgang für Meldungen. Aufrufer starten ihn per Execute-Workflow-Node (Modus „Einmal je Eintrag“, ohne auf das Ergebnis zu warten). Er sendet je Aufruf an Mattermost (Bot n8n-bot), per HTML-Mail an [email protected] (Absender [email protected]) und per ntfy. Jeder Weg fängt Fehler selbst ab, ein Ausfall eines Weges bricht den Aufrufer nicht ab.

Eingabefeld Wirkung
quelle, titel, text, status (success, error, warning, info) Inhalt der Meldung, Farbe und Plakette der Mail
kanal, kanalId, mattermostText Mattermost-Channel (Standard Berichte) und unveränderter Text
thema, prioritaet, tags, aktionen, klick, anhang ntfy
mattermost, ntfy, mail false schaltet den jeweiligen Weg ab, leer oder fehlend heißt aktiv
mailHtml fertiger HTML-Inhalt für die Mail. Der Aufrufer maskiert selbst. Ohne das Feld wird text maskiert und mit Zeilenumbrüchen eingesetzt

Morgenbericht 06:45

Der Workflow morgenbericht-news läuft täglich um 06:45 Uhr und ruft Publish mit mattermostText (Markdown), mailHtml (dasselbe als HTML), titel („Morgenbericht “) und mail: true auf. Ergebnis ist derselbe Bericht im privaten Mattermost-Channel News und als HTML-Mail. ntfy ist aus. Der Node Bericht bauen wandelt Überschriften, Listen, Tabellen (Termine, Wetter, Versionen), Links, Fett, Kursiv und Trennlinien aus dem Markdown in HTML um.

Abschnitt Inhalt
1. Termine heute Eine Tabelle Zeit, Termin, Ort, Kalender über DLRG, Outlook und HiOrg (Node Termine auswerten, Feld heute). Kopfzeile mit Anzahl, belegtem Zeitraum und Zahl der Überschneidungen. Ganztägige Termine zuerst, mehrtägige mit Ende („bis 16.11.“, „ab 18:00 (mehrtägig)“), Dauer kursiv, überlappende Termine mit ⚠️ (als frei markierte zählen nicht). Danach Wetter und Wochenschau
2. Sicherheitslücken BSI, CISA KEV, heise, The Hacker News, KI-Auswahl über den Ollama-PC
3. Health VictoriaMetrics-Werte, Backups, Zertifikate, Tokens. Die Zeile „Updates“ zählt die Apps mit Update, darunter steht die Tabelle App, läuft, neu (Major-Sprünge mit ⚠️). Quelle ist carplay-api /api/updates aus dem github-release-watcher, der alle Apps aus TECH und PROD prüft
4. News der Woche heise und The Hacker News

Der Workflow in n8n enthält die echten ICS-Links der Kalender, im Repo stehen nur Platzhalter (Hintergrund). Änderungen am Live-Workflow gehören deshalb in die betroffenen Nodes und nicht als Import der Repo-Datei.

Symptom Ursache Abhilfe
Bericht kommt in Mattermost, aber nicht per Mail mail im Node Morgenbericht vorbereiten steht auf false oder SMTP-Credential fehlt Wert auf true, Credential am Node HTML-Mail senden in Publish prüfen
Mail zeigt rohes Markdown (**, |---|) mailHtml wird nicht übergeben Zuweisung mailHtml im Node Morgenbericht vorbereiten prüfen

Beispiel-Workflow: Paperless → ntfy

Trigger: Paperless Webhook (POST /webhook/paperless)
  → HTTP Request: GET paperless.prod.homeserver/api/documents/{id}/
  → ntfy Node: Push "📄 Neues Dokument: {title}"
  1. In n8n: Neuer Workflow → Trigger: Webhook
  2. Webhook-URL aus n8n kopieren
  3. In Paperless: Einstellungen → Workflow-Trigger → URL eintragen
  4. ntfy-Node hinzufügen, Topic und Server konfigurieren

Beispiel-Workflow: xibosignage Inbox → Display

Fertiger, importierbarer Workflow unter
argocd/apps/tech/n8n/workflows/xibosignage-inbox-to-display.json: beobachtet
einen NFS-gemounteten Ordner (/data/xibosignage-inbox) per Local File
Trigger
, skaliert neue Bilder auf eine Pi-taugliche Auflösung (Edit
Image
) und schreibt sie nach /data/xibosignage-display, von wo ein
Raspberry-Pi-Kiosk sie per Slideshow anzeigt. Die beiden Ordner werden dafür
per statischer NFS-PV/PVC in den n8n-Pod gemountet
(values.yaml → xibosignage). Vollständige Anleitung inkl. NAS-Ordner-
Setup und Pi-Rollout: capulus-core/3-apps-workloads/300e0-xibosignage.md.


Beispiel-Workflow: Jährliche Secrets-Rotation → Zammad-Ticket

Fertiger, importierbarer Workflow unter
argocd/apps/tech/n8n/workflows/yearly-secrets-rotation-reminder.json:
Schedule Trigger (jährlich, Default 15. Januar 08:00 Uhr) → nativer
Zammad-Node (Ticket → Create) eröffnet ein Ticket in der Gruppe
Support::Administration als Erinnerung, die zentralen Secrets zu prüfen/
rotieren. Nutzt den echten n8n-nodes-base.zammad-Node (Credential-Typ
„Zammad Token Auth API“), nicht den generischen HTTP-Request-Node wie beim
banana-pi-down-to-zammad.json-Workflow. Vollständige Anleitung inkl.
Rotations-Checkliste je Secret: capulus-core/d-sicherheit/d0060-secrets-rotation.md.


Beispiel-Workflow: Nightly Worker Update → Zammad-Ticket

Fertiger, importierbarer Workflow unter
argocd/apps/tech/n8n/workflows/nightly-worker-update-to-zammad.json:
Webhook (POST /webhook/nightly-worker-update) → Code-Node baut aus
dem JSON-Bericht Titel + lesbaren Text (Status je Worker, geänderte Pakete,
Ansible-PLAY-RECAP, automatischer Reboot) → nativer Zammad-Node (Ticket →
Create) eröffnet ein Ticket in der Gruppe Support::Administration.
Absender ist nightly-worker-wake.sh (läuft nachts um 01:00 Uhr auf dem
Homeserver, siehe capulus-ansible/2-betrieb-hardware/20030-nightly-worker-update.md)
— IMMER am Ende jedes Laufs, egal ob erfolgreich, teilweise fehlgeschlagen
oder komplett abgebrochen. Nutzt denselben n8n-nodes-base.zammad-Node wie
yearly-secrets-rotation-reminder.json.


Beispiel-Workflow: ALAMOS-Einsatzalarm → Zammad-Ticket

Fertiger, importierbarer Workflow unter
argocd/apps/tech/n8n/workflows/alamos-einsatz-to-zammad.json: zwei
Webhook-Trigger (GET und POST, gleicher Pfad /webhook/alamos-einsatz,
je nachdem welche ALAMOS-Webhook-Variante konfiguriert ist — einziger
Auslöser, kein Polling
, die Ziel-URL muss im Alamos-Account eingetragen
sein) → Code-Node führt Query-Parameter/JSON-Body zusammen, gibt alle
empfangenen Felder im Ticket-Text aus und filtert Mehrfach-Auslösungen
desselben Alarms innerhalb von 2 Minuten → nativer
n8n-nodes-base.zammad-Node (Ticket → Create, Credential-Typ „Zammad
Token Auth API", gleiches Muster wie
nightly-worker-update-to-zammad.json) eröffnet ein Ticket in der Gruppe
Support::Administration. Volle Anleitung inkl. Alamos-seitiger
Webhook-Einrichtung und offener Fragen zu den genauen Feldnamen:
capulus-core/3-apps-workloads/300h0-alamos-einsatz-zammad.md.


Beispiel-Workflow: Externer Zammad → KI-Antwortentwurf (Ollama)

Zwei zusammengehörige, importierbare Workflows unter
argocd/apps/tech/n8n/workflows/: ein kleiner Auslöser (A) und die
eigentliche Ticket-Verarbeitung (B). Ollama läuft auf dem Desktop-PC und wird
in B bei Bedarf per Wake-on-LAN geweckt (300g0).

A) zammad-externer-ki-lauf-taeglich.json (Auslöser)

Schedule Trigger (1× täglich, Default 07:00 Uhr) und ein manueller
Trigger rufen per Execute Workflow Sub-Workflow B auf. Mehr passiert hier
nicht: Das Hochfahren und Herunterskalieren eines Ollama-Pods und das feste
Warten entfallen, weil der PC erst dann geweckt wird, wenn B ein Ticket
tatsächlich bearbeitet. An Tagen ohne Tickets bleibt der PC aus.

B) zammad-tickets-verarbeiten.json (Sub-Workflow)

Kein eigener Zeitplan — startet ausschließlich per Execute Workflow
Trigger
, aufgerufen von Workflow A. Nutzt
für alle drei direkten Zammad-Schritte den nativen
n8n-nodes-base.zammad-Node
, dessen Ticket-Ressource nur die
Operationen create/get/getAll/update/delete kennt — es gibt
keine eigene „Ticket Article“-Ressource und getAll akzeptiert
keinerlei Filter-/Query-Parameter (ruft serverseitig ungefiltert
GET /tickets auf der externen Zammad-Instanz https://ticket.emue365.de
auf, anderer Account als zammad.tech.homeserver); zurückgegebene Ticket-Felder
sind zudem rohe IDs (state_id/owner_id/group_id), keine Namen. Der
Workflow filtert deshalb clientseitig im Code-Node „Nur relevante Tickets“
(Zahlenvergleiche numerisch, nicht als String): Es werden bearbeitet
(a) Tickets des Eigentümers owner_id 5 mit Status „new“, „open“ oder
„pending reminder“ oder „pending close“ (state_id 1/2/3/6) und (b) alle Tickets der Gruppe Ausbildung
mit Status „open“, „pending reminder“ oder „pending close“ (state_id 2/3/6), gleich wem sie
zugewiesen sind. Die Gruppen-ID der Gruppe Ausbildung steht fest als AUSBILDUNG_GRUPPEN = [2] im Node
(der Zammad-Account darf GET /groups nicht aufrufen, das lieferte 403 Not authorized;
die ID ergibt sich aus Tickets, die an das Postfach der Ausbildung gehen). Beim ersten echten Testlauf (27.08.2026) zeigte sich außerdem:
der IF-Node verglich owner_id ursprünglich als String gegen das
tatsächlich numerische Zammad-Feld — unbemerkt, solange der Node mit
typeValidation: loose lief, aber sobald n8n ihn beim Öffnen/Speichern in
der UI automatisch auf das neuere Schema (v2.2, typeValidation: strict) hochzieht, bricht der Vergleich hart mit Wrong type ab, sobald
ein Ticket mit numerischem owner_id durchläuft. Bei eigenen Anpassungen
an diesem IF-Node also auf numerische Operatoren/Werte für numerische
Zammad-Felder achten, nicht auf Strings. Der Node
„Ticket-Artikel laden“ ist Ticket: Get (Feld id) — die Zammad-API
liefert dabei automatisch ein articles-Array mit dem Verlauf mit (der
native Node ruft dafür intern zusätzlich /ticket_articles/by_ticket/:id
auf), eine separate „Get Many“-Artikelabfrage ist nicht nötig. Der
Artikel-Verlauf geht an den Ollama-PC. Die Nodes dafür:

  1. LLM-Eingabe bauen (Code): macht aus Ticket und Artikeln die Eingabe
    (mail, history, context) als Base64-JSON, siehe
    300g0. Eine
    interne Notiz, die mit Kontext: beginnt, wird als Zusatzkontext
    mitgegeben.
  2. Ollama erreichbar? (Execute Command): node /opt/ollama-pc/cli.js probe.
  3. PC schläft? (IF): bei „nicht erreichbar“ weiter zu Ollama-PC wecken
    (HTTP-Request POST /api/power/wake, {"target": "ollama-pc"},
    Credential „carplay-api API Token“, bei Fehler geht der Ablauf
    weiter und cli.js meldet danach PC_NOT_WAKING), sonst direkt zum
    nächsten Node.
  4. Ollama-Antwort erzeugen (Execute Command): cli.js chat mit der Eingabe
    auf stdin. Das Skript wartet auf Ollama, lädt das Modell vor, baut den
    Prompt aus prompts/email_system.md und ruft /api/chat auf. Das Skript
    liegt als ConfigMap im n8n-Pod, die Konfiguration kommt aus OLLAMA_* in
    values.yaml (ollamaPc.env).
  5. Antwortentwurf extrahieren (Code): liest die JSON-Ausgabe. Bei einem
    Fehler bricht der Workflow mit der Meldung des Skripts ab
    (Ollama-Anfrage fehlgeschlagen (Ticket #…): PC_NOT_WAKING: …), das Ticket
    bleibt unverändert und wird am nächsten Tag erneut versucht.

Danach entscheidet „LLM-Eingabe bauen“ je Ticket, ob überhaupt ein Entwurf nötig ist.
Übersprungen wird (Meldung im n8n-Pod-Log, der PC wird nicht geweckt), wenn

Der Ticket-Status bleibt unverändert (kein „pending close“ mehr). Einzige
Ausnahme: Stand das Ticket auf „pending reminder“ oder „pending close“ und hat der Kunde geantwortet,
setzt „Status wieder auf offen setzen“ es nach dem Entwurf auf „open“ (state_id 2). Den Schutz
vor Doppel-Entwürfen übernehmen deshalb diese Prüfungen statt des Statuswechsels,
Tags werden weiterhin nicht gesetzt. Beantwortet das Team die Kundenmail und
schreibt der Kunde danach erneut, entsteht ein neuer Entwurf.

Die Ablage hängt vom Ticket ab (modus aus owner_id):

Gibt das Modell [INTERN: …]-Hinweise zurück, landen sie in beiden Fällen
zusätzlich in einer eigenen internen Notiz. Alle drei nativen
Zammad-Nodes nutzen dasselbe, bereits in n8n hinterlegte Credential
„Zammad ticket.emue365“ (Typ „Zammad Basic Auth API“). Zum Schluss
löst der Workflow einen ntfy-Push aus (Topic zammad-ki-entwuerfe, siehe
capulus-core/1-benachrichtigungen/10010-ntfy.md),
damit jemand den Entwurf prüfen und in Zammad manuell freigeben kann.

Wichtig: Der letzte Node „Abschluss (immer genau 1 Item)“ läuft im
Modus „Run Once for All Items“ und wird zusätzlich direkt vom
Trigger-Node gespeist — dadurch liefert dieser Sub-Workflow immer genau
ein Ergebnis-Item
zurück, auch an Tagen mit 0 gefundenen Tickets. Nur so
läuft Workflow A zuverlässig bis zum Ende durch, statt bei
0 Tickets einfach steckenzubleiben. Die dabei gemeldete Zahl
verarbeiteteTickets zieht von der Item-Anzahl bewusst 1 ab
($input.all().length - 1), weil genau diese eine garantierte
Passthrough-Item sonst mitgezählt würde — ungefixt hätte der Node an
Tagen mit 0 echten Tickets fälschlich „1 verarbeitet“ gemeldet (gefunden
beim ersten echten Testlauf, 27.08.2026).

Rein regelbasierte Standardanfragen sollten nicht über diesen
Workflow laufen, sondern direkt über Zammads eigene Trigger/Text-Module
in der externen Instanz — einfacher und ohne LLM-Kosten.

Hinweis zur Zuverlässigkeit: Resource/Operation/Feldnamen der drei
nativen Zammad-Nodes sind anhand des n8n-Zammad-Node-Quelltexts
(n8n-io/n8n, packages/nodes-base/nodes/Zammad) verifiziert, aber die
konkreten IDs (state_id, owner_id, group_id — instanzabhängig)
nicht gegen die laufende externe Zammad-Instanz getestet. Nach dem
Import jeden dieser Nodes einmal öffnen, die CHANGE-ME-Platzhalter durch
echte Werte ersetzen (idealerweise per Dropdown, nicht als Text
eintippen) und prüfen, ob Felder wie erwartet angezeigt werden.

NACH DEM IMPORT zwingend nötig:

  1. Beide Workflows importieren, Sub-Workflow B zuerst. In Workflow A,
    Node „Zammad Tickets verarbeiten“ (Execute Workflow), die echte
    Workflow-ID von B eintragen — wird beim Import nicht automatisch
    verknüpft.
  2. Credential „carplay-api API Token“ (Header-Auth, Authorization: Bearer <TOKEN> — der bereits versiegelte apiToken aus
    argocd/apps/tech/carplay-api/values.yaml, siehe
    300d0-carplay-api.md) anlegen und dem Node
    „Ollama-PC wecken“ in Workflow B zuweisen.
  3. In den nativen Zammad-Nodes in Workflow B („Offene Tickets
    suchen“, „Ticket-Artikel laden“, „Entwurf als interne Notiz speichern“,
    „Interne Hinweise als Notiz speichern“) das bestehende Credential
    „Zammad ticket.emue365“ (Typ Zammad Basic Auth API) neu zuweisen —
    Credential-IDs werden beim Import nicht übernommen.
  4. Für die Shared Drafts das Credential „Zammad ticket.emue365 API-Token“
    (Header Auth, Name Authorization, Wert Token token=<TOKEN>) anlegen und in
    den Nodes „Shared Draft prüfen“ und „Shared Draft speichern“ auswählen. Den
    Token erzeugt der Eigentümer in Zammad unter Profil → Token-Zugriff.
  5. In den Code-Nodes „Nur relevante Tickets“ und „LLM-Eingabe bauen“ die Konstante
    OWNER_ID auf die owner_id des Eigentümers der persönlichen Tickets setzen, in
    „Nur relevante Tickets“ zusätzlich AUSBILDUNG_GRUPPEN auf die Gruppen-ID.
  6. Topic zammad-ki-entwuerfe in der ntfy-App abonnieren.
  7. Der Ollama-PC muss vorher eingerichtet sein (Rolle ollama_pc, Modell
    geladen, ollamaPc.env.OLLAMA_URL gesetzt, Prompts gefüllt) — siehe
    300g0-ollama.md.
  8. Beide Workflows aktivieren — Import allein reicht nicht.

Vor dem produktiven Einsatz: Workflow A einmal manuell auslösen (nicht auf
den täglichen Trigger warten), mit einem Test-Ticket in der externen
Zammad-Instanz und schlafendem PC, damit der Wake-Weg mitgeprüft wird.


Beispiel-Workflow: E-Mail von Absender → WhatsApp-Kanal

Mails mit 1002011 im Betreff werden im Node Nachricht bauen übersprungen und nie an den Kanal gesendet. Der IMAP-Trigger kann Betreffs nicht ausschließen, n8n kennt in den Suchkriterien kein NOT. Deshalb trennt eine Regel im Postfach die Mails: Betreff enthält 1002011 → Ordner ISC-News. Dieser Trigger liest nur die INBOX und sieht die Mails nicht. Der ISC-Workflow liest den Ordner ISC-News (siehe 300k0).

Fertiger, importierbarer Workflow unter
argocd/apps/tech/n8n/workflows/email-to-whatsapp-kanal.json: Trifft eine
Mail von einer bestimmten Adresse ein, landet eine Nachricht (Betreff +
Textauszug, Bilder/Videos als Anhang) in einem WhatsApp-Kanal. Gepostet wird
ausschließlich in diesen einen Kanal — Chats und Gruppen sind gesperrt:
TARGET_ID muss <Ziffern>@newsletter sein, sonst bricht der Workflow ab
(geprüft im Code-Node und noch einmal im Sendeprozess). Das Ziel steht fest im
Workflow und kommt nie aus den Mail-Daten.

Postfach (IMAP, IDLE) ── FROM-Filter ──► Nachricht bauen ──► An WhatsApp senden
   E-Mail von Absender                   (Absender nochmal      (Chromium +
   (Mail danach "gelesen")                prüfen, Betreff        eigener Node-Prozess:
                                          dekodieren, Text)      whatsapp-web.js,
                                                                 Session auf PVC)
                                                │                      │
                                                └── bei Fehler ────────┴──► ntfy "whatsapp-relay"

Inoffizieller Weg, Sperrrisiko akzeptiert. Der Versand läuft über
WhatsApp Web (Bibliothek whatsapp-web.js),
nicht über die offizielle Cloud-API — die kann keine Kanäle befüllen.
WhatsApp verbietet automatisierte Nutzung; das Konto kann gesperrt werden.
Bewusst in Kauf genommen (Business-Konto).

Kanal-Beiträge sind für alle Follower sichtbar. Der Text enthält
standardmäßig die ersten 500 Zeichen der Mail. MAX_BODY_CHARS = 0 im Node
„Nachricht bauen“ schickt nur den Betreff.

Warum ein neues Paket im Image

Das Image enthielt zuvor [email protected]: eine Alpha von 04/2024 mit
Puppeteer 18, ohne Kanal-Unterstützung (kein Channel, keine
@newsletter-IDs) und von einem anderen npm-Account veröffentlicht als das
offizielle Paket. Ersetzt durch [email protected] (Puppeteer 24,
Channel-Klasse, Senden per client.sendMessage('<id>@newsletter', …)).

Warum ein eigener Prozess statt require() im Code-Node

Der n8n-Task-Runner (führt Code-Nodes aus) friert im Prozess alle globalen
Funktionen und ihre Prototypen ein (freezeGlobals() in @n8n/task-runner),
darunter Error.prototype. Puppeteer — von whatsapp-web.js für die
Chromium-Steuerung genutzt — setzt bei seinen Fehlerklassen this.name = … und
scheitert dann mit Cannot assign to read only property 'name' of object 'Error'. Der eigentliche Fehler ist dabei verdeckt. Nachgestellt mit der echten
Bibliothek: ohne Härtung lädt WhatsApp Web, mit Härtung bricht schon
Puppeteers rxjs beim Laden ab.

Deshalb startet der Node „An WhatsApp senden“ pro Ausführung einen normalen
Node.js-Prozess
(child_process.spawn, Funktion waChild im Node, per stdin
mit den Beiträgen gefüttert, Ergebnis als JSON auf stdout). Der Prozess
startet Chromium, sendet, beendet alles und hat eine eigene Zeitüberwachung.
Nötig ist nur NODE_FUNCTION_ALLOW_BUILTIN=child_process; ein Code-Node lädt
whatsapp-web.js selbst nicht mehr. Das gibt Code-Nodes Shell-Zugriff — der
Execute-Command-Node ist wegen NODES_EXCLUDE: "[]" ohnehin aktiv, die
Angriffsfläche wächst also nicht.

Laufzeit-Patches für den Medien-Versand

whatsapp-web.js 1.34.7 kommt mit dem aktuellen WhatsApp Web beim Senden von
Medien (nicht bei Text) an zwei Stellen nicht mehr zurecht. Der Sendeprozess
ändert deshalb vor dem Laden der Bibliothek deren Injektions-Funktion
(patchMediaSend in waChild); jede Änderung entfällt von selbst, sobald eine
künftige Version die Stelle behebt — dann Patch und Funktion entfernen und die
Version im Dockerfile anheben.

Symptom Ursache Änderung
Data passed to getter must include an id property (it's how we memoize) but got undefined Das interne __x_id des Medien-Modells überschreibt die Nachrichten-ID (Issues #201921, #201922) delete message.__x_id;
msg.avParams is not a function WhatsApp Web hat Msg.avParams() entfernt (Issue #201823, PR #201824) Aufruf ersetzt durch WAWebMediaMetadata.mediaMetadata(msg)

Stand 26.09.2026: beide Fixes sind upstream nicht released. Geprüft gegen
WhatsApp Web 2.3000.1048563346: WAWebMediaMetadata.mediaMetadata existiert,
avParams fehlt am Nachrichten-Modell, und beide Änderungen stehen im
injizierten sendMessage. Ob ein Bild damit tatsächlich im Kanal ankommt, ist
erst mit einem echten Lauf bestätigt; weitere Brüche im selben Pfad sind
möglich.

Einrichtung

  1. Image + Konfiguration ausrollen: Änderung an image/Dockerfile und
    values.yaml mergen → Build-Workflow
    baut das Image, der Bump-PR setzt image.tag; nach dessen Merge startet der
    n8n-Pod neu. Reine values.yaml-Änderungen (Env) starten den Pod ebenfalls
    neu. Ohne child_process scheitert der Sende-Node mit
    Module 'child_process' is disallowed, ohne neues Image meldet der
    Sendeprozess Cannot find module 'whatsapp-web.js'.

  2. Workflow importieren (n8n → Workflows → Import from File). Er kommt
    bewusst inaktiv herein.

  3. WhatsApp koppeln und Kanal-ID ermitteln (einmalig, vom Rechner mit
    kubectl-Zugriff auf den TECH-Cluster):

    kubectl -n n8n exec -i deploy/n8n -- node - < argocd/apps/tech/n8n/scripts/whatsapp-pair.js
    

    Im Terminal erscheint ein QR-Code → am Handy in der WhatsApp-Business-App
    Einstellungen → Verknüpfte Geräte → Gerät hinzufügen scannen. Danach listet
    das Skript alle Kanäle (…@newsletter, mit Rolle: owner/admin dürfen
    posten) mit ID. Die Kanalliste füllt sich erst einige
    Sekunden nach dem Start, das Skript wartet dafür bis zu 45 s. Taucht ein
    Kanal trotzdem nicht auf, per Einladungslink auflösen (in der App: Kanal →
    Info → Link teilen; der Code steht hinter whatsapp.com/channel/):
    kubectl -n n8n exec -i deploy/n8n -- node - --invite=<Code> < …/whatsapp-pair.js.
    Die Session liegt danach unter /home/node/.n8n/whatsapp-session auf dem
    n8n-PVC und übersteht Pod-Neustarts.

  4. Platzhalter im Workflow setzen:

    • Node „E-Mail von Absender“: IMAP-Credential zuweisen, in Options → Custom
      Email Rules
      die Adresse in ["UNSEEN", ["FROM", "…"]] eintragen.
    • Node „Nachricht bauen“: SENDER — dieselbe Adresse (oder @firma.de für
      eine ganze Domain). Beides ist Absicht: der Trigger filtert serverseitig,
      der Code-Node prüft ein zweites Mal, bevor etwas in den Kanal geht.
    • Node „An WhatsApp senden“: TARGET_ID (Kanal-ID aus Schritt 3, endet auf
      @newsletter).
  5. ntfy-Topic whatsapp-relay abonnieren (ntfy) —
    dorthin geht der Rückfall bei Fehlern.

  6. Testen, bevor aktiviert wird: im Node „Nachricht bauen“ per Pin Data
    ein Test-Item mit from, subject, textPlain setzen und den Workflow
    manuell ausführen → die Nachricht muss im Kanal erscheinen. Zuerst als
    Trockenlauf (TEST = true), dann echt. Danach
    Workflow aktivieren (Import allein reicht nicht) und eine echte
    Test-Mail vom Absender schicken.

Kanal wechseln

Nur TARGET_ID im Node „An WhatsApp senden“ ändern — die ID des neuen Kanals
liefert whatsapp-pair.js (Schritt 3 der Einrichtung). Voraussetzung: das
gekoppelte Konto muss Inhaber oder Admin des Kanals sein
; steht der Kanal
nicht in der Liste des Skripts, ist es das nicht. Ein Kanal-Inhaber fügt das Konto
in der App unter Kanal → Admins hinzu (Einladung im Konto annehmen), danach
erscheint der Kanal mit Rolle: admin in der Liste. Für einen Kanal, der nicht
aufgelistet wird, löst --invite=<Code> ID und Titel auf und sagt, ob das Konto
darin posten darf. Danach zuerst einen Trockenlauf machen.
Beiträge in einem echten Vereinskanal sind sofort für alle Follower sichtbar —
Tests deshalb weiter im Test-Kanal machen und erst zum Schluss umstellen.

Trockenlauf (TEST)

const TEST = true; im Node „Nachricht bauen“ führt den Workflow komplett
aus — Absender prüfen, Text bauen, Anhänge laden, Chromium starten,
WhatsApp-Session prüfen — und lässt nur den eigentlichen Sendeaufruf weg.
„An WhatsApp senden“ liefert dann pro Beitrag ein Item mit dryRun: true,
sent: false, der Text-Vorschau (text) bzw. Dateiname und bytes des
Anhangs. Damit lassen sich Aufbereitung, Anhangs-Regeln, Ziel-ID-Prüfung und die
Session testen, ohne den Kanal zu befüllen. Ein Fehler wie „nicht gekoppelt“
erscheint im Trockenlauf genauso wie im Echtlauf. Nur der Wert true zählt
('false' als Text schaltet nichts ein). Vor dem Aktivieren wieder auf false
setzen — steht TEST auf true, sendet der aktive Workflow nichts in den
Kanal. Der Trigger markiert die Mail auch im Trockenlauf als gelesen; zum
Testen deshalb besser Pin Data und manuelle Ausführung nutzen, statt eine
echte Mail zu verbrauchen.

Verhalten und Grenzen

Fehlerbehebung

Symptom Ursache / Lösung
Module 'child_process' is disallowed NODE_FUNCTION_ALLOW_BUILTIN=child_process noch nicht ausgerollt. Prüfen: kubectl -n n8n exec deploy/n8n -- env \| grep NODE_FUNCTION
WhatsApp-Prozess endete mit Code 1: … Cannot find module 'whatsapp-web.js' Neues Image noch nicht ausgerollt. Prüfen: kubectl -n n8n exec deploy/n8n -- ls /opt/wwebjs/node_modules/whatsapp-web.js
TARGET_ID muss ein WhatsApp-Kanal sein … Absichtliche Sperre: nur <Ziffern>@newsletter wird akzeptiert, keine Gruppen/Chats
Text gesendet, aber N Anhang/Anhänge fehlgeschlagen: … Data passed to getter must include an id property Bekannter Fehler beim Medien-Versand, siehe Laufzeit-Patches. Der Text ist im Kanal. Erscheint er trotz Patch, ist wahrscheinlich eine neue WhatsApp-Web-Version inkompatibel: Issues von whatsapp-web.js prüfen, Anhänge vorübergehend mit SEND_ATTACHMENTS = false abschalten
Text gesendet, aber N Anhang/Anhänge fehlgeschlagen: … msg.avParams is not a function Entfernte WhatsApp-Web-Funktion, siehe Laufzeit-Patches. Tritt auf, wenn der Node noch die Version ohne diesen Patch enthält: aktuelle JSON importieren
whatsapp-pair.js --invite=…: getRoleByIdentifier is not a function Die Bibliothek sucht die Funktion im alten WhatsApp-Web-Modul. Das Skript hier fragt selbst ab und findet sie im neuen Modul (WAWebNewsletterRoleIdentifier); gilt nur für das Skript, der Workflow nutzt die Einladung nicht
Cannot assign to read only property 'name' of object 'Error' Puppeteer läuft im Runner statt im eigenen Prozess (alte Workflow-Version ohne waChild). Aktuelle JSON importieren
WhatsApp-Session nicht (mehr) gekoppelt (QR-Code angefordert) Session fehlt oder wurde ungültig (z. B. Gerät in der App entfernt, Handy lange offline). whatsapp-pair.js erneut ausführen
Ein anderer WhatsApp-Versand läuft noch (Lock …) Lock von einem hart beendeten Lauf, wird nach ~5 min automatisch übernommen. Sofort: kubectl -n n8n exec deploy/n8n -- rmdir /home/node/.n8n/whatsapp-session.lock
WhatsApp Web wurde nicht rechtzeitig bereit Chromium zu langsam/OOM (Pod-Limit 2 Gi): kubectl -n n8n top pod, kubectl -n n8n describe pod auf OOMKilled prüfen; NFS-Latenz; ggf. READY_TIMEOUT_MS erhöhen
Senden schlägt fehl, obwohl gekoppelt Konto ist im Kanal nicht Inhaber/Admin → in der Ausgabe von whatsapp-pair.js muss bei der Rolle owner oder admin stehen
Nichts passiert bei neuen Mails Workflow aktiv? Execution-Liste ansehen. Wird die Mail vom Filter gefunden (Adresse exakt wie im From, IMAP-Suche ist ein Teilstring-Vergleich)? Bei „Trigger lieferte N Mail(s), aber keine passt zu SENDER“ stimmen Trigger-Filter und SENDER nicht überein

Beispiel-Workflow: ISC-News veröffentlichen

Fertiger, importierbarer Workflow unter
argocd/apps/tech/n8n/workflows/isc-news-veroeffentlichen.json: News per Mail entgegen (Betreff HOMEPAGE1002011, JSON- und Bild-Anhänge),
alternativ über Formular oder Webhook /webhook/isc-news. Der Workflow baut daraus HTML und Base64-Bilder und ruft den internen Dienst
isc-news-bot auf. Der legt die News im DLRG ISC an (siehe 300k0).
Erfolg und Fehler kommen per ntfy, optional mit Freigabe-Button vorher. Einrichtung und
Credential: 300k0, n8n-Workflow einrichten.

Der Workflow spricht den Dienst cluster-intern an. Dafür braucht es keine eigene
Egress-Policy im n8n-Chart: n8n hat bewusst keine Egress-Einschränkung (siehe
d0030, Ingress-only). Eine Policy, die n8n-Egress
einschränkt, würde jeden anderen ausgehenden Aufruf von n8n sperren. Die Ingress-Seite steht
im Chart des Dienstes (allow-ingress-n8n).

Beispiel-Workflow: ISC-Urkunden melden

argocd/apps/tech/n8n/workflows/isc-urkunden-melden.json: Donnerstags von 17:25 bis 20:00 Uhr fragt der Workflow alle 10 Minuten GET /urkunden beim isc-news-bot ab. Der erste Lauf des Abends merkt sich den Stand, danach geht für jede neu angelegte Urkunde (Seepferdchen, Schwimmabzeichen Bronze/Silber/Gold, Juniorretter) eine Mail mit Name, Geburtsdatum, Abzeichen, Prüfer, Prüfernummer und Registriernummer raus. Fehler kommen per ntfy (Topic isc-urkunden). Braucht die Credentials ISC-News-Bot API-Token und SMTP. Einrichtung und Details: capulus-core/3-apps-workloads/300m0-isc-urkunden-melden.md.

Beispiel-Workflow: Instagram-Post per Mail

Fertiger, importierbarer Workflow unter
argocd/apps/tech/n8n/workflows/instagram-post-per-mail.json: Eine Mail mit Betreff INSTAGRAM im Ordner Instagram (JSON-Anhang plus Bilder) wird zu einem Instagram-Beitrag, ein Bild als Einzelpost, mehrere als Karussell. Der Workflow wandelt die Bilder in JPEG um, schneidet sie bei Bedarf auf das erlaubte Seitenverhältnis zu und veröffentlicht über die offizielle Instagram Graph API. Erfolg und Fehler kommen per ntfy (Topic instagram), optional mit Freigabe-Button vorher.

Meta lädt Bilder nur per öffentlicher URL. Ein zweiter Zweig im selben Workflow liefert die kurz abgelegten JPEGs deshalb unter https://instagram-bilder-prod.pke-lab.de/webhook/instagram-bild aus; nur dieser Pfad ist nach außen geroutet, der Rest von n8n bleibt intern. Das erfordert Chart-Änderungen (instagram.* in der values.yaml, ein emptyDir, ein zweiter Ingress). Einrichtung, Meta-Token, Mail-Format, Sicherheit und Fehlerbehebung: capulus-core/3-apps-workloads/300l0-instagram-post-per-mail.md.


Beispiel-Workflows: MDM für iPads

Zwölf Workflows (mdm-*.json) betreiben den MDM-Stack: Basisprofile für neue Geräte, Sperrbildschirm-Text ändern, Ablauf-Überwachung, Verlängerung per Formular, DEP-Sync-Kontrolle, Healthcheck, Backup-Check, Nachricht an iPads, iPads sperren mit Nachricht, App auf iPads installieren, Hintergrundbild ändern und Auftrag per Mail oder Formular (Ordner Ausbildung-Ipads). Sie nutzen die Credentials MDM NanoMDM API, MDM NanoDEP API, MDM Automation DB und MDM Formulare (angelegt von argocd/apps/tech/mdm/scripts/mdm-n8n-setup.sh) sowie die bestehenden ntfy-publisher und Zammad EDV-Kretzer. Zwei Webhooks (/webhook/mdm-event-<Token>, /webhook/mdm-dep-sync-<Token>) rufen NanoMDM und depsyncer aus dem Namespace mdm auf. Beschreibung, Auslöser und Fehlerfälle: 300u0.

Custom Image (n8n-nodes-imap, whatsapp-web.js)

argocd/apps/tech/n8n/image/Dockerfile baut ein eigenes Image auf
Basis des offiziellen n8nio/n8n-Images mit n8n-nodes-imap vorinstalliert
(braucht sonst manuelle Installation über die UI, die bei jedem Pod-Neustart
verloren ginge, da ~/.n8n zwar persistent ist, N8N_CUSTOM_EXTENSIONS
aber bewusst außerhalb davon liegt — Details im Dockerfile-Kommentar).
Zusätzlich sind whatsapp-web.js + qrcode und ein Chromium unter
/opt/wwebjs bzw. /usr/bin/chromium-browser enthalten (siehe
E-Mail → WhatsApp-Kanal).
Gebaut/gepusht wird automatisiert über .github/workflows/build-images.yml
(siehe Chart-README dort
fürs allgemeine Vorgehen, f0060-build-images.md
für Details): jeder Push nach main, der image/Dockerfile ändert, löst
automatisch einen Build+Push nach ghcr.io/pkr-lab/n8n-custom aus — kein
manuelles argo submit mehr nötig.

Bei einem n8n-Versions-Update: FROM n8nio/n8n:<version> im Dockerfile
anpassen und committen/pushen — das baut automatisch. Den im Job-Summary
des Workflow-Runs gemeldeten Tag (sha-<commit-sha>) danach manuell in
image.tag in values.yaml eintragen und committen. n8n-nodes-imap-
Version im Dockerfile (npm install n8n-nodes-imap@<version>) unabhängig
davon aktuell halten, siehe npm-Registry.


Backup

Die Daten liegen auf local-path und damit nur auf der SSD des Nodes homeserver. Dagegen läuft täglich um 02:20 der verschlüsselte, versionierte restic-Job n8n-restic-backup auf das NAS-Volume (Datenbank per sqlite3 .backup, dazu config mit dem Credential-Schlüssel, whatsapp-session, nodes und ssh). Einrichtung, Test und Wiederherstellung stehen in 20010. Der Credential-Schlüssel in config und das restic-Passwort sind die beiden Dinge, ohne die eine Wiederherstellung nicht funktioniert.


Konfiguration (values.yaml)

Key Bedeutung Default
env.N8N_HOST Hostname für interne Links und Webhooks n8n.prod.homeserver
env.WEBHOOK_URL Basis-URL für Webhook-Endpunkte https://n8n.prod.homeserver/
env.N8N_EDITOR_BASE_URL Basis-URL der Oberfläche https://n8n.prod.homeserver
env.N8N_PROTOCOL Protokoll des Pod-Listeners, TLS endet an Traefik http
env.N8N_SECURE_COOKIE Session-Cookie mit Secure-Flag true
persistence.size Datenspeicher (Workflows + SQLite) 5Gi
env.NODE_FUNCTION_ALLOW_BUILTIN Node.js-Builtins für Code-Nodes (WhatsApp-Sendeprozess, MDM-Workflows: crypto, tls) child_process,crypto,tls
env.N8N_RESTRICT_FILE_ACCESS_TO Ordner, die die Nodes zum Lesen und Schreiben von Dateien betreten dürfen /data/xibosignage-inbox;/data/xibosignage-display;/data/instagram-bilder
instagram.enabled Ablage der Instagram-Bilder (emptyDir) und öffentlicher Ingress instagram-bilder-prod.pke-lab.de für den Bild-Abruf durch Meta true
xibosignage.enabled xibosignage-Inbox/Display-NFS-Mounts aktivieren true
resticBackup.enabled verschlüsselter restic-Backup-Job (n8n-restic-backup), braucht resticBackup.encryptedPassword aus scripts/seal-restic-password.sh n8n false
resticBackup.schedule Zeitplan des Backup-Jobs (Zeitzone resticBackup.timezone) 20 2 * * *
resticBackup.keepDaily / keepWeekly / keepMonthly Aufbewahrung der Snapshots 7 / 4 / 6

Sicherheit


Interne CA

Node.js vertraut nur seinem eingebauten Root-Store. Ohne weitere Konfiguration lehnt n8n deshalb HTTPS-Ziele mit Zertifikat der Homeserver-Root-CA ab (UNABLE_TO_VERIFY_LEAF_SIGNATURE), zum Beispiel https://zammad.tech.homeserver. Der Chart legt die Root-CA als ConfigMap n8n-ca an (Kopie von pki/homeserver-root-ca.pem in argocd/apps/tech/n8n/files/), mountet sie unter /etc/ssl/homeserver-ca und setzt NODE_EXTRA_CA_CERTS=/etc/ssl/homeserver-ca/homeserver-root-ca.pem.


Infotafel: Herunterfahren

argocd/apps/tech/n8n/workflows/infotafel-herunterfahren.json fährt die Infotafel (Raspberry Pi, Tailscale-IP 100.105.105.92) jeden Donnerstag um 19:15 Uhr (Europe/Berlin) per SSH herunter.

Auslöser Zeitplan 15 19 * * 4
Ablauf SSH-Node mit dem Credential SSH Infotafel (Herunterfahren) (Benutzer pela, eigener Key) führt sudo /usr/bin/systemctl poweroff aus. Ergebnis und Fehler gehen per ntfy an Home-Lab-System
Voraussetzung auf dem Pi Ansible-Rolle infotafel_poweroff: Der Public Key ist per forced command auf diesen einen Befehl beschränkt, dazu eine sudoers-Freigabe
Netz Der n8n-Pod muss 100.105.105.92:22 über den Tailscale-Knoten homeserver erreichen. Ist die Infotafel aus oder offline, kommt eine ntfy-Fehlermeldung
Wiederstart Der Pi startet nur nach Stromtrennung oder per Zeitschaltuhr