Paperless-ngx: dokumentpipeline, OCR og arkivdrift

Paperless-ngx er et selvhostet dokumenthåndteringssystem for innkommende filer og skannede papirdokumenter. Det mottar dokumenter fra en overvåket katalog, fra nettet eller REST-API-et eller fra e-postkasser, oppretter søkbar tekst og ved behov et standardisert arkiveksemplar, tilordner metadata og gjør bestandet søkbart via webgrensesnitt og API. Prosjektoversikten beskriver tjenesten som et søkbart nettarkiv; kildearkivet angir den samtidig som fellesskapets etterfølger til Paperless og Paperless-ng.

For administratorer er Paperless-ngx ikke én enkelt webapplikasjon, men en sammensetning av database, broker, web- og bakgrunnsprosesser, filbestand, søkeindeks og eksterne konvertere. En vellykket HTTP-status beviser bare at webprosessen svarer. Den sier ikke om consumeren gjenkjenner nye filer, Celery-oppgaver blir levert, OCR fungerer, arkivfiler blir skrevet, indeksen er oppdatert eller en eksport kan importeres igjen.

Forklaringen følger et dokument fra inngangen via consumer, parser og OCR til database, arkivfil og søkeindeks. Deretter følger automatisering, sikkerhet, drift og en gjenoppretting som kontrollerer alle delene samlet.

Paperless-ngx behandler et dokument som en pipeline: gjenkjenne inngangen, overta filen, opprette OCR og metadata, oppdatere database og søkeindeks og gjøre resultatet tilgjengelig via web eller API. Artikkelen følger denne veien og utleder drift, backup og diagnose av den.

Arkitektur: kontrollsti, arbeidssti og datasti

Arkitekturen kan deles inn i tre stier:

1. Kontrollsti: Nettleseren eller API-klienten kommuniserer via HTTP eller HTTPS med Django-applikasjonen. Angular-frontend er den interaktive klienten; Django tilbyr autentisering, forretningslogikk, administrasjonsgrensesnitt og REST-API. At prosjektet består av en Django-applikasjon og en Angular-frontend, dokumenteres i utviklingsdokumentasjonen.
2. Arbeidssti: Consumer, scheduler og workere oppretter og behandler asynkrone oppgaver. En Redis-kompatibel broker formidler mellom prosesser; Celery utfører blant annet konsum, e-posthenting, indeksvedlikehold og tilbakevendende vedlikehold. Bruksdokumentasjonen beskriver consumer, task processor og broker som separate roller.
3. Datasti: Den relasjonelle databasen lagrer dokumentobjekter, metadata, brukere, regler og oppgavestatus. Originaler, arkivversjoner og miniatyrbilder ligger i Media-katalogen; hjelpetilstander og søkedata ligger i Data-katalogen. Søkeindeksen er en projeksjon av dette autoritative bestandet.

Skillet er avgjørende operativt. Databasen og Media-katalogen må tilhøre samme logiske tidspunkt. En ny indeks kan bygges opp, men en tapt originalfil kan ikke rekonstrueres fra indeksen. På samme måte er en databasesikkerhetskopi uten tilhørende filer ikke tilstrekkelig for en DMS-gjenoppretting.

Teknologistakk og prosessroller

Backendkoden er hovedsakelig implementert i Python og er basert på Django. Nettleserfrontend bruker Angular. Avhengigheter som Django, Celery, OCRmyPDF og andre parsere kan spores i Python-prosjektmanifestet; imagebygging og native OCR-/PDF-avhengigheter vises i Dockerfile. Følgende roller er relevante for drift:

Den offisielle konfigurasjonsreferansen omtaler den Redis-kompatible brokeren som en påkrevd tjeneste. PostgreSQL, MariaDB og SQLite støttes som databaser; for nye installasjoner anbefaler installasjonsveiledningen PostgreSQL. Tika og Gotenberg er valgfrie og kreves sammen for Office-formater og behandling av e-postfiler (valgfrie tjenester).

Tjenesteinventar og faktisk konfigurasjon

