Paperless-ngx: Dokumentpipeline, OCR und Archivbetrieb

Paperless-ngx ist ein selbstgehostetes Dokumentenmanagementsystem für eingehende Dateien und gescannte Papierdokumente. Es nimmt Dokumente aus einem überwachten Verzeichnis, aus dem Web beziehungsweise der REST-API oder aus E-Mail-Postfächern entgegen, erzeugt durchsuchbaren Text und bei Bedarf ein normiertes Archivexemplar, ordnet Metadaten zu und macht den Bestand über Weboberfläche und API recherchierbar. Die Projektübersicht bezeichnet den Dienst als durchsuchbares Onlinearchiv; das Quellrepository weist ihn zugleich als Community-Nachfolger von Paperless und Paperless-ng aus.

Für Admins ist Paperless-ngx keine einzelne Webanwendung, sondern ein Verbund aus Datenbank, Broker, Web- und Hintergrundprozessen, Dateibestand, Suchindex und externen Konvertern. Ein erfolgreicher HTTP-Status beweist nur, dass der Webprozess antwortet. Er sagt nicht, ob der Consumer neue Dateien erkennt, Celery-Aufgaben zugestellt werden, OCR arbeitet, Archivdateien geschrieben werden, der Index aktuell ist oder ein Export wieder importiert werden kann.

Die Erklärung begleitet ein Dokument vom Eingang über Consumer, Parser und OCR bis zu Datenbank, Archivdatei und Suchindex. Danach folgen Automatisierung, Sicherheit, Betrieb und eine Wiederherstellung, die alle Teile gemeinsam prüft.

Paperless-ngx verarbeitet ein Dokument als Pipeline: Eingang erkennen, Datei übernehmen, OCR und Metadaten erzeugen, Datenbank und Suchindex aktualisieren und das Ergebnis über Web oder API bereitstellen. Der Artikel folgt diesem Weg und leitet daraus Betrieb, Backup und Diagnose ab.

Architektur: Steuerpfad, Arbeitspfad und Datenpfad

Die Architektur lässt sich in drei Pfade zerlegen:

1. Steuerpfad: Browser oder API-Client spricht über HTTP beziehungsweise HTTPS mit der Django-Anwendung. Das Angular-Frontend ist der interaktive Client; Django stellt Authentisierung, Geschäftslogik, Adminoberfläche und REST-API bereit. Dass das Projekt aus einer Django-Anwendung und einem Angular-Frontend besteht, dokumentiert die Entwicklungsdokumentation.
2. Arbeitspfad: Consumer, Scheduler und Worker erzeugen und bearbeiten asynchrone Aufgaben. Ein Redis-kompatibler Broker vermittelt zwischen Prozessen; Celery führt unter anderem Konsum, Mailabruf, Indexpflege und wiederkehrende Wartung aus. Die Nutzungsdokumentation beschreibt Consumer, Task Processor und Broker als getrennte Rollen.
3. Datenpfad: Die relationale Datenbank hält Dokumentobjekte, Metadaten, Benutzer, Regeln und Aufgabenstatus. Originale, Archivfassungen und Thumbnails liegen im Media-Verzeichnis; Hilfszustände und Suchdaten liegen im Data-Verzeichnis. Der Suchindex ist eine Projektion dieses führenden Bestands.

Die Trennung ist operativ entscheidend. Datenbank und Media-Verzeichnis müssen zum selben logischen Zeitpunkt gehören. Ein neuer Index lässt sich aufbauen, eine verlorene Originaldatei aber nicht aus dem Index rekonstruieren. Ebenso reicht eine Datenbanksicherung ohne die zugehörigen Dateien nicht für ein DMS-Restore.

Technologiestack und Prozessrollen

Der Backendcode ist überwiegend in Python implementiert und basiert auf Django. Das Browser-Frontend verwendet Angular. Abhängigkeiten wie Django, Celery, OCRmyPDF und weitere Parser sind im Python-Projektmanifest nachvollziehbar; Imageaufbau und native OCR-/PDF-Abhängigkeiten zeigt das Dockerfile. Für den Betrieb sind folgende Rollen relevant:

Die offizielle Konfigurationsreferenz bezeichnet den Redis-kompatiblen Broker als erforderlichen Dienst. PostgreSQL, MariaDB und SQLite werden als Datenbanken unterstützt; für neue Installationen empfiehlt die Installationsanleitung PostgreSQL. Tika und Gotenberg sind optional und werden für Office-Formate und die Verarbeitung von E-Mail-Dateien gemeinsam benötigt (optionale Dienste).

Dienstinventar und tatsächliche Konfiguration

Ein belastbares Inventar enthält Image oder Release, Datenbanktyp, Brokerziel, Mounts, effektive Umgebungsvariablen, UID/GID, Reverse Proxy, Zeitzone, OCR-Sprachen und externe Parser. Docker Compose ist eine verbreitete Verpackung, aber kein Architekturbeweis: Mehrere Prozessrollen können in einem Containerimage stecken, während ihre Zustände in separaten Volumes und Diensten liegen.

docker compose config --services
docker compose ps
docker compose images
docker compose config
docker inspect paperless-webserver

docker compose config --services
docker compose ps
docker compose images
docker compose config
docker inspect paperless-webserver

docker compose config rendert die tatsächlich zusammengeführte Compose-Konfiguration; docker compose ps zeigt Prozesse und veröffentlichte Ports; docker compose images identifiziert Images; docker inspect liefert Mounts, Netzwerk und Laufzeitparameter. Ausgaben können Secrets enthalten und gehören nur redigiert in Tickets.

Eingänge und Zustellgrenzen

Paperless-ngx kennt mehrere Eingänge, die vor der gemeinsamen Pipeline unterschiedliche Ausfallbereiche besitzen:

• Das Consume-Verzeichnis wird über Dateisystemereignisse beobachtet. Auf Dateisystemen ohne zuverlässiges inotify, etwa manchen NFS-Mounts, muss Polling aktiviert werden; dies nennt die Setup-Dokumentation.
• Browser und REST-API schreiben Uploads über den Webpfad. Reverse Proxy, Requestgrössenlimit, Timeout und temporärer Speicher liegen damit vor dem Tasksystem.
• Der Mailabruf liest regelbasiert aus konfigurierten Konten und erzeugt für passende Anhänge Aufgaben. IMAP-Verbindung, TLS, OAuth/Passwort, Ordner, Suchkriterium und Nachbearbeitungsaktion gehören zum Zustellvertrag.

Das Consume-Verzeichnis ist eine Übergabezone und kein Dokumentarchiv. Erfolgreich konsumierte Dateien werden dort entfernt, während Paperless neue verwaltete Dateien im Media-Bestand erzeugt. Die FAQ warnt ausdrücklich davor, das Media-Verzeichnis manuell zu verwalten.

Sind Prozesse und Eingänge bekannt, beginnt die eigentliche Verarbeitung. Jeder Schritt erzeugt andere Dateien, Datenbankeinträge und Fehlersignale.

Consume-Pipeline: vom Eingang zum Dokumentobjekt

Der fachliche Commit erfolgt nicht beim Erkennen einer Datei, sondern erst nach mehreren Schritten. Je Dateityp und Konfiguration umfasst die Pipeline typischerweise:

1. Erkennung und Stabilisierung: Dateiname, erlaubter Typ, Dateigrösse und Schreibabschluss werden geprüft.
2. Auftragserzeugung: Der Consumer beziehungsweise Webserver übergibt eine Aufgabe über den Broker.
3. Parsing und Vorverarbeitung: Parser extrahieren vorhandenen Text oder konvertieren das Eingangsdokument. Office- und E-Mail-Dateien können Tika und Gotenberg benötigen.
4. OCR: OCRmyPDF entscheidet anhand des OCR-Modus über Texterkennung; Tesseract erkennt konfigurierte Sprachen.
5. Archivfassung und Thumbnail: Eine Anzeige-/Archivdatei und Vorschaudaten werden erzeugt, soweit Dateityp und Einstellungen dies vorsehen.
6. Persistenz: Original und Ableitungen werden geschrieben; Datenbankobjekt, Prüfsummen, Text und technische Eigenschaften werden gespeichert.
7. Metadaten und Workflows: Regeln weisen Tags, Korrespondent, Dokumenttyp, Speicherpfad, Eigentümer oder andere Felder zu.
8. Indexierung: Der Volltextbestand wird im Suchindex aktualisiert.
9. Abschluss: Taskstatus und Log zeigen Erfolg oder Fehler; erst jetzt ist das Dokument fachlich auffindbar.

