Paperless-ngx: dokumentpipeline, OCR och arkivdrift

Paperless-ngx är ett självhostat dokumenthanteringssystem för inkommande filer och skannade pappersdokument. Det tar emot dokument från en övervakad katalog, från webben respektive REST-API:t eller från e-postlådor, skapar sökbar text och vid behov ett normaliserat arkivexemplar, tilldelar metadata och gör beståndet sökbart via webbgränssnitt och API. Projektöversikten beskriver tjänsten som ett sökbart onlinearkiv; källkodsförrådet anger samtidigt att den är efterföljaren till Paperless och Paperless-ng som drivs av communityn.

För administratörer är Paperless-ngx inte en enskild webbapplikation, utan en sammansättning av databas, broker, webb- och bakgrundsprocesser, filbestånd, sökindex och externa konverterare. En lyckad HTTP-status bevisar bara att webbprocessen svarar. Den säger inte om consumer-processen upptäcker nya filer, Celery-uppgifter levereras, OCR fungerar, arkivfiler skrivs, indexet är aktuellt eller en export kan importeras igen.

Förklaringen följer ett dokument från inkommande leverans via consumer, parser och OCR till databas, arkivfil och sökindex. Därefter följer automatisering, säkerhet, drift och en återställning som kontrollerar alla delar tillsammans.

Paperless-ngx bearbetar ett dokument som en pipeline: upptäcka ingången, överta filen, skapa OCR och metadata, uppdatera databasen och sökindexet samt tillhandahålla resultatet via webb eller API. Artikeln följer denna väg och härleder drift, backup och felsökning ur den.

Arkitektur: styrflöde, arbetsflöde och dataflöde

Arkitekturen kan delas upp i tre flöden:

1. Styrflöde: Webbläsaren eller API-klienten kommunicerar med Django-applikationen via HTTP respektive HTTPS. Angular-gränssnittet är den interaktiva klienten; Django tillhandahåller autentisering, affärslogik, administrativt gränssnitt och REST-API. Att projektet består av en Django-applikation och ett Angular-gränssnitt dokumenteras i utvecklingsdokumentationen.
2. Arbetsflöde: Consumer, scheduler och worker skapar och bearbetar asynkrona uppgifter. En Redis-kompatibel broker förmedlar mellan processer; Celery utför bland annat konsumtion, e-posthämtning, indexunderhåll och återkommande underhåll. Användningsdokumentationen beskriver consumer, task processor och broker som separata roller.
3. Dataflöde: Den relationella databasen innehåller dokumentobjekt, metadata, användare, regler och uppgiftsstatus. Original, arkivversioner och miniatyrbilder finns i Media-katalogen; hjälpstatus och sökdata finns i Data-katalogen. Sökindexet är en projektion av detta auktoritativa bestånd.

Separationen är operativt avgörande. Databasen och Media-katalogen måste höra till samma logiska tidpunkt. Ett nytt index kan byggas upp, men en förlorad originalfil kan inte återskapas från indexet. På samma sätt räcker inte en databassäkerhetskopia utan tillhörande filer för en DMS-restore.

Teknikstack och processroller

Backendkoden är huvudsakligen implementerad i Python och bygger på Django. Webbgränssnittet använder Angular. Beroenden som Django, Celery, OCRmyPDF och andra parser kan spåras i Python-projektmanifestet; imagebygge och inbyggda OCR-/PDF-beroenden visas i Dockerfile. Följande roller är relevanta för drift:

Den officiella konfigurationsreferensen betecknar den Redis-kompatibla brokern som en nödvändig tjänst. PostgreSQL, MariaDB och SQLite stöds som databaser; för nya installationer rekommenderar installationsguiden PostgreSQL. Tika och Gotenberg är valfria och behövs tillsammans för Office-format och bearbetning av e-postfiler (valfria tjänster).

Tjänsteinventering och faktisk konfiguration

