Paperless-ngx

Dokumentenmanagement mit OCR, Volltextsuche, ASN-Barcodes und nativer KI. Seit E7 (September 2026) produktiv, Greenfield auf paperless-ngx 3.1. GitHub

Design, Plan und Inbetriebnahme: Design · Umsetzungsplan · Runbook Inbetriebnahme. Stack-Doku im Repo: homeserver/paperless-ngx/docs.md.

Zugriff

URL	https://paperless.home.robinwerner.net (nur intern)
Netzwerk	proxy_network, paperlessngx_internal
Traefik	Ja
Konten	lokal, nur Robin; Lars und SSO in E7b/E8

Stack

Container	Image	Zweck
paperless_ngx	paperless-ngx:3.1.3	App, Consumer, KI-Client
paperless_db	postgres:18.6	Datenbank (SSD)
paperless_redis	redis:8.10.1	Broker
gotenberg	gotenberg:8.37.0	Mail/Office → PDF
tika	tika:3.3.1.0	Textextraktion
protonmail-bridge	enucatl/protonmail-bridge:3.26.0	IMAP-Brücke zu Proton, nur intern (Port 1243)

Secrets (PAPERLESS_SECRET_KEY, POSTGRES_PASSWORD, PAPERLESS_DBPASS) kommen aus Infisical (/paperless-ngx) über den Agent nach /run/infisical/paperless-ngx.env.

Zulauf

Papier: HP Color LaserJet Pro MFP 4302, Quick Set „Paperless" (Farbe, 300 dpi, beidseitig) → Samba-Freigabe [paperless] auf dem NUC (nativ, Include aus dem Repo, force user = paperless 977/988) → consume/robin/. ASN-Barcodes (ASN00042) setzen die Archivnummer und trennen den Stapel: an jeder Seite mit Etikett beginnt ein neues Dokument. Quick Set „Ablage" → /mnt/scanner bleibt für Dokumente, die nicht nach Paperless sollen (überwiegend Lars).

Mail: Proton-Label „Paperless" (von Hand oder per Proton-Filter) → Mail-Regel liest Labels/Paperless über die Bridge, PDF-Anhänge werden Dokumente (Eigentümer Robin, Tags Inbox + E-Mail), danach Verschieben nach Labels/Paperless-erledigt. Bei Bridge ist das ein Label-Tausch, die Mail bleibt im Posteingang. Bridge braucht einen bezahlten Proton-Plan; die Anmeldung läuft einmalig über das Compose-Profil init bei gestopptem Run-Container.

Ablage

Speicherpfade je Lebensbereich (Arbeit, Finanzen, Versicherungen, Wohnung, Gesundheit, Behörden, Studium & Zeugnisse, Fahrzeug, Verträge & Abos), erste Ordnerebene ist der Eigentümer, _Unsortiert als Auffang:

robin/Gesundheit/PVS Bremen/2025/2025-07-03 Rechnung … ASN00068.pdf

Dokumenttypen beschreiben die Art des Schreibens (Rechnung, Bescheinigung, Vertragsänderung, Zugangsdaten …); „Schreiben" ist nur der Rest, der in keinen Typ passt. Tags tragen Status und Thema (Inbox, Handeln, Dauerhaft, E-Mail), dazu ein Tag je Steuerjahr (Steuer 2025) mit gespeicherter Ansicht — die Belege eines Steuerjahrs kommen erst im Folgejahr, ein Datumsfilter trifft sie nicht. Dokumente, die Robin und Lars gemeinsam betreffen, tragen den Tag Gemeinsam. Mit Lars' Konto (E7b) werden sie eigentümerlos und landen unter gemeinsam/…; die ASN ist haushaltsweit eindeutig, es gibt nur einen Nummernkreis. Das Startschema liegt in homeserver/paperless-ngx/seed/schema.yaml und wird idempotent über die API eingespielt; was Robin in der UI ergänzt, wird dort nachgezogen (E7b).

KI

openai-like gegen llama-swap auf dem aiserver (10.10.10.7:9292): paperless-llamacpp für Vorschläge (die brain-Gewichte Qwen3.6 mit --reasoning off, Duell 27.09.: gleiche Treffer wie brain bei 9 statt 60 s je Anfrage), embed-llamacpp für den RAG-Index (täglich 03:30). Ausgabesprache fest de-de.

Workflow „Dokument hinzugefügt" mit drei Aktionen „KI-Vorschläge anwenden": Korrespondent mit Anlegen · Titel und Datum mit Überschreiben · Typ, Speicherpfad, Tags nur bestehende. Je Aktion zwei Anfragen (Klassifikation und Übersetzung), rund 40 s je Dokument.

Wie die KI wählt: Sie kennt nicht die Liste der Pfade, Typen und Tags, sondern nur Kandidaten aus ähnlichen Dokumenten im Embedding-Index. Die ersten Dokumente werden von Hand eingeordnet, danach greifen sie als Vorbilder. Der klassische Klassifikator läuft parallel und lernt aus denselben Einordnungen.

Betrieb

Baustein	Was
paperless-export.timer	document_exporter täglich 01:15 nach /mnt/paperless/export (vor Borg 02:04)
paperless-consume-collector.timer	alle 15 min Gauges in den node-exporter-Textfile-Collector
PaperlessConsumeStuck, PaperlessConsumeCollectorStale	Alarme (warning), paperless_ngx in ContainerDown
Uptime Kuma	HTTP-Monitor vom VPS
scripts/ai_load_report.py	Zeit Import → letzte KI-Aktion je Dokument aus der Aufgaben-API
scripts/ai_duel.py	Modellvergleich gegen handeingeordnete Dokumente (/ai_suggestions/)

Backup: /mnt/ssd/container-data/paperless und /mnt/paperless liegen in beiden borgmatic-Ketten, der DB-Dump greift automatisch, der Export ist Paperless' eigenes Sicherungsformat (document_importer). Restore-Probe: E7b.

Wichtige Pfade

Pfad	Zweck
/mnt/ssd/container-data/paperless/data	Index, Klassifikator, LLM-Index
/mnt/ssd/container-data/paperless/db	Postgres
/mnt/ssd/container-data/paperless/consume/robin	Zulauf (Samba [paperless])
/mnt/ssd/container-data/paperless/protonmail-bridge	Bridge-Vault und Mail-Cache (UID 1000)
/mnt/paperless/media	Dokumente (UNAS)
/mnt/paperless/export	nächtlicher Export (UNAS)
/mnt/paperless/trash	Papierkorb (UNAS)

Fallen

• /api/documents/<id>/suggestions/ ist der klassische Klassifikator; die KI antwortet unter /ai_suggestions/.
• Die KI-Felder in Einstellungen → Anwendungskonfiguration leer lassen, der Datenbankwert schlägt die Compose-Datei.
• Bridge-info zeigt 127.0.0.1:1143; aus dem Paperless-Container gilt protonmail-bridge:1243.
• Mail-Regel: eine Aktion „Nichts" gibt es nicht; „Als gelesen" holt nur ungelesene Mails, „Markieren" nur ohne Stern.
• Gelöschte Dokumente behalten im Papierkorb ihre ASN; vor dem Neu-Scannen derselben Etiketten den Papierkorb leeren.
• Embeddings: embed-llamacpp braucht --ubatch-size mindestens so groß wie der längste Abschnitt (2048).

Offen (E7b)

Dropbox-Spiegel · Restore-Probe · Lars und Eigentümertrennung · Vision-OCR nach Schwelle · Mail als PDF · Custom Fields · Leerseiten aus Duplex-Scans · schema.yaml-Abgleich · Korrespondenten-Dubletten.