Paperless-ngx im Lab: vom Scan zum brauchbaren Archiv

Ein Dokumentenarchiv ist mehr als OCR hinter einer Weboberfläche. Wie ich Scanner, Mailimport, PostgreSQL, kontrollierte KI-Klassifikation und Off-site-Backups zusammenführe — und warum Eigentümer, Upload-Grenzen und Restore-Zeitpunkte dabei wichtiger sind als der Modellname.
Table of contents

Nach dem Scannen liegt die Rechnung als scan_0042.pdf in einem Verzeichnis. Sie lässt sich öffnen, aber ohne brauchbaren Namen und Metadaten später nur schwer wiederfinden. Bei E-Mails ist es ähnlich: Der Anhang ist vorhanden, sein Zusammenhang steckt jedoch im Postfach. Ob beides zuverlässig gesichert ist, muss zusätzlich geklärt werden.

Paperless-ngx soll in meinem Lab Dokumente aufnehmen, durchsuchbar machen und mit brauchbaren Metadaten versehen. Nach dem ersten erfolgreichen Upload ging es vor allem darum, den gesamten Ablauf verlässlich zu gestalten: Wie landet ein Scan vollständig im Archiv? Was darf ein Sprachmodell entscheiden? Und wie stelle ich Dateien und Datenbank so wieder her, dass sie zusammenpassen?

Das Archiv ist eine Verarbeitungskette#

Ich betreibe Paperless als eigene Anwendung im Kubernetes-Cluster statt auf einem zusätzlichen NAS. Die Infrastruktur kommt über Flux aus Git; der Anwendungszustand liegt auf Ceph und in PostgreSQL.

flowchart LR SC[Scanner] --> SF[SFTPGo-Sidecar] SF --> CO[Consume-Verzeichnis] MAIL[Ausgewählte E-Mails] --> PL[Paperless-ngx] CO --> PL WEB[Web-Upload] --> PL PL --> PG[(PostgreSQL)] PL --> DF[Dragonfly / Task Queue] PL --> CONV[Tika und Gotenberg] PL --> AI[LiteLLM] AI --> CLOUD[Ollama Cloud] PL --> FILES[(Dokumente auf Ceph)]

Die Bausteine haben bewusst getrennte Aufgaben:

BausteinVerantwortung
Paperless-ngxImport, OCR, Suche, Dokumente und Metadaten
CloudNativePGPostgreSQL für das Archiv; separate Datenbank für LiteLLM
DragonflyRedis-kompatible Task- und Koordinationsdienste
Tika und GotenbergExtraktion und Konvertierung zusätzlicher Dokumentformate
SFTPGokontrollierter Übergang vom Scanner ins Consume-Verzeichnis
LiteLLMModellzugang, virtuelle Schlüssel und Budgetkontrolle

Paperless ist auf Version 3.1.2 samt Image-Digest festgelegt. Für OCR sind Deutsch und Englisch konfiguriert, für die Suche Deutsch. Zwei Task-Worker mit jeweils einem Thread begrenzen die parallele Verarbeitung. Damit bleibt der Aufbau überschaubar, sein Durchsatz ist aber entsprechend begrenzt.

Paperless und seine PostgreSQL-Instanz laufen jeweils als Singleton und sind in diesem Aufbau nicht hochverfügbar. Ich nutze den Cluster hier vor allem für deklarativen Betrieb, gemeinsamen Storage, Netzwerkregeln und Backups.

Ein Volume, aber mehrere Arten von Zustand#

Ein 100-GiB-RWO-Volume enthält die Unterverzeichnisse data, media, consume und export. Die Deployment-Strategie ist Recreate: Bei einem Update soll nicht ein zweiter Paperless-Pod gleichzeitig dasselbe Dokumentenvolume bearbeiten.

Die Trennung innerhalb des Volumes ist praktisch, ersetzt aber keine Trennung der Verantwortlichkeiten:

  • Dokumentdateien liegen auf dem PVC.
  • Metadaten, Benutzer, Mailregeln und Workflows liegen in PostgreSQL.
  • LiteLLM-Schlüssel und Abrechnungszustand liegen in einer eigenen Datenbank.
  • Die gewünschte Infrastruktur liegt in Git.

