Referenz¶

Alles, was die App kennt, zum Nachschlagen: die Einstellungen, die Schlüssel, unter denen Nextcloud sie führt, die Routen, die Versionen, die die Tests abdecken, wohin Daten gehen und was bleibt, wenn die App geht.

Einstellungen¶

Die Einstellungen liegen unter Verwaltungseinstellungen → Paperless Unified Search, nur für Administratoren, und gelten für jeden Benutzer der Nextcloud. Verbindung testen und speichern speichert sie erst, wenn Paperless antwortet; es und Verbindung trennen fragen nach dem Passwort, wenn es in den letzten 30 Minuten nicht bestätigt wurde.

Einstellung	Was sie tut	Standard	Schlüssel der App-Konfiguration
Paperless-URL	Die Adresse von Paperless, mit einem Pfad, wenn Paperless unter einem läuft, etwa `https://paperless.example.com`	—	`paperless_url`
Paperless läuft in meinem lokalen Netzwerk	Lässt Nextcloud diese URL, und keine andere, unter einer Adresse des lokalen Netzwerks erreichen, ohne Weiterleitungen (Details)	Aus	`allow_local`
Paperless-API-Token	Das Token des Paperless-Kontos der Suche; leer behält das gespeicherte, für denselben Server	—	Keiner: im Zugangsdatenmanager von Nextcloud, als `paperless_unified_search.api-token`
Archiv-Konto	Das Nextcloud-Konto, dessen Dateien für die Dokumente stehen; leer nimmt das Konto von Paperless Sync	Das Konto von Paperless Sync	`archive_owner`
Paperless immer in die globale Suche einbeziehen	Fragt Paperless bei jeder Suche jedes Benutzers, ohne Verbundene Dienste durchsuchen; lade Nextcloud nach einer Änderung neu	Aus	`always_search`

Verbindung trennen löscht die URL, das Token, die Schalter, das Archiv-Konto, die Version von Paperless und den Verlauf der Probleme. Verlauf leeren löscht nur den Verlauf.

Konfiguration der App¶

Nextcloud führt die Einstellungen in seiner App-Konfiguration, die occ liest:

occ config:list paperless_unified_search
occ config:app:get paperless_unified_search paperless_url

Schlüssel	Enthält
`paperless_url`	Die URL von Paperless, wie die Einstellungen sie gespeichert haben: ohne Schrägstrich am Ende, mit dem Host in seiner ASCII-Form
`allow_local`	Ob Paperless im lokalen Netzwerk läuft
`archive_owner`	Die ID des Archiv-Kontos, so geschrieben wie in Nextcloud; fehlt, wenn die Einstellungen das Konto von Paperless Sync nehmen
`always_search`	Ob jede Suche Paperless fragt
`paperless_version`, `paperless_api_version`	Die Versionen von Paperless und seiner API, etwa `3.3.0` und `10`, wie seine letzte Antwort sie genannt hat
`diagnostics`	Der Verlauf der Probleme der Suche, als JSON; ein Lazy-Schlüssel, den Nextcloud erst lädt, wenn er gelesen wird
`diagnostics_pending`	Ob ein Fehler im Verlauf noch auf eine Suche wartet, die funktioniert

Das Konto von Paperless Sync ist occ config:app:get paperless_sync target_user.

Schlüssel, die eine ältere Version hinterlassen hat und diese nicht mehr liest, gehen mit dem nächsten Update: Nextcloud führt den Reparaturschritt Remove the last failed search that Paperless Unified Search 0.3.0 kept nach jedem Update der App und bei occ maintenance:repair aus, und er löscht last_failure und last_recovery, die der Verlauf der Probleme in 0.4.0 ersetzt hat.

Ändere die Einstellungen in den Verwaltungseinstellungen, die zuerst die Verbindung testen. occ config:app:set kann trotzdem einen Schalter ein- oder ausschalten, etwa occ config:app:set paperless_unified_search always_search --value=true --type=boolean, was das nächste Neuladen jedes Benutzers übernimmt. Ändere paperless_url nicht auf diesem Weg: Das gespeicherte Token folgte der URL zum neuen Server, was die Einstellungen verhindern, indem sie erneut nach dem Token fragen.

Mit occ einrichten und prüfen¶

Vier Befehle von occ erledigen ohne Browser, was die Einstellungen tun, und mehr: Sie richten die App für Ansible, Docker und andere Skripte ein, testen sie für die Überwachung und sagen, warum ein Benutzer ein Dokument nicht findet.