Et robust inventar inneholder image eller release, databasetype, brokermål, mounts, effektive miljøvariabler, UID/GID, reverse proxy, tidssone, OCR-språk og eksterne parsere. Docker Compose er en utbredt pakking, men ikke et bevis på arkitektur: Flere prosessroller kan ligge i samme containerimage, mens tilstandene deres ligger i separate volumer og tjenester.

docker compose config --services
docker compose ps
docker compose images
docker compose config
docker inspect paperless-webserver

docker compose config --services
docker compose ps
docker compose images
docker compose config
docker inspect paperless-webserver

docker compose config gjengir den faktisk sammenslåtte Compose-konfigurasjonen; docker compose ps viser prosesser og publiserte porter; docker compose images identifiserer images; docker inspect viser mounts, nettverk og kjøretidsparametere. Utdata kan inneholde hemmeligheter og skal bare legges uredigert i saker etter redigering.

Innganger og leveringsgrenser

Paperless-ngx kjenner flere innganger som har ulike feilområder før den felles pipelinen:

• Consume-katalogen overvåkes via filsystemhendelser. På filsystemer uten pålitelig inotify, som enkelte NFS-mounts, må polling aktiveres; dette nevnes i oppsettdokumentasjonen.
• Nettleser og REST-API skriver opplastinger via webstien. Reverse proxy, grense for forespørselsstørrelse, timeout og midlertidig lagring ligger dermed foran oppgavesystemet.
• E-posthentingen leser regelbasert fra konfigurerte kontoer og oppretter oppgaver for matchende vedlegg. IMAP-forbindelse, TLS, OAuth/passord, mappe, søkekriterium og etterbehandlingshandling inngår i leveringskontrakten.

Consume-katalogen er en overleveringssone og ikke et dokumentarkiv. Vellykket konsumerte filer fjernes derfra, mens Paperless oppretter nye administrerte filer i Media-bestandet. FAQ advarer uttrykkelig mot å administrere Media-katalogen manuelt.

Når prosesser og innganger er kjent, begynner selve behandlingen. Hvert trinn oppretter forskjellige filer, databaseoppføringer og feilsignaler.

Consume-pipeline: fra inngang til dokumentobjekt

Det faglige commit-et skjer ikke når en fil oppdages, men først etter flere trinn. Avhengig av filtype og konfigurasjon omfatter pipelinen vanligvis:

1. Gjenkjenning og stabilisering: Filnavn, tillatt type, filstørrelse og fullført skriving kontrolleres.
2. Opprettelse av oppdrag: Consumeren eller webserveren overleverer en oppgave via brokeren.
3. Parsing og forbehandling: Parsere trekker ut eksisterende tekst eller konverterer inngangsdokumentet. Office- og e-postfiler kan kreve Tika og Gotenberg.
4. OCR: OCRmyPDF avgjør tekstgjenkjenning ut fra OCR-modusen; Tesseract gjenkjenner konfigurerte språk.
5. Arkivversjon og miniatyrbilde: En visnings-/arkivfil og forhåndsvisningsdata opprettes, så langt filtype og innstillinger tillater det.
6. Persistens: Original og avledninger skrives; dokumentobjekt, kontrollsummer, tekst og tekniske egenskaper lagres i databasen.
7. Metadata og arbeidsflyter: Regler tilordner tagger, korrespondent, dokumenttype, lagringssti, eier eller andre felt.
8. Indeksering: Fulltekstbestandet oppdateres i søkeindeksen.
9. Avslutning: Oppgavestatus og logg viser suksess eller feil; først nå er dokumentet faglig søkbart.

Pre- og post-consume-skript kan utvide stien. Dokumentasjonen for Consume Hooks tydeliggjør at slike skript kjøres i sikkerhets- og feilkonteksten til Paperless-prosessen. De skal versjoneres og kjøres med timeout og entydige exitkoder; en feilaktig hook kan blokkere hele inntaket.

OCR, arkivformat og kvalitetsgrenser