En robust inventering omfattar image eller release, databastyp, brokermål, mountar, effektiva miljövariabler, UID/GID, reverse proxy, tidszon, OCR-språk och externa parser. Docker Compose är en vanlig paketering, men inte något arkitekturbevis: Flera processroller kan finnas i en containerimage medan deras tillstånd ligger i separata volymer och tjänster.

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 återger den faktiskt sammanslagna Compose-konfigurationen; docker compose ps visar processer och publicerade portar; docker compose images identifierar images; docker inspect ger mountar, nätverk och körtidsparametrar. Utdata kan innehålla hemligheter och ska endast läggas in i ärenden i maskerad form.

Ingångar och leveransgränser

Paperless-ngx har flera ingångar som före den gemensamma pipelinen har olika felområden:

• Consume-katalogen övervakas med filsystemhändelser. På filsystem utan tillförlitlig inotify, exempelvis vissa NFS-mountar, måste polling aktiveras; detta anges i setup-dokumentationen.
• Webbläsare och REST-API skriver uppladdningar via webbsökvägen. Reverse proxy, gräns för begärans storlek, timeout och temporär lagring ligger därmed före uppgiftssystemet.
• E-posthämtningen läser regelbaserat från konfigurerade konton och skapar uppgifter för matchande bilagor. IMAP-anslutning, TLS, OAuth/lösenord, mapp, sökkriterium och åtgärd efter bearbetning hör till leveransavtalet.

Consume-katalogen är en överlämningszon och inte ett dokumentarkiv. Framgångsrikt konsumerade filer tas bort därifrån, medan Paperless skapar nya hanterade filer i Media-beståndet. FAQ varnar uttryckligen för att hantera Media-katalogen manuellt.

När processer och ingångar är kända börjar den faktiska bearbetningen. Varje steg skapar andra filer, databasposter och felsignaler.

Consume-pipeline: från ingång till dokumentobjekt

Det verksamhetsmässiga committet sker inte när en fil upptäcks, utan först efter flera steg. Beroende på filtyp och konfiguration omfattar pipelinen vanligtvis:

1. Identifiering och stabilisering: Filnamn, tillåten typ, filstorlek och avslutad skrivning kontrolleras.
2. Skapande av uppdrag: Consumer-processen respektive webbservern överlämnar en uppgift via brokern.
3. Parsing och förbearbetning: Parser extraherar befintlig text eller konverterar ingångsdokumentet. Office- och e-postfiler kan behöva Tika och Gotenberg.
4. OCR: OCRmyPDF avgör utifrån OCR-läget om textigenkänning ska hoppas över, köras igen eller tvingas fram; Tesseract känner igen konfigurerade språk.
5. Arkivversion och miniatyrbild: En visnings-/arkivfil och förhandsvisningsdata skapas i den mån filtyp och inställningar medger det.
6. Persistens: Original och derivat skrivs; databasobjekt, kontrollsummor, text och tekniska egenskaper lagras.
7. Metadata och arbetsflöden: Regler tilldelar taggar, korrespondent, dokumenttyp, lagringssökväg, ägare eller andra fält.
8. Indexering: Fulltextbeståndet uppdateras i sökindexet.
9. Avslut: Uppgiftsstatus och logg visar framgång eller fel; först nu är dokumentet verksamhetsmässigt sökbart.

Pre- och post-consume-skript kan utöka flödet. Dokumentationen om Consume Hooks klargör att sådana skript körs i Paperless-processens säkerhets- och felkontext. De ska versionshanteras, köras med timeout och tydliga exitkoder; en felaktig hook kan blockera hela inmatningen.

OCR, arkivformat och kvalitetsgränser

OCRmyPDF orkestrerar PDF-bearbetning och Tesseract-OCR. Läget avgör om befintlig text hoppas över, bearbetas på nytt eller tvingas fram. Språk, sidgräns, bildrensning, rotationskorrigering och utdataformat påverkar CPU-tid, filstorlek och igenkänningskvalitet. Inställningarna beskrivs i Paperless OCR-konfiguration och i OCRmyPDF-dokumentationen; språkmodeller och enginebeteende dokumenteras av Tesseract.

Originalet behålls som bevisobjekt. En arkiv-PDF är en härledd version som kan skapas på nytt vid senare ändringar av OCR eller arkivering. Denna skillnad ska ingå i koncepten för bevarande och bevisvärde:

OCR-framgång betyder inte verksamhetsmässig läsbarhet. Stickprov bör jämföra sidantal, orientering, texttäckning, specialtecken, tabeller, inbäddade signaturer och filstorlek. Toppar i CPU- och RAM-användning uppstår ofta vid rendering av stora eller bildrika PDF-filer, inte vid den avslutande databasskrivningen.

Original, arkiv, miniatyrbilder och sökvägsformat

Ett Paperless-dokument består av flera kopplade delar. Databasen känner till intern ID, titel, skapande- och tilläggsdatum, korrespondent, dokumenttyp, taggar, lagringssökväg, innehåll, ägare och ytterligare fält. Originalet och eventuellt arkiv- och miniatyrfiler ligger i Media-katalogen. Konfigurerbara filnamn och Storage Paths ändrar den fysiska ordningen, inte databasobjektets identitet.

Administratörer undviker direkta namnbyten eller flyttningar i Media-katalogen. Den officiella document_renamer tillämpar det konfigurerade formatet konsekvent. Ett externt filsynkverktyg får säkerhetskopiera beståndet, men inte självständigt organisera om det vid sidan av den körande applikationen. För grunder om lagring, se Storage, för kopiering och verifiering Rclone.

Metadata, matchning och arbetsflöden

Korrespondenter, dokumenttyper, taggar, lagringssökvägar, anpassade fält och datumvärden bildar en fasetterad ordning. De ersätter inte ett filträd, utan beskriver ett dokument längs flera oberoende dimensioner. Automatisk matchning ger förslag respektive tilldelningar baserat på igenkänt innehåll och tidigare data; den är ingen oföränderlig sanningskälla.

Arbetsflöden består av utlösare, valfria filter och sekventiella åtgärder. De kan vid konsumtion eller andra händelser sätta metadata, behörigheter och ytterligare egenskaper. Workflow-dokumentationen beskriver utlösare och åtgärder. För administratörer följer tre regler:

• Varje automatik behöver en definierad inmatningsmängd och ett observerbart resultat.
• Regelordning och flera träffar testas som policykod.
• Efter ändringar utvärderas befintliga dokument på nytt endast kontrollerat med document_retagger.

Sökning: databasfråga och Tantivy-projektion

Fulltextsökningen använder ett separat Tantivy-index. Databasen är fortsatt auktoritativ för dokumentobjekt och metadata; indexet snabbar upp sökning och rankning. Därför kan ett dokument vara synligt i databasen men saknas i fulltextsökningar. Migreringen till Tantivy och ändrade sökfält dokumenteras i migrationsguiden.

Efter uppgraderingar eller vid misstanke om drift kan indexet byggas om med managementkommandot. Omindexering är en reparation av en projektion, inte en återställning av originalen. Kapacitetsplanering tar hänsyn till indexstorlek, temporärt utrymme under en ombyggnad och I/O-belastningen parallellt med normal konsumtion.

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

Managementkommandon startas i Compose via docker compose exec i webbservercontainern. Bare-metal-installationer använder python3 manage.py; det stödda anropsformatet och den inbyggda hjälpen dokumenteras i administrationen.

OCR-filer och metadata bildar ännu ingen konsekvent tjänst. Databas, taskbroker och sökprojektion måste motsvara samma bearbetningsstatus.

Databas, broker och konsistens

PostgreSQL är standardvägen för nya installationer. MariaDB och SQLite är möjliga, men skiljer sig åt när det gäller backupverktyg, parallellbeteende och driftsgränser. Databasmigreringar är en del av en Paperless-uppgradering; en återkopierad äldre binärfil passar inte nödvändigtvis till ett redan migrerat schema. Databasdrift behandlas därför som en separat livscykel (PostgreSQL-backup och restore, MariaDB Backup and Restore).

Brokern transporterar uppgifter mellan processer. Redis-/Valkey-persistens ersätter inte backup av databas och dokument. Efter brokerförlust kan pågående eller levererade arbeten initieras på nytt, förloras eller synas som inkonsekvent uppgiftsstatus. Godkännandet sker därför på dokumentobjektet och dess filer, inte 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 kontrollerar om PostgreSQL-anslutningar accepteras, inte schema eller verksamhetsmässiga frågor. redis-cli testar brokeråtkomst med PING. docker compose logs sammanför tidsbegränsade tjänstloggar; credentials, dokumenttitlar och sökvägar maskeras före vidarebefordran.