Befehl	Was er tut	Exit-Code
`paperless_unified_search:setup`	Testet die Verbindung mit der URL und dem Token und speichert dann die Einstellungen, wie es Verbindung testen und speichern tut	0, sobald gespeichert, 1, wenn Paperless nicht antwortet oder eine Einstellung falsch ist, 2 bei einem falschen Aufruf, etwa einer fehlenden `--url` oder einer leeren Quelle des Tokens
`paperless_unified_search:test`	Testet die Verbindung mit den gespeicherten Einstellungen und nennt die Version von Paperless	0, wenn Paperless antwortet, sonst 1
`paperless_unified_search:search <user> <term>`	Sucht als der Benutzer und sagt für jedes Dokument, ob es ihm angezeigt wird, mit `--explain` auch, warum nicht	0, sobald Paperless geantwortet hat
`paperless_unified_search:check`	Testet die Verbindung und das Archiv-Konto und zählt die Dokumente von Paperless, die eine Datei haben	0, wenn die Suche Dokumente zeigen kann, sonst 1

Die App einrichten¶

Das Token kommt nie auf die Befehlszeile, wo der Verlauf der Shell und die Liste der Prozesse es anderen zeigen würden: setup liest es mit --token-stdin von der Standardeingabe oder mit --token-env=NAME aus einer Umgebungsvariablen. Eine Option, die du weglässt, behält ihren gespeicherten Wert, und ohne Token bleibt das gespeicherte, aber nur für den Server, für den es gespeichert wurde, wie auf der Seite der Einstellungen.

Option	Setzt
`--url=URL`	Die Adresse von Paperless, etwa `https://paperless.example.com`; erforderlich
`--token-stdin`, `--token-env=NAME`	Das API-Token, aus der ersten Zeile der Standardeingabe oder aus der Umgebungsvariablen `NAME`
`--archive-account=ID`	Das Konto, dem die synchronisierten Dateien gehören; leer für das Konto von Paperless Sync
`--allow-local`, `--no-allow-local`	Paperless läuft in meinem lokalen Netzwerk
`--always-search`, `--no-always-search`	Paperless immer in die globale Suche einbeziehen

Auf einem Server, als Benutzer des Webservers:

printf '%s\n' "$PAPERLESS_TOKEN" | sudo -u www-data php occ paperless_unified_search:setup \
  --url=https://paperless.example.com --archive-account=paperless --token-stdin

Mit Docker Compose und dem Image von Nextcloud, aus einer Datei, die nur du lesen kannst:

docker compose exec -T --user www-data nextcloud php occ paperless_unified_search:setup \
  --url=http://paperless:8000 --archive-account=paperless --allow-local --token-stdin \
  < paperless-token.txt

Mit Ansible, aus seinem Vault und ohne das Token in seiner Ausgabe:

- name: Connect Paperless Unified Search to Paperless-ngx
  ansible.builtin.command:
    argv: [php, occ, paperless_unified_search:setup, --url=https://paperless.example.com,
           --archive-account=paperless, --token-stdin]
    chdir: /var/www/nextcloud
    stdin: "{{ vault_paperless_token }}"
  become: true
  become_user: www-data
  no_log: true

Ein verborgenes Dokument erklären¶

Die Suche lässt jedes Dokument ohne Spur weg, das keine Datei des Archiv-Kontos hat, die der suchende Benutzer öffnen kann: Zwölf Dokumente, die jamie nicht öffnen darf, sehen genauso aus wie keines. search listet die Dokumente, die Paperless zuerst einordnet, standardmäßig 10 und mit --limit bis zu 50, und ob jedes dem Benutzer angezeigt wird, und --explain nennt den Grund für jedes, das nicht angezeigt wird:

$ occ paperless_unified_search:search jamie invoice --limit=5 --explain
+-----+-----------------------------------+------------+--------------------------------------------------------------------------------+
| ID  | Title                             | Verdict    | File                                                                           |
+-----+-----------------------------------+------------+--------------------------------------------------------------------------------+
| 412 | Electricity invoice - August 2026 | shown      | /Paperless/2026/Electricity invoice - August 2026 [P412].pdf                   |
| 389 | Home insurance renewal            | not shared | /Private/Home insurance renewal [P389].pdf of paperless, not shared with jamie |
| 371 | Internet invoice - July 2026      | shown      | /Paperless/2026/Internet invoice - July 2026 [P371].pdf                        |
| 356 | Water bill 2026                   | no file    |                                                                                |
| 344 | Old invoice                       | not owned  | /Scans/Old invoice [P344].pdf of jamie                                         |
+-----+-----------------------------------+------------+--------------------------------------------------------------------------------+
Paperless found 12 document(s) for "invoice"; 2 of the 5 above show to jamie.
Not shared (389): the archive account paperless has the file, but hasn't shared it with jamie. Share the file, or a folder that holds it, read-only with jamie.
Not owned (344): jamie sees a file with the marker of the document, but only the files of the archive account paperless stand for documents.
No file (356): no file of the archive account paperless has the marker of the document, such as [P356], in its name. The synchronization hasn't written it yet, or names files without it.