Für eine Wiederherstellung reicht deshalb eine Sicherung der YAML-Dateien nicht aus. Ein frischer Flux-Reconcile baut zwar die Dienste wieder auf, rekonstruiert aber nicht die Regeln aus der Paperless-Datenbank.

Der Scanner bekommt einen schmalen Eingang#

Für den Scanner ist ein SFTP-Endpunkt vorgesehen, hinter dem ein SFTPGo-Sidecar im Paperless-Pod sitzt. Eine allgemeine Dateifreigabe auf das Archiv bekommt er nicht. Beide Container sehen dasselbe Consume-Verzeichnis; das RWO-Volume muss dadurch nicht für einen zweiten Pod geöffnet werden.

Der Sidecar läuft im Portable Mode und braucht dafür weder eine zusätzliche Administrationsoberfläche noch eine eigene Datenbank. Sein Konto darf auflisten, hochladen und vorhandene Upload-Dateien ersetzen. SSH-Kommandos sind nicht Teil dieses Zugangs. Akzeptiert werden die vorgesehenen Scanformate wie PDF, JPEG, PNG und TIFF.

Damit Paperless nur vollständige Scans verarbeitet, ist der atomare Upload aktiviert. SFTPGo schreibt zunächst eine verborgene temporäre Datei und benennt sie erst nach erfolgreichem Transfer um. So wird der Scan nicht schon während der Übertragung vom Consumer aufgenommen.

1Upload beginnt → temporäre Datei → Transfer vollständig → Umbenennen → Consumer

Diese Übergabe verhindert das schwer reproduzierbare Timing-Problem zwischen Upload und Consumer. Eine verteilte Transaktion über das gesamte Archiv entsteht dadurch allerdings nicht.

Der externe SFTP-Zugang läuft über eine LAN-LoadBalancer-Adresse und ist auf die Scanneradresse eingeschränkt, zusätzlich durch die NetworkPolicy. Pod-Verkehr innerhalb des Paperless-Namespace bleibt durch die gemeinsame Policy erlaubt. Für ältere Scanner-Firmware sind einige ältere SSH-Algorithmen zugelassen. Das ist ein bewusster Kompatibilitätskompromiss an einem eng begrenzten Eingang, kein Muster für einen öffentlich erreichbaren SSH-Dienst.

Ein Scanauftrag entspricht einem Dokument. Rechnung, Vertrag und Brief müssen daher entweder getrennt gescannt oder durch eine ausdrücklich konfigurierte mechanische Trennung aufgeteilt werden. Die spätere semantische Klassifikation durch ein Sprachmodell übernimmt diese Aufgabe nicht zuverlässig.

E-Mail-Import: Auswahl vor Automatik#

Beim Mailimport möchte ich selbst entscheiden, welche Nachrichten ins Archiv gelangen. Der öffentlich dokumentierte Ablauf beginnt deshalb mit einer bewussten Auswahl von Nachrichten statt einer Regel über die komplette Inbox.

Das Modell verwendet drei Ordner. Mit neutralen Beispielnamen sieht es so aus:

1Archiv/Import
2    │ vollständige Nachricht als EML aufnehmen
3    ▼
4Archiv/Anhänge
5    │ unterstützte, nicht eingebettete Anhänge separat aufnehmen
6    ▼
7Archiv/Verarbeitet
8    └─ aufbewahren, abgleichen, erst später manuell löschen

Der Ablauf trennt diese Schritte, weil bei der eingesetzten Paperless-Version Teile der Verarbeitung asynchron laufen. Beim gleichzeitigen Import von Mail und Anhängen könnte die Nachricht schon verschoben werden, während ein zweiter Verarbeitungszweig noch arbeitet. Zwei getrennte Regeln sollen dieses Rennen vermeiden und machen den Fortschritt an der Ordnerposition erkennbar.

