231 lines
12 KiB
Markdown
231 lines
12 KiB
Markdown
# FEDEO Geräte-Agent
|
||
|
||
Der FEDEO Geräte-Agent läuft lokal auf macOS, Linux oder Raspberry Pi OS. Er holt instanzweite Scan-Aufträge von FEDEO ab, führt sie auf einem lokal angeschlossenen Scanner aus und lädt das Ergebnis wieder in FEDEO hoch.
|
||
|
||
Der Agent ist nicht an einen Mandanten gebunden. Jeder Auftrag enthält seinen Tenant selbst.
|
||
|
||
## Geführte Linux-Installation in FEDEO
|
||
|
||
Unter **Administration → Scanner → Agent einrichten** führt ein Assistent durch die Einrichtung:
|
||
|
||
1. Rechner benennen und den Agenten anlegen.
|
||
2. Die vom Scanner-Rechner erreichbare FEDEO-Serveradresse prüfen. Ein Backend-Pfad wie `/backend` muss erhalten bleiben. Optional den Autostart bei der Linux-Anmeldung aktivieren.
|
||
3. **Linux-Installation herunterladen**. Die Datei enthält die Software und die persönliche Konfiguration; ein Projekt-Checkout oder `npm install` ist nicht nötig.
|
||
4. Auf dem Scanner-Rechner im Download-Ordner den angezeigten Befehl `bash fedeo-agent-<ID>.sh` ausführen, ohne vorangestelltes `sudo`. Fehlende Pakete werden auf Mint/Ubuntu/Debian über `sudo apt-get` installiert. Node.js muss mindestens Version 20 haben; bei einer älteren Distribution gegebenenfalls zuerst Node.js aktualisieren.
|
||
5. Der Assistent wartet auf eine aktuelle Meldung des Agenten. Danach den erkannten Scanner und beispielsweise das Profil **ScanSnap iX1600: A4, Duplex, PDF, 300 dpi** wählen und abschließen.
|
||
6. Optional **Testscan öffnen**. Der eingerichtete Agent ist vorausgewählt. Erst ein Klick auf **Scannen** startet den Einzug; das Ergebnis landet im Hauptordner des aktuellen Mandanten.
|
||
|
||
Die Installationsdatei enthält einen Zugangstoken. Nach erfolgreicher Einrichtung löschen oder geschützt aufbewahren. Unter **Einrichtung öffnen** lässt sich ein bestehender Agent erneut installieren. Dafür den gespeicherten Token einfügen oder ausdrücklich einen neuen erzeugen; der bisherige Zugang wird dabei sofort ungültig.
|
||
|
||
Die Installation ist je Agent getrennt:
|
||
|
||
- Software: `~/.local/share/fedeo-device-agent/<ID>/`
|
||
- Konfiguration mit Dateirechten `0600`: `~/.config/fedeo-device-agent/<ID>.env`
|
||
- Arbeitsdateien: `~/.local/state/fedeo-device-agent/<ID>/`
|
||
- Benutzerdienst: `fedeo-device-agent-<ID>.service`
|
||
|
||
Die entsprechenden XDG-Verzeichnisse werden berücksichtigt. Der Autostart beginnt bei der Benutzeranmeldung. Ohne Autostart muss das gestartete Terminal geöffnet bleiben. Protokolle: `journalctl --user -u fedeo-device-agent-<ID>.service -f`. Eine erneute Installation ersetzt nur die Dateien dieses Agenten.
|
||
|
||
### Scannerverwaltung meldet HTTP 500 nach einem Serverupdate
|
||
|
||
Die älteren Scanner-SQL-Dateien `0051` bis `0053` waren nicht im Drizzle-Migrationsjournal eingetragen und wurden dadurch bei regulären Updates übersprungen. Die Vorwärtsmigration `0072_restore_instance_scan_agents` legt fehlende Tabellen und Spalten nachträglich an. Vorhandene Agenten, Tokens, Einstellungen und Scanaufträge bleiben erhalten.
|
||
|
||
Zuerst einen Backend-Stand mit dieser Migration ausrollen. Bei aktiviertem `FEDEO_RUN_MIGRATIONS` wird sie beim Start automatisch ausgeführt. Bei bewusst deaktivierten Startmigrationen muss anschließend im aktualisierten Backend `npm run migrate` ausgeführt werden. Die alten Journal-Zeitstempel nachträglich einzufügen genügt bei bereits aktualisierten Datenbanken nicht.
|
||
|
||
Der Datenbanktest läuft isoliert gegen ein temporäres PostgreSQL-Image und verwendet keine Anwendungskonfiguration:
|
||
|
||
```bash
|
||
cd backend
|
||
FEDEO_TEST_POSTGRES_IMAGE=postgres:16-alpine node --import tsx tests/instanceAgentMigration.test.ts
|
||
```
|
||
|
||
## Voraussetzungen
|
||
|
||
### macOS
|
||
|
||
```bash
|
||
brew install node sane-backends
|
||
scanimage -L
|
||
```
|
||
|
||
Für die Dateierstellung wird Python mit Pillow benötigt, beispielsweise über `npm run setup:opencv` (siehe unten).
|
||
|
||
Drucken nutzt später das macOS-Drucksystem/CUPS:
|
||
|
||
```bash
|
||
lpstat -p
|
||
```
|
||
|
||
### Linux und Raspberry Pi OS
|
||
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install -y nodejs npm sane-utils python3-pil
|
||
scanimage -L
|
||
```
|
||
|
||
Node.js muss mindestens Version 20 haben (`node --version`). CUPS ist nur für die optionale Druckererkennung erforderlich.
|
||
|
||
## ScanSnap iX1600 unter Linux per USB
|
||
|
||
Der iX1600 wird vom SANE-Backend `fujitsu` per USB unterstützt. Die USB-ID ist `04c5:1632`; die WLAN-Schnittstelle wird von diesem Backend nicht unterstützt. Quellen: [SANE-Geräteliste](https://sane-project.gitlab.io/website/sane-mfgs.html), [Fujitsu-Backend](https://sane-project.gitlab.io/website/man/sane-fujitsu.5.html).
|
||
|
||
1. Scanner einschalten und per USB anschließen. `lsusb -d 04c5:1632` und `scanimage -L` müssen ihn anzeigen. Den vollständigen Gerätenamen übernehmen, beispielsweise `fujitsu:ScanSnap iX1600:123456`.
|
||
2. Den oben beschriebenen Einrichtungsassistenten verwenden. Für eine manuelle Installation kann alternativ die API `POST /api/instance-agents` als Administrator einen Agenten und dessen einmalig ausgegebenen Token erstellen.
|
||
3. Im Verzeichnis `agents/fedeo-device-agent` die Abhängigkeiten installieren und konfigurieren:
|
||
|
||
```bash
|
||
npm ci
|
||
cp .env.example .env
|
||
chmod 600 .env
|
||
nano .env
|
||
```
|
||
|
||
```env
|
||
FEDEO_URL=https://deine-fedeo-instanz
|
||
FEDEO_AGENT_TOKEN=fedeo_agent_DEIN_TOKEN
|
||
FEDEO_SCANNER_NAME="fujitsu:ScanSnap iX1600:DEINE_SERIENNUMMER"
|
||
FEDEO_SCAN_SOURCE="ADF Duplex"
|
||
FEDEO_SCAN_FORMAT=pdf
|
||
FEDEO_SCAN_RESOLUTION=300
|
||
FEDEO_SCAN_MODE=Color
|
||
FEDEO_SCAN_POSTPROCESS=false
|
||
FEDEO_SCAN_TIMEOUT_SECONDS=900
|
||
```
|
||
|
||
`FEDEO_URL` ist die Basis-URL, unter der `/instance-agent/heartbeat` erreichbar ist, ohne zusätzliches `/api`.
|
||
4. `npm run build` und `npm start` ausführen. In FEDEO muss der Agent als online erscheinen.
|
||
5. In der Scannerverwaltung das erkannte Gerät wählen, **ScanSnap iX1600: A4, Duplex, PDF** anklicken und speichern.
|
||
6. Papier einlegen. Unter **Dateien → Scan** den Agenten wählen und **Scannen** anklicken. Der gesamte Stapel landet als ein PDF im aktuellen Ordner. Für den ersten Test zwei Blätter mit markierten Vorder- und Rückseiten verwenden: Das PDF muss vier Seiten in dieser Reihenfolge enthalten.
|
||
|
||
Der Agent liest im SANE-Batch-Modus bis zum leeren Einzug. Vorder- und Rückseiten werden in der vom Scanner gelieferten Reihenfolge gespeichert, einschließlich leerer Rückseiten. Es gibt keine automatische Leerseitenentfernung. „ADF Front“ scannt einen Stapel einseitig, „Flatbed“ eine einzelne Seite. Einzug-Scans benötigen PDF; PNG und TIFF sind für Einzelseiten verfügbar. Die Optionen entsprechen dem [scanimage-Handbuch](https://sane-project.gitlab.io/website/man/scanimage.1.html).
|
||
|
||
**Papierformat:** Das iX1600-Profil verwendet A4 mit 210 × 297 mm, einschließlich der Fujitsu-Einstellungen für die Papiergröße. Für andere Größen die Einstellung anpassen; „Scanner-Vorgabe“ übernimmt den am Treiber eingestellten Scanbereich. Die SANE-Quellen und Optionen lassen sich ohne Scan mit `scanimage -d 'DEIN_GERAETENAME' --source 'ADF Duplex' --help` prüfen.
|
||
|
||
**USB-Zugriff:** Wenn `lsusb` das Gerät sieht, `scanimage -L` jedoch nicht, zuerst Kabel, Stromversorgung, SANE-Version und Zugriffsrechte prüfen. Debian/Ubuntu/Mint liefern normalerweise passende udev-Regeln mit `libsane-common`. Andere Scanprogramme schließen. Einen dauerhaft laufenden Agenten unter einem Benutzer betreiben, der ebenfalls mit `scanimage -L` auf das Gerät zugreifen kann.
|
||
|
||
**Lange Stapel und Fehler:** Das Scan-Zeitlimit beträgt standardmäßig 15 Minuten; die Dateierstellung hat ein eigenes gleich langes Limit. Der Agent hält seinen Online-Status währenddessen aktuell. Der Dialog kann im Hintergrund weiterlaufen; Schließen stoppt den Scan nicht. Verbindungsfehler beim Abfragen des Status lösen keinen neuen Scan aus. Bei Papierstau, unvollständigem Duplex-Scan oder Uploadfehler wird kein automatischer erneuter Papiereinzug gestartet. Die Rohseiten bzw. die fertige Datei bleiben im gemeldeten Arbeitsverzeichnis zur Wiederherstellung erhalten. Nach erfolgreichem Upload werden sie gelöscht. Das Upload-Limit beträgt 100 MiB pro PDF; gegebenenfalls den Stapel teilen oder die Auflösung reduzieren.
|
||
|
||
## Konfiguration
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
nano .env
|
||
```
|
||
|
||
Wichtige Werte:
|
||
|
||
```env
|
||
FEDEO_URL=https://deine-fedeo-instanz
|
||
FEDEO_AGENT_TOKEN=fedeo_agent_...
|
||
FEDEO_SCANNER_NAME=
|
||
FEDEO_POLL_SECONDS=5
|
||
```
|
||
|
||
Wenn `FEDEO_SCANNER_NAME` leer bleibt, verwendet `scanimage` den Standard-Scanner.
|
||
|
||
## Entwicklung
|
||
|
||
```bash
|
||
npm ci
|
||
npm run dev
|
||
```
|
||
|
||
Nach Änderungen am Agenten oder am Linux-Installationsskript das im Frontend ausgelieferte Paket neu erstellen und mitcommitten:
|
||
|
||
```bash
|
||
npm run build:installer
|
||
```
|
||
|
||
`npm test` prüft mit `check:installer`, dass das Paket dem aktuellen Quellcode entspricht. Das Paket enthält keine Zugangsdaten; diese ergänzt erst der Browser beim Download. Die Installer-Tests verwenden temporäre Verzeichnisse und simulierte Systembefehle.
|
||
|
||
## OpenCV-Nachbearbeitung
|
||
|
||
Für automatischen Zuschnitt, leichte Entzerrung, Rotation und Kontrastkorrektur kann die OpenCV-Pipeline aktiviert werden.
|
||
|
||
```bash
|
||
npm run setup:opencv
|
||
```
|
||
|
||
Konfiguration:
|
||
|
||
```env
|
||
FEDEO_SCAN_POSTPROCESS=true
|
||
FEDEO_SCAN_POSTPROCESS_PROFILE=receipt
|
||
FEDEO_SCAN_POSTPROCESS_PYTHON=/pfad/zum/agent/.venv-opencv/bin/python
|
||
FEDEO_SCAN_POSTPROCESS_STRICT=false
|
||
```
|
||
|
||
Wenn `FEDEO_SCAN_POSTPROCESS_PYTHON` leer bleibt, verwendet der Agent automatisch `.venv-opencv/bin/python`, sofern diese Umgebung existiert, sonst `python3`. Pillow ist auch ohne Bildkorrektur für die Dateierstellung erforderlich. Falls OpenCV nicht installiert ist und `FEDEO_SCAN_POSTPROCESS_STRICT=false` gesetzt ist, werden die Rohseiten im gewünschten Ausgabeformat zusammengeführt. Eine fehlgeschlagene Korrektur verliert keine Seiten. Die Warnung erscheint im Scan-Ergebnis. Beim iX1600-Profil ist die Bildkorrektur zunächst ausgeschaltet, damit der vollständige A4-Scan erhalten bleibt.
|
||
|
||
Profile:
|
||
|
||
- `receipt`: Bons und schmale Belege werden bevorzugt hochkant zugeschnitten und kontrastiert.
|
||
- `document`: allgemeine Dokumente mit Farberhalt und moderater Verbesserung.
|
||
- `raw`: Zuschnitt/Entzerrung ohne starke Kontrastkorrektur.
|
||
|
||
## Container-Betrieb
|
||
|
||
Auf Linux und Raspberry Pi OS kann der Agent komplett im Container laufen. Dadurch bleiben Node.js, Python, OpenCV und SANE im Image. Auf dem Host werden dann nur Docker und Zugriff auf den USB-Scanner benötigt.
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
nano .env
|
||
docker compose -f docker-compose.example.yml up --build
|
||
```
|
||
|
||
Wenn FEDEO lokal auf dem Docker-Host läuft, verwende im Container nicht `localhost`, sondern:
|
||
|
||
```env
|
||
FEDEO_URL=http://host.docker.internal:3100
|
||
```
|
||
|
||
Scanner im Container prüfen:
|
||
|
||
```bash
|
||
docker compose -f docker-compose.example.yml run --rm fedeo-device-agent scanimage -L
|
||
```
|
||
|
||
Wenn der Scanner nicht sichtbar ist, hilft je nach Gerät/Host manchmal `privileged: true` im Compose-Beispiel. Auf macOS ist Docker dafür nur eingeschränkt geeignet, weil Docker Desktop USB-Scanner normalerweise nicht direkt an Linux-Container durchreichen kann. Für macOS bleibt deshalb der native Agent oder später eine signierte App der bessere Weg.
|
||
|
||
## Build
|
||
|
||
```bash
|
||
npm run build
|
||
npm start
|
||
```
|
||
|
||
## Tests
|
||
|
||
```bash
|
||
npm test
|
||
npm run test:python
|
||
```
|
||
|
||
Die Tests benötigen Python 3 mit Pillow. Sie simulieren `scanimage`, erstellen echte PDFs und prüfen Duplex-/Simplex-Stapel, Seitenreihenfolge, Auflösung, leeren Einzug, Papierstau, beschädigte Seiten, Dateinamen und OpenCV-Ausfälle. Ein Test mit angeschlossenem iX1600 bleibt zusätzlich erforderlich.
|
||
|
||
Hardwareprüfung am 17.09.2026: ScanSnap iX1600 per USB unter Linux Mint 22.3 mit SANE 1.2.1. Zwei A4-Blätter wurden mit 300 dpi in Farbe beidseitig gescannt; das erzeugte PDF enthält vier A4-Seiten in der Reihenfolge Vorderseite/Rückseite. Alle vier Seiten wurden visuell geprüft. Der Test umfasste den lokalen Agenten bis zur PDF-Erstellung; der FEDEO-Upload wird separat mit einem simulierten Dateispeicher getestet.
|
||
|
||
## FEDEO-Endpunkte
|
||
|
||
Der Agent nutzt:
|
||
|
||
- `POST /instance-agent/heartbeat`
|
||
- `GET /instance-agent/scan-jobs/next`
|
||
- `POST /instance-agent/scan-jobs/:id/status`
|
||
- `POST /instance-agent/scan-jobs/:id/upload`
|
||
|
||
## macOS Autostart
|
||
|
||
Die Vorlage liegt unter `system/macos/com.fedeo.device-agent.plist`. Nach Anpassung der Pfade kann sie als LaunchAgent installiert werden:
|
||
|
||
```bash
|
||
mkdir -p ~/Library/LaunchAgents
|
||
cp system/macos/com.fedeo.device-agent.plist ~/Library/LaunchAgents/
|
||
launchctl load ~/Library/LaunchAgents/com.fedeo.device-agent.plist
|
||
```
|
||
|
||
## Linux Autostart
|
||
|
||
Die Vorlage liegt unter `system/linux/fedeo-device-agent.service`.
|