OCRmyPDF orkestrerer PDF-behandling og Tesseract-OCR. Modusen avgjør om eksisterende tekst hoppes over, behandles på nytt eller tvinges gjennom. Språk, sidegrense, bildeopprydding, rotasjonskorrigering og utdataformat påvirker CPU-tid, filstørrelse og gjenkjenningskvalitet. Innstillingene beskrives i Paperless-OCR-konfigurasjonen og i OCRmyPDF-dokumentasjonen; språkmodeller og motoratferd dokumenteres av Tesseract.

Originalen beholdes som bevisobjekt. En arkiv-PDF er en avledet versjon som kan opprettes på nytt ved senere endringer i OCR eller arkivering. Dette skillet inngår i konsepter for oppbevaring og bevisverdi:

OCR-suksess betyr ikke faglig lesbarhet. Stikkprøver bør sammenligne sidetall, orientering, tekstdekning, spesialtegn, tabeller, innebygde signaturer og filstørrelse. CPU- og RAM-topper oppstår ofte ved rendering av store eller bilderike PDF-er, ikke ved den avsluttende databaseskrivingen.

Originaler, arkiver, miniatyrbilder og stiformat

Et Paperless-dokument består av flere koblede deler. Databasen kjenner intern ID, tittel, opprettelses- og tilleggsdato, korrespondent, dokumenttype, tagger, lagringssti, innhold, eier og andre felt. I Media-katalogen ligger originalen og eventuelt arkiv- og miniatyrbildefiler. Konfigurerbare filnavn og Storage Paths endrer den fysiske plasseringen, ikke identiteten til databaseobjektet.

Administratorer unngår direkte omdøping eller flytting i Media-katalogen. Den offisielle document_renamer bruker det konfigurerte formatet konsekvent. Et eksternt filsynkroniseringsverktøy kan sikkerhetskopiere bestanden, men skal ikke omorganisere den på egen hånd ved siden av den kjørende applikasjonen. Se Storage for grunnleggende lagring og Rclone for kopiering og verifikasjon.

Metadata, matching og arbeidsflyter

Korrespondenter, dokumenttyper, tagger, lagringsstier, egendefinerte felt og datoverdier utgjør en fasettert struktur. De erstatter ikke et filtre, men beskriver et dokument langs flere uavhengige dimensjoner. Automatisk matching gir forslag eller tilordninger basert på gjenkjent innhold og tidligere data; det er ikke en uforanderlig sannhetstjeneste.

Arbeidsflyter består av triggere, valgfrie filtre og sekvensielle handlinger. De kan sette metadata, tillatelser og andre egenskaper ved konsum eller andre hendelser. Arbeidsflytdokumentasjonen beskriver triggere og handlinger. For administratorer følger tre regler av dette:

• Hver automatisering trenger et definert inngangssett og et observerbart resultat.
• Regelrekkefølge og flere treff testes som policykode.
• Etter endringer vurderes eksisterende dokumenter på nytt bare kontrollert med document_retagger.

Søk: databasespørring og Tantivy-projeksjon

Fulltekstsøket bruker en separat Tantivy-indeks. Databasen forblir autoritativ for dokumentobjekter og metadata; indeksen akselererer søk og rangering. Dermed kan et dokument være synlig i databasen, men mangle i fulltekstsøk. Migreringen til Tantivy og endrede søkefelt dokumenteres i migreringsveiledningen.

Etter oppgraderinger eller ved mistanke om drift kan indeksen bygges på nytt via administrasjonskommandoen. Reindeksering reparerer en projeksjon, ikke en gjenoppretting av originaler. Kapasitetsplanlegging tar hensyn til indeksstørrelse, midlertidig plass under ombygging og I/O-belastning parallelt med normalt konsum.

docker compose exec webserver document_index list
docker compose exec webserver document_index reindex --if-needed
docker compose exec webserver document_sanity_checker
docker compose exec webserver document_thumbnails --help

docker compose exec webserver document_index list
docker compose exec webserver document_index reindex --if-needed
docker compose exec webserver document_sanity_checker
docker compose exec webserver document_thumbnails --help

Administrasjonskommandoer startes med Compose via docker compose exec i webservercontaineren. Bare-metal-installasjoner bruker python3 manage.py; den støttede kallformen og innebygde hjelpene dokumenteres i administrasjonen.