Der letzte Ordner ist dabei kein automatischer Papierkorb. Eine erfolgreich abgeschlossene Importaktion beweist noch nicht, dass jede Nachricht und jeder Anhang im gewünschten Zustand wiederherstellbar ist. Vor dem Löschen gehören Abgleich, Integritätsprüfung und ein getesteter Rückweg dazu.

Beim Einrichten der Regeln muss außerdem der IMAP-Ordnertrenner stimmen. Was ein Mailclient als Archiv/Import anzeigt, kann auf dem Server beispielsweise Archiv.Import heißen. Für die Regel zählt der tatsächliche Servername, nicht die Darstellung im Client.

Mailregeln und Klassifikationsworkflows sind Datenbankzustand, keine vollständig aus den Kubernetes-Manifesten erzeugte Konfiguration. Der Ablauf ist in der öffentlichen Repository-Historie dokumentiert. Für eine eigene Installation müssen die Regeln angelegt und mit Testnachrichten geprüft werden; die bloße IMAP-Netzwerkfreigabe richtet keinen Import ein.

Ein identischer Anhang ist nicht dasselbe wie ein ähnlicher Scan#

Die konfigurierte Duplikatbehandlung erkennt byteidentische Originale über ihre Prüfsumme. Derselbe PDF-Anhang aus einer erneut eingelesenen Mail kann dadurch als bereits vorhanden erkannt werden, ohne die Importkette dauerhaft aufzuhalten.

Ein neuer Scan desselben Papierblatts hat dagegen fast sicher andere Bytes. OCR-Ähnlichkeit kann Kandidaten liefern, ist aber keine verlässliche Löschentscheidung. Gerade bei Rechnungen können zwei fast identische Dokumente unterschiedliche Geschäftsvorgänge sein.

Deshalb würde ich mit einer kleinen Auswahl beginnen und die Treffer prüfen, bevor ich größere Bestände importiere. Ein unscharfer Vergleich nach dem Import eines ganzen Postfachs wäre keine verlässliche Grundlage, um Dokumente zu löschen.

KI ist ein Klassifikator, kein Archivverwalter#

Die KI-Anbindung nutzt Paperless’ integrierte Metadatenvorschläge. paperless-ai ist dabei ein interner Modellalias, kein zusätzlich installierter Dienst gleichen Namens.

Der tatsächliche Pfad lautet:

1Paperless
2  → OpenAI-kompatible interne API von LiteLLM
3  → native Ollama-Chat-API
4  → mistral-large-3:675b-cloud

„OpenAI-kompatibel“ bezeichnet hier das Protokoll zwischen Anwendung und Gateway, nicht den verwendeten Cloudanbieter. Das Modell läuft bei Ollama Cloud, nicht lokal auf meinen Cluster-Nodes.

Über das Gateway erhält Paperless einen begrenzten virtuellen Schlüssel; der Provider-Schlüssel bleibt bei LiteLLM. Außerdem lassen sich Modellroute, Parallelität und Budget dort zentral kontrollieren, ohne diese Funktionen in jeder Anwendung neu zu implementieren.

Strukturierte Ausgabe ist eine Schnittstelle#

Damit Paperless die Vorschläge verarbeiten kann, muss der Klassifikator Daten in der erwarteten Struktur liefern. Der konfigurierte Pfad fordert deshalb den nativen DocumentClassifierSchema-Tool-Call.

Diese Tool-Calls müssen vom Modell über die gewählte Providerroute bis zum Paperless-Parser erhalten bleiben. Ob das funktioniert, muss für die strukturierten Ausgaben geprüft werden; die nominelle API-Kompatibilität allein reicht als Nachweis nicht aus.

Ein versionsgebundener Kompatibilitätspatch fordert deutsche Titel, Tags und Dokumenttypen bereits im ersten Aufruf an und unterdrückt einen zweiten Lokalisierungsschritt. Eigennamen sollen unverändert bleiben. Das reduziert eine zusätzliche Fehlerstelle, ist aber auch eine bewusst eingegangene Wartungslast.

