- Fazit: Fehlertolerantere Suche und verbesserte OCR sind im Alltag spürbar
- Empfehlung: Ja, für UGREEN-NAS-Nutzer mit Docker Compose
- Aufwand: Gering – Backup prüfen, Tags setzen, Pull, Deploy
- Betrieb: Läuft nach dem Update stabil im Alltag
Inhaltsverzeichnis
- Warum ich aktualisiert habe
- Was der Sprung auf 3.2.1 bringt
- Vorbereitung des Updates
- Die YAML-Anpassung
- Der eigentliche Update-Ablauf
- Wenn etwas schiefgeht
- Persönliche Einordnung
- Fazit und Empfehlung
Warum ich Paperless-ngx auf 3.2.1 aktualisiert habe
Das Update ist mir nicht bei einer geplanten Wartung aufgefallen, sondern mitten im normalen Arbeitsablauf. Ich wollte ein bereits abgelegtes Dokument wiederfinden und habe dabei erneut gemerkt, wie wichtig eine zuverlässige Suche in Paperless-ngx ist. Wenn sich Rechnungen, Verträge und technische Unterlagen über Jahre ansammeln, muss ein Dokument auf Anhieb auffindbar sein – gerade dann, wenn es schnell gehen soll.
Paperless-ngx läuft bei mir auf einem UGREEN NAS. Deshalb ist ein Update nicht nur ein Klick auf „Aktualisieren“. Container, Datenbank, Dokumente und die bestehende Konfiguration müssen weiterhin sauber zusammenspielen. Gleichzeitig möchte ich den laufenden Betrieb möglichst wenig beeinträchtigen. Der entscheidende Maßstab ist für mich daher nicht allein die neue Versionsnummer, sondern ob die Anwendung danach im Alltag zuverlässig weiterarbeitet.
Der Sprung von der 3.1.x-Reihe auf Version 3.2.1 ist in diesem Zusammenhang interessant, weil es sich nicht nur um eine kleine Korrektur handelt. Mit der neuen Version geht Paperless-ngx den eingeschlagenen Weg weiter: Die Anwendung wird bei Stabilität, Bedienung, Suche und dem allgemeinen Umgang mit Dokumenten kontinuierlich verbessert. Für Selfhoster bedeutet das vor allem, dass sich ein Blick auf die eigene Installation lohnt – insbesondere dann, wenn Paperless-ngx bereits länger unverändert auf dem NAS läuft.
In diesem Beitrag zeige ich, wie ich das Update von Paperless-ngx 3.1.x auf 3.2.1 auf dem UGREEN NAS durchgeführt und anschließend geprüft habe, ob Suche, Dokumentenverwaltung und der laufende Betrieb weiterhin zuverlässig funktionieren.
Was bringt der Sprung von Paperless-ngx 3.1.x auf 3.2.1?
Der Wechsel von Paperless-ngx 3.1.x auf 3.2.1 ist mehr als ein reines Zwischenupdate. Die grundlegende Bedienung bleibt zwar vertraut, einige Verbesserungen wirken sich im täglichen Umgang mit dem Dokumentenbestand direkt aus. Besonders relevant sind die fehlertolerantere Suche und die Optimierungen bei der OCR-Verarbeitung. Gerade auf einem UGREEN NAS, auf dem Paperless-ngx viele Rechnungen, Verträge und gescannte Unterlagen automatisch verarbeitet, verbessern solche Details die Qualität der täglichen Arbeit.
Fuzzy Search: intelligente Fehlertoleranz bei der Suche
Eine der praktischen Neuerungen ist die Fuzzy Search. Dabei sucht Paperless-ngx nicht mehr ausschließlich nach einer exakt passenden Zeichenfolge, sondern berücksichtigt auch ähnliche Schreibweisen. Das ist hilfreich, wenn sich beim Erfassen oder Suchen ein Tippfehler eingeschlichen hat.
Auch typische OCR-Fehler können dadurch besser abgefangen werden. Ein gescanntes Dokument kann beispielsweise ein kleines „l“ und eine Ziffer „1“ verwechseln oder einzelne Buchstaben falsch erkennen. Die fehlertolerante Suche erhöht in solchen Fällen die Wahrscheinlichkeit, das gewünschte Dokument trotzdem zu finden. Das gilt auch für Teilbegriffe, wenn man sich beispielsweise nur an einen Bestandteil eines Firmennamens oder einer Rechnungsnummer erinnert.
Wichtig ist die richtige Erwartung: Ob ein Treffer entsteht, hängt vom Suchindex und vom konkreten Fehlerbild ab. Fuzzy Search korrigiert keine OCR-Fehler und garantiert keine Treffer. Stark beschädigte Scans, stark abweichende Schreibweisen oder völlig falsch erkannte Wörter bleiben problematisch. In der Praxis reduziert die Funktion aber die Zahl der Fälle, in denen eine Suche wegen eines einzigen abweichenden Zeichens ohne Treffer bleibt.
OCR-Ligaturen: bessere Erkennung von „fi“ und „fl“
Ebenfalls verbessert wurde die OCR-Verarbeitung durch die Aktualisierung auf OCRmyPDF 17.12. Dabei geht es unter anderem um sogenannte Ligaturen. Das sind verbundene Buchstaben, wie sie in vielen Schriftarten bei Kombinationen wie „fi“ oder „fl“ vorkommen.
Bei älteren OCR-Läufen konnten solche Buchstabenverbindungen teilweise fehlerhaft erkannt werden. Aus „Firma“ oder „flüssig“ konnten dadurch unvollständige oder falsch zusammengesetzte Textstellen entstehen. Die verbesserte Verarbeitung sorgt dafür, dass diese Kombinationen zuverlässiger in durchsuchbaren Text umgewandelt werden.
Die genannte Versionsangabe sollte vor der Veröffentlichung gegen die Release-Notes beziehungsweise das tatsächlich eingesetzte Image geprüft werden. Ebenso lässt sich der Effekt lokal nachvollziehen: Importiere ein neues Testdokument mit „fi“- und „fl“-Verbindungen und kontrolliere den extrahierten Text. Ein bereits vorhandenes Dokument dient dabei als unveränderter Vergleich.
Der Effekt betrifft vor allem neu verarbeitete Dokumente. Bereits importierte Dateien werden durch das Update nicht automatisch erneut per OCR verarbeitet. Wer von der Verbesserung für den vorhandenen Bestand profitieren möchte, muss die betreffenden Dokumente daher gezielt neu verarbeiten lassen und das Ergebnis anschließend separat prüfen. Für neu eingehende Scans greift die optimierte OCR-Verarbeitung dagegen direkt.
Vorbereitung des Updates
Bevor der erste Container neu erstellt wird, sollte der aktuelle Zustand des Paperless-ngx-Stacks dokumentiert werden. Dazu gehören mindestens die derzeit verwendete Paperless-Version, die Namen und Status aller Container, die gemounteten Verzeichnisse sowie die relevanten Einstellungen in der docker-compose.yml beziehungsweise der verwendeten YAML-Datei. Auch ein kurzer Funktionstest – etwa Anmeldung, Dokumentensuche und Upload – ist sinnvoll. So lässt sich nach dem Update eindeutig feststellen, ob die Anwendung wieder vollständig arbeitet.
Backup nicht nur voraussetzen, sondern prüfen
Auf dem UGREEN NAS läuft die Datensicherung idealerweise automatisiert jede Nacht. Das ist eine wichtige Grundlage für Wartungsarbeiten, ersetzt aber nicht die Kontrolle vor einem Versionssprung. Entscheidend ist nicht, dass ein Backup-Auftrag existiert, sondern dass die letzte Sicherung tatsächlich erfolgreich abgeschlossen wurde.
Vor dem Update sollte daher geprüft werden:
- Wann wurde das letzte Backup ausgeführt?
- Wurde es ohne Fehler beendet?
- Sind Datenbank und Paperless-Dokumentenverzeichnisse enthalten?
- Ist der Backup-Speicher erreichbar und sind die Dateien vorhanden?
In der Praxis heißt das, im Backup-Bereich des UGREEN NAS die Zeitstempel und den Status des letzten Laufs zu kontrollieren und die enthaltenen Daten nachzuvollziehen. Sinnvoll ist ein konsistenter Snapshot, der Datenbank und Dokumentenverzeichnisse zum gleichen Zeitpunkt abbildet. Ein Dump der Datenbank und ein davon zeitlich getrennter Kopiervorgang der Dokumente können im Fehlerfall zu einem inkonsistenten Stand führen.
Ein Update sollte erst begonnen werden, wenn eine aktuelle und nachvollziehbare Sicherung vorhanden ist. Besonders wichtig ist die Datenbank: Die Dokumente allein reichen nicht aus, da Zuordnungen, Tags, Korrespondenten und weitere Metadaten in der Datenbank gespeichert werden. Im Fehlerfall muss außerdem klar sein, wie sich der vorherige Stand wiederherstellen lässt.
Feste Versions-Tags statt latest
Für den Versionswechsel wird nicht pauschal der Tag latest verwendet, sondern jede relevante Paperless-Komponente erhält einen festen Versionsstand, beispielsweise 3.2.1. Das macht den Stack reproduzierbar: Die gleiche YAML-Datei startet auch später genau die getestete Version und nicht automatisch einen möglicherweise inzwischen veröffentlichten Nachfolger.
Der Einsatz von latest birgt mehrere Risiken. Ein erneuter Image-Pull kann zu einem anderen Softwarestand führen, ohne dass die Konfiguration geändert wurde. Außerdem können einzelne Images zu unterschiedlichen Zeitpunkten aktualisiert werden. Dadurch entstehen schwer nachvollziehbare Inkonsistenzen zwischen Webserver, Hintergrundprozessen und anderen Bestandteilen des Stacks.
Ein fester Tag bietet dagegen:
- einen klar definierten Ausgangs- und Zielstand,
- reproduzierbare Deployments,
- eine einfachere Fehlersuche,
- kontrollierte Rollbacks,
- und eine saubere Dokumentation des Updates.
Wichtig ist die Unterscheidung: Alle Paperless-Services – Webserver, Worker, Scheduler und die weiteren Paperless-Container – verwenden denselben festen Paperless-Tag, beispielsweise ghcr.io/paperless-ngx/paperless-ngx:3.2.1. Datenbank, Redis beziehungsweise Broker und weitere externe Komponenten tragen dagegen ihre eigenen Versionsschemata. Sie erhalten ebenfalls feste, aufeinander abgestimmte Tags – aber nicht denselben Paperless-Tag.
Die YAML-Anpassung
Die eigentliche Änderung erfolgt in der YAML-Datei des Paperless-Stacks. Dabei sollte nicht nur nach einer Zeile gesucht werden, die nach dem Webserver aussieht. Ein typischer Paperless-Stack besteht aus mehreren zusammengehörenden Komponenten: dem Webserver, Hintergrundprozessen für Aufgaben und Dokumentenverarbeitung, einem Scheduler oder ähnlichen Diensten sowie der Datenbank und Redis beziehungsweise dem verwendeten Broker.
Zunächst sollten alle Services und deren Image-Angaben vollständig geprüft werden. Wird nur der Webcontainer aktualisiert, können die übrigen Dienste weiterhin mit einem älteren Stand laufen. Das kann zu inkompatiblen Abhängigkeiten, fehlerhaften Hintergrundaufgaben oder einem uneinheitlichen Verhalten der Anwendung führen.
Vor dem Speichern empfiehlt sich eine kurze Bestandskontrolle:
- Alle Services der YAML-Datei auflisten.
- Jede Image-Zeile und jeden verwendeten Tag prüfen.
- Nur die für das Update vorgesehenen Versionsangaben ändern.
- Volumes, Netzwerke, Umgebungsvariablen und Abhängigkeiten unverändert lassen.
- Die Datei anschließend auf Syntax- und Einrückungsfehler kontrollieren.
Der eigentliche Update-Ablauf
Sobald die YAML-Konfiguration geprüft und ein Backup erfolgreich erstellt und geprüft wurde, folgt die technische Umsetzung. Auf dem UGREEN NAS erfolgt dies in einem strukturierten Ablauf.
Schritt 1: Images herunterladen
Zunächst werden die neuen Container-Images geladen. Wichtig ist, den Pull-Vorgang vollständig abzuwarten und auf Fehlermeldungen zu achten. Ein erfolgreicher Download bedeutet, dass die Images lokal verfügbar sind. Prüfe, ob alle erwarteten Images mit dem vorgesehenen Versionsstand vorhanden sind.
Schritt 2: Container neu bereitstellen
Im nächsten Schritt werden die Container mit den neuen Images neu erstellt. Dabei kommt es zu einer kurzen Unterbrechung der Erreichbarkeit. Laufende Importe sollten vor dem Update abgeschlossen sein. Nach dem Deploy ist zu prüfen, ob alle Container den Status „running“ beziehungsweise „healthy“ melden.
Schritt 3: Logs prüfen
Bevor die Weboberfläche getestet wird, lohnt sich ein Blick in die Logs. Besonders relevant sind erfolgreiche Datenbankmigrationen, der vollständige Start des Webservers sowie die Verbindung zu Datenbank und Redis.
Schritt 4: Funktionstest durchführen
Der finale Schritt ist die praktische Verifizierung:
- Anmeldung: Weboberfläche öffnen und einloggen.
- Suche: Ein bekanntes Dokument suchen.
- Dokumentimport: Ein Testdokument hochladen und die Verarbeitung prüfen.
- Fuzzy Search: Einen Suchbegriff absichtlich leicht abweichend eingeben und prüfen, ob dennoch passende Treffer geliefert werden.
Was tun, wenn etwas schiefgeht?
Ursachen systematisch eingrenzen
Startet ein Container nicht oder ist Paperless-ngx nicht erreichbar, gilt: Keine hektischen Änderungen. Beginne mit den Container- und Anwendungslogs. Prüfe die Erreichbarkeit der Abhängigkeiten und die Schreibrechte auf dem UGREEN NAS.
Rollback: Image zurücksetzen reicht oft nicht
Ein wichtiger technischer Hinweis: Ein Rollback des Container-Images stellt nicht automatisch den vorherigen Datenbankzustand wieder her. Wenn das Update das Datenbankschema verändert hat, ist eine ältere Anwendungsversion oft inkompatibel mit der neuen DB-Struktur.
Ein echtes Rollback erfolgt daher ausschließlich über ein geprüftes Backup:
- Alte Container stoppen.
- Datenbank und die relevanten Verzeichnisse wiederherstellen: Datenbank-Dump, media, consume und gegebenenfalls export.
- Die Wiederherstellung muss konsistent erfolgen – alle Bestandteile aus demselben Sicherungsstand.
- Dateirechte und Besitzverhältnisse der wiederhergestellten Verzeichnisse prüfen.
- Altes Image-Tag in der YAML-Datei wieder eintragen.
- Stack neu starten.
Persönliche Einordnung
Das Update von Paperless-ngx auf dem UGREEN NAS war technisch überschaubar. Entscheidend ist nicht, möglichst schnell auf Deploy zu klicken, sondern den Ablauf sauber vorzubereiten. Ein geprüftes Backup nimmt dem Update das Risiko, bei einem unerwarteten Fehler ohne Rückfallebene dazustehen.
Auch feste Tags in der YAML-Datei zahlen sich aus. Mit paperless-ngx:3.2.1 ist jederzeit nachvollziehbar, welche Version eingesetzt wird. Automatische Tags wie latest können dagegen unbeobachtet neue Änderungen einspielen. Die Kombination aus klarer Versionsangabe, geprüftem Backup und anschließender Funktionskontrolle macht den Betrieb planbarer.
Fazit und Empfehlung
Für UGREEN-NAS-Besitzer, die Paperless-ngx per Docker Compose betreiben, ist das Update von 3.1.x auf 3.2.1 eine sinnvolle Investition. Der Aufwand bleibt überschaubar, während die fehlertolerantere Suche und die OCR-Verarbeitung im Alltag konkrete Vorteile bringen.
Der bewährte Ablauf im Überblick:
Backup prüfen ? YAML-Tags festlegen ? Image pullen ? Stack deployen ? Logs prüfen ? Funktionstest.
Weiterführende Beiträge auf alleswasbewegt.de
- Paperless-ngx von Version 2 auf Version 3 aktualisieren – für Betreiber, die noch eine wesentlich ältere Version einsetzen.
- Paperless-GPT – die perfekte Ergänzung zu Paperless-ngx – Erfahre, wie du dein Archiv mit KI-Erweiterungen für automatische Analysen und bessere Auswertungen optimieren kannst.
- Alle Beiträge aus der Paperless-Serie – Der vollständige Überblick über alle Paperless-Artikel auf alleswasbewegt.de.
Auf alleswasbewegt.de findest du außerdem weitere Beiträge zu Selfhosting, Docker, NAS-Systemen und dem zuverlässigen Betrieb eigener Dienste.