---
config:
  flowchart:
    wrappingWidth: 400
    nodeSpacing: 30
---
flowchart TB
    accTitle: Warum ein Dokument nicht angezeigt wird
    accDescr: Paperless findet Dokument 389, wenn jamie sucht, und occ paperless_unified_search:search jamie invoice --explain stellt nacheinander drei Fragen. Sieht jamie eine Datei des Archiv-Kontos mit [P389] im Namen? Dann wird das Dokument angezeigt. Sonst: Hat das Archiv-Konto eine solche Datei in seinen eigenen Ordnern? Dann ist sie nicht mit jamie geteilt, und die Datei oder ihren Ordner nur lesend mit jamie zu teilen, zeigt sie an. Sonst: Sieht jamie eine Datei mit der Kennung eines anderen Kontos? Dann gehört sie nicht dem Archiv-Konto, denn nur Dateien des Archiv-Kontos stehen für Dokumente. Sonst gibt es keine Datei, und die Synchronisierung muss erst eine mit der Kennung im Namen schreiben.

    hit["Paperless findet Dokument 389,<br>wenn jamie sucht"] --> visible{"Sieht jamie eine Datei<br>des Archiv-Kontos<br>mit [P389] im Namen?"}
    visible -- "ja" --> shown["angezeigt"]
    visible -- "nein" --> archived{"Hat das Archiv-Konto<br>eine solche Datei in seinen<br>eigenen Ordnern?"}
    archived -- "ja" --> unshared["nicht geteilt: die Datei<br>oder ihren Ordner nur<br>lesend mit jamie teilen"]
    archived -- "nein" --> other{"Sieht jamie eine Datei<br>mit [P389] eines anderen<br>Kontos?"}
    other -- "ja" --> unowned["nicht im Besitz: nur Dateien<br>des Archiv-Kontos<br>stehen für Dokumente"]
    other -- "nein" --> missing["keine Datei: die<br>Synchronisierung eine mit<br>der Kennung schreiben lassen"]

    classDef yes fill:#16a34a2e,stroke:#16a34a,stroke-width:2px
    classDef no fill:#dc26262e,stroke:#dc2626,stroke-width:2px
    class shown yes
    class unshared,unowned,missing no

Ohne --explain entscheidet search so wie die Suche selbst, mit einer Suche im Datei-Cache, und nennt jedes Dokument, das nicht angezeigt wird, hidden; mit der Option folgt für jede weitere Frage eine Suche im Datei-Cache, für die Dokumente, die noch nicht erklärt sind. --json schreibt die Dokumente für Skripte, jedes mit seinen Feldern id, title, verdict, path und owner.

Die ganze Einrichtung prüfen¶

check testet die Verbindung und das Archiv-Konto und vergleicht die Dokumente, die das Konto des API-Tokens in Paperless sieht, mit den Dateien des Archiv-Kontos, deren Namen ihre Kennungen tragen:

$ occ paperless_unified_search:check
✓ Paperless 3.3.0 (API 10) answers at https://paperless.example.com.
✓ The archive account is paperless, the account of Paperless Sync.
! Coverage: 1,180 of 1,234 Paperless document(s) have a file of the archive account. Without one, among others: 17, 18, 19, 20, 23, 31, 40, 41, 42, 57.

Dokumente ohne Datei sind kein Fehler, solange die Suche andere zeigen kann: Die Synchronisierung hat sie vielleicht noch nicht geschrieben oder lässt manche absichtlich weg. Hat kein einziges Dokument eine Datei, etwa bei einem Archiv-Konto, dem keine der synchronisierten Dateien gehört, endet check mit 1 und sagt, was zu korrigieren ist. search --explain mit einem Begriff eines solchen Dokuments sagt, warum es nicht angezeigt wird.

In der Übersicht der Verwaltung¶

Verwaltungseinstellungen → Übersicht prüft die App unter den anderen Prüfungen der Einrichtung von Nextcloud, ebenso occ setupchecks. Sie warnt, wenn die Suche aus einem Grund, den ein Administrator beheben kann, keine Paperless-Dokumente zeigt, und verlinkt die Einstellungen der App: ein Token, das Nextcloud nicht mehr entschlüsseln kann, kein Archiv-Konto oder eines, das nicht existiert, oder eine fehlgeschlagene Suche, nach der keine mehr funktioniert hat. Sonst nennt sie das Paperless, mit dem die App verbunden ist, mit der Version seiner letzten Antwort. Sie liest nur, was die App gespeichert hat, und sendet keine Anfrage an Paperless, also öffnet sich die Übersicht so schnell wie ohne sie.