Konfiguration, Secret Key och sökvägsupplösning

Med Docker levereras inställningar vanligtvis som miljövariabler respektive Compose-env-fil; paperless.conf gäller inte där. Bare-metal-installationer söker konfiguration i en dokumenterad ordning. Vissa inställningar kan dessutom lagras i applikationen och åsidosätta miljövärden. Den effektiva konfigurationen är därför mer än en enskild fil (konfigurationsordning).

PAPERLESS_SECRET_KEY signerar sessioner och känsliga värden och är obligatorisk. PAPERLESS_URL, Allowed Hosts, CSRF- och CORS-inställningar definierar webbgränsen. Credentials för databas, e-post, OAuth, Tika och valfri AI är hemligheter. Docker-konfigurationer kan använda _FILE-varianten för många värden och därmed mountade hemligheter; detta dokumenteras i setup-guiden.

Konfigurationsbackup omfattar minst:

• Compose-/tjänstdefinition och pinnad image-referens,
• miljö utan klartextkopior i oskyddade repositories,
• Secret Key och externa hemlighetsreferenser,
• UID/GID, volym- och bind-mount-tilldelning,
• proxy-, DNS-, certifikat- och e-postkontokonfiguration,
• OCR-språk, filnamnsformat, arbetsflöden och anpassade hooks.

Webbgräns, TLS och reverse proxy

Applikationen bör vara åtkomlig via HTTPS bakom en korrekt konfigurerad reverse proxy. Hostheader, ursprungs-URL, CSRF Trusted Origins, Forwarded Headers och uppladdningsgränser måste stämma överens. Proxyn får endast sätta Remote-User-header när den tillförlitligt autentiserar den föregående identiteten och tar bort klientheaders med samma namn.

Säkerhetsdokumentationen beskriver Secret Key, URL-, host-, CORS- och CSRF-parametrar. Grunder för certifikat och transport finns under TLS, systematisk härdning under Härtning. Projektet varnar i repositoryt för att dokument lagras i klartext och att Paperless-ngx inte bör drivas på en opålitlig värd.

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 kontrollerar TCP-åtkomst i Windows; ss visar lokala lyssnare; curl visar status, omdirigering och headers; Resolve-DnsName respektive getent kontrollerar namnupplösning; docker compose port visar den faktiska portmappningen.

Identiteter, globala rättigheter och objekträttigheter

Paperless-ngx använder Django-modellen för användare och grupper. Globala behörigheter styr vilka objekttyper och UI-/API-områden ett konto får använda. Objektbaserade rättigheter styr Owner, View och Change för ett visst dokument, en tagg eller ett annat objekt. Behörighetsdokumentationen betonar att en taggs rättigheter inte automatiskt övergår till dokument som markerats med den.

Superusers får se alla objekt. Staff-/adminstatus ska skiljas från detta och möjliggör bland annat backend- och systemvyer. För den dagliga driften används vanliga konton och grupper; tjänstekonton får endast nödvändiga API- och objekträttigheter. Arbetsflöden kan sätta ägare och rättigheter vid konsumtion, vilket är särskilt viktigt för ägarlösa dokument från Consume-kataloger.

Autentisering kan ske lokalt, med reverse-proxy-Remote-User eller med konfigurerade social-/OIDC-förfaranden. Remote User aktiveras endast bakom en sluten proxygräns. MFA-, sessions- och tokenlivscykel inkluderas i det övergripande identitetskonceptet.

REST-API och automationsgräns

REST-API:t är åtkomligt under applikationsprefixet; en interaktiv schemavy finns under /api/schema/view/. Bland annat stöds Basic-, Session-, Token-, Remote-User- och Headless-OIDC-autentisering. API-dokumentationen beskriver sökning, objektbehörigheter, bulkoperationer och versionsheaders.