Pre- und Post-Consume-Skripte können den Pfad erweitern. Die Dokumentation zu Consume-Hooks macht deutlich, dass solche Skripte im Sicherheits- und Fehlerkontext des Paperless-Prozesses laufen. Sie gehören versioniert, mit Timeout und eindeutigen Exitcodes betrieben; ein fehlerhaftes Hook kann die gesamte Aufnahme blockieren.

OCR, Archivformat und Qualitätsgrenzen

OCRmyPDF orchestriert PDF-Verarbeitung und Tesseract-OCR. Der Modus entscheidet, ob vorhandener Text übersprungen, erneut verarbeitet oder erzwungen wird. Sprache, Seitenlimit, Bildbereinigung, Rotationskorrektur und Ausgabeformat beeinflussen CPU-Zeit, Dateigrösse und Erkennungsqualität. Die Einstellungen sind in der Paperless-OCR-Konfiguration und in der OCRmyPDF-Dokumentation beschrieben; Sprachmodelle und Engineverhalten dokumentiert Tesseract.

Das Original bleibt als Beweisobjekt erhalten. Ein Archiv-PDF ist eine abgeleitete Fassung, die durch spätere OCR-/Archiveränderungen neu erzeugt werden kann. Diese Unterscheidung gehört in Aufbewahrungs- und Beweiswertkonzepte:

OCR-Erfolg bedeutet nicht fachliche Lesbarkeit. Stichproben sollten Seitenzahl, Orientierung, Textdeckung, Sonderzeichen, Tabellen, eingebettete Signaturen und Dateigrösse vergleichen. CPU- und RAM-Spitzen entstehen oft beim Rendern grosser oder bildreicher PDFs, nicht beim abschliessenden Datenbankschreiben.

Originale, Archive, Thumbnails und Pfadformat

Ein Paperless-Dokument besteht aus mehreren gekoppelten Teilen. Die Datenbank kennt interne ID, Titel, Erstellungs- und Hinzufügedatum, Korrespondent, Dokumenttyp, Tags, Speicherpfad, Inhalt, Eigentümer und weitere Felder. Im Media-Verzeichnis liegen Original und gegebenenfalls Archiv- und Thumbnaildatei. Konfigurierbare Dateinamen und Storage Paths ändern die physische Anordnung, nicht die Identität des Datenbankobjekts.

Admins vermeiden direkte Umbenennungen oder Verschiebungen im Media-Verzeichnis. Der offizielle document_renamer wendet das konfigurierte Format konsistent an. Ein externes Filesync-Werkzeug darf den Bestand sichern, aber nicht neben der laufenden Anwendung eigenmächtig reorganisieren. Für Speichergrundlagen siehe Storage, für Kopie und Verifikation Rclone.

Metadaten, Matching und Workflows

Korrespondenten, Dokumenttypen, Tags, Speicherpfade, benutzerdefinierte Felder und Datumswerte bilden eine facettierte Ordnung. Sie ersetzen keinen Dateibaum, sondern beschreiben ein Dokument entlang mehrerer unabhängiger Dimensionen. Automatisches Matching liefert Vorschläge beziehungsweise Zuweisungen auf Basis des erkannten Inhalts und bisheriger Daten; es ist kein unveränderlicher Wahrheitsdienst.

Workflows bestehen aus Triggern, optionalen Filtern und sequenziellen Aktionen. Sie können beim Konsum oder bei anderen Ereignissen Metadaten, Berechtigungen und weitere Eigenschaften setzen. Die Workflow-Dokumentation beschreibt Trigger und Aktionen. Für Admins folgen daraus drei Regeln:

• Jede Automatik braucht eine definierte Eingangsmenge und ein beobachtbares Ergebnis.
• Regelreihenfolge und Mehrfachtreffer werden wie Policycode getestet.
• Nach Änderungen werden Bestandsdokumente nur kontrolliert mit dem document_retagger neu bewertet.

Suche: Datenbankabfrage und Tantivy-Projektion

Die Volltextsuche verwendet einen separaten Tantivy-Index. Die Datenbank bleibt für Dokumentobjekte und Metadaten führend; der Index beschleunigt Recherche und Ranking. Dadurch kann ein Dokument in der Datenbank sichtbar sein, aber in Volltextsuchen fehlen. Die Migration auf Tantivy und veränderte Suchfelder dokumentiert der Migrationsleitfaden.

