PKR-Lab

30050 - Paperless-ngx — Dokumentenmanagement mit OCR

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/30050-paperless-ngx.md

Paperless-ngx — Dokumentenmanagement mit OCR

Cluster: PROD · Ordner argocd/apps/prod/paperless-ngx/ · URL https://paperless.prod.homeserver. kubectl-Befehle in diesem Doc gelten für den PROD-Cluster (Zugriff je Cluster).

Paperless-ngx digitalisiert Briefe, Rechnungen und Verträge per OCR und macht
sie volltextdurchsuchbar. Dokumente können per Scanner, Smartphone-Foto oder
E-Mail eingereicht werden — alles Weitere läuft automatisch.


Architektur

paperless.prod.homeserver  →  Traefik  →  paperless-ngx (Port 8000)
                                          ├── Redis Sidecar (localhost:6379)
                                          ├── PVC: data   (20 Gi, nas)
                                          ├── PVC: media  (50 Gi, nas)
                                          ├── PVC: consume (5 Gi, nas)
                                          ├── PVC: export (10 Gi, nas)
                                          └── PVC: redis   (1 Gi, nas)

Erster Start

Nach dem Deploy muss ein Admin-Account angelegt werden:

kubectl -n paperless-ngx exec -it deploy/paperless-ngx -- \
  python3 manage.py createsuperuser

Danach ist die Web-UI unter https://paperless.prod.homeserver erreichbar.


Secret Key sichern

Der PAPERLESS_SECRET_KEY in values.yaml ist ein Platzhalter und muss
vor dem ersten produktiven Einsatz durch einen echten geheimen Wert ersetzt
werden. Empfohlen: SealedSecret anlegen.

# Zufälligen Key generieren:
python3 -c "import secrets; print(secrets.token_hex(50))"

# Als SealedSecret:
echo -n "<generated-key>" | kubeseal --raw \
  --namespace paperless-ngx --name paperless-ngx-secret \
  --from-file=/dev/stdin

Dann in values.yaml die Env-Variable auf einen secretKeyRef umstellen.


Dokumente einreichen

Consume-Ordner (automatisch)

Dateien im Consume-Verzeichnis werden automatisch verarbeitet. Der PVC
paperless-ngx-consume kann per kubectl cp befüllt werden:

kubectl -n paperless-ngx cp /lokale/datei.pdf \
  $(kubectl -n paperless-ngx get pod -l app.kubernetes.io/name=paperless-ngx \
    -o jsonpath='{.items[0].metadata.name}'):/usr/src/paperless/consume/

Web-Upload

Direkt über die Web-UI unter https://paperless.prod.homeserver/upload.

E-Mail-Import (optional)

Paperless kann E-Mails mit Anhängen automatisch abholen (IMAP). Konfiguration
in der Admin-UI unter Mail → E-Mail-Konten.


n8n-Integration

Mit n8n (https://n8n.prod.homeserver) lassen sich Paperless-Ereignisse
weiterverarbeiten, z. B.:

Neues Dokument in Paperless (Webhook)
  → Kategorisierung prüfen
  → ntfy-Push "📄 Neue Rechnung erkannt: {Titel}"

Paperless bietet eine REST-API unter https://paperless.prod.homeserver/api/.


Backup

# Export aller Dokumente (inkl. Metadaten):
kubectl -n paperless-ngx exec deploy/paperless-ngx -- \
  document_exporter ../export

# Export-Verzeichnis lokal sichern:
kubectl -n paperless-ngx cp \
  $(kubectl -n paperless-ngx get pod -l app.kubernetes.io/name=paperless-ngx \
    -o jsonpath='{.items[0].metadata.name}'):/usr/src/paperless/export/ \
  ./paperless-backup/

Konfiguration (values.yaml)

Key Bedeutung Default
persistence.media.size Speicher für Originaldokumente 50Gi
persistence.data.size Datenbank + Thumbnails + Caches 20Gi
env.PAPERLESS_OCR_LANGUAGE Tesseract-Sprachcodes deu+eng
env.PAPERLESS_URL Öffentliche URL für Links https://paperless.prod.homeserver
resources.limits.memory RAM-Limit (OCR ist speicherhungrig) 2Gi

Fehlersuche

kubectl -n paperless-ngx get pods,pvc,ingress
kubectl -n paperless-ngx logs deploy/paperless-ngx -c paperless-ngx --tail=100
kubectl -n paperless-ngx logs deploy/paperless-ngx -c redis --tail=30
kubectl -n paperless-ngx exec deploy/paperless-ngx -- document_exporter ../export
Symptom Ursache Lösung
Pod Pending, PVC Pending StorageClass nas oder NAS nicht bereit (fünf PVCs: data, media, consume, export, redis) kubectl -n paperless-ngx describe pvc, NAS-Speicher
Pod CreateContainerConfigError oder Start bricht ab (SECRET_KEY) SealedSecret für PAPERLESS_SECRET_KEY nicht entschlüsselt oder noch Platzhalter Abschnitt „Secret Key sichern“, Sealed Secrets
Pod startet mehrfach neu (OOMKilled) OCR braucht mehr als das Limit (2 GiB) resources.limits.memory erhöhen, PAPERLESS_TASK_WORKERS und PAPERLESS_THREADS_PER_WORKER (je 1) niedrig halten
Anmeldung unmöglich (kein Benutzer) Admin-Account noch nicht angelegt Abschnitt „Erster Start“, createsuperuser
Dokumente im Consume-Ordner werden nicht aufgenommen Datei im falschen PVC oder Rechte (Benutzer 1000), Consumer-Fehler Log lesen (consumer), Rechte im PVC prüfen, Abschnitt „Dokumente einreichen“
OCR liefert falsche Sprache PAPERLESS_OCR_LANGUAGE/PAPERLESS_OCR_LANGUAGES passt nicht auf deu+eng bzw. deu eng setzen
Weboberfläche: falsche Links (http://…) PAPERLESS_URL falsch https://paperless.prod.homeserver
Seite nicht erreichbar Ingress, DNS, NetworkPolicy (default-ingress lässt nur den Namespace selbst, kube-system und extraIngressNamespaces zu) kubectl -n paperless-ngx get ingress,networkpolicy, Namespace des Aufrufers (zum Beispiel n8n) in networkPolicy.extraIngressNamespaces eintragen
n8n erreicht Paperless nicht NetworkPolicy blockt n8n wie oben, Abschnitt „n8n-Integration“
Redis-Fehler im Log (Connection refused) Redis-Sidecar nicht bereit kubectl logs … -c redis, PVC redis prüfen
Datenverlust-Sorge nach Neuaufbau SQLite-DB liegt im PVC data, Dokumente im PVC media Abschnitt „Backup“ (Exporter), NAS-Backup
Dienst steht in PROD Application heißt prod-paperless-ngx kubectl-Kontext PROD (a0010)

Allgemeine Fehlersuche: zentrale Fehlersuche.