Die Routen der Einstellungen¶

Die Seite der Einstellungen speichert über vier Routen der App, die nur Administratoren aufrufen dürfen, jede mit dem CSRF-Token von Nextcloud. Ein Skript ruft sie mit der Anmeldung eines Administrators und dem Header OCS-APIRequest: true auf, wie es die End-to-End-Tests tun; /index.php steht vor /apps, wo Nextcloud ohne Pretty URLs läuft.

Route	Tut
`POST /apps/paperless_unified_search/settings`	Testet die Verbindung und speichert, mit den Parametern `url`, `token`, `archiveOwner`, `allowLocal` und `alwaysSearch`; fragt nach dem Passwort wie Verbindung testen und speichern
`DELETE /apps/paperless_unified_search/settings`	Verbindung trennen: löscht die Einstellungen, das Token und den Verlauf; fragt nach dem Passwort
`DELETE /apps/paperless_unified_search/settings/diagnostics`	Verlauf leeren
`POST /apps/paperless_unified_search/settings/try`	Suche ausprobieren: sucht mit dem Parameter `term` als das Konto `user` und sagt für jedes Dokument, ob es angezeigt wird und warum nicht, nur mit seiner ID und seinem Titel; das Protokoll hält fest, welcher Administrator als wer gesucht hat, ohne den Begriff

curl -u admin -H 'OCS-APIRequest: true' -H 'Accept: application/json' \
  --data-urlencode 'url=https://paperless.example.com' \
  --data-urlencode 'archiveOwner=paperless' \
  --data-urlencode "token@$HOME/.paperless-token" \
  'https://cloud.example.com/apps/paperless_unified_search/settings'

token@file übergibt das Token in einer Datei, was es aus dem Verlauf der Shell und der Liste der Prozesse heraushält. Eine gespeicherte Einstellung antwortet mit HTTP 200 und den Einstellungen als JSON: url, tokenConfigured, alwaysSearch, archiveOwner, syncAccount, tokenUnreadable, archiveOwnerMissing, allowLocal, paperlessVersion und paperlessApiVersion, nie mit dem Token. Eine Ablehnung antwortet mit HTTP 400, oder 500, wenn etwas nach dem Test fehlgeschlagen ist, mit der message, die in der Sprache des Administrators zu zeigen ist, und einem code:

Code	Bedeutet
`invalid_url`, `unsupported_scheme`, `url_extras`, `host_not_ascii`	Die URL ist keine, ist nicht HTTP oder HTTPS, hat Zugangsdaten, eine Abfrage oder ein Fragment, oder einen Host, der nicht in seiner ASCII-Form ist
`token_required`, `token_for_other_server`	Es ist kein Token gespeichert, oder das gespeicherte ist für einen anderen Server
`unknown_archive_account`	Das Archiv-Konto existiert nicht
`unauthorized`	Paperless hat das Token abgelehnt, mit HTTP 401 oder 403
`not_found`	HTTP 404: Der Pfad der URL ist falsch
`redirect`	Die URL leitet weiter, und mit dem lokalen Netzwerk folgt Nextcloud keiner Weiterleitung
`http`	Ein anderer Status, etwa ein Fehler von Paperless mit 5xx
`unsupported_version`	HTTP 406: Paperless ist älter als 2.16 und spricht Version 9 seiner API nicht; ein Update von Paperless-ngx behebt es
`not_paperless`	Die Antwort ist keine Liste von Dokumenten von Paperless-ngx
`local_address`	Nextcloud hat die Adresse des lokalen Netzwerks verweigert
`tls`, `tls_handshake`	Nextcloud vertraut dem Zertifikat nicht oder konnte keine verschlüsselte Verbindung aufbauen
`unknown_host`, `timeout`, `unreachable`	Der Host lässt sich nicht auflösen, Paperless hat nicht rechtzeitig geantwortet, oder die Verbindung ist fehlgeschlagen
`internal`	Etwas nach dem Test ist fehlgeschlagen, etwa die Datenbank; das Protokoll von Nextcloud enthält es

Die Fehlerbehebung sagt, was gegen jeden zu tun ist.

Die Suche und der Smart Picker¶

	ID	Wo