Nach Upgrades oder bei Verdacht auf Drift kann der Index über das Managementkommando neu aufgebaut werden. Reindexierung ist eine Reparatur einer Projektion, kein Restore der Originale. Kapazitätsplanung berücksichtigt Indexgrösse, temporären Platz während eines Neuaufbaus und die I/O-Last parallel zum normalen Konsum.

docker compose exec webserver document_index list
docker compose exec webserver document_index reindex --if-needed
docker compose exec webserver document_sanity_checker
docker compose exec webserver document_thumbnails --help

docker compose exec webserver document_index list
docker compose exec webserver document_index reindex --if-needed
docker compose exec webserver document_sanity_checker
docker compose exec webserver document_thumbnails --help

Managementkommandos werden bei Compose über docker compose exec im Webservercontainer gestartet. Bare-Metal-Installationen verwenden python3 manage.py; die unterstützte Aufrufform und die eingebauten Hilfen dokumentiert die Administration.

OCR-Dateien und Metadaten allein bilden noch keinen konsistenten Dienst. Datenbank, Taskbroker und Suchprojektion müssen zum selben Verarbeitungsstand passen.

Datenbank, Broker und Konsistenz

PostgreSQL ist für neue Installationen der Standardpfad. MariaDB und SQLite sind möglich, unterscheiden sich aber in Backupwerkzeugen, Parallelverhalten und Betriebsgrenzen. Datenbankmigrationen sind Teil eines Paperless-Upgrades; ein zurückkopiertes altes Binary passt nicht zwingend zu einem bereits migrierten Schema. Datenbankbetrieb wird deshalb als eigener Lifecycle behandelt (PostgreSQL-Backup und Restore, MariaDB Backup and Restore).

Der Broker transportiert Aufgaben zwischen Prozessen. Redis-/Valkey-Persistenz ist nicht der Ersatz für Datenbank- und Dokumentbackup. Nach Brokerverlust können laufende oder zugestellte Arbeiten erneut angestossen, verloren oder als inkonsistenter Taskstatus sichtbar werden. Die Abnahme erfolgt deshalb am Dokumentobjekt und seinen Dateien, nicht an einer leeren Queue.

docker compose exec db pg_isready
docker compose exec broker redis-cli PING
docker compose logs --since 30m webserver
docker compose logs --since 30m broker db

docker compose exec db pg_isready
docker compose exec broker redis-cli PING
docker compose logs --since 30m webserver
docker compose logs --since 30m broker db

pg_isready prüft die Annahme von PostgreSQL-Verbindungen, nicht Schema oder fachliche Abfragen. redis-cli testet mit PING die Brokererreichbarkeit. docker compose logs führt zeitlich begrenzte Dienstlogs zusammen; Credentials, Dokumenttitel und Pfade werden vor Weitergabe redigiert.

Konfiguration, Secret Key und Pfadauflösung

Bei Docker werden Einstellungen typischerweise als Environment beziehungsweise Compose-Env-Datei geliefert; paperless.conf gilt dort nicht. Bare-Metal-Installationen suchen Konfiguration in einer dokumentierten Reihenfolge. Manche Einstellungen können zusätzlich in der Anwendung gespeichert werden und Environmentwerte übersteuern. Die effektive Konfiguration ist deshalb mehr als eine einzelne Datei (Konfigurationsreihenfolge).

PAPERLESS_SECRET_KEY signiert Sitzungen und sensible Werte und ist obligatorisch. PAPERLESS_URL, Allowed Hosts, CSRF- und CORS-Einstellungen definieren die Webgrenze. Datenbank-, Mail-, OAuth-, Tika- und optionale AI-Credentials sind Geheimnisse. Docker-Setups können für zahlreiche Werte die _FILE-Variante und damit gemountete Secrets verwenden; dies dokumentiert die Setup-Anleitung.

Konfigurationsbackup umfasst mindestens:

• Compose-/Service-Definition und gepinnte Image-Referenz,
• Environment ohne Klartextkopien in ungeschützten Repositories,
• Secret Key und externe Secret-Referenzen,
• UID/GID, Volume- und Bind-Mount-Zuordnung,
• Proxy-, DNS-, Zertifikats- und Mailkontokonfiguration,
• OCR-Sprachen, Dateinamenformat, Workflows und Custom Hooks.