En API-token är en hemlighet och tilldelas separat för varje automation. Klienter tar hänsyn till paginering, filter, behörigheter, API-version och idempotenta upprepningar. Ett lyckat uppladdningssvar innebär ännu inte att OCR är slutförd; automationer korrelerar dokument- respektive task-ID fram till verksamhetsmässigt slutstatus. Principer för avtal, autentisering och retrybeteende finns under API:er.

E-posthämtning som meddelandegränssnitt

E-postkonton och e-postregler kopplar Paperless-ngx till en IMAP-brevlåda. Schedulern kontrollerar som standard regelbundet konfigurerade konton, tillämpar regler och överlämnar matchande bilagor till Consume-pipelinen. Managementkommandot mail_fetcher kan utlösa hämtningen manuellt; detta dokumenteras i administrationen för e-posthämtning.

För meddelandeadministratörer ska följande värden ingå i runbooken:

• server-FQDN, port och TLS-läge,
• autentiseringsmetod, utgång av hemlighet/token och tjänstekonto,
• IMAP-mapp, sökkriterium, filtyper och maximal meddelandestorlek,
• åtgärd efter lyckad eller misslyckad import,
• hantering av flera leveranser av samma meddelande och identiska bilagor,
• korrelation mellan Message-ID, Paperless-task och dokument-ID.

IMAP-semantik definieras av RFC 9051. En lyckad IMAP-hämtning bevisar bara ingången till uppgiftsflödet; OCR- och arkivslutförande övervakas separat.

Office-dokument, Tika och Gotenberg

Apache Tika extraherar innehåll och metadata från många filtyper; Gotenberg tillhandahåller konverteringstjänster. Paperless behöver båda när den valfria Office-/e-postbearbetningen är aktiverad. Deras ändpunkter konfigureras separat (Tika Server, Gotenberg-konfiguration).

De båda tjänsterna ökar attackytan, resursbehovet och felutrymmet. De görs endast åtkomliga internt, får CPU-/RAM-/timeoutgränser och publiceras inte som ett allmänt konverterings-API. Om PDF-filer fungerar men DOCX eller EML konsekvent misslyckas börjar felsökningen i denna sidoväg, inte hos Tantivy eller databasen.

Container-, bare-metal- och lagringsdrift

De officiella vägarna är installationsskript, Docker Compose och bare metal. Compose ger reproducerbara tjänstdefinitioner och separata volymer; bare metal ger mer kontroll över processer, paket och systemd, men kräver uttrycklig livscykelhantering. Setup-matrisen ordnar vägarna efter arbetsinsats och användning.

Persistenta kataloger förväxlas inte med containerlivscykeln. Med Compose löses Media, Data, Consume, Export och databassökvägen medvetet upp. Fjärr- eller nätverksfilsystem kontrolleras för POSIX-beteende, atomiskt namnbyte, låsning, latens, inotify och tillgänglighet. Ett kort avbrott kan annars se ut som en permanent dokumentförlust. Grunder om mountar finns under Container och Storage.

Vid en störning fastställs först i vilken pipelinefas dokumentet befinner sig. Därefter kontrolleras kö, worker, extern konverterare, databas och fillagring målmedvetet.

Observerbarhet och uppgiftsdiagnostik

En meningsfull driftöversikt skiljer mellan fyra signaler:

• Tjänstehälsa: Processen körs, porten lyssnar, databas och broker är åtkomliga.
• Genomströmning: nya uppgifter, slutförda dokument, körtider och ködjup.
• Fel: uppgifter per steg och filtyp, parser-/OCR-exit, e-post- och lagringsfel.
• Beståndsintegritet: saknade eller skadade original/arkiv/miniatyrbilder, föräldralösa filer, indexdrift.

Den inbyggda Sanity Checker upptäcker bland annat saknade, oläsbara eller jämfört med den lagrade kontrollsumman förändrade filer samt föräldralösa Media-filer. Den fullständiga listan finns i Sanity Checker-dokumentationen. Ett larm om antal fel utan dokument-/task-ID och pipelinefas är knappast användbart.

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 visar momentan CPU-/minnesanvändning, docker system df Docker-diskanvändning. Båda är ögonblicksbilder. För orsaker korreleras tidsserier, task-ID och Paperless-loggar. Allmän metodik finns under felsökning.