Der Suchanbieter	`paperless_unified_search_documents`	Paperless-Dokumente in der Suche von Nextcloud und `GET /ocs/v2.php/search/providers/paperless_unified_search_documents/search?term=…` in seiner OCS-API, mit `limit` (standardmäßig 5, bis zu 50) und `cursor`
Der Anbieter des Smart Pickers	`paperless_unified_search-documents`	Paperless-Dokumente im Smart Picker von Talk, Text, Deck und Mail

Aus Skripten und KI-Assistenten nutzen zeigt die Antwort der API.


ID	`paperless_unified_search-recent`, Neu in Paperless, angeboten, sobald die Einstellungen ein Paperless und ein Archiv-Konto nennen, das existiert
Einträge	`GET /ocs/v2.php/apps/dashboard/api/v2/widget-items?widgets[]=paperless_unified_search-recent` mit `limit` (standardmäßig 7, bis zu 30), wie das Dashboard von Nextcloud und seine Apps sie anfragen: die neuesten Dokumente, die der Benutzer öffnen kann, jedes mit seinem Titel, einer Zeile mit dem Tag, an dem Paperless es hinzugefügt hat, seinem Korrespondenten und seinem Typ, dem Link und der Vorschau seiner Datei und als `sinceId` dem Moment, an dem Paperless es hinzugefügt hat; `sinceIds[paperless_unified_search-recent]` mit einem solchen Moment listet nur die Dokumente, die danach hinzugekommen sind
Der Link unter der Liste	Mit dir geteilte Dateien, die Ansicht von Dateien mit den Dateien, die andere mit dem Benutzer teilen; das Web-Dashboard von Nextcloud zeigt ihn, und sechs Dokumente, erst wenn die Liste voll ist; keiner für das Archiv-Konto
Paperless	Eine Anfrage nach den 25 Dokumenten, die es zuletzt hinzugefügt hat, höchstens einmal in der Minute für alle Benutzer gemeinsam, die der verteilte Cache von Nextcloud solange behält (mit einem Memory-Cache, wie Nextcloud ihn empfiehlt; ohne einen fragt jedes Dashboard Paperless); ein Paperless, das nicht antwortet, ruht ebenfalls eine Minute, und das Widget sagt Paperless ist gerade nicht erreichbar.

Anfragen an Paperless¶

Jede Anfrage der App an Paperless ist ein GET von <URL>/api/documents/, oder von /api/correspondents/ und /api/document_types/ für die Namen der Korrespondenten und Typen einer Seite, vom Nextcloud-Server aus:


Header	`Authorization: Token …`, `Accept: application/json` und `User-Agent: Nextcloud-Paperless-Unified-Search/<version>`
Eine Suche	`query` mit dem Begriff, `page`, `page_size=25` und `fields=id,title,created,correspondent,document_type,__search_hit__`; bei Paperless 3 eine Anfrage, die es noch nicht verarbeiten kann, noch einmal mit `text` statt `query`
Der Test der Verbindung	`page_size=1` und `fields=id`
Die neuesten Dokumente des Dashboards	`ordering=-added`, `page=1`, `page_size=25` und `fields=id,title,added,correspondent,document_type`, höchstens einmal in der Minute für alle Benutzer, mit 5 Sekunden für die Antwort und ohne zweiten Versuch
Zeit	3 Sekunden zum Verbinden, 10 Sekunden für die Antwort
Ein zweiter Versuch	Nur für eine Anfrage, die innerhalb von 3,5 Sekunden fehlgeschlagen ist, bevor sie eine Verbindung hatte, und deren Adresse Nextcloud nicht verweigert hat
Weiterleitungen	Ohne Paperless läuft in meinem lokalen Netzwerk bis zu 5, nie an eine Adresse des lokalen Netzwerks; Nextcloud lässt das Token bei einer Weiterleitung auf ein anderes Schema, einen anderen Host oder Port weg, was Paperless dann ablehnt, und behält es bei einer innerhalb desselben Servers. Mit dem Schalter keine

Kompatibilität¶

	Nextcloud 33	Nextcloud 34	Nextcloud 35
Paperless-ngx 3.x (API 9)	End-to-End-Tests	End-to-End-Tests	End-to-End-Tests
Paperless-ngx 2.16 bis 2.20 (API 9)	Unit-Tests	Unit-Tests	Unit-Tests

