Paperless-ngx Dokumente automatisch in Dropbox synchronisieren

Paperless-ngx Dokumente automatisch in Dropbox spiegeln: Hash-basierte Synchronisation, Unicode-Normalisierung und eventbasierte Automatisierung mit systemd.path.

17. Juli 2026

KI-generiertPaperless-ngx Dokumente automatisch in Dropbox synchronisieren

Dieses Projekt ist ein wunderbares Beispiel, wie man einen KI-Agenten für seine Arbeit einsetzen kann. Das Script, Die Einrichtung auf dem Paperless-LXC, dieser Blogbeitrag und das GitHub Repository wurden von meinem Hermes-KI-Agenten unter meiner Anleitung erstellt.

Paperless-ngx ist ein großtartiges Werkzeug, um Dokumente zu archivieren, zu durchsuchen und zu verwalten. Doch manchmal möchte man seine Dokumente auch außerhalb der Web-Oberfläche zur Verfügung haben – strukturiert, lesbar und direkt auf dem eigenen Rechner. Genau dafür habe ich meinen Paperless-ngx Dokumentenbestand automatisch in einen Dropbox-Ordner synchronisiert.

Warum das sinnvoll ist

Es gibt mehrere gute Gründe, warum eine gespiegelte, ordentliche Dokumentenstruktur auf dem eigenen Computer oder in der Cloud sinnvoll sein kann:

1. Lokale Durchsuchbarkeit unter macOS Wer einen Mac nutzt, kann aus der Dropbox-Synchronisation enorm profitieren: Die PDFs liegen in einer klaren Ordnerstruktur auf der Festplatte und sind damit vollständig über Spotlight durchsuchbar. Man findet Rechnungen, Verträge oder Bescheide also nicht nur in Paperless, sondern direkt über die macOS-Suche – ohne zusätzliche Software.

2. Unabhängigkeit vom Paperless-Server Wenn der Paperless-Container oder der Server einmal nicht erreichbar ist, liegen die Dokumente dennoch als normale PDF-Dateien vor. Das schafft eine zusätzliche Sicherheitsebene und erleichtert den Zugriff von unterwegs.

3. Klare, nachvollziehbare Ordnerstruktur Paperless speichert Dokumente nach Absender und Jahr sortiert. Wer diese Struktur auch außerhalb von Paperless haben möchte – etwa für ein Jahresarchiv, die Steuerberatung oder die Übergabe an Familienmitglieder – bekommt sie durch den Sync automatisch gespiegelt.

4. Backup und Langzeitarchiv Eine Kopie in Dropbox ist kein vollwertiges Backup im klassischen Sinn, aber sie ist ein bequemer Zweitort. Wenn etwas mit der Paperless-Datenbank oder dem Speicher schiefgeht, bleiben die eigentlichen Dokumente erhalten.

Ausgangslage

Paperless-ngx läuft bei mir in einem LXC-Container. Die Dokumente liegen strukturiert unterhalb von media/documents/ in zwei Ordnern:

Ziel war es, beide Ordner in einen Dropbox-Ordner zu spiegeln, damit ich dort jederzeit eine lesbare Kopie habe – auch ohne direkten Zugriff auf Paperless.

Warum nicht einfach rsync?

rsync ist für viele Szenarien die erste Wahl. Hier gab es aber mehrere Anforderungen, die eine eigene Lösung sinnvoll machten:

  1. Zwei Quellen, ein Ziel: archive/ und originals/ sollen zusammengeführt werden.
  2. Priorität: Gibt es eine Datei in beiden Quellen, soll die OCR-Version aus archive/ gewinnen.
  3. SHA-256 statt Zeitstempel: Dropbox und Paperless können unterschiedliche Zeitstempel haben; ein Hash-Vergleich ist zuverlässiger.
  4. Unicode-Normalisierung: Dateinamen mit Umlauten können je nach Dateisystem unterschiedlich kodiert sein (NFC vs. NFD). Das führt sonst zu doppelten oder nicht gefundenen Dateien.
  5. Logging, Lockfile und Tests: Ein produktiver Sync sollte nachvollziehbar, idempotent und automatisiert testbar sein.

Die Lösung: Ein Python-Synchronisationsskript

Ich habe ein Python-Skript entwickelt, das folgende Schritte ausführt:

  1. Scannt archive/ und originals nach regulären Dateien.
  2. Berechnet für jede Datei einen SHA-256-Hash.
  3. Normalisiert alle relativen Pfade auf Unicode-NFC.
  4. Bestimmt den gewünschten Zielzustand (archive hat Vorrang vor originals).
  5. Kopiert neue oder geänderte Dateien atomar in das Ziel.
  6. Entfernt Dateien aus dem Ziel, die weder in archive noch in originals existieren.
  7. Entfernt leere Verzeichnisse.

Zusätzlich werden Dropbox-interne Dateien wie .sync/, .DS_Store, Thumbs.db und desktop.ini über eine Exclude-Liste ignoriert.

Besonderheit: Umgang mit Unicode-Dateinamen

Ein konkretes Beispiel war die Datei Shelly Download printed user guide - English, Deutsch, Italiano, Español, Português, Français.pdf. Deren Sonderzeichen lagen im Quellverzeichnis in einer anderen Unicode-Normalisierung vor als im Ziel. Durch die NFC-Normalisierung und ein Mapping auf die tatsächlichen Dateipfade konnte das Skript die Dateien korrekt zuordnen, ohne sie fälschlicherweise als neu oder gelöscht zu klassifizieren.

Tests vor dem echten Lauf

Bevor das Skript auf die echten Daten losgelassen wurde, habe ich mit pytest mehrere Tests geschrieben:

Das gibt Sicherheit, bevor man 21.000+ Dateien verändert.

Deployment und Ausführung

Das Skript liegt auf dem LXC unter /home/paperless/bin/ und wird als Benutzer paperless ausgeführt. So hat es die nötigen Rechte für die Paperless-Daten und den Dropbox-Ordner, ohne root zu benötigen.

Erstlauf

Anschließend zeigte ein Verifizierungslauf mit --dry-run 0 Kopien und 0 Löschungen – Quelle und Ziel waren konsistent.

Automatisierung: Event-basiert statt nur zeitgesteuert

Neben einem täglichen Cron-Job um 07:00 Uhr habe ich eine systemd.path-Unit eingerichtet. Sie überwacht archive/ und originals/ und startet den Sync-Service sofort, wenn sich etwas ändert. Das hat den Vorteil, dass neue Dokumente nicht bis zum nächsten Morgen warten müssen, aber dennoch keine ständigen unnötigen Rechenläufe durchgeführt werden.

Der Cron bleibt als Sicherheitsnetz erhalten.

Fazit

Der Sync zwischen Paperless-ngx und Dropbox läuft jetzt zuverlässig und weitgehend automatisch. Durch den Hash-basierten Vergleich, die Unicode-Normalisierung und die Kombination aus event-basiertem und zeitgesteuertem Trigger ist die Lösung sowohl robust als auch ressourcenschonend.

Alle Quellen, die Installationsanleitung und die Systemd-Units gibt es im Repository: https://github.com/UhlhornHH/paperless-dropbox-sync

XlpJuop2VExl