OCR-filer og metadata alene utgjør ennå ikke en konsistent tjeneste. Database, oppgavebroker og søkeprojeksjon må være på samme behandlingsnivå.

Database, broker og konsistens

PostgreSQL er standardvalget for nye installasjoner. MariaDB og SQLite er mulige, men skiller seg i backupverktøy, parallellatferd og driftsgrenser. Databasemigreringer inngår i en Paperless-oppgradering; en tilbakekopiert gammel binærfil passer ikke nødvendigvis til et allerede migrert skjema. Databaseoperasjon behandles derfor som en egen livssyklus (PostgreSQL-backup og gjenoppretting, MariaDB Backup and Restore).

Brokeren transporterer oppgaver mellom prosesser. Redis-/Valkey-persistens erstatter ikke sikkerhetskopi av database og dokumenter. Etter brokertap kan pågående eller leverte arbeider startes på nytt, gå tapt eller bli synlige som inkonsistent oppgavestatus. Godkjenningen skjer derfor på dokumentobjektet og filene dets, ikke på en tom kø.

docker compose exec db pg_isready
docker compose exec broker redis-cli PING
docker compose logs --since 30m webserver
docker compose logs --since 30m broker db

docker compose exec db pg_isready
docker compose exec broker redis-cli PING
docker compose logs --since 30m webserver
docker compose logs --since 30m broker db

pg_isready kontrollerer om PostgreSQL-forbindelser aksepteres, ikke skjema eller faglige spørringer. redis-cli tester brokertilgjengelighet med PING. docker compose logs samler tidsavgrensede tjenestelogger; legitimasjon, dokumenttitler og stier redigeres før videreformidling.

Konfigurasjon, Secret Key og stioppløsning

Med Docker leveres innstillinger vanligvis som miljøvariabler eller Compose-env-fil; paperless.conf gjelder ikke der. Bare-metal-installasjoner søker etter konfigurasjon i en dokumentert rekkefølge. Enkelte innstillinger kan dessuten lagres i applikasjonen og overstyre miljøverdier. Den effektive konfigurasjonen er derfor mer enn én enkelt fil (konfigurasjonsrekkefølge).

PAPERLESS_SECRET_KEY signerer økter og sensitive verdier og er obligatorisk. PAPERLESS_URL, Allowed Hosts, CSRF- og CORS-innstillinger definerer webgrensen. Database-, e-post-, OAuth-, Tika- og valgfrie AI-legitimasjoner er hemmeligheter. Docker-oppsett kan bruke _FILE-varianten for en rekke verdier og dermed mountede hemmeligheter; dette dokumenteres i oppsettsveiledningen.

Konfigurasjonsbackup omfatter minst:

• Compose-/tjenestedefinisjon og festet image-referanse,
• miljøvariabler uten klartekstkopier i ubeskyttede repositories,
• Secret Key og eksterne hemmelighetsreferanser,
• UID/GID, volum- og bind-mount-tilordning,
• proxy-, DNS-, sertifikat- og e-postkontokonfigurasjon,
• OCR-språk, filnavnformat, arbeidsflyter og egendefinerte hooks.

Webgrense, TLS og reverse proxy

Applikasjonen bør være tilgjengelig via HTTPS bak en riktig konfigurert reverse proxy. Host-header, opprinnelses-URL, CSRF Trusted Origins, Forwarded Headers og opplastingsgrenser må passe sammen. Proxyen må bare sette Remote-User-headere når den pålitelig autentiserer identiteten foran og fjerner klientheadere med samme navn.

Sikkerhetsdokumentasjonen beskriver Secret Key, URL-, host-, CORS- og CSRF-parametere. Sertifikat- og transportgrunnlag finnes under TLS, systematisk sikring under herding. Prosjektet advarer i repositoryet om at dokumenter lagres i klartekst og at Paperless-ngx ikke bør driftes på en vert som ikke er til å stole på.

Test-NetConnection paperless.example.net -Port 443
curl.exe -sS -D - -o NUL https://paperless.example.net/
Resolve-DnsName paperless.example.net
docker compose port webserver 8000