Webgrenze, TLS und Reverse Proxy

Die Anwendung sollte hinter einem korrekt konfigurierten Reverse Proxy über HTTPS erreichbar sein. Hostheader, Ursprungs-URL, CSRF Trusted Origins, Forwarded Headers und Uploadgrenzen müssen zusammenpassen. Der Proxy darf Remote-User-Header nur setzen, wenn er die vorgelagerte Identität verlässlich authentisiert und gleichnamige Clientheader entfernt.

Die Security-Dokumentation beschreibt Secret Key, URL-, Host-, CORS- und CSRF-Parameter. Zertifikats- und Transportgrundlagen stehen unter TLS, systematische Absicherung unter Härtung. Das Projekt warnt im Repository, dass Dokumente im Klartext gespeichert werden und Paperless-ngx nicht auf einem nicht vertrauenswürdigen Host betrieben werden soll.

Test-NetConnection paperless.example.net -Port 443
curl.exe -sS -D - -o NUL https://paperless.example.net/
Resolve-DnsName paperless.example.net
docker compose port webserver 8000

ss -lntp
curl -sS -D - -o /dev/null https://paperless.example.net/
getent ahosts paperless.example.net
docker compose port webserver 8000

Test-NetConnection prüft unter Windows TCP-Erreichbarkeit; ss zeigt lokale Listener; curl macht Status, Redirect und Header sichtbar; Resolve-DnsName beziehungsweise getent prüfen die Namensauflösung; docker compose port zeigt die tatsächliche Portabbildung.

Identitäten, globale Rechte und Objektrechte

Paperless-ngx verwendet das Django-Benutzer- und Gruppenmodell. Globale Berechtigungen steuern, welche Objektarten und UI-/API-Bereiche ein Konto verwenden darf. Objektbezogene Rechte steuern Owner, View und Change für ein bestimmtes Dokument, Tag oder anderes Objekt. Die Berechtigungsdokumentation betont, dass Rechte eines Tags nicht automatisch auf damit markierte Dokumente übergehen.

Superuser dürfen alle Objekte sehen. Staff-/Adminstatus ist davon zu unterscheiden und ermöglicht unter anderem Backend- und Systemansichten. Für den Tagesbetrieb werden normale Konten und Gruppen verwendet; Servicekonten erhalten nur die benötigten API- und Objektrechte. Workflows können Owner und Rechte beim Konsum setzen, was besonders für unbesessene Dokumente aus Consume-Verzeichnissen wichtig ist.

Authentisierung ist lokal, per Reverse-Proxy-Remote-User oder über konfigurierte Social-/OIDC-Verfahren möglich. Remote User wird nur hinter einer geschlossenen Proxygrenze aktiviert. MFA-, Session- und Tokenlebenszyklus werden in das allgemeine Identitätskonzept aufgenommen.

REST-API und Automationsgrenze

Die REST-API ist unter dem Anwendungspräfix erreichbar; eine interaktive Schemaansicht liegt unter /api/schema/view/. Unterstützt werden unter anderem Basic-, Session-, Token-, Remote-User- und Headless-OIDC-Authentisierung. Die API-Dokumentation beschreibt Suche, Objektberechtigungen, Bulkoperationen und Versionsheader.

Ein API-Token ist ein Secret und wird pro Automation getrennt vergeben. Clients beachten Pagination, Filter, Berechtigungen, API-Version und idempotente Wiederholung. Ein erfolgreiches Upload-Response ist noch nicht gleichbedeutend mit abgeschlossener OCR; Automationen korrelieren Dokument- beziehungsweise Task-ID bis zum fachlichen Endzustand. Grundsätze zu Vertrags-, Authentisierungs- und Retryverhalten stehen unter APIs.

Mailabruf als Messaging-Schnittstelle

Mailkonten und Mailregeln verbinden Paperless-ngx mit einem IMAP-Postfach. Der Scheduler prüft standardmässig periodisch konfigurierte Konten, wendet Regeln an und übergibt passende Anhänge an die Consume-Pipeline. Das Managementkommando mail_fetcher kann den Abruf manuell auslösen; dies dokumentiert die Administration zum Mailabruf.

Für Messaging-Admins gehören folgende Werte in das Runbook:

• Server-FQDN, Port und TLS-Modus,
• Authentisierungsmethode, Secret-/Tokenablauf und Servicekonto,
• IMAP-Ordner, Suchkriterium, Dateitypen und maximale Nachrichtengrösse,
• Aktion nach erfolgreichem oder fehlgeschlagenem Import,
• Umgang mit mehrfach zugestellten Nachrichten und gleichen Anhängen,
• Korrelation zwischen Message-ID, Paperless-Task und Dokument-ID.

IMAP-Semantik wird durch RFC 9051 definiert. Ein erfolgreicher IMAP-Abruf beweist nur den Eingang in den Taskpfad; OCR- und Archivabschluss werden separat überwacht.

Office-Dokumente, Tika und Gotenberg

Apache Tika extrahiert Inhalte und Metadaten aus zahlreichen Dateitypen; Gotenberg stellt Konvertierungsdienste bereit. Paperless benötigt beide, wenn die optionale Office-/E-Mail-Verarbeitung aktiviert ist. Ihre Endpunkte werden getrennt konfiguriert (Tika Server, Gotenberg-Konfiguration).

Die beiden Dienste vergrössern Angriffsfläche, Ressourcenbedarf und Fehlerraum. Sie werden nur intern erreichbar gemacht, erhalten CPU-/RAM-/Timeoutgrenzen und werden nicht als allgemeine Konvertierungs-API veröffentlicht. Wenn PDFs funktionieren, DOCX oder EML aber konsistent scheitern, beginnt die Diagnose an diesem Seitenpfad und nicht bei Tantivy oder der Datenbank.

Container-, Bare-Metal- und Speicherbetrieb

Die offiziellen Wege sind Installationsskript, Docker Compose und Bare Metal. Compose liefert reproduzierbare Dienstdefinitionen und getrennte Volumes; Bare Metal gibt mehr Kontrolle über Prozesse, Pakete und systemd, verlangt aber explizites Lifecycle-Management. Die Setup-Matrix ordnet die Wege nach Aufwand und Einsatz ein.

Persistente Verzeichnisse werden nicht mit dem Containerlebenszyklus verwechselt. Bei Compose sind Media, Data, Consume, Export und Datenbankpfad bewusst aufgelöst. Remote- oder Netzwerkdateisysteme werden auf POSIX-Verhalten, atomare Umbenennung, Sperren, Latenz, inotify und Verfügbarkeit geprüft. Ein kurzer Unterbruch kann sonst wie ein dauerhafter Dokumentverlust aussehen. Grundlagen zu Mounts stehen unter Container und Storage.

Bei einer Störung wird zuerst festgestellt, in welcher Pipelinephase das Dokument steht. Danach werden Queue, Worker, externer Konverter, Datenbank und Dateispeicher gezielt geprüft.

Beobachtbarkeit und Taskdiagnose

Eine sinnvolle Betriebsübersicht trennt vier Signale:

• Dienstgesundheit: Prozess läuft, Port lauscht, Datenbank und Broker erreichbar.
• Durchsatz: neue Aufgaben, abgeschlossene Dokumente, Laufzeiten und Warteschlangentiefe.
• Fehler: Tasks nach Stufe und Dateityp, Parser-/OCR-Exit, Mail- und Storagefehler.
• Bestandsintegrität: fehlende oder beschädigte Originale/Archive/Thumbnails, verwaiste Dateien, Indexdrift.

Der eingebaute Sanity Checker erkennt unter anderem fehlende, unlesbare oder gegenüber der gespeicherten Prüfsumme veränderte Dateien sowie verwaiste Media-Dateien. Die vollständige Liste steht in der Sanity-Checker-Dokumentation. Ein Alarm auf Fehlerzahl ohne Dokument-/Task-ID und Pipelinephase ist kaum handlungsfähig.

docker compose logs --since 1h --timestamps webserver
docker compose exec webserver document_sanity_checker
docker compose exec webserver mail_fetcher
docker stats --no-stream
docker system df -v

docker compose logs --since 1h --timestamps webserver
docker compose exec webserver document_sanity_checker
docker compose exec webserver mail_fetcher
docker stats --no-stream
docker system df -v

docker stats zeigt momentane CPU-/Speichernutzung, docker system df die Docker-Datenträgerbelegung. Beide sind Momentaufnahmen. Für Ursachen werden Zeitreihe, Task-ID und Paperless-Logs korreliert. Allgemeine Methodik steht unter Troubleshooting.

