Herstelgereedheid

Libre WebUI biedt als eerste veiligheidspoort voor back-up en herstel een alleen-lezen herstelinventaris. Deze meldt welke bekende status bestaat en welke gedetecteerde omstandigheden een momentopname blokkeren. De inventaris verkrijgt geen onderhoudsvergrendeling en kopieert, versleutelt, uploadt, verwijdert, herstelt of repareert geen gegevens.

libre-webui recovery-check --json > recovery-inventory.json

Voer vanuit een broncheckout eenmaal npm run build:backend uit en vervang libre-webui recovery-check door npm run recovery:check --. Verpakte npx- en Homebrew-installaties onderzoeken standaard ~/.libre-webui; DATA_DIR en expliciete padopties overschrijven die locatie.

De opdracht sluit af met status 0 wanneer geen blokkerende problemen zijn gevonden, 1 wanneer het rapport volledig is maar herstelblokkades bestaan, en 2 bij ongeldige argumenten of een onverwachte verzamelfout. Gebruik --data-dir PATH of --database PATH om een niet-standaardlocatie te onderzoeken. Een standaard- of --data-dir-volume-inventaris accepteert alleen het canonieke bestand DATA_DIR/data.sqlite en weigert hardgekoppelde, symbolisch gekoppelde of niet-reguliere database-/WAL-/SHM-vermeldingen. Een expliciet pad --database mag buiten DATA_DIR liggen, maar de gekozen database en alle bijbehorende bestanden moeten nog steeds reguliere bestanden zijn en mogen geen symbolische koppelingen zijn. Wanneer --database zonder --data-dir wordt gebruikt, behandelt herstel de bovenliggende map van de database als gegevenshoofdmap, zodat de overeenkomende sleutel, blobs en plug-indefinities samen worden geïnventariseerd.

De runtime leest ook historische plug-indefinities uit de deterministische map plugins van het backendpakket en, bij een relatieve PLUGINS_DIR, uit de historische locatie relatief aan de backend. Herstel inventariseert deze actieve verouderde paden en blokkeert een momentopname van alleen het volume wanneer ze aangepaste definities bevatten. Verpakte implementaties kunnen --legacy-plugins-dir PATH meermaals doorgeven wanneer hun image-indeling die compatibiliteitsmappen verplaatst.

Voer de opdracht voor de besloten Compose-implementatie binnen de geïmplementeerde container uit, zodat het rapport het gekoppelde volume, de code en de geheimen van die container beschrijft:

docker exec libre-webui \
  libre-webui recovery-check --json --data-dir /app/backend/data

Wat de inventaris controleert

Het geversioneerde JSON-rapport registreert:

• versies van applicatie, Node.js, besturingssysteem en architectuur;
• grootte van het SQLite-bestand en WAL/SHM, quick_check, controle van vreemde sleutels, schemavingerafdruk, gebruikersversie, ontbrekende vereiste tabellen en bronbestandsvalidatie zonder volgen voordat een particuliere inspectiemomentopname wordt gemaakt;
• leesbaarheid, schrijfbaarheid, aantal bestanden en aantal bytes van de gegevensmap;
• de gekozen bron van de versleutelingssleutel en een eenrichtingsvingerafdruk van 16 tekens;
• validatie zonder volgen en met één koppeling voor het permanente bestand .encryption_key;
• aanwezigheid, aantallen, grootten en opname in de gegevensmap van aangepaste plug-indefinities, plus de versleutelde lokale blobhoofdmap, ingebedde media, stemreferenties, documenttekst, verouderde documentvectoren en platformvectoren met hun ACL-/filterrijen;
• begrensde, alleen-lezen authenticatie van elk canoniek lokaal blobobject en elke ingebedde envelop voor platformvectoren, inclusief volledige controle van blobdelen/checksums en beschikbaarheid van de geconfigureerde sleutel;
• begrensde, alleen-lezen authenticatie van elke herkenbare verouderde AES-GCM-tekstenvelop in chats, notities, documenten, voorkeuren, plug-ingeheimen, galerij-/mediastatus en account-e-mail, plus elke met AAD gebonden envelop voor opgeslagen stemnaam, opname en transcriptie;
• aantallen Work-taken/-uitvoeringen/-voorbeelden en de verwachte Docker-volumes, Kubernetes-PVC's of gehashte hostpadidentiteiten; Docker-volumes moeten zowel het beheerde label als de exacte ID van de eigenaars-taak bevatten;
• statussen van verouderde mediageneratietaken plus duurzame taken per status, pogingen per uitkomst, aantallen gebeurtenisstromen/-gebeurtenissen en de laatste algemene gebeurteniscursor;
• begrensde, alleen-lezen authenticatie van elke versleutelde duurzame taak- en gebeurtenispayload, plus begrensde syntaxisvalidatie van elke ondoorzichtige referentiepayload; en
• expliciete blokkades, waarschuwingen en gegevens die buiten de applicatiegegevensmap staan.