ss -lntp
curl -sS -D - -o /dev/null https://paperless.example.net/
getent ahosts paperless.example.net
docker compose port webserver 8000

Test-NetConnection kontrollerer TCP-tilgjengelighet i Windows; ss viser lokale lyttere; curl viser status, omdirigering og headere; Resolve-DnsName eller getent kontrollerer navneoppløsning; docker compose port viser den faktiske porttilordningen.

Identiteter, globale rettigheter og objektrettigheter

Paperless-ngx bruker Django-modellen for brukere og grupper. Globale tillatelser styrer hvilke objekttyper og UI-/API-områder en konto kan bruke. Objektbaserte rettigheter styrer Owner, View og Change for et bestemt dokument, en tagg eller et annet objekt. Tillatelsesdokumentasjonen fremhever at rettighetene til en tagg ikke automatisk overføres til dokumenter som er merket med den.

Superbrukere kan se alle objekter. Staff-/adminstatus må skilles fra dette og gir blant annet tilgang til backend- og systemvisninger. I den daglige driften brukes vanlige kontoer og grupper; tjenestekontoer får kun nødvendige API- og objektrettigheter. Arbeidsflyter kan sette eier og rettigheter ved konsum, noe som er spesielt viktig for eierløse dokumenter fra Consume-kataloger.

Autentisering kan være lokal, via reverse-proxy-Remote-User eller gjennom konfigurerte Social-/OIDC-prosedyrer. Remote User aktiveres bare bak en lukket proxygrense. MFA-, økt- og tokenlivssyklus inngår i det generelle identitetskonseptet.

REST-API og automatiseringsgrense

REST-API-et er tilgjengelig under applikasjonsprefikset; en interaktiv skjemavisning finnes under /api/schema/view/. Blant annet støttes Basic-, Session-, Token-, Remote-User- og Headless-OIDC-autentisering. API-dokumentasjonen beskriver søk, objekttillatelser, bulkoperasjoner og versjonsheadere.

Et API-token er en hemmelighet og tildeles separat for hver automatisering. Klienter tar hensyn til paginering, filtre, tillatelser, API-versjon og idempotent gjentakelse. Et vellykket opplastingssvar betyr ennå ikke at OCR er fullført; automatiseringer korrelerer dokument- eller oppgave-ID til den faglige sluttilstanden. Prinsipper for kontrakt, autentisering og retry-atferd finnes under API-er.

E-posthenting som meldingsgrensesnitt

E-postkontoer og e-postregler kobler Paperless-ngx til en IMAP-postkasse. Scheduler-en kontrollerer som standard konfigurerte kontoer periodisk, anvender regler og overleverer matchende vedlegg til Consume-pipelinen. Administrasjonskommandoen mail_fetcher kan utløse hentingen manuelt; dette dokumenteres i administrasjonen for e-posthenting.

For meldingsadministratorer inngår følgende verdier i runbooken:

• Server-FQDN, port og TLS-modus,
• autentiseringsmetode, utløp av hemmelighet/token og tjenestekonto,
• IMAP-mappe, søkekriterium, filtyper og maksimal meldingsstørrelse,
• handling etter vellykket eller mislykket import,
• håndtering av flere leverte meldinger og like vedlegg,
• korrelasjon mellom Message-ID, Paperless-oppgave og dokument-ID.

IMAP-semantikk defineres av RFC 9051. En vellykket IMAP-henting beviser bare inngangen til oppgavestien; fullføring av OCR og arkivering overvåkes separat.

Office-dokumenter, Tika og Gotenberg

Apache Tika trekker ut innhold og metadata fra mange filtyper; Gotenberg tilbyr konverteringstjenester. Paperless krever begge når valgfri Office-/e-postbehandling er aktivert. Endepunktene deres konfigureres separat (Tika Server, Gotenberg-konfigurasjon).