Nextcloud: Die End-to-End-Tests führen die App im aktuellen Release jeder Version aus, die appinfo/info.xml unterstützt, in jedem Pull Request, der die App ändert, und bei jeder Änderung von main, und jeden Montag auch in der kommenden Version von Nextcloud, ihrer Beta oder ihrem Release Candidate.
Paperless-ngx: Die End-to-End-Tests fragen eine Nachbildung von Paperless, die so antwortet wie Paperless-ngx 3.3.0: ihre Seiten, ihre Felder, ihre Header der Version, ihre Ausschnitte und ihre Ablehnung einer Anfrage, die noch getippt wird. Die Unit-Tests prüfen die Antworten von 2.20 und 3.3, etwa dass nur Paperless 3 den einfachen Modus seiner Suche bekommt, den Paperless 2 nicht kennt. Jede Anfrage nennt Version 9 der API, die Paperless-ngx 2.16 und neuer und jedes 3.x sprechen, also kann ein neues Release von Paperless die Treffer nicht unbemerkt ändern; Vertragstests prüfen die App jede Woche gegen echtes Paperless-ngx, das letzte Release von 2.20 und das neueste von 3.x. Ein älteres Paperless antwortet mit HTTP 406, und der Test der Verbindung sagt das.
PHP: 8.2 oder neuer, soweit Nextcloud es unterstützt; die Unit-Tests laufen auf 8.2.

Datenflüsse¶

Von	An	Was	Wann
Der Browser oder eine App des Benutzers	Nextcloud	Der Suchbegriff	Immer, wenn der Benutzer sucht
Nextcloud	Paperless	Der Begriff, die Seite und die Felder, mit denen zu antworten ist, und das API-Token	Mit eingeschaltetem Verbundene Dienste durchsuchen, nach der Wahl von Paperless-Dokumente im Smart Picker, über die API oder immer, wenn Paperless vertraut wird
Paperless	Nextcloud	Von jedem Dokument, das das Konto des Tokens ansehen darf: seine ID, sein Titel, sein Datum, die IDs seines Korrespondenten und seines Typs und der Ausschnitt um den Begriff; die Versionen von Paperless und seiner API	In jeder Antwort
Nextcloud	Der Browser oder eine App des Benutzers	Von jedem Dokument, dessen Datei der Benutzer öffnen kann: sein Titel, sein Datum und sein Ausschnitt und der Link, die ID und der Pfad seiner Datei	In jeder Antwort
Nextcloud	Paperless	Die Anfrage nach den 25 Dokumenten, die Paperless zuletzt hinzugefügt hat, mit den Feldern, die das Dashboard zeigt, und das API-Token	Höchstens einmal in der Minute, wenn das Dashboard eines Benutzers das Widget zeigt
Paperless	Nextcloud	Von jedem dieser Dokumente, das das Konto des Tokens ansehen darf: seine ID, sein Titel, der Moment, an dem Paperless es hinzugefügt hat, und die IDs seines Korrespondenten und seines Typs	In jeder Antwort
Nextcloud	Der Browser oder eine App des Benutzers	Von jedem der neuesten Dokumente, dessen Datei der Benutzer öffnen kann: sein Titel, der Tag, an dem Paperless es hinzugefügt hat, sein Korrespondent und sein Typ und der Link und die Vorschau seiner Datei	Immer, wenn das Dashboard das Widget zeigt

---
config:
  sequence:
    wrap: true
    width: 120
    actorMargin: 10