Kapacitet, parallellitet och gränsvärden

Kapacitetsplanering börjar med sidor per dag, inmatningsformat, genomsnittlig och maximal filstorlek, OCR-språk, parallella uppgifter, bevarandetid och sökvolym. Ett dokument kan samtidigt skapa original, arkiv-PDF, miniatyrbild, databaspost, fulltextindex och tillfälliga renderfiler. Det lediga utrymmet måste även täcka omindexering, export och uppgradering.

Fler parallella workers snabbar upp CPU-bunden OCR endast tills CPU, RAM och I/O är mättade. Samtidigt ökar antalet tillfälliga filer och databasanslutningar. E-posthämtning och consumer får skapa fler uppgifter än workers kan bearbeta; därför övervakas köålder i stället för bara aktuell kölängd. Gränser testas med representativa dokument, inte med små text-PDF:er.

Säkerhetskopieringsomfattningen följer datamodellen: Original, arkiv, databas, konfiguration, Secret Key och eventuella ytterligare tjänster måste kunna återställas tillsammans.

Backup: vilka objekt som säkerhetskopieras tillsammans

Den officiella backupdokumentationen anger två huvudvägar: Document Exporter eller en samordnad säkerhetskopiering av volymer/kataloger och databas. Exportern skriver dokument, miniatyrbilder, metadata och databasinnehåll till en portabel katalog. API-token följer inte med; export och import bör vara versionskompatibla.

En fullständig recoveryuppsättning innehåller:

Exportern kan uppdatera befintliga exporter och valfritt jämföra kontrollsummor. Det sparar tid, men ersätter inte en separat, versionshanterad kopia: Med --delete kan raderade dokument tas bort från exportmålet. Detaljer och alternativ dokumenteras 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 och sha256sum säkrar överföringsbeviset för manifestet. En kontrollsumma bevisar bara likhet mellan två byteuppsättningar, inte importerbarhet eller verksamhetsmässig fullständighet. Grundläggande backupprinciper finns under Backup och Disaster Recovery.

Restore och godkännande

document_importer förutsätter en tom installation respektive, med --data-only, en tom databas. Ett restoretest använder därför isolerade målsökvägar, en Paperless-version som passar säkerhetskopian och inga produktionsvolymer.

Godkännandet omfattar minst:

1. Lägg in konfiguration och hemligheter i målmiljön.
2. Tillhandahåll tom databas och tomma Media-/Data-sökvägar.
3. Importera exporten eller återställ databas och filer konsekvent.
4. Kör migreringar och vid behov indexuppbyggnad kontrollerat.
5. Kontrollera användarinloggning, grupper och behörigheter.
6. Jämför dokumentantal, metadata och stickprov från original och arkiv.
7. Testa fulltextsökning och visning av miniatyrbilder.
8. Kör Sanity Checker utan oförklarade fynd.
9. Konsumera ett nytt testdokument via den verkliga ingången.
10. Dokumentera RPO och RTO med tidsstämplar.

En restore anses framgångsrik först efter detta end-to-end-test. ”Containern startar” är inget godkännandekriterium.

Uppdateringar, databasmigreringar och rollbackgräns

Före en uppdatering avslutas aktiva Consume-uppgifter, en säkerhetskopia skapas och release notes kontrolleras för breaking changes. Uppdateringsguiden skiljer mellan Docker- och bare-metal-förfaranden och beskriver databasmigrering samt behovsstyrd omindexering. En image pinnas till en godkänd serie eller en digest; latest är ingen reproducerbar rollbackpunkt.

Efter en databasmigrering är rollback normalt en restore av databasen och det matchande filbeståndet, inte bara start av den gamla imagen. Nya arkiv eller metadata som tillkommit efter säkerhetskopieringspunkten måste hanteras verksamhetsmässigt före återgången. Allmänna principer för release och change finns under Releases och Migration.

Changelog är den tidsberoende källan för nya funktioner, breaking changes och korrigeringar. Denna artikel beskriver däremot stabila arkitektur- och driftsprinciper.

Felbilder per pipelinefas