Kapazität, Parallelität und Grenzwerte

Kapazitätsplanung beginnt mit Seiten pro Tag, Eingangsformaten, durchschnittlicher und maximaler Dateigrösse, OCR-Sprachen, parallelen Tasks, Aufbewahrungszeit und Suchvolumen. Ein Dokument kann gleichzeitig Original, Archiv-PDF, Thumbnail, Datenbanksatz, Volltextindex und temporäre Renderdateien erzeugen. Der freie Platz muss auch Neuindexierung, Export und Upgrade berücksichtigen.

Mehr Workerparallelität beschleunigt CPU-gebundene OCR nur bis CPU, RAM und I/O gesättigt sind. Sie erhöht gleichzeitig die Zahl temporärer Dateien und Datenbankverbindungen. Mailabruf und Consumer dürfen mehr Aufgaben erzeugen, als Worker abarbeiten; deshalb wird Queuealter statt nur momentaner Queuelänge beobachtet. Limits werden mit repräsentativen Dokumenten getestet, nicht mit kleinen Text-PDFs.

Der Sicherungsumfang folgt dem Datenmodell: Originale, Archive, Datenbank, Konfiguration, Secret Key und gegebenenfalls zusätzliche Dienste müssen gemeinsam wiederherstellbar sein.

Backup: Welche Objekte gemeinsam gesichert werden

Die offizielle Backup-Dokumentation nennt zwei Hauptwege: den Document Exporter oder eine abgestimmte Sicherung von Volumes/Verzeichnissen und Datenbank. Der Exporter schreibt Dokumente, Thumbnails, Metadaten und Datenbankinhalt in ein transportables Verzeichnis. API-Tokens werden nicht übernommen; Export und Import sollten versionskompatibel sein.

Ein vollständiges Recoveryset enthält:

Der Exporter kann bestehende Exporte aktualisieren und optional Prüfsummen vergleichen. Das spart Zeit, ersetzt aber keine getrennte, versionierte Kopie: Mit --delete können gelöschte Dokumente aus dem Exportziel entfernt werden. Details und Optionen dokumentiert der document_exporter.

docker compose exec -T webserver document_exporter ../export --compare-checksums
Get-ChildItem -Recurse .\export | Measure-Object -Property Length -Sum
Get-FileHash .\export\manifest.json -Algorithm SHA256
docker compose exec webserver document_sanity_checker

docker compose exec -T webserver document_exporter ../export --compare-checksums
du -sh ./export
sha256sum ./export/manifest.json
docker compose exec webserver document_sanity_checker

Get-FileHash und sha256sum sichern den Transfernachweis für das Manifest. Eine Prüfsumme beweist nur Gleichheit zweier Bytesätze, nicht die Importierbarkeit oder fachliche Vollständigkeit. Backupgrundlagen stehen unter Backup und Disaster Recovery.

Restore und Abnahme

Der document_importer erwartet eine leere Installation beziehungsweise bei --data-only eine leere Datenbank. Ein Restoretest verwendet deshalb isolierte Zielpfade, eine zur Sicherung passende Paperless-Version und keine produktiven Volumes.

Die Abnahme umfasst mindestens:

1. Konfiguration und Secrets in die Zielumgebung einspielen.
2. Leere Datenbank und leere Media-/Data-Pfade bereitstellen.
3. Export importieren oder Datenbank und Dateien konsistent zurückspielen.
4. Migrationen und gegebenenfalls Indexaufbau kontrolliert ausführen.
5. Benutzeranmeldung, Gruppen und Berechtigungen prüfen.
6. Dokumentzahl, Metadaten und Stichproben aus Original und Archiv vergleichen.
7. Volltextsuche und Thumbnailanzeige testen.
8. Sanity Checker ohne unerklärte Findings ausführen.
9. Ein neues Testdokument über den echten Eingang konsumieren.
10. RPO und RTO mit Zeitstempeln dokumentieren.

Ein Restore gilt erst nach diesem End-to-End-Test als erfolgreich. «Container startet» ist kein Abnahmekriterium.

Updates, Datenbankmigrationen und Rollbackgrenze

Vor einem Update werden aktive Consume-Aufgaben beendet, eine Sicherung erstellt und Release Notes auf Breaking Changes geprüft. Der Updateleitfaden trennt Docker- und Bare-Metal-Verfahren und beschreibt Datenbankmigration sowie bedarfsabhängigen Reindex. Ein Image wird auf eine freigegebene Serie oder einen Digest gepinnt; latest ist kein reproduzierbarer Rollbackpunkt.