De to tjenestene øker angrepsflaten, ressursbehovet og feilrommet. De gjøres bare tilgjengelige internt, får CPU-/RAM-/timeoutgrenser og publiseres ikke som generelt konverterings-API. Hvis PDF-er fungerer, men DOCX eller EML konsekvent feiler, starter diagnosen ved denne sidestien og ikke ved Tantivy eller databasen.

Container-, bare-metal- og lagringsdrift

De offisielle metodene er installasjonsskript, Docker Compose og Bare Metal. Compose gir reproduserbare tjenestedefinisjoner og separate volumer; Bare Metal gir mer kontroll over prosesser, pakker og systemd, men krever eksplisitt livssyklusadministrasjon. Oppsettsmatrisen klassifiserer metodene etter innsats og bruk.

Persistente kataloger må ikke forveksles med containerens livssyklus. Med Compose løses Media, Data, Consume, Export og databasestien bevisst. Fjern- eller nettverksfilsystemer kontrolleres for POSIX-atferd, atomisk omdøping, låsing, latens, inotify og tilgjengelighet. Et kort avbrudd kan ellers se ut som permanent dokumenttap. Grunnleggende om mounts finnes under Container og Storage.

Ved en feil fastslås først hvilken pipelinefase dokumentet befinner seg i. Deretter kontrolleres kø, worker, ekstern konverterer, database og fillagring målrettet.

Observerbarhet og oppgavediagnose

En fornuftig driftsoversikt skiller mellom fire signaler:

• Tjenestehelse: Prosessen kjører, porten lytter, database og broker er tilgjengelige.
• Gjennomstrømning: Nye oppgaver, fullførte dokumenter, kjøretider og kødybde.
• Feil: Oppgaver etter trinn og filtype, parser-/OCR-exit, e-post- og lagringsfeil.
• Bestandsintegritet: Manglende eller skadede originaler/arkiver/miniatyrbilder, foreldreløse filer, indeksdrift.

Den innebygde Sanity Checker oppdager blant annet manglende, ulesbare eller filer som er endret i forhold til lagret kontrollsum, samt foreldreløse Media-filer. Den fullstendige listen finnes i Sanity Checker-dokumentasjonen. En alarm på antall feil uten dokument-/oppgave-ID og pipelinefase er knapt handlingsdyktig.

docker compose logs --since 1h --timestamps webserver
docker compose exec webserver document_sanity_checker
docker compose exec webserver mail_fetcher
docker stats --no-stream
docker system df -v

docker compose logs --since 1h --timestamps webserver
docker compose exec webserver document_sanity_checker
docker compose exec webserver mail_fetcher
docker stats --no-stream
docker system df -v

docker stats viser øyeblikkelig CPU-/minnebruk, docker system df viser Docker-diskbruken. Begge er øyeblikksbilder. For årsaker korreleres tidsserie, oppgave-ID og Paperless-logger. Generell metodikk finnes under Troubleshooting.

Kapasitet, parallellitet og grenseverdier

Kapasitetsplanlegging starter med sider per dag, inngangsformater, gjennomsnittlig og maksimal filstørrelse, OCR-språk, parallelle oppgaver, oppbevaringstid og søkevolum. Et dokument kan samtidig opprette original, arkiv-PDF, miniatyrbilde, databasepost, fulltekstindeks og midlertidige renderfiler. Ledig plass må også ta høyde for reindeksering, eksport og oppgradering.

Mer workerparallellitet akselererer CPU-bundet OCR bare til CPU, RAM og I/O er mettet. Samtidig øker den antallet midlertidige filer og databaseforbindelser. E-posthenting og consumer kan opprette flere oppgaver enn workere behandler; derfor observeres køalder, ikke bare øyeblikkelig kølengde. Grenser testes med representative dokumenter, ikke små tekst-PDF-er.

Sikkerhetskopiomfanget følger datamodellen: Originaler, arkiver, database, konfigurasjon, Secret Key og eventuelt tilleggstjenester må kunne gjenopprettes samlet.

Backup: Hvilke objekter som sikkerhetskopieres sammen

Den offisielle backupdokumentasjonen nevner to hovedmetoder: Document Exporter eller koordinert sikkerhetskopi av volumer/kataloger og database. Exporter-en skriver dokumenter, miniatyrbilder, metadata og databaseinnhold til en transportabel katalog. API-tokens overtas ikke; eksport og import bør være versjonskompatible.

