Ein Dokument ist schnell hochgeladen. Bei mehreren tausend PDFs wird eine andere Frage wichtiger: Können wir nachher nachvollziehen, was tatsächlich übernommen wurde?
Unsere Ausgangslage war eine gewachsene Dateiablage. Die Dokumente lagen in Unterordnern, manche Inhalte kamen mehrfach vor, und zusätzliche Unterlagen sollten später noch dazukommen. Diese Sammlung wollten wir in Paperless-ngx überführen. Dabei sollte die bisherige Ordnung als Orientierung erhalten bleiben.
Der eigentliche Upload war nur ein Teil der Arbeit. Mehr Aufmerksamkeit brauchten die Vorbereitung, der Inhaltsvergleich und die Frage, wie ein unterbrochener Lauf zuverlässig fortgesetzt werden kann. Dieser Beitrag beschreibt die Erfahrungen aus der Migration. Beispiele sind frei gewählt und zeigen keine tatsächlichen Dokumentnamen oder internen Systemdaten.
Erst den Bestand verstehen
Paperless-ngx verwaltet Dokumente und macht sie über Suchfunktionen und Metadaten zugänglich. Korrespondenten, Dokumenttypen und Tags helfen beim Ordnen. Ein Speicherpfad beschreibt dagegen die Ablage der Dateien. Diese Begriffe erfüllen unterschiedliche Aufgaben. Die Projektanleitung zu Dokumenten und Metadaten erklärt die Grundlagen.
Für unsere Migration wollten wir zunächst die vorhandenen PDFs übernehmen. Andere Dateitypen gehörten nicht automatisch zum Auftrag. Damit war der Umfang klar genug, um einen überprüfbaren Plan zu erstellen.
Wir erfassten die Dateien, ihre Grössen und die vorgesehenen Ablagezuordnungen. Eine einfache Liste gab bereits Antworten auf wichtige Fragen: Wie viele PDFs gibt es? Wie gross ist der Bestand? Welche Unterordner müssen berücksichtigt werden? Gibt es Dateien ohne Inhalt?
Dabei fanden wir eine Datei mit null Bytes. Sie trug zwar die Endung PDF, enthielt aber kein Dokument. Die Prüfung hielt deshalb an. Nach dem Vergleich mit der ursprünglichen Ablage war klar, dass auch dort nur eine leere Datei vorhanden war.
Solche Fälle vor dem Import zu klären, macht den späteren Abschluss verständlicher. Eine Datei soll nicht einfach aus der Statistik verschwinden, weil ein Skript sie stillschweigend auslässt.
Kopiert, synchronisiert und importiert sind drei Zustände
OneDrive verwendeten wir als Bereitstellungsweg. Das Kopieren in einen lokalen synchronisierten Ordner und die vollständige Übertragung in die Cloud waren jedoch zwei getrennte Schritte.
Während der Synchronisierung blieb die angezeigte Restmenge zeitweise stehen. Eine Zählung des Cloudbestands zeigte, dass noch Dateien fehlten. Erst als die erwartete Dateianzahl dort vorhanden war, erstellten wir den vollständigen Importplan.
Auch diese Zählung war nur eine erste Kontrolle. Gleiche Anzahlen und passende Gesamtgrössen sagen noch nicht, ob jede einzelne Datei mit der Quelle übereinstimmt. Dafür folgte ein Inhaltsabgleich.
Für den Ablauf half uns diese Trennung:
Bestand aufnehmen
-> Bereitstellung vollständig synchronisieren
-> Inhalte und Ablagezuordnung prüfen
-> geplantes Paket importieren
-> gespeicherte Originale und Zuordnung bestätigenSo konnten wir eine stockende Cloudübertragung von einem Problem bei der Dokumentenverarbeitung unterscheiden. Ein Fortschrittsbalken allein hätte diese Unterscheidung nicht geliefert.
Mit einem kleinen Paket beginnen
Wir starteten mit einem begrenzten Test und erweiterten den Umfang schrittweise. Dabei prüften wir die erzeugten Dokumenteinträge, die gespeicherten Originale und die Ablagezuordnung.
Dieser Einstieg war wichtig, weil ein technischer Importerfolg noch nicht jede fachliche Frage beantwortet. Liegt das Dokument am gewünschten Ort? Lässt es sich öffnen? Ist Text vorhanden? Passt die Zuordnung zur bisherigen Sammlung?
Ein kleines Paket lässt sich dabei besser überblicken. Es zeigt, ob die gewählte Vorgehensweise funktioniert, bevor ein grosser Bestand dieselben Annahmen verwendet.
Erst nach diesen Prüfungen liessen wir den grösseren Lauf arbeiten. Die Paketgrenzen und ihre zugehörigen Pläne blieben erhalten. Dadurch war später nachvollziehbar, welcher Abschluss zu welchem Bestand gehörte.
Gleicher Inhalt unter verschiedenen Namen
Duplikate waren einer der interessantesten Teile der Migration. Zwei Dateien können unterschiedlich heissen und dennoch exakt dieselben Daten enthalten. Umgekehrt beweist derselbe Dateiname in zwei Ordnern keine inhaltliche Übereinstimmung.
Wir verglichen deshalb SHA256-Prüfsummen der Dateien. Bei übereinstimmender Prüfsumme behandelten wir die Dateien im Rahmen unseres Abgleichs als bytegleich. Das ist ein Vergleich der Dateidaten, keine inhaltliche Interpretation des Dokuments.
Zwei separat erzeugte PDFs desselben Schreibens können unterschiedliche Prüfsummen haben, etwa durch andere eingebettete Metadaten. Unser Verfahren sollte solche Dokumente nicht automatisch als fachlich identisch zusammenführen.
Bei den tatsächlich gleichen Dateien blieb eine weitere Entscheidung offen: Welche Ablagezuordnung sollte der spätere Paperless-Eintrag erhalten? Eine technische Prüfung kann feststellen, dass zwei Quellen übereinstimmen. Sie weiss aber nicht, welcher der bisherigen Ordner fachlich der richtige ist.
Wir trennten diese Gruppen deshalb vom eindeutig zuordenbaren Bestand. Nach der bewussten Auswahl übernahmen wir jeden der betreffenden neuen Inhalte einmal. So wurde aus einer Duplikatliste eine nachvollziehbare Ablageentscheidung.
Ein Dateiname kann gleich aussehen und anders gespeichert sein
Während der Verarbeitung hielten Prüfungen wegen abweichender Namen an. Die Dokumente waren dabei teilweise bereits erfolgreich importiert. Der Abbruch entstand erst bei der anschliessenden Kontrolle.
Ein Fall betraf die Gross-/Kleinschreibung der Dateiendung. In einem anderen Fall spielte die Unicode-Schreibweise eine Rolle: Ein sichtbarer Umlaut kann aus einem einzelnen Zeichen oder aus einem Grundbuchstaben mit kombinierendem Zeichen bestehen. Auf dem Bildschirm sieht beides gleich aus, ein exakter Zeichenvergleich kann trotzdem einen Unterschied melden.
Ausserdem wurde in einem Dateinamen ein geschütztes Leerzeichen entfernt. Auch das verändert die Zeichenfolge, obwohl der Unterschied beim Lesen kaum auffällt.
Die Lösung bestand jeweils darin, die konkrete Abweichung zu untersuchen. Wir prüften das zugehörige Dokument, die tatsächliche Ablage und die Prüfsumme des gespeicherten Originals. Erst danach erweiterten wir die erlaubten Namensvergleiche gezielt.
Eine pauschale Regel, die alle Leerzeichen entfernt oder ähnliche Namen gleichsetzt, wäre dafür zu weit gegangen. Sie könnte zwei verschiedene Dateien auf denselben Vergleichsnamen reduzieren. Mehrdeutige Treffer mussten deshalb weiterhin einen Stopp auslösen.
Diese Fälle waren eine nützliche Erinnerung: Der Dateiname ist ein wichtiges Merkmal, aber kein Ersatz für die Prüfung des gespeicherten Inhalts.
Nach einem Abbruch zuerst prüfen
Bei einer längeren Verarbeitung ist ein Abbruch nicht gleichbedeutend mit einem fehlgeschlagenen Upload. Genau diese Unterscheidung brauchten wir bei den Namensabweichungen.
Für die übernommenen Dateien führten wir persistente Prüfbelege. Sie verbanden die jeweilige Quelle mit dem erzeugten Dokumenteintrag und dem verifizierten Original. Bei einer Wiederaufnahme konnte der Ablauf vorhandene Übernahmen nachprüfen, bevor er einen weiteren Upload versuchte.
Das vermied, einen bereits erledigten Schritt nur aufgrund einer fehlenden letzten Erfolgsmeldung erneut auszuführen. Gleichzeitig durfte ein gespeicherter Status allein nicht genügen: Das zugehörige Original musste tatsächlich vorhanden sein und mit dem erwarteten Dateiinhalt übereinstimmen.
Nach Korrektur der jeweiligen Vergleichsregel setzten wir denselben Auftrag fort. Der Abschluss bestätigte die Prüfung aller geplanten Positionen. Die getrennt behandelten Duplikatgruppen wurden anschliessend mit ihrer ausgewählten Zuordnung übernommen.
Neue Dokumente bekommen einen neuen Abgleich
Nach dem grossen Lauf kamen weitere PDFs hinzu. Dafür erweiterten wir nicht rückwirkend den ursprünglichen Plan. Wir stellten die zusätzlichen Unterlagen bereit und erzeugten nach vollständiger Synchronisierung einen neuen Plan mit Inhaltsabgleich gegen den inzwischen vorhandenen Bestand.
Damit liessen sich bereits übernommene Inhalte von neuen Dokumenten unterscheiden. Die ursprünglichen Berichte blieben verständlich, und jede Ergänzungsrunde erhielt ihren eigenen Abschluss.
Dieses Vorgehen machte auch den Begriff «fertig» genauer. Ein Importpaket kann vollständig abgeschlossen sein, während weitere Unterlagen noch auf ihre eigene Übernahme warten. Die Bestätigung eines Pakets muss sich deshalb auf dessen festgelegten Umfang beziehen.
Prüfsumme und Suche beantworten unterschiedliche Fragen
Zum Abschluss gehörte die Prüfung des gespeicherten Originals. Eine passende Prüfsumme bestätigte die Übereinstimmung mit der vorgesehenen Quelldatei. Das war unser technischer Nachweis für den Dateiinhalt.
Eine andere Frage ist, wie gut ein Dokument später gefunden wird. Ein PDF kann bereits eine Textschicht enthalten oder eine Texterkennung benötigen. Vorhandener Text sagt für sich allein wenig darüber aus, ob etwa ein schlecht lesbarer Betrag richtig erkannt wurde.
Deshalb gehören für eine fachliche Abnahme auch Sichtprüfungen und passende Suchbeispiele dazu. Die Datei vollständig gespeichert zu haben und sie im Alltag gut nutzen zu können, sind zwei ergänzende Ziele.
Sicherung und Migration gemeinsam denken
Eine Dokumentensammlung besteht aus mehr als den PDFs. Zu einer Anwendung gehören auch ihre Datenbank, Metadaten, Einstellungen und die für den Betrieb benötigte Konfiguration.
Wir ergänzten die Migration deshalb um eine Datenbank- und Konfigurationssicherung mit verschlüsselter Ablage auf einem S3-kompatiblen Ziel. Bei den geprüften Sicherungsläufen wurden die erzeugten Archive zurückgelesen und verglichen.
Für ein Wiederherstellungskonzept müssen Dokumentdateien und Anwendungsdaten zusammenpassen. Liegen sie in unterschiedlichen Sicherungsverfahren, braucht es einen abgestimmten Wiederherstellungsstand. Ein Datenbankstand, der auf inzwischen fehlende Dateien verweist, wäre dafür keine ausreichende Grundlage.
Die Paperless-Projektanleitung zur Sicherung und Wiederherstellung beschreibt unter anderem den Dokumentenexport sowie die Sicherung der verwendeten Datenbestände. Welcher Weg passt, hängt von der Installation ab.
Das Rücklesen eines Archivs bestätigt dessen Lesbarkeit und den geprüften Datenvergleich. Für einen vollständigen Restore müssen zusätzlich Anwendung, Dokumente und Metadaten gemeinsam wieder funktionieren. Diese Unterscheidung haben wir auch im Beitrag Ein Backup ist ein Anfang. Der Restore ist der Beweis. beschrieben.
Was uns bei dieser Migration geholfen hat
Der Bestand liess sich schrittweise übernehmen, einschliesslich der nachträglich bereitgestellten Dokumente. Besonders hilfreich waren ein klar abgegrenzter Plan, der Inhaltsvergleich und die getrennte Behandlung von Duplikaten.
Die Unterbrechungen zeigten, weshalb ein eigener Prüfschritt nach dem Upload sinnvoll ist. Er machte Abweichungen sichtbar, die eine reine Erfolgsmeldung der Übertragung nicht erklärt hätte. Mit den Prüfbelegen konnten wir gezielt weiterarbeiten.
Für ähnliche Vorhaben würde ich wieder klein anfangen: ein überschaubares Paket übernehmen, seine Ablage und Verwendung prüfen und erst danach den Umfang erhöhen. So wird aus vielen einzelnen Uploads ein Vorgang, dessen Ergebnis sich auch später noch erklären lässt.