Der Patch prüft seine erwarteten Quelltextstellen exakt. Passt ein zukünftiges Paperless-Image nicht mehr dazu, schlägt der Init-Schritt fehl. Dadurch wird eine inkompatible Änderung sichtbar, bevor eine falsch gepatchte Klassifikation unbemerkt weiterläuft.

Für Updates müssen deshalb Image und Kompatibilitätspfad gemeinsam getestet werden. Der Austausch des Digests allein reicht als Upgrade-Test nicht aus.

Die überraschend wichtige Reihenfolge: erst Eigentümer, dann Vorschläge#

Der öffentlich dokumentierte Klassifikationsablauf trennt deterministische Zuweisung von asynchroner KI-Arbeit:

  1. Zu Beginn der Verarbeitung werden Eigentümer und ein fester Ablagepfad zugewiesen.
  2. Nach dem Anlegen und Parsen des Dokuments wird die KI-Klassifikation angestoßen.
  3. Das Ergebnis darf ausgewählte Metadaten ergänzen beziehungsweise ersetzen.

Diese Reihenfolge ist wichtig, weil Paperless die Vorschläge mit der Taxonomie abgleicht, die für den Dokumenteigentümer sichtbar ist. Bei einem Scan ohne Eigentümer können vorhandene, benutzereigene Tags oder Dokumenttypen daher nicht wie erwartet zugeordnet werden. Der Anwendungskontext muss feststehen, bevor die KI-Antwort verarbeitet wird.

Auch der Ablagepfad bleibt eine feste Workflow-Entscheidung. Damit ist vorgegeben, in welchen organisatorischen Bereich ein Dokument gehört; das Modell entscheidet nicht darüber. Die Zugriffskontrolle erfolgt unabhängig vom Verzeichnisnamen über Eigentümer, Gruppen und Dokumentberechtigungen.

Für die eigentlichen Vorschläge beschreibt das Runbook folgende Auswahl:

1Felder:             Titel, Tags, Dokumenttyp, Dokumentdatum
2Neue Taxonomie:     nicht automatisch erzeugen
3Vorhandene Werte:   für diese Felder überschreiben erlauben
4Ablagepfad:         nicht vom Modell wählen lassen
5Benutzerdef. Felder: nicht durch KI-Vorschläge befüllen

Das Überschreiben ist hier nötig, weil ein frisch eingelesener Scan bereits den Dateinamen als Titel und ein Datum besitzt. Würden nur leere Felder gefüllt, blieben gerade diese Werte oft unverändert.

In einem synthetischen Beispiel kann aus scan_0042.pdf der Titel „Rechnung Beispiel GmbH – September 2026“ werden, ergänzt um den vorhandenen Dokumenttyp Eingangsrechnung. Daraus lässt sich noch nicht ableiten, dass Rechnungsnummer, Zahlungsstatus oder ein prüfpflichtiger Geldbetrag korrekt extrahiert wurden. Dafür bleibt ein eigener, kontrollierter Arbeitsschritt nötig.

Klassifiziert heißt nicht geprüft. Ein plausibler Titel und passende Tags bestätigen weder Betrag noch Fälligkeit, steuerliche Einordnung oder Vollständigkeit. Auch Temperatur null macht ein Sprachmodell nicht zu einem deterministischen Validator.

Die KI-Aktion ist vom eigentlichen Import entkoppelt. Schlägt sie fehl, soll das Dokument trotzdem aufgenommen werden und für die manuelle Nachbearbeitung vorhanden bleiben. Im dokumentierten Ablauf sind Wiederholungen nach Timeouts begrenzt. Ein Budgetblock lässt sich durch erneute Anfragen nicht beheben und darf daher keine endlosen Retries auslösen.

Kostenkontrolle braucht einen verlässlichen Zähler#

LiteLLM begrenzt den virtuellen Schlüssel auf den vorgesehenen Modellalias. Dazu kommen eine parallele Anfrage, zehn Requests pro Minute, 50.000 Tokens pro Minute und maximal 2.048 Ausgabetokens pro Antwort.