---
sequenceDiagram
    accTitle: Der Datenfluss einer Suche
    accDescr: Ein Benutzer sucht nach invoice. Die globale Suche gibt den Begriff, den Cursor, das Limit, den Datumsfilter und den Benutzer an den Suchanbieter. Ohne Begriff, Archiv-Konto oder Verbindung antwortet der Anbieter ohne Treffer und fragt Paperless nicht. Sonst fragt der Paperless-Client, bis die Seite mit Treffern voll ist, Paperless-ngx mit dem Token nach der Seite mit 25 Treffern, die den nächsten Treffer enthält, innerhalb der Tage des Datumsfilters und nur nach den Feldern, die ein Treffer zeigt, und Paperless antwortet mit der ID, dem Titel, dem Datum, den IDs des Korrespondenten und des Typs und dem Ausschnitt der Dokumente 412, 389, 371 und weiterer und damit, ob es eine nächste Seite gibt. Ein Aufruf des Dateisuchers deckt alle Dokumente dieser Seite ab und liefert für jedes eine Datei des Archiv-Kontos mit seiner Kennung oder keine. Für die Dokumente mit Datei fragen die Namen Paperless über den Client nach den Korrespondenten und den Typen, die der Cache nicht enthält, mit einer Anfrage je Art, und behalten ihre Namen zehn Minuten lang. Das wiederholt sich für höchstens 4 Seiten von Paperless oder 3 Sekunden. Der Anbieter antwortet mit einem Eintrag für jedes Dokument mit Datei, bis zum Limit, mit der Vorschau der Datei oder dem Symbol ihres Typs, dem Titel, dem Datum in der Sprache des Benutzers, dem Korrespondenten, dem Typ und dem Ausschnitt, und mit dem Cursor des ersten Treffers, den er nicht durchgegangen ist.

    actor User as Benutzer
    participant Search as Globale Suche
    participant Provider as Suchanbieter
    participant Client as Paperless-Client
    participant Paperless as Paperless-ngx
    participant Locator as Dateisucher
    participant Names as Namen
    User->>Search: invoice
    Search->>Provider: Begriff, Cursor, Limit,<br>Datumsfilter und Benutzer
    alt kein Begriff, kein Archiv-Konto oder keine Verbindung
        Provider-->>Search: keine Treffer, ohne Paperless zu fragen
    else
        loop bis die Seite mit Treffern voll ist, für höchstens 4 Seiten von Paperless oder 3 Sekunden
            Provider->>Client: Begriff, die Tage des Datumsfilters,<br>die Seite mit 25 Treffern mit dem nächsten
            Client->>Paperless: GET /api/documents/<br>?query=invoice&page=1<br>&page_size=25&fields=…<br>&created__date__gte=…,<br>mit dem Token
            Paperless-->>Client: ID, Titel, Datum, Korrespondent,<br>Typ und Ausschnitt der Dokumente<br>412, 389, 371, … und ob es<br>eine nächste Seite gibt
            Provider->>Locator: die Dokumente der Seite,<br>Benutzer, Archiv-Konto
            Locator-->>Provider: je Dokument eine Datei des<br>Archiv-Kontos mit seiner Kennung<br>oder keine
            Provider->>Names: die Korrespondenten und Typen<br>der Dokumente mit Datei
            Names->>Paperless: über den Client, für die IDs,<br>die dem Cache fehlen: GET<br>/api/correspondents/?id__in=3,5<br>und /api/document_types/?id__in=1,2
            Paperless-->>Names: ihre Namen, die der Cache<br>zehn Minuten lang behält
            Names-->>Provider: die Namen
        end
        Provider-->>Search: ein Eintrag für jedes Dokument mit Datei, bis zum Limit: Vorschau oder Symbol, Titel, Datum, Korrespondent, Typ und Ausschnitt, und der Cursor des nächsten Treffers
    end

Nextcloud speichert die Einstellungen in seiner App-Konfiguration, das Token verschlüsselt in seinem Zugangsdatenmanager und den Verlauf der letzten 20 Probleme, ohne den Begriff, das Token und die Abfrage einer URL. Sein verteilter Cache behält die Namen der Korrespondenten und Typen zehn Minuten lang und von den 25 neuesten Dokumenten ihre IDs, Titel, die Momente, an denen Paperless sie hinzugefügt hat, und die IDs ihrer Korrespondenten und Typen eine Minute lang, für alle Benutzer; vom Text der Dokumente wird nichts gespeichert. Die Architecture erklärt jeden Schritt und das Sicherheitsdesign, was jeden davon schützt.

Sicherheit und Datenschutz¶