Et fullstendig gjenopprettingssett inneholder:

Exporter-en kan oppdatere eksisterende eksporter og sammenligne kontrollsummer valgfritt. Dette sparer tid, men erstatter ikke en separat, versjonert kopi: Med --delete kan slettede dokumenter fjernes fra eksportmålet. Detaljer og alternativer dokumenteres av document_exporter.

docker compose exec -T webserver document_exporter ../export --compare-checksums
Get-ChildItem -Recurse .\export | Measure-Object -Property Length -Sum
Get-FileHash .\export\manifest.json -Algorithm SHA256
docker compose exec webserver document_sanity_checker

docker compose exec -T webserver document_exporter ../export --compare-checksums
du -sh ./export
sha256sum ./export/manifest.json
docker compose exec webserver document_sanity_checker

Get-FileHash og sha256sum sikrer overføringsbeviset for manifestet. En kontrollsum beviser bare likhet mellom to byte-sekvenser, ikke importerbarhet eller faglig fullstendighet. Grunnleggende om backup finnes under Backup og disaster recovery.

Gjenoppretting og godkjenning

document_importer forventer en tom installasjon eller, med --data-only, en tom database. En gjenopprettingstest bruker derfor isolerte målstier, en Paperless-versjon som passer sikkerhetskopien og ingen produksjonsvolumer.

Godkjenningen omfatter minst:

1. Legg inn konfigurasjon og hemmeligheter i målmiljøet.
2. Klargjør tom database og tomme Media-/Data-stier.
3. Importer eksporten eller gjenopprett database og filer konsistent.
4. Utfør migreringer og eventuelt indeksbygging kontrollert.
5. Kontroller brukerinnlogging, grupper og tillatelser.
6. Sammenlign dokumentantall, metadata og stikkprøver fra original og arkiv.
7. Test fulltekstsøk og visning av miniatyrbilder.
8. Kjør Sanity Checker uten uforklarte funn.
9. Konsumer et nytt testdokument gjennom den reelle inngangen.
10. Dokumenter RPO og RTO med tidsstempler.

En gjenoppretting anses først som vellykket etter denne ende-til-ende-testen. «Containeren starter» er ikke et godkjenningskriterium.

Oppdateringer, databasemigreringer og rollbackgrense

Før en oppdatering fullføres aktive Consume-oppgaver, en sikkerhetskopi opprettes og release notes gjennomgås for breaking changes. Oppdateringsveiledningen skiller mellom Docker- og bare-metal-prosedyrer og beskriver databasemigrering og behovsbasert reindeksering. Et image festes til en utgitt serie eller en digest; latest er ikke et reproduserbart rollbackpunkt.

Etter en databasemigrering er rollback normalt en gjenoppretting av database og tilhørende filbestand, ikke bare oppstart av det gamle imaget. Nye arkiver eller metadata som er opprettet etter sikkerhetskopieringspunktet, må behandles faglig før tilbakespranget. Generelle prinsipper for release og endring finnes under Releases og Migration.

Endringsloggen er den tidsavhengige kilden for nye funksjoner, breaking changes og rettelser. Denne artikkelen beskriver derimot stabile arkitektur- og driftsprinsipper.

Feilbilder etter pipelinefase

Fordi et dokument går gjennom flere behandlingstrinn, viser det synlige symptomet ofte bare den siste vellykkede fasen. Tabellen leder fra symptomet til neste robuste bevis.

Den offisielle Troubleshooting-samlingen supplerer med konkrete feilmeldinger. Administratorer lagrer alltid oppgave-ID, dokumentnavn, tidsvindu, effektiv konfigurasjon, container-/prosessstatus og tilstanden til alle avhengige tjenester før endringer.

Teknisk historie

Det opprinnelige Paperless-prosjektet etablerte grunnmodellen med Consume-katalog, OCR og søkbart arkiv. Paperless-ng fortsatte utviklingen som en fork. Paperless-ngx oppstod deretter som den offisielle fellesskapsetterfølgeren for å fordele vedlikehold og ansvar mellom flere bidragsytere; denne avstamningen beskrives i prosjektets README.