Nach einer Datenbankmigration ist ein Rollback normalerweise ein Restore von Datenbank und dazu passendem Dateibestand, nicht nur das Starten des alten Images. Neue Archive oder Metadaten, die nach dem Sicherungspunkt entstanden sind, müssen vor dem Rücksprung fachlich behandelt werden. Allgemeine Release- und Change-Grundsätze stehen unter Releases und Migration.

Der Changelog ist die zeitabhängige Quelle für neue Funktionen, Breaking Changes und Korrekturen. Dieser Artikel beschreibt dagegen stabile Architektur- und Betriebsprinzipien.

Fehlerbilder nach Pipelinephase

Weil ein Dokument mehrere Verarbeitungsschritte durchläuft, zeigt das sichtbare Symptom oft nur die letzte erfolgreiche Phase. Die Tabelle führt vom Symptom zum nächsten belastbaren Beleg.

Die offizielle Troubleshooting-Sammlung ergänzt konkrete Fehlermeldungen. Admins sichern vor Änderungen immer Task-ID, Dokumentname, Zeitfenster, effektive Konfiguration, Container-/Prozessstatus und den Zustand aller abhängigen Dienste.

Technische Geschichte

Das ursprüngliche Paperless-Projekt etablierte das Grundmodell aus Consume-Verzeichnis, OCR und durchsuchbarem Archiv. Paperless-ng führte die Entwicklung als Fork weiter. Paperless-ngx entstand danach als offizieller Community-Nachfolger, um Pflege und Verantwortung auf mehrere Mitwirkende zu verteilen; diese Abstammung beschreibt das Projekt-README.

Die Plattform entwickelte sich von einer primär serverseitigen Django-Anwendung zu einem DMS mit Angular-Frontend, REST-API, objektbezogenen Berechtigungen, Workflowengine und paralleler Taskverarbeitung. OCRmyPDF/Tesseract blieben die OCR-Basis; Tika und Gotenberg erweiterten die unterstützten Eingangsformate. Der Suchpfad wechselte von Whoosh zu Tantivy, wodurch der Index als eigene Migrations- und Betriebsdomäne sichtbar wurde (Tantivy-Migration).

Diese Geschichte erklärt die heutige Architektur: Ein Paperless-ngx-Dokument ist gleichzeitig relationales Objekt, Satz verwalteter Dateien, OCR-Ergebnis und Suchprojektion. Wartung und Recovery müssen alle vier Perspektiven berücksichtigen.

Admin-Checkliste

Zum Abschluss werden Eingänge, Worker, Speicher, Suche und Backup gemeinsam geprüft. Die Checkliste hilft, keine externe Abhängigkeit ausserhalb des Paperless-Containers zu übersehen.

• Inventar: Image/Commit, Django-/Angular-Anwendung, Worker, Scheduler, Broker, Datenbank, Tika/Gotenberg, Proxy und Mounts.
• Datenobjekte: Datenbank, Original, Archiv, Thumbnail, Index, Konfiguration, Secrets und Exportmanifest getrennt benennen.
• Eingänge: Consume, Upload/API und Mail jeweils mit Grössen-, Typ-, Authentisierungs- und Fehlerregel dokumentieren.
• Pipeline: Task-ID über Parser, OCR, Archivierung, Metadaten und Index bis zum Abschluss korrelieren.
• Berechtigungen: globale und objektbezogene Rechte, Superuser, Gruppen und Workflowzuweisungen testen.
• Kapazität: Queuealter, OCR-Laufzeit, temporären Platz, Media-/Indexwachstum und Datenbankverbindungen überwachen.
• Sicherheit: HTTPS, Proxyvertrauen, Secret Key, Tokens, Klartextspeicher und externe Parser in das Bedrohungsmodell aufnehmen.
• Backup: Datenbank und Media konsistent sichern; Konfiguration und Secrets nicht vergessen.
• Restore: leere Zielinstanz, passende Version, Stichproben, Suche, Sanity Checker und neuen Consume-Lauf prüfen.
• Change: Release Notes, Schema-/Indexmigration, freier Platz und echte Rollbackgrenze vorab festhalten.