digiscan-ng Agent

Scanner-Agent für den Betrieb mit SANE-kompatiblen Scannern. Läuft als systemd-Service direkt auf dem Scan-Rechner — kein Docker, kein Container.

Unterstützte Scanner

Profil	Modell	Anschluss	Besonderheit
panakvs	Panasonic KV-S5076H	USB	Udev-Regel für stabilen Gerätepfad erforderlich
canon_dr	Canon DR-9080C	USB / SCSI	Automatische Schwarzrand-Korrektur nach dem Scan
airscan	Brother MFC-L2750DW u.a.	Netzwerk (AirScan/eSCL)	Keine lokale Treiberinstallation nötig

Warum kein Docker?

USB-Scanner mit proprietären SANE-Backends funktionieren nicht zuverlässig in Containern, da Host-Treiberbibliotheken nicht portierbar sind. Direktinstallation auf dem Host ist die einzig zuverlässige Lösung.

---

Voraussetzungen

Debian / Ubuntu

# SANE + Scanner-Treiber
sudo apt install sane sane-utils

# Python + Basis
sudo apt install python3 python3-venv

# OCR
sudo apt install ocrmypdf

# Barcode-Erkennung (Laufzettel / Trennblätter)
sudo apt install libzbar0

# Bildverarbeitung (Schwarzrand-Korrektur, Leerseiten-Erkennung)
sudo apt install python3-numpy python3-pil
# oder via pip im venv (install.sh erledigt das automatisch)

# Optional: unpaper (verbesserte Bildkorrektur für Canon DR-Serie)
sudo apt install unpaper

Fedora / RHEL / CentOS

# SANE + Scanner-Treiber
sudo dnf install sane-backends sane-backends-drivers-scanners

# Für AirScan/eSCL (Netzwerkscanner)
sudo dnf install sane-airscan

# Python + Basis
sudo dnf install python3 python3-virtualenv

# OCR
sudo dnf install ocrmypdf
# falls nicht im Repo: pip install ocrmypdf

# Barcode-Erkennung (Laufzettel / Trennblätter)
sudo dnf install zbar
# pyzbar wird via pip im venv installiert (requirements.txt)

# Bildverarbeitung
sudo dnf install python3-numpy python3-pillow

# Optional: unpaper
sudo dnf install unpaper

# Firewall: Agent-Port freigeben (Standard: 8089)
sudo firewall-cmd --permanent --add-port=8089/tcp
sudo firewall-cmd --reload

Wichtig auf Fedora: Firewalld ist standardmäßig aktiv und blockiert eingehende Verbindungen. Ohne die Firewall-Regel kann der Server den Agent nicht erreichen — der Scanner erscheint dann als "nicht gefunden" in der UI, obwohl der Agent lokal läuft und den Scanner erkennt.

Scanner-Test (alle Distros)

# Prüfen ob Scanner erkannt wird:
scanimage --list-devices

# Hinweis: SANE 1.4+ (Fedora 43+) gibt die Liste auf stderr aus:
scanimage --list-devices 2>&1

---

Installation

# 1. Repo klonen oder Dateien nach /opt/digiscan-ng-agent kopieren
sudo mkdir -p /opt/digiscan-ng-agent
sudo cp agent.py requirements.txt install.sh setup-usb.sh /opt/digiscan-ng-agent/

# 2. Installationsskript ausführen (legt venv an + installiert Python-Pakete + systemd-Service)
cd /opt/digiscan-ng-agent
sudo bash install.sh

# 3. Konfiguration anpassen
sudo nano /etc/digiscan-agent.conf

Konfiguration (/etc/digiscan-agent.conf)

# URL des digiscan-ng Servers
# Immer direkt auf SvelteKit zeigen (Port 3000), nie über Caddy/nginx
# Wenn Agent und Server auf verschiedenen Rechnern: IP des Servers angeben
DIGISCAN_SERVER=http://192.168.1.77:3000

# Secret muss mit AGENT_SECRET in digiscan-ng/.env übereinstimmen
DIGISCAN_SECRET=...   # openssl rand -hex 32

# Port auf dem der Agent lauscht (muss in Firewall freigegeben sein)
AGENT_PORT=8089

Zur Server-URL: Der Agent kommuniziert direkt mit SvelteKit auf Port 3000, nicht über Caddy oder nginx. Das vermeidet TLS-Zertifikatsprobleme auf dem Scan-Rechner. AGENT_PROXY_MODE=true in der Server-.env sorgt dafür dass der Browser den Agent über den SvelteKit-Proxy erreicht — der Agent selbst spricht immer HTTP zum Server.

---

USB-Berechtigungen

Falls Scanner nur als root erkannt wird:

# Automatisch via Skript (empfohlen):
sudo bash setup-usb.sh

# Oder manuell:
sudo cp 60-digiscan-scanner.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
# Dann Benutzer zur scanner-Gruppe hinzufügen und neu einloggen:
sudo usermod -aG scanner $USER

---

Betrieb

# Status
sudo systemctl status digiscan-agent

# Logs live verfolgen
journalctl -u digiscan-agent -f

# Neustart
sudo systemctl restart digiscan-agent

---

Scanner-Profile — Besonderheiten

Panasonic KV-S5076H (panakvs)

USB-Pfad kann sich nach Neustart ändern (libusb:BUS:DEV). Die Udev-Regel in 60-digiscan-scanner.rules legt einen stabilen Symlink an. Pflichtschritt nach der Installation:

sudo bash setup-usb.sh

Canon DR-9080C (canon_dr)

Kein Udev-Symlink nötig — canon_dr-Backend adressiert den Scanner stabil. Der Agent korrigiert nach jedem Scan automatisch schwarze Ränder (ADF-Gehäuse-Reflexion) und normalisiert die Helligkeit.

Profil wird im digiscan-ng Admin-Bereich unter Scan-Stationen ausgewählt.

AirScan/eSCL — Netzwerkscanner (airscan)

Kein USB, keine udev-Regel. Scanner muss im selben Netzwerk erreichbar sein. sane-airscan (bzw. libsane-airscan) muss installiert sein.

---

Häufige Probleme

Problem	Ursache	Lösung
"Kein Scanner gefunden" in der UI, Agent läuft	Firewall blockiert Port 8089	firewall-cmd --add-port=8089/tcp
scanimage --list-devices gibt nichts aus	Auf Fedora: Ausgabe auf stderr	scanimage --list-devices 2>&1 testen; Agent ≥ v4.1 liest beide Streams
Unable to find zbar shared library	zbar nicht installiert	Debian: apt install libzbar0 · Fedora: dnf install zbar
Scanner nur als root erkannt	USB-Berechtigungen fehlen	sudo bash setup-usb.sh ausführen
Agent erkennt Scanner, aber Scan schlägt fehl	Falsches Profil in der DB	Im Admin-Bereich Scan-Station prüfen: Profil muss zum Gerät passen
Scan bleibt nach letztem Blatt stehen	Kein Abschlussblatt (Laufzettel) gescannt	💾 Jetzt speichern klicken — normales Verhalten ohne Barcode