Für die Abrechnung sind Tages- und Monatsfenster konfiguriert: 15 beziehungsweise 300 in LiteLLMs USD-Recheneinheiten. Diese Werte werden mit hinterlegten Tokenpreisen verrechnet. Sie sind keine Zusicherung über die tatsächliche Rechnung oder Vertragslogik des Providers.

Damit diese Grenzen auch bei Fehlern gelten, hängen die Budgetreservierungen an PostgreSQL. Ist der maßgebliche Abrechnungszustand nicht verfügbar, soll das Gateway Anfragen ablehnen, statt sie ungezählt durchzulassen.

Ein kleiner Reconciler hält Schlüssel und Limits aktuell. Er schreibt die Budgetfenster jedoch nicht bei jedem Lauf erneut: Die eingesetzte LiteLLM-Logik kann dadurch den Reset-Zeitpunkt verschieben. Eine vermeintlich idempotente Aktualisierung hätte dann die Grenze verändert, die sie eigentlich durchsetzen soll.

Bei den Kontextgrößen ist zwischen Anwendung und Modell zu unterscheiden. Paperless ist auf 8.192 Tokens konfiguriert, auch wenn die Gateway-Metadaten ein größeres Modellfenster beschreiben. Die Providerkonfiguration erweitert das Limit in Paperless nicht automatisch und stellt somit keine vollständige Auswertung langer Verträge sicher.

Datenschutz ist ein Datenfluss, kein Standortetikett#

Obwohl das Archiv im eigenen Cluster läuft, verlassen Dokumentinhalte für die Cloudklassifikation diese Umgebung.

Deshalb gehört vor automatische KI-Verarbeitung eine bewusste Entscheidung darüber, welche Dokumentklassen diesen Weg nehmen dürfen. Besonders sensible Inhalte sind nicht allein deshalb für ein Cloudmodell geeignet, weil der Upload in eine selbst betriebene Anwendung erfolgt.

Die Netzwerkregeln bilden diesen Datenfluss ab: Paperless nutzt das interne Gateway; LiteLLM hat den expliziten Zugang zum Modellanbieter. Tika und Gotenberg erhalten keinen ausgehenden Netzwerkzugang, damit sie bei der Konvertierung keine Tracking-Pixel oder externen Office-Ressourcen nachladen.

Prompt-Logging ist reduziert, und Prompts sollen nicht in den Spend-Logs landen. Das ersetzt keine Prüfung der Verarbeitungs- und Speicherbedingungen beim Cloudanbieter.

RAG und Dokumentchat sind nicht aktiviert. Das Embedding-Backend ist ungesetzt, sodass auch kein Vektorindex im Hintergrund aufgebaut wird. Zunächst möchte ich den Dokumentenfluss und die Metadaten beherrschen, bevor eine weitere abgeleitete Datenhaltung hinzukommt.

Zugang: privates Netz und eigene Anmeldung#

Die Weboberfläche ist über einen nativen tailnet-operator-Ingress erreichbar. Der Agent terminiert HTTPS und leitet an Paperless weiter. Für größere Uploads und längere Verarbeitungspfade sind die Request-Budgets explizit festgelegt, statt sich auf den Standardtimeout zu verlassen.

Die Anwendung authentifiziert ihre Benutzer selbst über Pocket ID mit OIDC und PKCE. Lokale und soziale Selbstregistrierung sind deaktiviert; ein lokaler Wiederherstellungslogin bleibt erhalten.

Damit werden Netzwerkzugang und Anwendungsberechtigungen getrennt geprüft. Das Tailnet bestimmt, wer die Anwendung erreichen darf. Paperless prüft die Anmeldung und legt fest, welche Dokumente sichtbar sind. Diese zweite Ebene bleibt auch bei einer privaten Netzwerkadresse notwendig.

Backup: Dateien und Datenbank müssen sich wieder treffen#

Das Dokumentenvolume wird täglich über VolSync und restic gesichert, mit getrennten Zielen bei BorgBase und Cloudflare R2. PostgreSQL hat zusätzlich lokale Snapshots, Barman-Basisbackups und WAL-Archivierung nach Garage. Der gemeinsame Archivpfad wird verschlüsselt nach R2 kopiert.