Het rapport bevat nooit versleutelingssleutels, JWT-/sessiegeheimen, providerreferenties, plug-ininhoud, gebruikersinhoud of letterlijke hostwerkruimtepaden. Alleen booleans die de aanwezigheid van geheimen aangeven en de niet-omkeerbare vingerafdruk van de versleutelingssleutel worden uitgevoerd.

Een alleen-lezen gegevenskoppeling is geldig voor herstelinspectie en levert een waarschuwing op, geen blokkade. De applicatie vereist voor gereedheid nog steeds schrijfbare opslag; start Libre WebUI nooit tegen de alleen-lezen momentopname die de back-uphelper gebruikt.

Blokkades

Behandel elke blokkade als een mislukte herstelpoort. Gebruikelijke blokkades zijn een ontbrekende of beschadigde database, een onvolledig schema, een ontbrekende/conflicterende sleutel, beschadigde of niet-geauthenticeerde verouderde of platformciphertekst, overschreden controlegrenzen, een onleesbare gegevensmap, een gekoppelde of niet-reguliere SQLite-bron, actieve Work-uitvoeringen of -voorbeelden, mediataken of duurzame taken, een ontbrekende of onjuist gelabelde Work-werkruimte, afwijkende koppen of volgordegaten in duurzame gebeurtenissen, aangepaste plug-indefinities buiten de gegevensmap of een runtimebesturingsvlak dat externe werkruimten niet kan controleren. Breng actief werk tot rust en los ontbrekende afhankelijkheden op voordat u de momentopname maakt; bewerk het rapport niet om een blokkade te verbergen.

Versleutelde duurzame payloads worden tegen hun taak-/gebeurtenisidentiteit geauthenticeerd en als canonieke begrensde JSON gevalideerd. Ondoorzichtige referentiepayloads worden alleen begrensd en op syntaxis gecontroleerd: het huidige substraat heeft geen gezaghebbende blobreferentierepository waarmee herstel het bestaan van een doel of de toegang ertoe kan bewijzen. Het rapport markeert referenceTargetsVerified als false en waarschuwt telkens wanneer zulke referenties aanwezig zijn; het stelt payload- of referentiewaarden nooit beschikbaar.

Verouderde tekstvelden stammen van vóór een verplichte envelopmarkering. Echte plattetekstrijen uit oudere schemageneraties blijven daarom leesbaar en worden niet als geauthenticeerde ciphertekst gemeld. Canonieke enveloppen worden altijd geauthenticeerd; driedelige waarden met een IV of authenticatietag ter breedte van een envelop worden bij misvorming gesloten geweigerd. Opgeslagen stemvelden hebben een ondubbelzinnige binaire envelop en moeten altijd tegen hun profiel-, eigenaar- en veldidentiteit worden geauthenticeerd. De JSON-sectie encryption.legacyCiphertext rapporteert totalen van geauthenticeerde tekst-/binaire records en bytes zonder platte tekst beschikbaar te stellen.

Wanneer de kolom users.email_lookup van schema v4 aanwezig is, authenticeert herstel ook elke niet-null-e-mail en berekent het bijbehorende domeingescheiden sleutelgebonden zoektoken opnieuw. Een ontbrekend of afwijkend token, of een token bij een null-e-mail, blokkeert de momentopname. Databases van vóór v4 blijven compatibel omdat ze deze afgeleide zoekkolom niet hebben.