Eftersom ett dokument genomgår flera bearbetningssteg visar det synliga symptomet ofta bara den senast lyckade fasen. Tabellen leder från symptom till nästa robusta bevis.

Den officiella felsökningssamlingen kompletterar med konkreta felmeddelanden. Administratörer sparar alltid task-ID, dokumentnamn, tidsfönster, effektiv konfiguration, container-/processstatus och tillståndet för alla beroende tjänster före ändringar.

Teknisk historia

Det ursprungliga Paperless-projektet etablerade grundmodellen med Consume-katalog, OCR och sökbart arkiv. Paperless-ng fortsatte utvecklingen som en fork. Paperless-ngx uppstod därefter som den officiella efterföljaren som drivs av communityn, för att fördela underhåll och ansvar över flera medverkande; denna härkomst beskrivs i projektets README.

Plattformen utvecklades från en främst serversidig Django-applikation till ett DMS med Angular-gränssnitt, REST-API, objektbaserade behörigheter, arbetsflödesmotor och parallell uppgiftsbearbetning. OCRmyPDF/Tesseract förblev OCR-grunden; Tika och Gotenberg utökade de stödda inmatningsformaten. Sökvägen bytte från Whoosh till Tantivy, vilket gjorde indexet synligt som en egen migrations- och driftdomän (Tantivy-migrering).

Denna historia förklarar dagens arkitektur: Ett Paperless-ngx-dokument är samtidigt ett relationellt objekt, en uppsättning hanterade filer, ett OCR-resultat och en sökprojektion. Underhåll och recovery måste beakta alla fyra perspektiv.

Checklista för administratörer

Avslutningsvis kontrolleras ingångar, workers, lagring, sökning och backup gemensamt. Checklistan hjälper till att inte förbise något externt beroende utanför Paperless-containern.

• Inventering: Image/commit, Django-/Angular-applikation, worker, scheduler, broker, databas, Tika/Gotenberg, proxy och mountar.
• Dataobjekt: Nämn databas, original, arkiv, miniatyrbild, index, konfiguration, hemligheter och exportmanifest separat.
• Ingångar: Dokumentera Consume, uppladdning/API och e-post med regler för storlek, typ, autentisering och fel.
• Pipeline: Korrelera task-ID genom parser, OCR, arkivering, metadata och index fram till avslut.
• Behörigheter: Testa globala och objektbaserade rättigheter, superusers, grupper och arbetsflödestilldelningar.
• Kapacitet: Övervaka köålder, OCR-körtid, temporärt utrymme, Media-/indextillväxt och databasanslutningar.
• Säkerhet: Inkludera HTTPS, proxyförtroende, Secret Key, token, klartextlagring och externa parser i hotmodellen.
• Backup: Säkerhetskopiera databas och Media konsekvent; glöm inte konfiguration och hemligheter.
• Restore: Kontrollera tom målinstans, lämplig version, stickprov, sökning, Sanity Checker och ny Consume-körning.
• Ändring: Dokumentera release notes, schema-/indexmigrering, ledigt utrymme och faktisk rollbackgräns i förväg.

Källor

• Paperless-ngx – dokumentation
• Paperless-ngx – GitHub-repository
• Paperless-ngx – utveckling
• Paperless-ngx – användning
• Celery
• Paperless-ngx – Python-projektmanifest
• Paperless-ngx – Dockerfile
• Paperless-ngx – konfiguration
• Redis-kompatibel broker
• PostgreSQL
• Paperless-ngx – installation
• Docker – compose config
• Docker – compose ps
• Docker – compose images
• Docker – inspect
• Paperless-ngx – FAQ
• Paperless-ngx – Consume Hooks
• OCRmyPDF – dokumentation
• Tesseract – dokumentation
• 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 – handbok
• Microsoft – Resolve-DnsName
• Linux man-pages – getent(1)
• Docker – compose port
• Paperless-ngx – REST-API
• RFC 9051 – IMAP4rev2
• Apache Tika – serverdrift
• Gotenberg – konfiguration
• Docker – stats
• Docker – system df
• Microsoft – Get-FileHash
• GNU Coreutils – sha2 utilities
• Paperless-ngx – Changelog
• Paperless-ngx – felsökning