Paperless-ngx Backup & Restore: Die richtige Strategie
Erstelle ein sicheres, inkrementelles Paperless-ngx Backup mit Docker und stelle deine Dokumente im Notfall wieder her. Mit Anleitung für PostgreSQL und MariaDB, Schritt für Schritt erklärt.
Auf YouTube ansehen
Inhalt
Paperless-ngx 3.4.2PostgreSQL 18MariaDB 11.8Docker 29.9Ubuntu 24.04Ein Dokumentenmanagementsystem (DMS) wie Paperless-ngx ist das Herzstück des papierlosen Büros. Aber was passiert, wenn der Server ausfällt, ein Update fehlschlägt oder die Datenbank korrupt ist? Ohne ein vernünftiges Backup sind nicht nur die Einstellungen weg, sondern im schlimmsten Fall deine wichtigen Dokumente.
Ich zeige dir eine Backup-Strategie, die sowohl die Datenbank als auch die Dateien sichert, dabei Speicherplatz spart und von allein läuft. Sie funktioniert mit PostgreSQL und mit MariaDB. Getestet habe ich sie mit Paperless-ngx 3.4.2 auf einem frischen Ubuntu-24.04-Server, einmal mit PostgreSQL 18 und einmal mit MariaDB 11.
Warum einfach Ordner kopieren nicht reicht
Viele Nutzer kopieren einfach den gesamten Docker-Ordner. Das kann funktionieren, birgt aber Risiken:
- Datenbank-Konsistenz: Wenn du die Datenbank-Dateien kopierst, während der Container läuft, kann das Backup korrupt und unbrauchbar sein.
- Interne Verknüpfungen: Paperless verknüpft Dokumente in der Datenbank mit Dateien im Dateisystem. Wenn diese nicht synchron gesichert werden, gibt es Probleme.
Die sauberste Lösung ist eine Kombination aus einem SQL-Dump der Datenbank und dem integrierten Document Exporter von Paperless.
Die Strategie
Wir wollen folgendes erreichen:
- Einen sauberen Dump der Datenbank erstellen.
- Die Dokumente mit dem Paperless Exporter in ein verarbeitbares Format bringen (dabei werden auch Metadaten in
json-Dateien geschrieben). - Diese Daten inkrementell sichern, um Speicherplatz zu sparen (wir wollen nicht jeden Tag 10 GB kopieren, wenn sich nur zwei PDFs geändert haben).
- Alte Backups automatisch löschen (Retention Policy).
Der Export enthält auch die Datenbankinhalte (Tags, Korrespondenten, Benutzer, Einstellungen) in der Datei manifest.json. Für den Restore brauchst du deshalb im Normalfall nur den Export. Der SQL-Dump ist nur ein zusätzliches Sicherheitsnetz.
Vorbereitung
Oben im Artikel kannst du deine Werte eintragen: Pfade, Service-Namen und Datenbankzugang. Sie stehen danach in den Befehlen.
In der compose.yaml hat jeder Eintrag direkt unter services: einen Service-Namen, zum Beispiel db und webserver. Docker Compose vergibt daraus beim Start Container-Namen, es sei denn, du setzt selbst container_name. Das Skript nutzt docker compose exec, und dieser Befehl will immer den Service-Namen (webserver, db).
Erstelle auf deinem Server eine Datei, z.B. backup-paperless.sh.
nano {{paperless_dir}}/backup-paperless.shFüge folgenden Inhalt ein:
#!/bin/bash
set -e
set -o pipefail
# --- KONFIGURATION ---
# Pfad, wo die Backups landen sollen
BACKUP_BASE_DIR="{{backup_dir}}"
# Dein Paperless-Verzeichnis (wo die compose.yaml liegt)
PAPERLESS_DIR="{{paperless_dir}}"
# Name des Symlinks für das letzte Backup
LATEST_LINK="${BACKUP_BASE_DIR}/latest"
# Namen der SERVICES aus der compose.yaml (nicht der Container-Namen!)
# Das sind die Einträge direkt unter "services:".
DB_SERVICE="{{db_service}}"
WEBSERVER_SERVICE="{{webserver_service}}"
# Datenbank Zugangsdaten (aus deiner compose.yaml)
DB_USER="{{db_user}}"
DB_NAME="{{db_name}}"
# Wie viele Tage sollen Backups behalten werden?
RETENTION_DAYS=30
DOCKER_COMPOSE_CMD="/usr/bin/docker compose"
echo "========================================================"
echo "Starte Paperless-Backup: $(date)"
echo "========================================================"
# Alle Compose-Befehle laufen im Paperless-Verzeichnis
cd "${PAPERLESS_DIR}"
# 1. Neues Backup-Verzeichnis erstellen
DATE_STAMP=$(date +"%Y-%m-%d_%H-%M-%S")
BACKUP_DIR="${BACKUP_BASE_DIR}/${DATE_STAMP}"
mkdir -p "${BACKUP_DIR}"
# Bei einem Fehler das unvollständige Backup wieder entfernen
trap 'rm -rf "${BACKUP_DIR}"' ERR
echo "[+] Erstelle Backup-Verzeichnis: ${BACKUP_DIR}"
# 2. Datenbank sichern (PostgreSQL)
echo "[+] Erstelle PostgreSQL-Dump..."
${DOCKER_COMPOSE_CMD} exec -T "${DB_SERVICE}" pg_dump -U "${DB_USER}" -d "${DB_NAME}" > "${BACKUP_DIR}/paperless-db.sql"
# Prüfen ob der Dump leer ist
if [ ! -s "${BACKUP_DIR}/paperless-db.sql" ]; then
echo "FEHLER: Datenbank-Dump ist leer!"
exit 1
fi
echo " -> Datenbank-Dump erfolgreich."
# 3. Paperless Dokumente exportieren
echo "[+] Starte den document_exporter..."
${DOCKER_COMPOSE_CMD} exec -T "${WEBSERVER_SERVICE}" document_exporter ../export --delete --no-progress-bar
echo " -> Document-Exporter erfolgreich ausgeführt."
# 4. Dokumente inkrementell mit rsync und Hard-Links sichern
echo "[+] Synchronisiere Dokumente..."
if [ -d "${LATEST_LINK}" ]; then
LINK_DEST_OPTION="--link-dest=${LATEST_LINK}/documents"
echo " -> Vorheriges Backup gefunden. Nutze Hard-Links."
else
LINK_DEST_OPTION=""
echo " -> Kein vorheriges Backup gefunden. Erstelle Voll-Kopie."
fi
# Annahme: ./export ist im PAPERLESS_DIR gemountet
rsync -a --delete ${LINK_DEST_OPTION} "${PAPERLESS_DIR}/export/" "${BACKUP_DIR}/documents/"
echo " -> Dokumente synchronisiert."
# 5. 'latest' Symlink aktualisieren
echo "[+] Aktualisiere 'latest'-Link."
ln -snf "${BACKUP_DIR}" "${LATEST_LINK}"
# 6. Alte Backups löschen
echo "[+] Lösche Backups älter als ${RETENTION_DAYS} Tage..."
find "${BACKUP_BASE_DIR}" -maxdepth 1 -type d -not -name "latest" -not -path "${BACKUP_BASE_DIR}" -mtime +${RETENTION_DAYS} -exec rm -rf {} \;
echo " -> Bereinigung abgeschlossen."
echo "========================================================"
echo "Paperless-Backup erfolgreich abgeschlossen!"
echo "========================================================"- Bricht ein Schritt ab, räumt
trapdas halbe Backup-Verzeichnis weg. Sonst wird beim nächsten Lauf ein unvollständiges Backup als Basis für die Hard-Links genommen. --deleteentfernt aus dem Export-Ordner Dateien von Dokumenten, die du in Paperless gelöscht hast.--no-progress-barhält das Log sauber.- Die letzte
find-Zeile schließt den Backup-Ordner selbst aus.
Skript ausführbar machen
Damit das Skript läuft, müssen wir ihm die entsprechenden Rechte geben:
chmod +x {{paperless_dir}}/backup-paperless.shErster Testlauf
Starte das Skript einmal von Hand, bevor du es automatisierst:
{{paperless_dir}}/backup-paperless.sh========================================================
Starte Paperless-Backup: Thu Nov 5 05:27:54 AM UTC 2026
========================================================
[+] Erstelle Backup-Verzeichnis: /home/deployn/backup/2026-11-05_05-27-54
[+] Erstelle PostgreSQL-Dump...
-> Datenbank-Dump erfolgreich.
[+] Starte den document_exporter...
-> Document-Exporter erfolgreich ausgeführt.
[+] Synchronisiere Dokumente...
-> Kein vorheriges Backup gefunden. Erstelle Voll-Kopie.
-> Dokumente synchronisiert.
[+] Aktualisiere 'latest'-Link.
[+] Lösche Backups älter als 30 Tage...
-> Bereinigung abgeschlossen.
========================================================
Paperless-Backup erfolgreich abgeschlossen!
========================================================Beim zweiten Lauf meldet das Skript Vorheriges Backup gefunden. Nutze Hard-Links. Das spart Platz: In meinem Test belegte das erste Backup mit 30 Dokumenten 1,4 MB, das zweite nur noch 516 KB, weil unveränderte Dateien per Hard-Link auf das erste zeigen. Den Unterschied siehst du mit du -sh:
du -sh {{backup_dir}}/*Wichtig: Der Export-Pfad
Das Skript geht davon aus, dass du in deiner compose.yaml ein Volume für den Export definiert hast. Das sollte ungefähr so aussehen:
volumes:
- ./data:/usr/src/paperless/data
- ./media:/usr/src/paperless/media
- ./export:/usr/src/paperless/export # <--- WICHTIG
- ./consume:/usr/src/paperless/consumeDer document_exporter Befehl im Skript (../export) bezieht sich auf den Pfad innerhalb des Containers. Da Paperless im Container oft in /usr/src/paperless/src arbeitet, führt ../export zu /usr/src/paperless/export, was wir nach außen gemappt haben.
Automatisierung mit Cron
Niemand macht Backups gerne manuell. Richten wir einen Cronjob ein, der das jede Nacht um 3 Uhr erledigt.
crontab -eFüge folgende Zeile hinzu (angepasst an deinen Pfad):
0 3 * * * {{paperless_dir}}/backup-paperless.sh >> /var/log/paperless_backup.log 2>&1Oder erstelle einen anderen Zeitplan.
Restore: Der Ernstfall (Disaster Recovery)
Ein Backup ist wertlos, wenn man es nicht wiederherstellen kann. Hier ist der Weg zurück, falls dein Server komplett neu aufgesetzt werden muss.
1. Frische Installation vorbereiten
Lege ein neues Paperless-Verzeichnis mit derselben compose.yaml an, als wäre es ein neuer Server. Erstelle die leeren Ordner data, media, export, consume und db und starte den kompletten Stack, also Datenbank und Webserver:
docker compose up -d
docker compose psWarte, bis der Webserver healthy meldet. Er legt dabei die Datenbanktabellen an.
2. Backup in den Export-Ordner kopieren
Kopiere den Inhalt von documents aus deinem Backup in den Ordner export der neuen Installation. Der Punkt am Ende von documents/. ist wichtig, damit der Inhalt und nicht der Ordner selbst kopiert wird:
cp -r {{backup_dir}}/latest/documents/. export/3. Importer ausführen
docker compose exec -T {{webserver_service}} document_importer ../export --no-progress-barFound existing user(s), this might indicate a non-empty installation
Checking the manifest
Copy files into paperless...
Updating search index...Die erste Zeile ist harmlos, wenn du beim Start einen Admin-Benutzer angelegt hast (zum Beispiel über PAPERLESS_ADMIN_USER). Der Importer liest die manifest.json, schreibt Dokumente, Tags, Korrespondenten und Benutzer in die Datenbank, kopiert die Dateien in media und baut den Suchindex neu auf.
Danach gelten die Zugangsdaten aus dem Backup. In meinem Test hat der Admin-Benutzer der frischen Installation ein anderes Passwort bekommen als der aus dem Backup. Nach dem Import galt nur noch das alte Passwort.
Variante: Nur die Datenbank aus dem SQL-Dump zurückspielen
Der Dump in paperless-db.sql enthält nur die Datenbank, keine Dokumentdateien. Er ist nützlich, wenn nur die Datenbank kaputt ist und der Ordner media noch vorhanden ist, oder wenn du die PostgreSQL-Version wechseln willst. Starte dafür nur den Datenbank-Service mit einer leeren Datenbank und spiele den Dump ein:
docker compose up -d {{db_service}}
docker compose exec -T {{db_service}} psql -U {{db_user}} -d {{db_name}} -v ON_ERROR_STOP=1 < {{backup_dir}}/latest/paperless-db.sqlDie Schritte für einen Versionswechsel stehen in Paperless-ngx: PostgreSQL auf Version 18 aktualisieren.
MariaDB statt PostgreSQL
Paperless-ngx läuft auch mit MariaDB. Hier ändert sich fast nichts, denn der Document Exporter und der Importer arbeiten mit beiden Datenbanken gleich. Wenn du nur den Export sicherst, brauchst du keine Anpassung. Willst du zusätzlich einen SQL-Dump, tauschst du im Skript die Zeile mit pg_dump aus:
${DOCKER_COMPOSE_CMD} exec -T "${DB_SERVICE}" pg_dump -U "${DB_USER}" -d "${DB_NAME}" > "${BACKUP_DIR}/paperless-db.sql"
${DOCKER_COMPOSE_CMD} exec -T "${DB_SERVICE}" sh -c 'mariadb-dump -h localhost -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"' > "${BACKUP_DIR}/paperless-db.sql"Die Zeile mit sh -c liest Benutzer, Passwort und Datenbankname aus den Umgebungsvariablen des Datenbank-Containers (MARIADB_USER, MARIADB_PASSWORD, MARIADB_DATABASE). So steht kein Passwort im Skript. Das setzt voraus, dass diese Variablen bei deinem db-Service in der compose.yaml stehen, wie im offiziellen Beispiel. Die Variablen DB_USER und DB_NAME aus dem Skript werden dann nicht benutzt.
Zum Zurückspielen eines Dumps nimmst du den passenden Gegenbefehl:
docker compose exec -T {{db_service}} sh -c 'mariadb -h localhost -u"$MARIADB_USER" -p"$MARIADB_PASSWORD" "$MARIADB_DATABASE"' < {{backup_dir}}/latest/paperless-db.sqlDer Restore mit dem Importer (Schritte 1 bis 3 oben) bleibt unverändert.
3-2-1 Regel nicht vergessen
Das Skript oben sichert die Daten lokal in einen anderen Ordner. Wenn deine Festplatte stirbt, ist auch das Backup weg.
Du solltest den Ordner {{backup_dir}} unbedingt auf ein externes Ziel kopieren. Das kannst du beispielsweise mit:
- Rclone (Upload zu Google Drive, OneDrive, S3)
- BorgBackup (Verschlüsseltes Backup auf einen anderen Server)
- Synology Hyper Backup (Wenn du auf einem NAS bist)
PostgreSQL-Version wechseln
Der Datenbank-Dump ist auch der Weg, um die Datenbank auf eine neuere PostgreSQL-Version zu bringen. Die Schritte dafür stehen in Paperless-ngx: PostgreSQL auf Version 18 aktualisieren.
Fazit
Das Skript sichert Datenbank und Dokumente in einem Lauf, und dank Hard-Links belegt jedes weitere Backup nur den Platz der geänderten Dateien. Beim Einrichten kommt es vor allem auf die Service-Namen in der compose.yaml an.
Teste den Restore-Prozess unbedingt einmal in einer virtuellen Maschine oder auf einem Test-System, bevor du dich im Notfall darauf verlassen musst!
FAQ
Häufige Fragen
Reicht der Document Exporter allein als Backup?
Für den Restore meist ja. Der Export enthält neben den Dokumenten auch die Datenbankinhalte in der Datei manifest.json, und der Importer stellt beides wieder her. Der zusätzliche SQL-Dump ist ein Sicherheitsnetz, zum Beispiel für einen Wechsel der Datenbankversion.
Funktioniert das Backup auch mit MariaDB?
Ja. Exporter und Importer sind unabhängig von der Datenbank. Für einen zusätzlichen SQL-Dump tauschst du im Skript pg_dump gegen mariadb-dump aus. Der Abschnitt zu MariaDB oben zeigt die nötigen Befehle.
Kann ich das Backup machen, während Paperless läuft?
Ja. Der Dump und der Document Exporter funktionieren im laufenden Betrieb.
Warum ist das zweite Backup so viel kleiner als das erste?
Das Skript nutzt rsync mit Hard-Links. Dateien, die sich nicht geändert haben, werden nicht erneut kopiert, sondern zeigen auf die Datei im vorherigen Backup. In meinem Test waren es 1,4 MB für das erste und 516 KB für das zweite Backup.
Wie prüfe ich, ob mein Backup wirklich funktioniert?
Spiele es auf einem Testserver oder in einer virtuellen Maschine ein, wie im Restore-Abschnitt beschrieben. Vergleiche danach die Anzahl der Dokumente und melde dich mit deinen Zugangsdaten an.
Änderungsprotokoll
Skript überarbeitet: Unvollständige Backups werden bei Fehlern entfernt, Restore mit dem Importer neu beschrieben. Abschnitt zu MariaDB und FAQ ergänzt.