Das Paperless-API-Token wird nur im serverseitigen Zugangsdatenmanager von Nextcloud gespeichert.
Das Token wird nie an JavaScript im Browser zurückgegeben und nie in HTML ausgegeben.
Das Token wird nur an den Paperless-Server gesendet, für den es gespeichert wurde; eine URL mit anderem Schema, Host oder Port braucht es erneut.
Das Speichern der Einstellungen und das Trennen der Verbindung fragen nach dem Passwort des Administrators, wenn es in den letzten 30 Minuten nicht bestätigt wurde.
occ nimmt das Token von seiner Standardeingabe oder aus einer Umgebungsvariablen, nie von der Befehlszeile, wo der Verlauf der Shell und die Liste der Prozesse es zeigen würden.
Der Schutz von Nextcloud vor Adressen des lokalen Netzwerks bleibt für jede App eingeschaltet. Paperless läuft in meinem lokalen Netzwerk hebt ihn nur für die Anfragen dieser App an die Paperless-URL der Einstellungen auf, die keiner Weiterleitung folgen.
Suchtreffer werden über die Sicht des aktuellen Benutzers auf das Dateisystem von Nextcloud gefiltert.
Die Einstellungen zeigen Administratoren den Verlauf der Probleme der Suche ohne das API-Token, den Suchbegriff und die Abfrage einer URL.
Suche ausprobieren zeigt Administratoren, welche Dokumente ein Benutzer zu einem Begriff findet, nur mit ihren IDs und Titeln, ohne ihren Inhalt, einen Ausschnitt oder ihre Dateien; das Audit-Protokoll der App Auditing / Logging (admin_audit) hält fest, welcher Administrator als welcher Benutzer gesucht hat, gleich bei welcher Protokollstufe, ebenso das Protokoll von Nextcloud auf der Stufe info, ohne den Begriff.
Suchbegriffe werden nur von Server zu Server gesendet, wenn die Suche in verbundenen Diensten oder der Modus für den vertrauenswürdigen Dienst eingeschaltet ist, nachdem der Benutzer im Smart Picker Paperless-Dokumente gewählt hat, oder wenn ein Client diese Suche über ihre ID in der API anfragt.
Ein Link, den der Smart Picker einfügt, ist der Link der Datei in Nextcloud, der seine Vorschau nur Lesern zeigt, die die Datei öffnen können.
Das Widget des Dashboards zeigt einem Benutzer nur die neuesten Dokumente, deren Dateien er öffnen kann. Der verteilte Cache von Nextcloud behält die IDs, Titel, Korrespondenten und Typen der 25 neuesten Dokumente eine Minute lang, die für jeden Benutzer dieselben sind, und nie ihren Text.
Administratoren können dem eingerichteten Paperless-Server ausdrücklich vertrauen, um ihn automatisch in die globalen Suchen jedes Benutzers einzubeziehen.
Keine Zugangsdaten für den Betrieb, privaten Hostnamen, internen Adressen oder Konfiguration einer Instanz gehören in dieses Repository.
Gitleaks durchsucht jeden Push und jeden Pull Request.
Dependency Review blockiert neu hinzugefügte verwundbare oder nicht freigegebene Abhängigkeiten.
Psalm analysiert den PHP-Code und CodeQL das JavaScript in jedem Pull Request.
Jedes Release enthält eine SPDX-SBOM, eine abgetrennte Signatur und öffentliche Build-Provenienz von Sigstore.
OpenSSF Scorecard prüft die Sicherheit der Lieferkette des Repositorys jede Woche.

Sicherheitsprobleme meldest du so, wie SECURITY.md es beschreibt.

Das Protokoll von Nextcloud¶

Die App schreibt in das Protokoll von Nextcloud mit app auf paperless_unified_search, nie mit dem Begriff oder dem Token. Die Meldungen sind auf Englisch:

Stufe	Meldung	Bedeutet
Warning	The test of the connection to Paperless failed: reason (error)	Verbindung testen und speichern ist fehlgeschlagen; der Grund ist der `code` der Routen oben
Error	The settings of Paperless Unified Search could not be saved (error)	Etwas nach dem Test ist fehlgeschlagen, etwa die Datenbank
Warning	Paperless unified search failed (error)	Eine Suche ist fehlgeschlagen; Probleme der Suche enthält sie auch
Warning	Paperless unified search left out n result(s) it could not show (error)	Treffer, deren Dateien nicht geantwortet haben, wurden weggelassen
Warning	Paperless unified search skipped n file(s) it could not read (error)	Dateien des Archivs, die Nextcloud nicht lesen konnte
Warning	Paperless unified search looks for the files of each document on its own …	Eine Version von Nextcloud, deren Abfrage des Datei-Caches die App noch nicht kennt: Die Suche funktioniert trotzdem, mit einer Abfrage je Dokument statt einer je Seite
Warning	The stored Paperless API token can't be decrypted …	Das `secret` der `config.php` hat sich geändert: Gib das Token erneut ein
Debug	Paperless rejected the query of a search with HTTP status	Eine Anfrage, die noch getippt wird, oder eine Seite nach der letzten: kein Problem

Deinstallieren¶

Verbindung trennen in den Einstellungen. Das löscht die URL, das Token, die Schalter, das Archiv-Konto, die Version von Paperless und den Verlauf der Probleme; nur diagnostics_pending bleibt, mit den Schlüsseln, die Nextcloud von jeder App führt, etwa enabled und installed_version.
Die App entfernen: occ app:remove paperless_unified_search deaktiviert sie und löscht ihren Code; oder Apps → Deaktivieren und Entfernen im Browser. Nextcloud behält die App-Konfiguration einer entfernten App: occ config:list paperless_unified_search listet, was übrig ist, und occ config:app:delete paperless_unified_search <key> löscht einen Schlüssel.
In Paperless löschst du das API-Token oder das Konto der Suche: Ein Token, das Nextcloud vergessen hat, funktioniert weiter, bis auch Paperless es vergisst.

Die Dateien des Archivs und ihre Freigaben bleiben, wie sie sind: Sie gehören dem Archiv-Konto und der Synchronisierung, nicht dieser App. Ohne Verbindung trennen bleibt das verschlüsselte Token im Zugangsdatenmanager von Nextcloud, unter paperless_unified_search.api-token, bis die App wieder installiert und getrennt wird.