diff --git a/Kapitel 16/Premium Rohtext.md b/Kapitel 16/Premium Rohtext.md new file mode 100644 index 0000000..aa81d69 --- /dev/null +++ b/Kapitel 16/Premium Rohtext.md @@ -0,0 +1,815 @@ +# Premium – Paperless-ngx: Automatisierung, Integration & erweiterte OCR-Verarbeitung + +Paperless-ngx ist im UCC nicht nur eine Dokumentenablage, sondern die Grundlage für ein **vollautomatisiertes Archivsystem**. +Im Free-Kapitel wurde die Basiskonfiguration gelegt – ein zentraler Container mit OCR, Benutzerverwaltung und HTTPS-Zugang. +Dieser Premium-Teil erweitert das Setup zu einer **intelligenten Dokumentenpipeline**, die Dateien automatisch erkennt, verschlagwortet, verteilt und mit anderen Diensten im UCC verknüpft. + +Ziel ist ein **selbstlernendes Dokumentenarchiv**, das ohne manuelle Eingriffe arbeitet: +E-Mails und Cloud-Uploads werden automatisch übernommen, OCR-Ergebnisse mit n8n weiterverarbeitet und fertige Dokumente z. B. in Nextcloud synchronisiert. +Zusätzlich lernst du, wie du die **OCR-Engine optimierst** und Paperless-ngx so konfigurierst, dass mehrsprachige Dokumente fehlerfrei erkannt werden. + +👉 **Screenshot geeignet:** Architekturdiagramm mit Datenfluss zwischen Paperless-ngx, n8n und Nextcloud + +> [!NOTE] +> Dieses Kapitel setzt eine vollständig funktionierende Free-Installation voraus. +> Stelle sicher, dass dein Paperless-Container läuft, über HTTPS erreichbar ist und Dokumente manuell verarbeitet werden können. + +Am Ende dieses Kapitels steht ein vollständig automatisiertes Dokumentensystem, das alle relevanten Quellen selbst erfasst, +automatisch indiziert und nahtlos mit anderen Komponenten des UCC zusammenarbeitet – ohne Cloud-Dienste oder externe APIs. + +--- + +## Erweiterte OCR- und Spracherkennung + +Die standardmäßige OCR-Erkennung in Paperless-ngx ist auf eine Sprache begrenzt und verwendet Basisparameter. +Für produktive Umgebungen lohnt sich eine erweiterte Konfiguration, um mehrsprachige Dokumente und bessere Textergebnisse zu erzielen. + +👉 **Screenshot geeignet:** Ausschnitt aus der Weboberfläche mit aktivem OCR-Status und Fortschrittsanzeige + +### OCR-Sprachen nachinstallieren + +Die Engine **Tesseract** unterstützt mehrere Sprachen gleichzeitig. +Um zusätzliche Sprachpakete zu aktivieren, installiere sie direkt im Container: + +```bash +apt install -y tesseract-ocr-deu tesseract-ocr-eng tesseract-ocr-fra +``` + +Damit erkennt Paperless-ngx deutsche, englische und französische Dokumente parallel. + +> [!NOTE] +> Du kannst beliebig viele Sprachpakete kombinieren. +> Jede zusätzliche Sprache erhöht den Speicherbedarf und verlängert die OCR-Laufzeit – halte die Auswahl also so klein wie möglich. + +#### Verfügbare Sprachpakete (Auswahl) + +| Sprache | Paketname | Code | +|----------|------------|------| +| Deutsch | `tesseract-ocr-deu` | `deu` | +| Englisch | `tesseract-ocr-eng` | `eng` | +| Französisch | `tesseract-ocr-fra` | `fra` | +| Italienisch | `tesseract-ocr-ita` | `ita` | +| Spanisch | `tesseract-ocr-spa` | `spa` | +| Polnisch | `tesseract-ocr-pol` | `pol` | +| Niederländisch | `tesseract-ocr-nld` | `nld` | +| Dänisch | `tesseract-ocr-dan` | `dan` | +| Schwedisch | `tesseract-ocr-swe` | `swe` | +| Norwegisch | `tesseract-ocr-nor` | `nor` | +| Türkisch | `tesseract-ocr-tur` | `tur` | +| Tschechisch | `tesseract-ocr-ces` | `ces` | +| Ungarisch | `tesseract-ocr-hun` | `hun` | +| Kroatisch | `tesseract-ocr-hrv` | `hrv` | +| Portugiesisch | `tesseract-ocr-por` | `por` | +| Rumänisch | `tesseract-ocr-ron` | `ron` | + +Beispiel für zweisprachige Umgebung (Deutsch + Englisch): + +```bash +apt install -y tesseract-ocr-deu tesseract-ocr-eng +``` + +und in der `.env`: + +``` +PAPERLESS_OCR_LANGUAGE=deu+eng +``` + +> [!TIP] +> Wenn du nicht sicher bist, welche Sprachcodes verfügbar sind, kannst du mit +> ```bash +> apt search tesseract-ocr- +> ``` +> alle installierbaren Pakete anzeigen. +> Wähle nur die Sprachen, die du tatsächlich benötigst, um Ressourcen zu sparen. + +👉 **Screenshot geeignet:** Terminalausgabe von `apt search tesseract-ocr-` mit mehreren Sprachpaketen sichtbar + +### OCR-Parameter anpassen + +Die Qualität der Texterkennung hängt stark von den OCR-Einstellungen ab. +Paperless-ngx nutzt standardmäßig nur die nötigsten Parameter – für die Premium-Version optimieren wir sie gezielt, +damit Dokumente in unterschiedlichen Formaten, Sprachen und Layouts zuverlässig erkannt werden. + +Öffne die Konfigurationsdatei: + +```bash +nano /opt/paperless/.env +``` + +Suche den Abschnitt mit den OCR-Einstellungen und passe ihn wie folgt an (oder füge ihn hinzu, falls noch nicht vorhanden): + +``` +# Spracheinstellungen +PAPERLESS_OCR_LANGUAGE=deu+eng+fra + +# Reinigungs- und Verarbeitungsmodus +PAPERLESS_OCR_CLEAN=clean-final +PAPERLESS_OCR_MODE=skip + +# Zusätzliche Tesseract-Parameter +PAPERLESS_OCR_USER_ARGS=--psm 1 --oem 3 +``` + +#### Erklärung der Parameter + +| Variable | Beschreibung | +|-----------|--------------| +| `PAPERLESS_OCR_LANGUAGE` | Definiert die verwendeten Sprachen für die Texterkennung. Hier: Deutsch, Englisch, Französisch. Paperless prüft automatisch jede Seite in allen angegebenen Sprachen. | +| `PAPERLESS_OCR_CLEAN` | Aktiviert eine Nachbearbeitung des Dokuments, um Kontrast, Kanten und Ränder zu optimieren. Der Wert `clean-final` sorgt für bestmögliche Lesbarkeit, besonders bei Scans. | +| `PAPERLESS_OCR_MODE` | Steuert, wann OCR ausgeführt wird. `skip` bedeutet: OCR wird nur bei Bedarf gestartet, wenn keine Textschicht vorhanden ist. So sparst du Ressourcen und beschleunigst den Import. | +| `PAPERLESS_OCR_USER_ARGS` | Übergibt erweiterte Parameter direkt an Tesseract.
`--psm 1` analysiert das gesamte Seitenlayout mit mehreren Textblöcken.
`--oem 3` aktiviert die moderne neuronale Texterkennung (LSTM). | + +> [!TIP] +> Wenn du häufig gescannte Formulare, Quittungen oder Bildschirmfotos importierst, kann `--psm 4` (mehrspaltige Layoutanalyse) oder `--psm 6` (einheitlicher Absatz) bessere Ergebnisse liefern. +> Diese Werte lassen sich gefahrlos testen – die Änderungen greifen sofort nach einem Neustart des Dienstes. + +Speichern (STRG + O, Enter), schließen (STRG + X) und Paperless-ngx neu starten: + +```bash +systemctl restart paperless +``` + +> [!NOTE] +> Änderungen in der `.env` wirken sich nur auf neu importierte Dokumente aus. +> Bereits archivierte Dateien behalten ihre ursprünglichen OCR-Daten. +> Du kannst ältere Dokumente bei Bedarf manuell neu verarbeiten lassen – das wird im Premium-Kapitel zur Automatisierung behandelt. + +👉 **Screenshot geeignet:** geöffnete `.env`-Datei mit kommentierten OCR-Parametern und markiertem Abschnitt `PAPERLESS_OCR_USER_ARGS` + +## Automatisierte Dokumentenverarbeitung mit n8n + +Paperless-ngx kann über n8n automatisiert mit anderen Diensten im UCC interagieren. +Damit lassen sich Dokumente automatisch importieren, sortieren und weiterverarbeiten – +zum Beispiel aus E-Mail-Anhängen, Cloud-Uploads oder gemeinsamen Team-Ordnern. + +👉 **Screenshot geeignet:** Architekturdiagramm mit Datenfluss zwischen E-Mail → n8n → Paperless-ngx → Nextcloud + +### Ziel der Integration + +- Automatischer Import von E-Mail-Anhängen oder Scan-Uploads in Paperless +- Automatische Verschlagwortung und Weitergabe nach OCR-Erkennung +- Übergabe fertiger Dokumente an Nextcloud, Affine oder Kopia +- Zentrale Protokollierung aller Vorgänge in n8n + +### Voraussetzungen + +Damit n8n und Paperless zuverlässig miteinander kommunizieren können, müssen beide Systeme korrekt eingerichtet und erreichbar sein. + +1. **n8n-Container** ist eingerichtet und über HTTPS erreichbar + Test im Browser: + ``` + https://n8n.deinedomain.tld + ``` + Wenn das Dashboard angezeigt wird, funktioniert die Verbindung. + Alternativ im Terminal prüfen: + ```bash + curl -k https://n8n.deinedomain.tld + ``` + Die Ausgabe sollte HTML enthalten. + +2. **Paperless-Container** läuft stabil + Prüfe den Status in Proxmox oder direkt in der Konsole: + ```bash + pct status + ``` + Wenn „stopped“ → starten: + ```bash + pct start + ``` + Anschließend sicherstellen, dass der Dienst aktiv ist: + ```bash + systemctl status paperless + ``` + Die Ausgabe muss **active (running)** anzeigen. + +3. **Paperless REST-API aktiv und erreichbar** + Die REST-API wird automatisch mit dem Dienst gestartet und läuft standardmäßig auf Port **8000**. + Prüfe die Erreichbarkeit: + ```bash + ss -tulpen | grep 8000 + ``` + Eine Zeile mit `0.0.0.0:8000` oder `[::]:8000` zeigt, dass der Port offen ist. + Falls keine Ausgabe erfolgt, starte den Dienst neu: + ```bash + systemctl restart paperless + ``` + Danach Browser-Test: + ``` + http://:8000/api/ + ``` + Wenn eine JSON-Ausgabe erscheint (z. B. `{ "count": 0, "next": null, ... }`), ist die REST-API korrekt aktiv. + +4. **API-Token erstellen** + Melde dich in der Weboberfläche von Paperless-ngx als Administrator an. + Gehe zu **Einstellungen → API Tokens → Neues Token anlegen**. + Vergib einen aussagekräftigen Namen, z. B. `n8n-automation`, und kopiere den generierten Token. + Er wird später im Workflow verwendet. + +> [!NOTE] +> Jeder Benutzer kann eigene Tokens anlegen. Für Automatisierungen empfiehlt sich ein dedizierter technischer Account mit eingeschränkten Rechten. + +👉 **Screenshot geeignet:** Paperless-API-Token-Übersicht mit markiertem Token `n8n-automation` + +### Workflow in n8n erstellen + +Öffne dein n8n-Dashboard und lege einen neuen Workflow an. + +#### Node 1 – IMAP Email (Trigger) + +**Zweck:** Liest neue E-Mails ein und extrahiert Anhänge zur Weiterverarbeitung in Paperless-ngx. + +**Node-Typ:** IMAP Email +**Name:** Eingang – Rechnungsimport + +**Parameter:** +- **Email Protocol:** IMAP +- **Host:** `imap..tld` +- **Port:** `993` +- **SSL/TLS:** aktiviert +- **User:** `` +- **Password:** `` + +> [!NOTE] +> Einige Mailanbieter (z. B. Google, Outlook, GMX, Web.de) blockieren den direkten Login mit dem Hauptpasswort. +> Erstelle ein **anwendungsspezifisches Passwort**, das nur für n8n gilt. +> Anleitung findest du in der Dokumentation deines Anbieters unter „App-Passwörter“ oder „Zugriff durch Drittanbieter“. + +**Optionen:** +- **Download Attachments:** aktiviert +- **Attachment Prefix:** `/data/mail-imports/` +- **Mark Email As Read:** aktiviert + +👉 **Screenshot geeignet:** n8n-Node „IMAP Email“ mit aktivem Attachment-Download + +#### Node 2 – HTTP Request → Upload zu Paperless + +**Zweck:** Sendet die empfangenen Anhänge automatisch über die REST-API an Paperless-ngx. + +**Node-Typ:** HTTP Request +**Name:** Upload → Paperless API + +**Parameter:** +- **Method:** POST +- **URL:** + ``` + https://paperless.deinedomain.tld/api/documents/post_document/ + ``` +- **Authentication:** Header +- **Header Parameter:** + - `Authorization`: `Token ` + - `Content-Type`: `multipart/form-data` +- **Body Parameters:** + - `document`: `{{$binary.data}}` + - `title`: `{{$json["subject"]}}` + - `correspondent`: `"Mailimport"` + +> [!NOTE] +> Paperless akzeptiert Uploads nur mit gültigem API-Token. +> Prüfe Domain, Port und Protokoll (`https://`), sonst antwortet der Server mit 403 oder 401. + +👉 **Screenshot geeignet:** n8n-Workflow mit HTTP Request-Node „Upload → Paperless API“ + +#### Node 3 – HTTP Request → Nextcloud Export + +**Zweck:** Exportiert fertig verarbeitete Dokumente aus Paperless direkt in Nextcloud zur zentralen Ablage. + +**Node-Typ:** HTTP Request +**Name:** Export → Nextcloud + +**Parameter:** +- **Method:** PUT +- **URL:** + ``` + https://nextcloud.deinedomain.tld/remote.php/dav/files//Archiv/{{ $json["title"] }}.pdf + ``` +- **Authentication:** Header +- **Header Parameter:** + - `Authorization`: `Basic ` + - `Content-Type`: `application/pdf` +- **Body:** + - `{{$binary.document.data}}` + +> [!TIP] +> Diese Integration ermöglicht einen vollständigen Dokumentenfluss vom Mail-Eingang über OCR bis zum archivierten PDF in Nextcloud. +> Alternativ kann der Export auch in Kopia oder einen dedizierten Backup-Ordner geleitet werden. + +👉 **Screenshot geeignet:** n8n-Workflow mit allen drei Nodes (IMAP → Paperless Upload → Nextcloud Export) + +### Workflow-Aufbau + +Der Workflow besteht aus **drei Haupt-Nodes**, die direkt miteinander verbunden sind: + +1. **Node 1 (IMAP Email)** → **Node 2 (HTTP Request → Paperless API)** + - Überträgt jede empfangene E-Mail samt Anhang an Paperless-ngx. + +2. **Node 2 (HTTP Request → Paperless API)** → **Node 3 (HTTP Request → Nextcloud Export)** + - Wenn der Upload erfolgreich war (`status == 200`), wird das resultierende Dokument automatisch in Nextcloud gespeichert. + +Damit ergibt sich eine lineare Abfolge: + +``` +IMAP Email → Upload Paperless → Export Nextcloud +``` + +Optional kann zwischen Node 2 und 3 ein **IF-Node** eingefügt werden, +der nur bei erfolgreichem Upload (HTTP 200 OK) den Export ausführt. + +👉 **Screenshot geeignet:** n8n-Canvas mit verbundenen Nodes (1 → 2 → 3) + +--- + +## Automatisches Tagging & Sortierlogik + +Dieser Abschnitt erweitert den bestehenden Workflow aus **Kapitel Premium – Paperless-ngx**. +Du setzt also direkt dort an, wo die Dokumente nach dem Upload bereits in Paperless angekommen sind. +Ziel ist, die erkannten oder importierten Dokumente automatisch zu klassifizieren – zum Beispiel anhand des E-Mail-Betreffs oder Dateinamens. + +👉 **Screenshot geeignet:** n8n-Canvas mit kompletter Verbindung IMAP → Paperless → Nextcloud → Tagging + +### Erweiterung des bestehenden Workflows + +Der bisherige Ablauf endet nach dem erfolgreichen Export in Nextcloud: + +``` +IMAP Email → Upload Paperless → Export Nextcloud +``` + +Daran anschließend folgen nun drei zusätzliche Nodes, die über die Main-Connection mit **Node 3 (Export Nextcloud)** verbunden werden. +Damit wird der Ablauf linear fortgeführt: + +``` +IMAP Email → Upload Paperless → Export Nextcloud → IF Bedingung → Tag Create → Tag Assign +``` + +### Node 4 – IF (Bedingung: enthält Schlagwort) + +**Zweck:** Prüft, ob der E-Mail-Betreff oder der Dateiname ein bestimmtes Schlüsselwort enthält, z. B. „Rechnung“, „Vertrag“ oder „Steuer“. + +**Node-Typ:** IF +**Name:** Bedingung – Enthält Schlagwort + +**Verbindung:** +Eingang von **Node 3 – Export Nextcloud** +TRUE-Ausgang geht an **Node 5 – Tag Create**, FALSE-Ausgang beendet den Workflow. + +**Parameter:** +- **Parameter 1:** `{{$json["subject"]}}` +- **Operation:** Contains +- **Value:** `"Rechnung"` + +👉 **Screenshot geeignet:** IF-Node mit Bedingung `subject contains Rechnung` + +> [!TIP] +> Du kannst mehrere dieser IF-Nodes in Reihe oder parallel verwenden, um verschiedene Kategorien zu erkennen – +> etwa für unterschiedliche Absender, Betreffzeilen oder Dokumenttypen. + +### Node 5 – HTTP Request → Tag erstellen + +**Zweck:** Erstellt in Paperless-ngx automatisch das passende Tag, falls es noch nicht existiert. +Wird das Tag bereits gefunden, liefert die API den bestehenden Datensatz zurück. + +**Node-Typ:** HTTP Request +**Name:** Tag Create → Paperless API + +**Verbindung:** +Eingang von **Node 4 – IF Bedingung (TRUE-Pfad)** +Ausgang an **Node 6 – Tag zuweisen** + +**Parameter:** +- **Method:** POST +- **URL:** + ``` + https://paperless.deinedomain.tld/api/tags/ + ``` +- **Authentication:** Header +- **Header Parameter:** + - `Authorization`: `Token ` + > [!NOTE] + > Verwende hier denselben **API-Token**, den du bereits im Free-Kapitel beim Test der REST-API erzeugt hast. + > Paperless erlaubt mehrere gleichzeitige Tokens pro Benutzer – du kannst denselben Key auch in n8n einsetzen, + > solange der Benutzer dieselben Zugriffsrechte behält. + + - `Content-Type`: `application/json` +- **Body:** + ```json + { + "name": "Rechnung" + } + ``` + +👉 **Screenshot geeignet:** HTTP Request-Node „Tag Create → Paperless API“ + +> [!NOTE] +> Paperless behandelt diesen Vorgang idempotent – das bedeutet, das Tag wird nur einmal angelegt, +> doppelte Requests sind unkritisch. + +### Node 6 – HTTP Request → Tag dem Dokument zuweisen + +**Zweck:** Verknüpft das zuvor angelegte oder vorhandene Tag mit dem zuletzt hochgeladenen Dokument in Paperless. + +**Node-Typ:** HTTP Request +**Name:** Tag Assign → Dokument + +**Verbindung:** +Eingang von **Node 5 – Tag Create** +Keine weiteren Ausgänge erforderlich. + +**Parameter:** +- **Method:** PATCH +- **URL:** + ``` + https://paperless.deinedomain.tld/api/documents/{{ $json["id"] }}/ + ``` +- **Authentication:** Header +- **Header Parameter:** + - `Authorization`: `Token ` + > [!NOTE] + > Verwende hier denselben **API-Token**, den du bereits im Free-Kapitel beim Test der REST-API erzeugt hast. + > Paperless erlaubt mehrere gleichzeitige Tokens pro Benutzer – du kannst denselben Key auch in n8n einsetzen, + > solange der Benutzer dieselben Zugriffsrechte behält. + + - `Content-Type`: `application/json` +- **Body:** + ```json + { + "tags": ["/api/tags/1/"] + } + ``` + +👉 **Screenshot geeignet:** HTTP Request-Node „Tag Assign → Dokument“ + +> [!TIP] +> Die Tag-ID `/api/tags/1/` kann dynamisch aus dem vorherigen Request übernommen werden, +> z. B. mit einem „Set“-Node oder per JavaScript-Ausdruck `{{$json["id"]}}`. + +### Ergebnis + +Damit ist dein Workflow vollständig automatisiert: +Jede eingehende E-Mail wird verarbeitet, hochgeladen, archiviert, und anschließend intelligent getaggt. + +``` +IMAP Email → Upload Paperless → Export Nextcloud → IF Schlagwort → Tag Create → Tag Assign +``` + +Das Ergebnis ist eine vollständig automatisierte Dokumentenpipeline – +von der Eingangsmail bis zur verschlagworteten, archivierten PDF-Datei im UCC-System. + +--- + +## Integration mit anderen UCC-Diensten + +Paperless-ngx fügt sich direkt in die Infrastruktur des UCC ein. +Dokumente werden automatisch kategorisiert, in Nextcloud archiviert, über Kopia gesichert und durch Vaultwarden abgesichert. +In diesem Abschnitt konzentrieren wir uns auf die automatische **Kategorisierung und Ablage in Nextcloud**. + +👉 **Screenshot geeignet:** Diagramm mit Datenfluss Paperless → n8n → Nextcloud + +### Nextcloud – Automatische Ablage und Kategorisierung + +Nach erfolgreicher OCR-Verarbeitung und Tagging sollen die Dokumente automatisch in Nextcloud abgelegt werden. +Die Zuordnung erfolgt über einen **Switch-Node**, der anhand der erkannten Tags entscheidet, +und einen **Merge-Node**, der alle Kategorien wieder zu einem gemeinsamen Strang zusammenführt, +bevor ein einzelner Upload-Node die Datei in Nextcloud schreibt. + +Der vollständige Ablauf: + +``` +IMAP Email → Upload Paperless → Switch Kategorie → Merge Kategorien → Upload Nextcloud +``` + +### Node 7 – Switch (Kategoriewahl) + +**Zweck:** +Analysiert die im JSON enthaltenen Tags und ordnet sie einer definierten Kategorie zu. + +**Node-Typ:** Switch +**Name:** Kategorie bestimmen + +**Verbindung:** +Eingang von **Node 2 – Upload Paperless** + +**Parameter (Community-Version):** +- **Mode:** `Rules` +- **Property Name:** `{{$json["tags"]}}` +- **Routing Rules:** + | # | Data Type | Operation | Value | Beschreibung | + |---|------------|------------|--------|---------------| + | 1 | String | contains | Rechnung | Ausgang 1 | + | 2 | String | contains | Vertrag | Ausgang 2 | + | 3 | String | contains | Versicherung | Ausgang 3 | + +> [!TIP] +> Jede weitere Regel im Switch erzeugt automatisch einen neuen Ausgang. +> So bleibt die Workflow-Struktur klar und skalierbar. + +👉 **Screenshot geeignet:** Switch-Node mit drei Ausgängen (Rechnung, Vertrag, Versicherung) + +### Node 8 – Merge (Kategorien zusammenführen) + +**Zweck:** +Führt die verschiedenen Ausgänge des Switch wieder zu einem einheitlichen Datenstrom zusammen, +damit der Upload zentral ausgeführt werden kann. + +**Node-Typ:** Merge +**Name:** Kategorien zusammenführen + +**Verbindung:** +Eingänge von allen Ausgängen des Switch-Nodes (Rechnung, Vertrag, Versicherung) + +**Parameter:** +- **Mode:** `Merge By Position` + +> [!NOTE] +> Der Merge-Node sorgt dafür, dass alle Dokumente unabhängig von ihrer Kategorie +> gesammelt an den Upload-Node übergeben werden. + +👉 **Screenshot geeignet:** Merge-Node mit drei Eingängen, verbunden mit Switch-Ausgängen + +### Node 9 – HTTP Request (Upload zu Nextcloud) + +**Zweck:** +Lädt das zusammengeführte Dokument in den zentralen Nextcloud-Ordner hoch. +Der Ordnerpfad kann optional dynamisch aus dem Tag abgeleitet werden. + +**Node-Typ:** HTTP Request +**Name:** Upload → Nextcloud + +**Verbindung:** +Eingang von **Node 8 – Merge Kategorien** + +**Parameter (Community-Version):** +- **Method:** `PUT` +- **URL:** + ``` + https://nextcloud.deinedomain.tld/remote.php/dav/files//Archiv/{{$json["tags"][0]}}/{{$json["title"]}}.pdf + ``` +- **Authentication:** Basic Auth +- **User:** `` +- **Password:** `` *(empfohlen: aus Vaultwarden-Secret)* +- **Send Binary Data:** aktiviert +- **Binary Property:** `document` + +> [!TIP] +> Durch die Variable `{{$json["tags"][0]}}` wählt n8n automatisch den ersten erkannten Tag +> als Ordnername. Damit entfällt die manuelle Zuweisung im Switch. + +👉 **Screenshot geeignet:** HTTP-Node mit dynamischer URL und aktivem Binary-Upload + +### Ergebnis + +Der Workflow arbeitet nun vollständig dynamisch: +1. Paperless erkennt und taggt Dokumente. +2. n8n liest die Tags aus. +3. Der Switch verteilt sie logisch. +4. Der Merge fasst alle Ströme wieder zusammen. +5. Ein einzelner HTTP-Request lädt die Datei in den passenden Nextcloud-Ordner. + +Das Ergebnis ist ein sauberer, wartungsfreier Datenfluss – +flexibel erweiterbar und perfekt in das UCC-System integriert. + +### Kopia – Automatische Sicherung der Paperless-Daten + +Damit deine verarbeiteten Dokumente und OCR-Ergebnisse dauerhaft erhalten bleiben, +müssen die wichtigsten Paperless-Verzeichnisse regelmäßig gesichert werden. +Dafür kommt im UCC wie gewohnt **Kopia** zum Einsatz. + +👉 **Screenshot geeignet:** Kopia-Webinterface mit aktivem Backup-Job „Paperless“ + +#### Zu sichernde Verzeichnisse + +| Verzeichnis | Beschreibung | +|--------------|--------------| +| `/opt/paperless/data/` | Enthält alle Dokumente (PDFs, OCR-Dateien, Previews) | +| `/opt/paperless/media/` | Temporäre Uploads und eingehende Dateien | +| `/etc/paperless/` | System- und OCR-Konfiguration | + +Diese Verzeichnisse sollten täglich oder wöchentlich gesichert werden – je nach Änderungsfrequenz. + +#### Snapshot manuell testen + +```bash +kopia snapshot create /opt/paperless/data +``` + +Wenn der Befehl erfolgreich ist, erscheint in der Übersicht ein neuer Eintrag „paperless-data“. +Danach lässt sich das Backup über den Webclient oder den Zeitplan automatisieren. + +> [!NOTE] +> Wenn du bereits eine globale UCC-Sicherungsstrategie hast, in der alle Container-Verzeichnisse erfasst werden, +> brauchst du Paperless nicht separat hinzufügen. +> Prüfe aber, ob die `data`- und `media`-Ordner wirklich enthalten sind. + +👉 **Screenshot geeignet:** Terminalausgabe von `kopia snapshot create /opt/paperless/data` (erfolgreicher Lauf) + +#### Automatisierte Sicherung per n8n (optional) + +Falls du Kopia-Backups direkt aus dem Workflow starten möchtest, +kannst du über einen **HTTP Request** oder **Execute Command Node** den Kopia-CLI-Aufruf anstoßen. + +Beispiel über Execute Command Node: + +**Node-Typ:** Execute Command +**Name:** Kopia Snapshot starten + +**Verbindung:** +Eingang vom letzten Node des Workflows (Upload Nextcloud oder Merge Kategorien) + +**Parameter:** +- **Command:** + ``` + kopia snapshot create /opt/paperless/data + ``` + +> [!TIP] +> Dieser Schritt ist optional, aber praktisch, wenn du Dokumentenverarbeitung und Sicherung koppeln möchtest. +> So kannst du nach jedem Upload automatisch ein Snapshot-Update auslösen. + +👉 **Screenshot geeignet:** Execute Command Node „Kopia Snapshot starten“ mit Command-Feld + +### Vaultwarden – Sichere Verwaltung sensibler Zugangsdaten + +Für die sichere Speicherung von Zugangsdaten, Tokens und Passwörtern nutzt du Vaultwarden. +So stellst du sicher, dass n8n keine sensiblen Daten im Klartext enthält. + +#### Vorgehensweise + +1. Öffne die Vaultwarden-Weboberfläche. +2. Erstelle einen neuen **Eintrag vom Typ „API Key“**. +3. Vergib den Namen `Paperless_API_Token`. +4. Trage dort den im Free-Kapitel erstellten Paperless-Token ein. +5. Optional: Lege auch Nextcloud- und SMTP-Logins als separate Secrets an. +6. Exportiere die Secrets als Umgebungsvariablen für n8n: + ```bash + export PAPERLESS_API_TOKEN= + export NEXTCLOUD_PASS= + ``` +7. In n8n kannst du dann auf diese Werte zugreifen, z. B.: + ``` + {{$env.PAPERLESS_API_TOKEN}} + ``` + +> [!NOTE] +> Diese Methode schützt alle sensiblen Daten zuverlässig, +> da sie nicht in exportierten Workflows oder Logs auftauchen. + +👉 **Screenshot geeignet:** Vaultwarden-Eintrag „Paperless_API_Token“ mit ausgeblendeten Werten + +Mit dieser Integration ist das System komplett: +- Paperless verarbeitet und erkennt Dokumente, +- n8n organisiert sie automatisch, +- Nextcloud speichert sie zentral, +- Kopia sichert sie regelmäßig, +- Vaultwarden schützt alle Anmeldeinformationen. + +Damit ist dein UCC vollständig automatisiert, sicher und transparent dokumentiert. + +--- + +## Überwachung & Health-Checks mit Netdata + +Damit Paperless-ngx im Dauerbetrieb stabil läuft, sollte die Instanz über Netdata überwacht werden. +So erkennst du Engpässe, ungewöhnliche CPU-Last durch OCR-Verarbeitung oder verzögerte Uploads frühzeitig. +Die Integration erfolgt wie bei allen anderen Containern über das Netdata-Streaming-System. + +👉 **Screenshot geeignet:** Netdata-Dashboard mit aktiver Paperless-Instanz (CPU-Last und I/O-Aktivität sichtbar) + +### Paperless-Container als Child hinzufügen + +1. Öffne die Konsole deines Paperless-Containers. +2. Installiere den Netdata-Agent (falls noch nicht vorhanden): + ```bash + bash <(curl -Ss https://my-netdata.io/kickstart.sh) --stable-channel --disable-telemetry + ``` +3. Öffne die Streaming-Konfiguration: + ```bash + nano /etc/netdata/stream.conf + ``` +4. Ergänze oder ändere die folgenden Zeilen: + ``` + [stream] + enabled = yes + destination = :19999 + api key = paperless-ngx + hostname = Paperless + ``` +5. Dienst neu starten: + ```bash + systemctl restart netdata + ``` + +> [!NOTE] +> Der Parent-Container ist deine zentrale Netdata-Instanz aus Kapitel 15. +> Stelle sicher, dass Port 19999 intern erreichbar ist. + +👉 **Screenshot geeignet:** `stream.conf` mit konfiguriertem `destination`-Eintrag + +### Relevante Metriken + +Nach dem Neustart erscheint der Paperless-Container automatisch im Netdata-Dashboard. +Wichtige Kennzahlen: + +| Bereich | Beschreibung | +|----------|--------------| +| **CPU usage** | Belastung durch OCR-Prozesse (`tesseract` oder `celery`) | +| **Disk I/O** | Schreibaktivität in `/opt/paperless/data/` | +| **Network** | Upload-Volumen zu Nextcloud | +| **Processes** | Laufende Worker- und Gunicorn-Prozesse | +| **Memory** | Puffer- und Cacheverbrauch während OCR-Phasen | + +> [!TIP] +> Dauerhafte CPU-Last über 80 % deutet oft auf parallel laufende OCR-Jobs hin. +> In diesem Fall kann ein Neustart des Containers oder eine Erhöhung der CPU-Zuteilung sinnvoll sein. + +👉 **Screenshot geeignet:** Paperless-Dashboard mit CPU- und Disk-I/O-Diagrammen + +### Alarmierung (optional) + +Wenn du bereits das Premium-Netdata-Kapitel umgesetzt hast, +kannst du dortige Alarmregeln wiederverwenden, um bei hoher CPU-Last oder Fehlern im OCR-Dienst benachrichtigt zu werden. + +Beispielregel in `/etc/netdata/health.d/paperless.conf`: + +``` +alarm: paperless_cpu_high +on: system.cpu +lookup: average -1m unaligned of user + system +units: % +every: 30s +warn: $this > 80 +crit: $this > 95 +to: sysadmin +info: Paperless CPU usage is too high +``` + +> [!NOTE] +> Die Regel nutzt den gleichen Benachrichtigungskanal wie deine bestehenden Alerts (Discord, Mail oder n8n-Webhook). +> Du kannst auch spezifische Health-Checks nur für Paperless aktivieren. + +👉 **Screenshot geeignet:** Health-Tab in Netdata mit aktiviertem Alarm „paperless_cpu_high“ + +Damit ist Paperless-ngx in dein bestehendes Monitoring eingebunden. +Alle wichtigen Metriken erscheinen zentral in Netdata, +und Störungen können sofort erkannt oder automatisch weitergeleitet werden. + +--- + +## Ergebnis + +Nach Abschluss dieses Premium-Kapitels ist Paperless-ngx vollständig in das UCC integriert – +nicht nur als Dokumentenarchiv, sondern als **intelligentes, automatisiertes Verwaltungssystem**, +das sich nahtlos in Nextcloud, Netdata, Kopia und Vaultwarden einfügt. + +Deine UCC-Struktur arbeitet jetzt folgendermaßen: + +| Dienst | Aufgabe | Automatisierung | +|---------|----------|----------------| +| **Paperless-ngx** | Zentrale Dokumentenverarbeitung (OCR, Tagging, Indexierung) | verarbeitet E-Mails und Uploads automatisch | +| **n8n** | Workflow-Automatisierung | verteilt, verschiebt und kategorisiert Dokumente in Nextcloud | +| **Nextcloud** | Speicherung und gemeinsame Nutzung | erhält automatisch sortierte Dateien | +| **Kopia** | Sicherung | erstellt Snapshots der relevanten Verzeichnisse | +| **Vaultwarden** | Zugriffsschutz | verwaltet Tokens und Zugangsdaten verschlüsselt | +| **Netdata** | Überwachung | kontrolliert Ressourcenauslastung, OCR-Last und Systemzustand | + +👉 **Screenshot geeignet:** Gesamtübersicht des UCC mit Paperless, n8n, Nextcloud, Netdata, Kopia und Vaultwarden + +### Vorteile des erweiterten Paperless-Setups + +* **Vollautomatischer Dokumentenfluss:** + E-Mails und Scans werden automatisch erkannt, verarbeitet und abgelegt – ohne manuelles Eingreifen. + +* **Kategorisierung über Tags:** + Intelligente Klassifikation in Nextcloud-Ordner auf Basis von Tags oder OCR-Inhalten. + +* **Zentrale Sicherung:** + Kopia erstellt eigenständig Snapshots der Paperless-Daten und OCR-Cache-Dateien. + +* **Transparente Systemüberwachung:** + Netdata überwacht die Ressourcennutzung, erkennt Engpässe und alarmiert bei Überlastung. + +* **Sichere Zugangsdaten:** + Vaultwarden hält alle API-Tokens und Passwörter zentral unter Kontrolle. + +> [!TIP] +> Dieses Setup ist modular erweiterbar: +> Du kannst später PDF-Kompression, Texterkennung für zusätzliche Sprachen oder direkte Uploads aus mobilen Apps ergänzen. +> Alles fügt sich sauber in die bestehende Struktur ein. + +### Zusammenfassung der Architektur + +``` +📧 Eingang → Paperless-ngx (OCR, Tagging) + ↓ +🔁 n8n → (Switch → Merge → Upload → Nextcloud) + ↓ +💾 Kopia → Sicherung der Daten + ↓ +🧠 Vaultwarden → Schlüsselverwaltung + ↓ +📊 Netdata → Monitoring & Alerts +``` + +👉 **Screenshot geeignet:** Architekturdiagramm mit allen Datenflüssen zwischen Paperless, n8n, Nextcloud, Kopia, Vaultwarden und Netdata + +Damit ist dein Dokumenten-Workflow im UCC vollständig automatisiert, +datensicher, erweiterbar und zentral überwacht – +ein System, das für Streamer, Kreative und Technikinteressierte gleichermaßen praxistauglich ist. \ No newline at end of file