Huidige back-upgrens

De helper voor besloten implementatie stopt de applicatie als die actief was en gebruikt de onveranderlijke image, het gekoppelde gegevensvolume en de omgeving van die container om een geïntegreerd soloarchief te maken. Het manifest wordt met Ed25519 ondertekend en de volledige payload wordt versleuteld met een door de beheerder bewaarde AES-256-GCM-back-upsleutel. Het bevat SQLite, lokale blobs en ingebedde vectoren, runtimekiezers en de beschermde configuratie die nodig is om herstelde status te ontsleutelen. De helper controleert de handtekening, ciphertekstchecksum en ontsleutelde payload voordat het archief en metadatarapport worden gepubliceerd. libre-webui-restore accepteert alleen een nieuw Docker-volume, controleert de ontsleutelde herstelinventaris voordat gegevens worden gekopieerd en publiceert herstelde configuratie als privébestanden in een nieuwe doelmap.

Beschermde runtimeconfiguratie omvat de PostgreSQL-pool, verbindings-, inactiviteits-, statement- en migratievergrendelingstime-outs; de Redis-verbindingstime-out; beide duurzame blobquotuminstellingen; de platformkiezers; en het S3-voorvoegsel en de adresseringsmodus. Deze waarden staan in de ondertekende en versleutelde payload, niet in het plattetekstmanifest, en worden bij een toegepast herstel als configuratie in modus 0600 opnieuw gepubliceerd.

Het soloarchief bevat geen Docker Work-volumes, Kubernetes-PVC's, hostgebonden werkruimtemappen, Ollama-modellen of externe providerstatus. Houd die uitsluitingen uit het ondertekende manifest zichtbaar en maak afzonderlijk momentopnamen van externe Work-opslag. Het teamprofiel gebruikt de afzonderlijke offline teamworkflow: een geëxporteerde PostgreSQL-momentopname, exacte geversioneerde S3-ciphertekstobjecten, PGVector-inventaris, runtimeconfiguratie en sleutelidentiteit worden in dezelfde ondertekende/versleutelde archiefindeling verzegeld en tijdens herstel tegen een schoon PostgreSQL-/S3-doel gecontroleerd. Redis-cache, aanwezigheid, wake-ups en leases worden vanuit canonieke SQL-status opnieuw opgebouwd.

Teamback-up authenticeert ook elke begrensde versleutelde duurzame taak- en gebeurtenispayload in de exacte geëxporteerde PostgreSQL-momentopname. De beschermde ondertekende inventaris registreert de totalen voor taken, gebeurtenissen, stromen, cursors, enveloppen, referenties en geauthenticeerde platte tekst. Elke gebeurtenisstroom moet exact de aaneengesloten reeks 1..last_sequence bevatten en de algemene cursorreeks van PostgreSQL mag niet achterlopen op de hoogste opgeslagen cursor. Herstel herhaalt deze controles tegen het schone doel en vereist dat het volledige resultaat met de ondertekende broninventaris overeenkomt voordat succes wordt gemeld. Gaten tussen afzonderlijke algemene cursorwaarden zijn geldig omdat identiteitsallocatie in PostgreSQL niet transactioneel is; reeksen per stroom vormen het aaneengesloten ordeningscontract.

Wanneer PLUGINS_DIR buiten DATA_DIR wijst, inventariseert herstel die exacte map en markeert haar als uitgesloten van het applicatievolumearchief. Alle definities daar blokkeren de momentopname van alleen het volume totdat de beheerder een overeenkomende momentopname van de plug-inmap regelt. Dezelfde regel geldt voor actieve verouderde plug-inmappen. Symbolisch gekoppelde, niet-reguliere of onleesbare JSON-definities zijn altijd blokkades en worden nooit gevolgd of stilzwijgend weggelaten.