Plattformen utviklet seg fra en primært serversidebasert Django-applikasjon til et DMS med Angular-frontend, REST-API, objektbaserte tillatelser, arbeidsflytmotor og parallell oppgavebehandling. OCRmyPDF/Tesseract forble OCR-grunnlaget; Tika og Gotenberg utvidet de støttede inngangsformatene. Søkestien gikk fra Whoosh til Tantivy, noe som gjorde indeksen synlig som et eget migrerings- og driftsdomene (Tantivy-migrering).

Denne historien forklarer dagens arkitektur: Et Paperless-ngx-dokument er samtidig et relasjonelt objekt, et sett med administrerte filer, et OCR-resultat og en søkeprojeksjon. Vedlikehold og gjenoppretting må ta hensyn til alle fire perspektivene.

Sjekkliste for administratorer

Til slutt kontrolleres innganger, workere, lagring, søk og backup samlet. Sjekklisten bidrar til at ingen ekstern avhengighet utenfor Paperless-containeren overses.

• Inventar: Image/commit, Django-/Angular-applikasjon, worker, scheduler, broker, database, Tika/Gotenberg, proxy og mounts.
• Dataobjekter: Navngi database, original, arkiv, miniatyrbilde, indeks, konfigurasjon, hemmeligheter og eksportmanifest separat.
• Innganger: Dokumenter Consume, opplasting/API og e-post hver med regel for størrelse, type, autentisering og feil.
• Pipeline: Korreler oppgave-ID via parser, OCR, arkivering, metadata og indeks til fullføring.
• Tillatelser: Test globale og objektbaserte rettigheter, superbrukere, grupper og arbeidsflyttilordninger.
• Kapasitet: Overvåk køalder, OCR-kjøretid, midlertidig plass, Media-/indeksvekst og databaseforbindelser.
• Sikkerhet: Ta med HTTPS, proxytiltro, Secret Key, tokens, klartekstlagring og eksterne parsere i trusselmodellen.
• Backup: Sikkerhetskopier database og Media konsistent; ikke glem konfigurasjon og hemmeligheter.
• Gjenoppretting: Kontroller tom målforekomst, passende versjon, stikkprøver, søk, Sanity Checker og ny Consume-kjøring.
• Endring: Dokumenter release notes, skjema-/indeksmigrering, ledig plass og reell rollbackgrense på forhånd.

Kilder

• Paperless-ngx – dokumentasjon
• Paperless-ngx – GitHub-repository
• Paperless-ngx – utvikling
• Paperless-ngx – bruk
• Celery
• Paperless-ngx – Python-prosjektmanifest
• Paperless-ngx – Dockerfile
• Paperless-ngx – konfigurasjon
• Redis-kompatibel broker
• PostgreSQL
• Paperless-ngx – installasjon
• Docker – compose config
• Docker – compose ps
• Docker – compose images
• Docker – inspect
• Paperless-ngx – FAQ
• Paperless-ngx – Consume Hooks
• OCRmyPDF – dokumentasjon
• Tesseract – dokumentasjon
• Paperless-ngx – Document Renamer
• Paperless-ngx – Tantivy-migrering
• Docker – compose exec
• PostgreSQL – Backup and Restore
• MariaDB – Backup and Restore
• PostgreSQL – pg_isready
• Redis – redis-cli
• Docker – compose logs
• Microsoft – Test-NetConnection
• Linux man-pages – ss(8)
• curl – håndbok
• Microsoft – Resolve-DnsName
• Linux man-pages – getent(1)
• Docker – compose port
• Paperless-ngx – REST-API
• RFC 9051 – IMAP4rev2
• Apache Tika – serverdrift
• Gotenberg – konfigurasjon
• Docker – stats
• Docker – system df
• Microsoft – Get-FileHash
• GNU Coreutils – sha2-verktøy
• Paperless-ngx – endringslogg
• Paperless-ngx – Troubleshooting