Inhaltsverzeichnis
Im vorherigen Artikel habe ich meinen praktischen Workflow mit ASN und QR-Codes beschrieben.
Dieser Artikel ist die technische Ergänzung dazu.
Denn so einfach der Ablauf später ist –
die automatische Erkennung von QR-Codes und ASN in Paperless-NGX funktioniert nicht automatisch. Sie muss bewusst aktiviert und sauber konfiguriert werden.
In diesem Artikel zeige ich, wie Paperless QR-Codes und ASN technisch verarbeitet, welche Komponenten beteiligt sind und worauf man achten sollte, damit das zuverlässig funktioniert.
Wo die QR-Code-Erkennung in Paperless stattfindet
Die wichtigste Klarstellung zuerst:
Nicht das Webinterface erkennt QR-Codes, sondern der Consumer.
Paperless-NGX besteht intern aus mehreren Diensten. Für alles, was mit Import, OCR, Barcodes und ASN zu tun hat, ist ausschließlich der Consumer zuständig.
Der Consumer verarbeitet:
- Dateien aus dem Import-Verzeichnis
- Scans
- mehrseitige PDFs
- E-Mail-Anhänge
Alles, was neu ins System kommt, läuft genau einmal durch diesen Prozess.
QR-Code-Erkennung ist kein Standardfeature
Die Barcode- und QR-Code-Erkennung ist kein automatisch aktives Feature.
Sie muss explizit eingeschaltet werden.
Paperless nutzt dafür eine Barcode-Engine, die jede Seite eines Dokuments analysiert und nach bekannten Code-Formaten sucht. Ohne diese Engine gibt es keine ASN-Erkennung, egal wie sauber die QR-Codes gedruckt sind.
Das ist einer der häufigsten Gründe, warum QR-Codes „nicht funktionieren“.
Die relevanten Einstellungen für ASN und QR-Codes
In Docker-Setups – wie sie typischerweise auf einer NAS laufen – wird die QR-Code- und ASN-Erkennung über Environment-Variablen gesteuert.
Bewährte Einstellungen sind zum Beispiel:
PAPERLESS_CONSUMER_ENABLE_BARCODES=true
PAPERLESS_CONSUMER_ENABLE_ASN_BARCODE=true
PAPERLESS_CONSUMER_ASN_BARCODE_PREFIX=ASN
PAPERLESS_CONSUMER_BARCODE_SCANNER=ZXINGWas diese Optionen bewirken
- ENABLE_BARCODES
Aktiviert die generelle Barcode- und QR-Code-Erkennung - ENABLE_ASN_BARCODE
Erlaubt Paperless, erkannte Codes als ASN zu interpretieren - ASN_BARCODE_PREFIX
Definiert, welcher Prefix als gültige ASN erkannt wird
(z. B.ASN000123) - BARCODE_SCANNER
Legt fest, welche Erkennungs-Engine genutzt wird
Alle vier Optionen gehören zusammen. Fehlt eine davon, wird ein QR-Code zwar eventuell erkannt, aber nicht korrekt als ASN verarbeitet.
Wie Paperless ein Dokument mit ASN verarbeitet
Der Ablauf beim Import sieht intern so aus:
- Das Dokument landet im Import-Verzeichnis
- Der Consumer liest die Datei ein
- Jede Seite wird analysiert:
- OCR
- Barcode- / QR-Code-Erkennung
- Wird ein gültiger ASN-Code gefunden:
- wird der Wert extrahiert
- dem Dokument zugewiesen
- im ASN-Feld gespeichert
Ab diesem Moment ist die ASN:
- fest mit dem Dokument verknüpft
- im Webinterface sichtbar
- vollständig durchsuchbar
Wichtig:
Die ASN wird ausschließlich beim Import gesetzt.
Ein späteres Ändern oder Hinzufügen eines QR-Codes hat keine Wirkung.
Typische Probleme aus der Praxis
QR-Code wird nicht erkannt
Die häufigsten Ursachen:
- Barcode-Erkennung nicht aktiviert
- falscher oder abweichender Prefix
- QR-Code zu klein gedruckt
- schlechter Kontrast
- zu niedrige Scanauflösung
QR-Codes sollten:
- klar gedruckt sein
- ausreichend groß
- nicht am Rand abgeschnitten
NAS- und Plattformbesonderheiten
Auf manchen NAS-Systemen, insbesondere auf ARM-basierten Geräten, kann es Einschränkungen bei der Barcode-Engine geben.
Typische Symptome:
- OCR funktioniert
- QR-Code-Erkennung ist unzuverlässig oder fehlt
In solchen Fällen hilft:
- ein Blick in die Consumer-Logs
- saubere Druckqualität
- realistische Erwartungen an Scanner und Auflösung
Logs sind der wichtigste Debug-Helfer
Wenn ASN oder QR-Codes nicht erkannt werden, ist der erste Schritt immer:
Die Logs des Consumer-Containers prüfen.
Dort sieht man:
- ob Barcodes gefunden wurden
- welcher Code erkannt wurde
- warum ein Code verworfen wurde
Ohne Logs ist Fehlersuche bei ASN reines Rätselraten.
Abgrenzung: QR-Codes vs. Dokumententrennung
QR-Codes und ASN nutze ich in meinem Workflow primär zur Identifikation und Wiederfindbarkeit von Dokumenten.
Paperless kann darüber hinaus auch Dokumente automatisch trennen.
Dieser Ansatz basiert jedoch auf einem anderen Konzept und gehört in einen eigenen Artikel, den ich separat behandle.
Hier geht es bewusst nur um:
- ASN
- QR-Codes
- eindeutige Zuordnung
Fazit
Die QR-Code- und ASN-Erkennung in Paperless-NGX ist kein Gimmick, sondern ein sehr solides technisches Feature – wenn man es bewusst aktiviert und versteht.
Wichtig ist:
- den Consumer zu kennen
- die Barcode-Erkennung explizit einzuschalten
- saubere QR-Codes zu nutzen
- und die Logs ernst zu nehmen
Dann wird aus einem kleinen QR-Code ein zuverlässiges Bindeglied zwischen Papier und digitalem Archiv.
Was mache ich damit in der Praxis?
ASN & QR-Codes in Paperless-NGX – mein einfacher Workflow mit einem Aktenordner
Dokumente automatisch trennen in Paperless-NGX – Stapelscans sauber verarbeiten
- Teil 1: Warum Scannen allein nicht reicht
- Teil 2: Wie Paperless-NGX im Hintergrund arbeitet
- Teil 3: Installation & Setup auf meiner UGREEN-NAS
- Teil 4: Konfiguration & Strukturen
- Teil 5: Papier-Workflow
- Teil 6: E-Mail-Import
- Teil 7: Automatisierung & Workflows
- Teil 8: Backups & Sicherheit
- Teil 9: Praxisbeispiele
- Teil 10: Mein komplettes Setup – Paperless-NGX Serie
- Mein optimiertes docker-compose.yml für Paperless-NGX auf der UGREEN-NAS
- Automatisierungsregeln & Templates – Paperless-NGX Serie
- Paperless GPT – Die perfekte Ergänzung zu Paperless-NGX
- Wartung der Paperless Instanz auf dem UGREEN NAS