Duurzame taken en geordende gebeurtenissen zijn in beide profielen actief. Herstel blokkeert terwijl een taakpoging of Work-uitvoering actief is, valideert taak-/gebeurtenispayloads en aaneengesloten stroomkoppen en bewaart hun canonieke SQL-status. Solo voert de begrensde ingebedde worker uit; team voert dezelfde geregistreerde handlers in een externe worker uit en gebruikt Redis alleen voor wake-up en fan-out.

Bewaar versleutelings- en JWT-geheimen voor productie in een beschermde geheimenbeheeroplossing, houd back-uparchieven versleuteld buiten de host en test herstelacties in een schone compatibele omgeving. De inventaris is een voorafgaande momentopname van bekende status, geen onderhoudsvergrendeling of onafhankelijk bewijs dat elke externe resource kan worden hersteld.

Opdrachten voor ondertekende en versleutelde back-ups

De onderstaande voorbeelden gebruiken de geïnstalleerde opdracht libre-webui uit algemene npm of Homebrew. Vervang zonder algemene installatie libre-webui door npx --yes libre-webui@latest. Bouw vanuit een broncheckout de backend eenmaal en vervang libre-webui backup door npm run recovery:backup --. De productie-Docker-image biedt dezelfde opdracht via /usr/local/bin/libre-webui. Teamback-up en -herstel vereisen daarnaast pg_dump en pg_restore van PostgreSQL 16; deze zijn opgenomen in de productie-image en op het opdrachtpad van de Homebrew-formule. Installeer expliciet een compatibele PostgreSQL-client voordat u deze opdrachten vanuit gewone npm/npx gebruikt.

Genereer de door de beheerder bewaarde AES-256-GCM-archiefsleutel en het Ed25519-ondertekeningssleutelpaar in een privémap en verplaats daarna de privésleutels naar beschermde opslag buiten de host:

install -d -m 0700 /absolute/private/libre-backup-keys
libre-webui backup keygen \
  --directory /absolute/private/libre-backup-keys

Maak voor een tot rust gebrachte solo-gegevensmap een archief en controleer het onafhankelijk:

libre-webui backup create \
  --offline \
  --data-dir /absolute/path/to/libre-data \
  --output /absolute/backups/libre-solo.lwbackup \
  --encryption-key /absolute/private/libre-backup-keys/backup-encryption.key \
  --signing-private-key /absolute/private/libre-backup-keys/backup-signing-private.pem

libre-webui backup verify \
  --archive /absolute/backups/libre-solo.lwbackup \
  --encryption-key /absolute/private/libre-backup-keys/backup-encryption.key \
  --signing-public-key /absolute/private/libre-backup-keys/backup-signing-public.pem

Voer herstel eerst als voorafgaande controle uit en pas het daarna uitsluitend toe op een nieuwe, lege doelmap:

libre-webui backup restore-preflight \
  --archive /absolute/backups/libre-solo.lwbackup \
  --target /absolute/restore/libre-data \
  --encryption-key /absolute/private/libre-backup-keys/backup-encryption.key \
  --signing-public-key /absolute/private/libre-backup-keys/backup-signing-public.pem

libre-webui backup restore-apply \
  --archive /absolute/backups/libre-solo.lwbackup \
  --target /absolute/restore/libre-data \
  --encryption-key /absolute/private/libre-backup-keys/backup-encryption.key \
  --signing-public-key /absolute/private/libre-backup-keys/backup-signing-public.pem

libre-webui backup restore-verify \
  --target /absolute/restore/libre-data

Stop voor teammodus alle applicatiereplica's en workers, houd de PostgreSQL-/S3-/sleutelringomgeving van de bron geladen en maak het gecoördineerde archief:

libre-webui backup create-team \
  --offline \
  --output /absolute/backups/libre-team.lwbackup \
  --encryption-key /absolute/private/libre-backup-keys/backup-encryption.key \
  --signing-private-key /absolute/private/libre-backup-keys/backup-signing-private.pem