Garage ist dabei ein lokaler Zwischen- und Wiederherstellungsspeicher. Es liegt im selben Cluster wie das Archiv und ist allein keine unabhängige Katastrophensicherung.

Bei der Wiederherstellung müssen die gewählten Stände von Dateien und Datenbank zusammenpassen. PVC-Snapshots und Datenbankbackups laufen getrennt und bilden keine gemeinsame Transaktion. Deshalb muss ihr zeitlicher Zusammenhang beim Restore berücksichtigt werden:

1Anwendungen stoppen
2    → passenden PVC-Snapshot wählen
3    → PostgreSQL auf einen dazu passenden Zeitpunkt wiederherstellen
4    → Dokumentenvolume wiederherstellen
5    → Anwendungen starten
6    → Konsistenz und Dokumentzugriff prüfen

Das dokumentierte Restore-Modell wählt den Datenbankzeitpunkt nicht später als den gewählten PVC-Snapshot. Damit soll die Datenbank nicht bereits auf Dateien zeigen, die im wiederhergestellten Volume noch fehlen. Trotzdem bleiben Konsistenzprüfung und ein isolierter Probelauf notwendig; ein Zeitvergleich allein beweist keinen fehlerfreien Gesamtzustand.

Ein portabler document_exporter-Export kann diesen Rückweg ergänzen. Er ist im beschriebenen Aufbau aber kein automatisch laufender zusätzlicher Sicherungsjob. Die vorhandenen Backup-Manifeste sind außerdem kein Nachweis für einen bereits bestandenen vollständigen Disaster-Recovery-Test.

Was ich vor einem großen Import prüfen würde#

Vor dem Import tausender Dokumente würde ich den Ablauf mit einer kleinen, repräsentativen Testmenge prüfen. Damit lassen sich die wichtigsten Fragen schneller beantworten:

  • Kommt ein mehrseitiger Scan erst nach vollständigem Upload im Consumer an?
  • Bleiben EML und Anhänge im vorgesehenen Ablauf nachvollziehbar?
  • Wird ein erneut gelieferter identischer Anhang als Duplikat erkannt?
  • Stehen Eigentümer und Taxonomie fest, bevor die KI arbeitet?
  • Bleibt ein Dokument bei Modellfehler oder Budgetblock manuell bearbeitbar?
  • Funktionieren OIDC-Anmeldung, Vorschau und Originaldownload?
  • Lassen sich Dateien und Datenbank isoliert in einem konsistenten Zustand wiederherstellen?

Mit diesen Prüfungen lässt sich beurteilen, ob der gesamte Dokumentenfluss funktioniert, einschließlich der Fehlerfälle und der Wiederherstellung.

Fazit#

Mit Paperless lassen sich Scans und ausgewählte Mails in einem durchsuchbaren Archiv zusammenführen. Im Betrieb kommt es darauf an, dass die Übergaben funktionieren. Dateien müssen vollständig ankommen, Zuständigkeiten vor der Klassifikation feststehen und Backups einen konsistenten Wiederherstellungsstand ermöglichen.

Innerhalb dieses Ablaufs nimmt mir die KI einen Teil der Sortierarbeit ab. Die Ablagestruktur bleibt fest vorgegeben, und die fachliche Prüfung bleibt eine eigene Aufgabe. So unterstützt die Klassifikation den Archivbetrieb, ohne dass ich ihr die Verantwortung für die Dokumente überlasse.

Quellenstand: öffentliche Lab-Manifeste Anfang Oktober 2026, insbesondere applications/paperless/, plus der dortigen Git-Historie entnommene Betriebsabläufe aus docs/PAPERLESS.md vor der Dokumentationsbereinigung 26d3bf37. Das Lab-Repository enthält Konfiguration und Historie; persönliche Dokumente, Konten und konkrete Netzwerkadressen sind hier absichtlich nicht abgebildet.