Paperless-ngx: Scanner einrichten mit Samba, Barcodes und App

Ein Scanner, der direkt in Paperless-ngx speichert, ist der Punkt, an dem aus Papierstapeln ein Archiv wird. Du legst den Brief ein, drückst eine Taste, und kurz darauf ist er durchsuchbar im System.

Die Technik dahinter heißt Consume-Ordner. Paperless beobachtet einen Ordner und übernimmt jede Datei, die dort erscheint. Ich zeige hier, wie du diesen Ordner per Samba im Netzwerk freigibst, damit Scanner und Computer hineinschreiben, wie du mit Unterordnern Tags vergibst und wie du einen Stapel mit Trennblättern in einzelne Dokumente zerlegst. Zum Schluss geht es um das Handy.

Die Wege ins System

Es gibt vier Wege, ein Dokument in Paperless zu bringen:

In diesem Beitrag geht es um den Consume-Ordner und die App.

Der Consume-Ordner

In der Standard-compose.yaml von Paperless-ngx hängt unter dem Dienst paperless diese Zeile:

- ./consume:/usr/src/paperless/consume

Der Ordner consume neben deiner compose.yaml ist also der Eingang. Kopiere eine PDF hinein, und Paperless übernimmt sie nach wenigen Sekunden. Die Datei im Ordner verschwindet dabei, Paperless legt sie in media ab. Das Verhalten ist so gewollt.

Unterordner beachtet Paperless nur, wenn du das einschaltest. Ergänze in der .env:

PAPERLESS_CONSUMER_RECURSIVE=true
PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS=true

PAPERLESS_CONSUMER_SUBDIRS_AS_TAGS macht aus den Namen der Unterordner Tags. Eine Datei in consume/Steuer/ bekommt den Tag “Steuer”. Existiert er nicht, legt Paperless ihn an.

Samba-Freigabe

Ein Scanner kann nicht auf den Ordner eines Servers zugreifen, bevor du ihn im Netzwerk freigibst. Dafür nutze ich einen kleinen Samba-Container im selben Compose-Projekt. Ergänze unter services diesen Dienst:

    samba:
        image: dockurr/samba
        container_name: paperless-samba
        restart: unless-stopped
        environment:
            NAME: scans
            USER: scanner
            PASS: dein-starkes-passwort
            UID: 1000
            GID: 1000
        ports:
            - "192.168.1.10:445:445"
        volumes:
            - ./consume:/storage

• NAME ist der Name der Freigabe, USER und PASS sind die Zugangsdaten für den Scanner.
• UID und GID müssen zu dem Benutzer passen, dem Paperless gehört, standardmäßig 1000.
• Ersetze 192.168.1.10 durch die IP-Adresse deines Servers im lokalen Netz. Dann hört Samba nur dort zu.

Starte den Container:

sudo docker compose up -d

Wichtig: Gib Port 445 nie ins Internet frei. Samba gehört in dein lokales Netz. Steht dein Paperless auf einem VPS, erreicht dein Scanner zu Hause den Server nur über ein VPN wie WireGuard oder Tailscale. Alternativ nimmst du für den VPS die App oder den Upload im Browser und betreibst Samba nur auf einem Server im Heimnetz.

Freigabe testen

Bevor du den Scanner konfigurierst, prüfe die Freigabe mit smbclient (auf Debian: sudo apt install smbclient):

smbclient //192.168.1.10/scans -U scanner -c "ls"

Nach der Passwortabfrage siehst du den Inhalt des Ordners. Teste dann einen Upload:

smbclient //192.168.1.10/scans -U scanner -c "put rechnung.pdf"

Nach etwa 20 Sekunden taucht das Dokument in Paperless auf, und rechnung.pdf ist aus consume verschwunden. Im Log siehst du es auch:

sudo docker compose logs -f paperless

Erscheint die Datei, funktioniert die Kette.

Unterordner als Tags testen

Ich lege dazu in consume einen Ordner Steuer an und lade die Datei dort hinein:

smbclient //192.168.1.10/scans -U scanner -c "cd Steuer; put spendenquittung.pdf"

Das Dokument kommt mit den Tags “Inbox” und “Steuer” an. Der Tag “Inbox” stammt aus meinem Workflow, “Steuer” aus dem Ordnernamen. So kannst du am Scanner mehrere Zielordner anlegen, etwa Steuer, Versicherung und Auto, und jede Datei landet sofort mit dem richtigen Tag im System.

Scanner konfigurieren

Die genauen Menüs unterscheiden sich pro Hersteller. Du suchst nach “Scan to Folder”, “Scan to SMB” oder “Scan to Network Folder”. Diese Angaben brauchst du fast überall:

Stelle den Scanner auf PDF und 300 dpi. Das reicht für saubere Texterkennung, ohne dass die Dateien riesig werden.

Scanner mit Funktion “Scan to FTP” funktionieren auch, brauchen aber einen FTP-Server vor dem Ordner. Samba ist einfacher.

Ältere Scanner sprechen manchmal nur SMB1. Aktuelle Samba-Versionen schalten das aus, und ich rate dir nicht, es einzuschalten. In dem Fall lohnt sich eher ein Scanner-Tausch oder ein Raspberry Pi als Zwischenstation.

Stapel mit Barcodes trennen

Wenn du zwanzig Briefe auf einmal einlegst, entsteht eine einzige PDF. Paperless kann sie zerlegen, wenn zwischen den Briefen ein Blatt mit einem speziellen Barcode liegt. Dafür schaltest du die Barcode-Erkennung ein:

PAPERLESS_CONSUMER_ENABLE_BARCODES=true

Der Standard-Trennbarcode lautet PATCHT. Du druckst ein Blatt mit diesem Code aus (im Netz gibt es fertige “PATCH-T”-Trennblätter) und legst es zwischen die Briefe. Paperless teilt die PDF an jedem dieser Blätter und wirft die Trennblätter weg. Das Original verschwindet, die Teile werden eigene Dokumente.

Archivseriennummern per Barcode

Zusätzlich kann Paperless die Archivseriennummer (ASN) aus einem Barcode lesen. Das nutze ich, wenn ich Papier aufhebe: Auf jedes Original klebe ich einen Aufkleber mit ASN00042, und Paperless trägt die Nummer 42 ins Dokument ein. Später finde ich den Ordner im Schrank über die Nummer.

PAPERLESS_CONSUMER_ENABLE_ASN_BARCODE=true

Der Barcode besteht aus dem Präfix ASN und der Nummer. Das Präfix änderst du mit PAPERLESS_CONSUMER_ASN_BARCODE_PREFIX.

Test mit einem Stapel

Ich habe eine PDF mit drei Seiten gebaut: Seite 1 ist eine Rechnung mit dem Barcode ASN00042, Seite 2 ein Trennblatt PATCHT, Seite 3 ein Vertrag mit ASN00043. Nach dem Ablegen im Consume-Ordner hat Paperless zwei Dokumente angelegt, das erste mit ASN 42, das zweite mit ASN 43.

Die Trennseite ist weg, und Paperless hat die Seiten sauber verteilt. Mein Workflow hat danach den Wartungsvertrag über das Wort “Kündigungsfrist” erkannt und passend getaggt.

Die ASN muss eindeutig sein. Lädst du dieselbe Datei ein zweites Mal hoch, lehnt Paperless sie mit “Given ASN 42 already exists” ab. Im Log steht der Fehler, das Dokument selbst wird nicht doppelt angelegt.

Mit dem Handy scannen

Unterwegs geht es mit einer App, die per API in dein Paperless hochlädt. Die Paperless-Entwickler führen im Wiki eine Liste. Ich nenne hier nur Apps, die dort stehen:

• Android: Paperless Mobile, Paperless NGX Uploader für den Teilen-Dialog, Waraq für Paperless 3.
• iOS: Swift Paperless, Less Paper und QuickScan.

Die Apps brauchen die Adresse deines Servers und einen Benutzer. Tipp: Lege in Paperless einen eigenen Benutzer für die App an und vergib ein langes Passwort.

Die Apps eignen sich vor allem für Belege, die du unterwegs bekommst und sofort erfassen willst.

Typische Fehler

Dateien bleiben im Consume-Ordner liegen. Prüfe das Log mit sudo docker compose logs paperless. Häufige Ursache sind falsche Besitzrechte: Paperless läuft mit der Benutzer-ID 1000 und muss den Ordner lesen und löschen dürfen.

Der Scanner meldet “Zugriff verweigert”. Die UID oder GID im Samba-Container passen nicht zum Ordner, oder Benutzername oder Passwort stimmen nicht. Teste die Freigabe zuerst mit smbclient.

Dateien erscheinen erst nach langer Zeit. Liegt der Consume-Ordner auf einem Netzlaufwerk, erkennt Linux neue Dateien nicht immer sofort. Setze dann PAPERLESS_CONSUMER_POLLING=10, damit Paperless alle zehn Sekunden nachsieht.

Ein Dokument fehlt, obwohl die Datei weg ist. Schau ins Log mit sudo docker compose logs paperless. Dort steht, ob Paperless die Datei zum Beispiel wegen einer doppelten ASN abgelehnt hat.

FAQ