Laad vóór herstel omgevingsvariabelen voor een afzonderlijke, lege PostgreSQL-database en een lege geversioneerde S3-bucket. De voorafgaande controle verifieert de handtekening en het versleutelde archief, valideert de beschermde inventaris en bewijst dat de gekozen doeldatabase en het bucketvoorvoegsel leeg zijn, zonder gegevens te publiceren. Toepassen herstelt naar die schone doelen, controleert het resulterende PostgreSQL-schema, de exacte S3-objecten en PGVector-records en schrijft de beschermde runtimeconfiguratie naar een nieuwe privémap:

libre-webui backup restore-team-preflight \
  --archive /absolute/backups/libre-team.lwbackup \
  --encryption-key /absolute/private/libre-backup-keys/backup-encryption.key \
  --signing-public-key /absolute/private/libre-backup-keys/backup-signing-public.pem

libre-webui backup restore-team-apply \
  --archive /absolute/backups/libre-team.lwbackup \
  --configuration-output /absolute/restore/libre-team-config \
  --encryption-key /absolute/private/libre-backup-keys/backup-encryption.key \
  --signing-public-key /absolute/private/libre-backup-keys/backup-signing-public.pem

Richt herstel nooit op de brondatabase, bronbucket, een bestaande gegevensmap of een configuratiemap met bestanden. Bewaar de openbare ondertekeningssleutel bij het hersteldraaiboek; bezit van alleen het archief en de openbare sleutel kan de payload niet ontsleutelen.

Als teamherstel meldt dat terugdraaien onvolledig was, behandelt u beide gekozen doelen als vervuild en probeert u niet onmiddellijk opnieuw. Onderzoek en wis de PostgreSQL-doeldatabase en som daarna elke objectversie en verwijdermarkering onder het exacte S3-doelvoorvoegsel op en verwijder deze. Voer restore-team-preflight opnieuw uit; toepassen kan pas veilig opnieuw worden geprobeerd nadat die voorafgaande controle voor schone doelen slaagt.

Geplande geverifieerde hersteloefeningen

Back-ups die nooit zijn hersteld, zijn hoop en geen herstel. Een oefening bewijst dat de instantie echt herstelbaar is door de exacte bovenstaande pijplijn van begin tot eind uit te voeren, zonder uitvaltijd en zonder beheerder:

1. Een momentopname van de tot rust gebrachte gegevensmap wordt voorbereid: de SQLite-database via de online back-up-API, blobs en bestanden via een fysieke kopie. De oefening wacht op een rustig moment en weigert te draaien wanneer een duurzame taak bezig is, dezelfde regel die recovery-check afdwingt.
2. De voorbereide kopie wordt een ondertekend, met AES-256-GCM versleuteld archief met tijdelijke oefensleutels en voert de volledige herstelinventaris uit.
3. Het archief wordt gecontroleerd, naar een geïsoleerd tijdelijk doel hersteld en de herstelde omgeving wordt opnieuw gecontroleerd.
4. De oefening registreert wat is gemeten: de herstelduur is de aangetoonde RTO en de afstand tussen geslaagde oefeningen begrenst de haalbare RPO van de huidige planning. Daarna worden alle artefacten verwijderd. Oefeningen zijn verificatie, geen back-ups: er wordt geen archief of sleutel bewaard.

Schakel de planning in met RECOVERY_DRILL_INTERVAL_HOURS (bijvoorbeeld 24); oefeningen draaien dan op de gedeelde scheduler onder een coördinatorlease, zodat replica's en overlappende tikken geen dubbele uitvoering kunnen starten. De pagina System toont de oefengeschiedenis met een knop "Run drill now" voor beheerders, ondersteund door GET /api/recovery/drills en POST /api/recovery/drills/run. Een oefening die onbeheerd mislukt, waarschuwt elke beheerder via het meldingenpostvak (en alle geabonneerde webhookdoelen); handmatige uitvoeringen melden hun weigering daarentegen rechtstreeks. RECOVERY_DRILL_HISTORY begrenst de bewaarde geschiedenis (standaard 60 vermeldingen).

Oefeningen dekken het soloprofiel (SQLite), waarin het bestandssysteemarchief het gezaghebbende back-uppad is. Het teamprofiel behoudt de gecoördineerde stroom backup create-team; de hersteloefening daarvan blijft voorlopig een stap in het beheerdersdraaiboek.