Paperless-ngx 3.0 sicher aktualisieren: ein Praxisbericht
Veröffentlicht am 23. Juli 2026 · zuletzt aktualisiert am 28. August 2026 / in Digitale Archive
Inhaltsübersicht
Kurz gesagt
Dieser Beitrag dokumentiert mein tatsächlich durchgeführtes Docker-Upgrade von Paperless-ngx 2.20.15 auf 3.0.0. Vorher prüfte ich Bestand, Konfiguration, eigene Skripte und Borg-Sicherung. Danach testete ich Datenbank, API, Suche, Download, OCR und die eigene Duplikatroutine.
Zwei Probleme stammten aus meiner gewachsenen Konfiguration: eine zweite vollständige Paperless-Prozessgruppe und eine veraltete Dateinamensvorlage. Beide waren keine neuen Fehler von Paperless-ngx 3.0.
Ausgangslage
| Bereich | Ermittelter Stand am 23.07.2026 |
|---|---|
| Host | Intel NUC5i3RYB, 4 logische CPUs, 7,6 GiB RAM |
| Betriebssystem | Debian GNU/Linux 13.6 |
| Docker | Engine 29.6.2, Compose 2.26.1 |
| Paperless | 2.20.15 → 3.0.0 |
| Datenbank | SQLite im WAL-Modus |
| Zusatzdienste | Redis 7.4.9, Tika 3.3.1, Gotenberg 8.34.0 |
| Bestand | 1.844 Dokumente, rund 1,9 GiB Medien |
| Backup | BorgBackup 1.4.0 auf eingebundenem NAS-Repository |
Welche Änderungen meine Installation betrafen
| Änderung | Meine Maßnahme | Ergebnis |
|---|---|---|
| Ausgangsversion 2.20.15 | vor dem Upgrade bestätigt | Voraussetzung erfüllt |
Pflicht für PAPERLESS_SECRET_KEY |
Existenz geprüft, Wert nicht ausgegeben | Start erfolgreich |
| MD5 → SHA-256 | eigenes Duplikatskript auf 64-stellige Hashwerte erweitert | 1.844 Dokumente migriert; Test erfolgreich |
| Whoosh → Tantivy | Neuaufbau des Suchindex abgewartet | Standardsuche und Testsuche erfolgreich |
| OCR und Archivdatei getrennt | beide Einstellungen kontrolliert | Bild-PDF erkannt, Archiv-PDF abrufbar |
| Consumer-Polling umbenannt | neue Variable gesetzt | Polling aktiv |
| API-Versionen unter 9 entfernt | Analysewerkzeug von v6 auf v10 geändert | API meldete Version 3.0.0 |
| Dateinamensvorlage | alte Django-Filter durch gültige Jinja-Syntax ersetzt | Testimport ohne alte Warnung |
| zusätzliche Prozessgruppe | zweiten vollständigen Paperless-Container entfernt | Scheduler-Konflikt beseitigt |
Andere Breaking Changes wurden nur daraufhin geprüft, ob sie meine SQLite-Installation und meine Skripte betrafen. Eine allgemeine Zusammenfassung aller Änderungen von Paperless-ngx 3 steht in der offiziellen Migrationsdokumentation.
Sicherung und Rückweg
Vor dem Upgrade entstand das Borg-Archiv paperless-debian-2026-07-23_12-34-31. borg check --last 1 war erfolgreich; der konsistente Datenbanksnapshot db_consistent.sqlite3, Compose-Datei, Umgebungsdatei und Skriptkonfiguration waren im Archiv nachweisbar.
Ein Rollback hätte nicht nur das alte Image benötigt. Datenbank, Medien, Compose-Datei, Umgebungsdatei, eigene Skripte und das exakte Image 2.20.15 hätten gemeinsam zurückgesetzt werden müssen. Währenddessen hätte kein neuer Import stattfinden dürfen.
Der frühere Restore-Test wurde von mir als erfolgreich bestätigt. Im aktuellen Upgrade-Protokoll ist sein Umfang jedoch nicht detailliert genug dokumentiert, um ihn als erneut nachgewiesenen vollständigen Host-Restore auszuweisen.
Durchführung und reale Probleme
Nach der Sicherung setzte ich das Image fest auf Version 3.0.0. Datenbankmigrationen, Umstellung der Dokumentprüfsummen und Neuaufbau des Suchindex liefen vollständig durch.
Doppelte Paperless-Prozessgruppe
paperless-webserver und paperless-worker starteten jeweils Webdienst, Consumer, Celery-Worker und Scheduler gegen dieselben Daten. Das führte zu Migrations- und Scheduler-Konflikten. Für diesen kleinen Host entfernte ich den zusätzlichen vollständigen Container.
IPv4-Bindung
Mein lokales Netz bleibt bewusst bei IPv4. Mit PAPERLESS_BIND_ADDR=0.0.0.0 band ich die Anwendung ausdrücklich daran.
Dateinamensvorlage und Klassifikator
Ein Testimport deckte die alte Template-Syntax auf. Nach der Umstellung auf Jinja blieb der bestehende Speicherpfad erhalten. Das alte Klassifikationsmodell wurde beim ersten Import verworfen; die Dokumente selbst waren davon nicht betroffen.
End-to-End-Test
Ein synthetisches bildbasiertes PDF ohne produktive Daten durchlief den echten Eingang:
| Prüfschritt | Ergebnis |
|---|---|
Ablage über consume |
erfolgreich |
| konfigurierte Stabilitätswartezeit | berücksichtigt; Taskstart nach rund 925 Sekunden |
| OCR | 278 Zeichen; Testphrase zweimal gefunden |
| Verarbeitung | rund 19,7 Sekunden |
| Dokumentdatum und PDF-Abruf | erfolgreich |
| Workflows | allgemeine Tags angewendet |
| Korrespondent, Dokumenttyp, Speicherpfad | bewusst nicht erfunden |
| SHA-256-Duplikattest | identische zweite Datei vor Import nach duplicates verschoben |
| Bereinigung | alle Testartefakte entfernt; Bestand wieder 1.844 Dokumente |
Der Test prüfte damit mehr als einen gestarteten Webserver: Eingang, OCR, Suche, Workflows, Dokumentabruf und die eigene Fail-closed-Duplikatroutine. Wie ähnliche Dokumente danach ohne automatisches Löschen geprüft werden, zeigt der Praxistest zur Fuzzy Duplicate Detection.
Messwerte und Grenzen
Nach der Bereinigung antwortete die lokale Startseite in fünf Einzelmessungen nach rund 3,4 bis 4,1 ms. Beim Testimport nutzte Paperless etwa einen CPU-Kern und maximal rund 916 MiB RAM. Der Neustart bis zur ersten HTTP-Antwort dauerte rund 93 Sekunden, bis zum Docker-Status healthy rund 100 Sekunden.
Das sind Messwerte dieser Installation und keine allgemeine Leistungszusage. Ein identischer Vorher-Nachher-Test für OCR, große PDFs und parallele Last wurde nicht durchgeführt.
Ergebnis
Datenbankintegrität, API v10, Suche, Dokumentabruf, OCR und die eigene SHA-256-Routine funktionierten nach dem Upgrade. Die doppelte Prozessgruppe und die alte Dateinamenssyntax wurden bereinigt. Eine Kontrollprüfung unter 3.0.3 zeigte keine funktionalen Abweichungen; spätere Patch- und Minor-Updates stehen im separaten Artikel Paperless-ngx 3.x kontrolliert aktualisieren.
Offen bleiben ein erneut vollständig protokollierter Host-Restore und reproduzierbare Vergleichsmessungen mit großen Dokumenten.
Quellen
Weiterführende Paperless-Praxis
- Updates innerhalb der Paperless-ngx-3.x-Reihe – kontrollierte Patch- und Minor-Updates nach dem Major-Upgrade
- Dubletten mit Fuzzy Duplicate Detection prüfen – ähnliche Dokumente bewerten, ohne automatisch zu löschen
- Paperless-ngx zuverlässig sichern – Backup, Prüfung und Wiederherstellbarkeit
- Paperless-ngx-Arbeitsabläufe aus der Praxis – Regeln, Posteingang und menschliche Sichtkontrolle
Persönliche Unterstützung
Dieser Artikel vermittelt die fachlichen Grundlagen. Wenn Sie die beschriebenen Methoden auf einen konkreten Bestand oder ein bestehendes System übertragen möchten, finden Sie ergänzende Informationen unter Dienstleistungen.