Gendannelsesberedskab
Libre WebUI har en skrivebeskyttet gendannelsesopgørelse som første sikkerhedsgate for backup og gendannelse. Den rapporterer, hvilken kendt tilstand der findes, og hvilke fundne forhold der blokerer et snapshot. Den tager ingen vedligeholdelseslås og kopierer, krypterer, uploader, sletter, reparerer eller gendanner ikke data.
libre-webui recovery-check --json > recovery-inventory.json
Fra en kildekode-checkout kører du npm run build:backend én gang og erstatter libre-webui recovery-check med npm run recovery:check --. Pakkede installationer via npx og Homebrew inspicerer som standard ~/.libre-webui; DATA_DIR og eksplicitte stiindstillinger tilsidesætter den placering.
Kommandoen afslutter med status 0, når der ikke findes blokeringer, 1, når rapporten er komplet, men der findes blokeringer for gendannelse, og 2 ved ugyldige argumenter eller en uventet fejl under indsamlingen. Brug --data-dir PATH eller --database PATH til at inspicere en anden placering end standarden. En standardopgørelse af en diskenhed eller en opgørelse med --data-dir accepterer kun den kanoniske fil DATA_DIR/data.sqlite og afviser database-, WAL- og SHM-poster, der er hårde links eller symlinks eller ikke er almindelige filer. En eksplicit --database-sti må ligge uden for DATA_DIR, men den valgte database og eventuelle tilhørende filer skal stadig være almindelige filer og må ikke være symlinks. Når --database bruges uden --data-dir, behandler gendannelsen databasens overordnede mappe som datarod, så den tilhørende nøgle, blobs og plugin-definitioner opgøres samlet.
Runtime læser også historiske plugin-definitioner fra den deterministiske plugins-mappe i backendpakken og, for en relativ PLUGINS_DIR, fra dens historiske placering i forhold til backend. Gendannelsen opgør disse aktive legacy-stier og blokerer et snapshot, der kun omfatter diskenheden, når de indeholder tilpassede definitioner. Pakkede installationer kan angive --legacy-plugins-dir PATH flere gange, når deres image-layout flytter disse kompatibilitetsmapper.
For den private Compose-installation kører du kommandoen inde i den udrullede container, så rapporten beskriver containerens monterede diskenhed, kode og hemmeligheder:
docker exec libre-webui \
libre-webui recovery-check --json --data-dir /app/backend/data
Hvad opgørelsen kontrollerer
Den versionerede JSON-rapport registrerer:
- versioner af programmet, Node.js, operativsystemet og arkitekturen;
- størrelser på SQLite-filen og WAL/SHM,
quick_check, validering af fremmednøgler, skemafingeraftryk, user version, manglende påkrævede tabeller og no-follow-validering af kildefiler, før et privat inspektionssnapshot oprettes; - datamappens læsbarhed og skrivbarhed samt antal filer og bytes;
- den valgte kilde til krypteringsnøglen og et envejsfingeraftryk på 16 tegn;
- no-follow-validering med ét link for den vedvarende fil
.encryption_key; - tilstedeværelse, antal, størrelser og placering i datamappen for tilpassede plugin-definitioner samt den krypterede lokale blobrod, indlejrede medier, stemmereferencer, dokumenttekst, legacy-dokumentvektorer og platformsvektorer med deres ACL- og filterrækker;
- begrænset, skrivebeskyttet autentificering af hvert kanonisk lokalt blobobjekt og hver envelope for indlejrede platformsvektorer, herunder fuld verifikation af blobchunks og checksummer og kontrol af, at de konfigurerede nøgler er tilgængelige;
- begrænset, skrivebeskyttet autentificering af hver genkendelig legacy-AES-GCM-tekstenvelope i chats, noter, dokumenter, præferencer, plugin-hemmeligheder, galleri- og medietilstand og kontoens e-mail samt hver AAD-bundet envelope for navn, optagelse og transskription af gemte stemmer;
- antal Work-opgaver, -kørsler og -forhåndsvisninger og de forventede Docker-diskenheder, Kubernetes-PVC'er eller hashede identiteter for værtsstier; Docker-diskenheder skal have både den administrerede etiket og det præcise ID på den opgave, der ejer dem;
- tilstande for legacy-jobs til mediegenerering samt vedvarende jobs efter tilstand, forsøg efter udfald, antal event-streams og events og den seneste globale eventcursor;
- begrænset, skrivebeskyttet autentificering af hver krypteret payload for vedvarende jobs og events samt begrænset syntaksvalidering af hver uigennemsigtig referencepayload; og
- eksplicitte blokeringer, advarsler og data, der ligger uden for programmets datamappe.
Rapporten indeholder aldrig krypteringsnøgler, JWT-/sessionshemmeligheder, legitimationsoplysninger til udbydere, plugin-indhold, brugerindhold eller faktiske stier til arbejdsområder på værten. Der udsendes kun booleske værdier for, om hemmeligheder findes, og det ikke-reversible fingeraftryk af krypteringsnøglen.
En skrivebeskyttet datamontering er gyldig til gendannelsesinspektion og giver en advarsel, ikke en blokering. Programmets readiness kræver stadig skrivbar lagring; start aldrig Libre WebUI mod det skrivebeskyttede snapshot, som backuphjælperen bruger.
Blokeringer
Betragt enhver blokering som en mislykket gendannelsesgate. Typiske blokeringer er en manglende eller beskadiget database, et ufuldstændigt skema, en manglende eller modstridende nøgle, beskadiget eller ikke-autentificeret legacy- eller platformschiffertekst, overskredne verifikationsgrænser, en ulæselig datamappe, en SQLite-kilde, der er linket eller ikke er en almindelig fil, aktive Work-kørsler eller forhåndsvisninger, mediejobs eller vedvarende jobs, et manglende eller forkert mærket Work-arbejdsområde, uoverensstemmelser i hoveder for vedvarende events eller huller i sekvenser, tilpassede plugin-definitioner uden for datamappen eller et runtime-kontrolplan, der ikke kan verificere eksterne arbejdsområder. Stop aktivt arbejde, og løs manglende afhængigheder, før du tager snapshottet; redigér ikke rapporten for at skjule en blokering.
Krypterede vedvarende payloads autentificeres mod deres job- eller eventidentitet og valideres som kanonisk, begrænset JSON. Uigennemsigtige referencepayloads bliver kun størrelsesbegrænset og syntakskontrolleret: det nuværende fundament har intet autoritativt repository for blobreferencer, som gendannelsen kan bruge til at bevise, at målet findes eller er tilgængeligt. Rapporten sætter referenceTargetsVerified til false og advarer, når sådanne referencer findes; den viser aldrig payload- eller referenceværdier.
Legacy-tekstfelter er ældre end en obligatorisk envelope-markør, så ægte klartekstrækker fra ældre skemagenerationer forbliver læsbare og rapporteres ikke som autentificeret chiffertekst. Kanoniske envelopes autentificeres altid; tredelte værdier med en IV eller et autentificeringstag i envelope-bredde fejler lukket, hvis de er misdannede. Felter for gemte stemmer har en entydig binær envelope og skal altid autentificeres mod deres profil-, ejer- og feltidentitet. JSON-sektionen encryption.legacyCiphertext rapporterer totaler for autentificerede tekst- og binærposter og bytes uden at vise klartekst.
Når skema v4's kolonne users.email_lookup findes, autentificerer gendannelsen også hver e-mail, der ikke er null, og beregner dens domæneadskilte, nøglebaserede opslagstoken igen. Et manglende eller uoverensstemmende token eller et token knyttet til en e-mail, der er null, blokerer snapshottet. Databaser fra før v4 forbliver kompatible, fordi de ikke har denne afledte opslagskolonne.
Nuværende backupgrænse
Hjælpeværktøjet til den private installation stopper programmet, hvis det kørte, og bruger containerens uforanderlige image, monterede datadiskenhed og miljø til at oprette et integreret soloarkiv. Manifestet er signeret med Ed25519, og hele payloaden er krypteret med en AES-256-GCM-backupnøgle, som operatøren har. Arkivet indeholder SQLite, lokale blobs og indlejrede vektorer, runtimevalg og den beskyttede konfiguration, der skal til for at dekryptere den gendannede tilstand. Hjælpeværktøjet verificerer signaturen, chiffertekstens checksum og den dekrypterede payload, før arkivet og metadatarapporten udgives. libre-webui-restore accepterer kun en ny Docker-diskenhed, verificerer den dekrypterede gendannelsesopgørelse, før der kopieres data, og udgiver den gendannede konfiguration som private filer i en ny målmappe.
Den beskyttede runtimekonfiguration omfatter PostgreSQL-timeouts for pool, forbindelse, inaktivitet, sætninger og migreringslås, Redis-forbindelsestimeouten, begge indstillinger for vedvarende blobkvoter, platformsvalgene samt S3-præfiks og adresseringstilstand. Disse værdier ligger i den signerede og krypterede payload, ikke i manifestet i klartekst, og udgives igen som konfiguration med tilstand 0600 ved en anvendt gendannelse.
Soloarkivet omfatter ikke Docker Work-diskenheder, Kubernetes-PVC'er, arbejdsområdemapper bundet til værten, Ollama-modeller eller tilstand hos eksterne udbydere. Hold disse undtagelser i det signerede manifest synlige, og tag snapshots af ekstern Work-lagring separat. Teamprofilen bruger det separate offline-flow for team: et eksporteret PostgreSQL-snapshot, præcist versionerede S3-chiffertekstobjekter, PGVector-opgørelse, runtimekonfiguration og nøgleidentitet forsegles i samme signerede og krypterede arkivformat og verificeres mod et rent PostgreSQL/S3-mål under gendannelsen. Redis-cache, presence, wake-ups og leases genopbygges fra den kanoniske SQL-tilstand.
Teambackup autentificerer også hver begrænset krypteret payload for vedvarende jobs og events i det præcise eksporterede PostgreSQL-snapshot. Dens beskyttede, signerede opgørelse registrerer totaler for jobs, events, streams, cursorer, envelopes, referencer og autentificeret klartekst. Hver event-stream skal indeholde præcis den sammenhængende sekvens 1..last_sequence, og PostgreSQL's globale cursorsekvens må ikke ligge efter den største gemte cursor. Gendannelsen gentager disse kontroller mod det rene mål og kræver, at hele resultatet matcher den signerede kildeopgørelse, før den melder succes. Huller mellem forskellige globale cursorværdier er gyldige, fordi PostgreSQL's identitetsallokering ikke er transaktionel; sekvenserne pr. stream er kontrakten for sammenhængende rækkefølge.
Når PLUGINS_DIR peger uden for DATA_DIR, opgør gendannelsen præcis den mappe og markerer den som udeladt fra arkivet over programmets diskenhed. Eventuelle definitioner dér blokerer snapshottet af diskenheden, indtil operatøren sørger for et tilsvarende snapshot af plugin-mappen. Samme regel gælder for aktive legacy-plugin-mapper. JSON-definitioner, der er symlinks, ikke er almindelige filer eller ikke kan læses, er altid blokeringer og bliver aldrig fulgt eller stiltiende udeladt.
Vedvarende jobs og ordnede events er aktive i begge profiler. Gendannelsen blokerer, mens et jobforsøg eller en Work-kørsel er aktiv, validerer job- og eventpayloads og sammenhængende stream-hoveder og bevarer deres kanoniske SQL-tilstand. Solo kører den begrænsede indlejrede worker; team kører de samme registrerede handlers i en ekstern worker og bruger kun Redis til vækning og fan-out.
Til produktion skal krypterings- og JWT-hemmeligheder gemmes i en beskyttet secret manager, backuparkiver skal opbevares krypteret uden for værten, og gendannelser skal testes i et rent, kompatibelt miljø. Opgørelsen er et preflight-snapshot af kendt tilstand, ikke en vedligeholdelseslås eller et uafhængigt bevis for, at alle eksterne ressourcer kan gendannes.
Signerede og krypterede backupkommandoer
Eksemplerne nedenfor bruger den installerede libre-webui-kommando fra global npm eller Homebrew. Uden global installation erstatter du libre-webui med npx --yes libre-webui@latest. Fra en kildekode-checkout bygger du backend én gang og erstatter libre-webui backup med npm run recovery:backup --. Docker-produktionsimaget har samme kommando i /usr/local/bin/libre-webui. Teambackup og -gendannelse kræver desuden PostgreSQL 16 pg_dump og pg_restore; de følger med produktionsimaget og ligger på kommandostien for Homebrew-formlen. Installér eksplicit en kompatibel PostgreSQL-klient, før du bruger disse kommandoer fra almindelig npm/npx.
Generér operatørens AES-256-GCM-arkivnøgle og Ed25519-signeringsnøglepar i en privat mappe, og flyt derefter de private nøgler til beskyttet lagring uden for værten:
install -d -m 0700 /absolute/private/libre-backup-keys
libre-webui backup keygen \
--directory /absolute/private/libre-backup-keys
For en solo-datamappe uden aktivitet opretter du et arkiv og verificerer det uafhængigt:
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
Gendan først som preflight, og anvend derefter kun på en ny, tom målmappe:
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
I teamtilstand stopper du alle programreplikaer og workers, holder kildens miljø for PostgreSQL, S3 og nøglering indlæst og opretter det koordinerede arkiv:
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
Indlæs miljøvariabler for en separat, tom PostgreSQL-database og en tom versioneret S3-bucket før gendannelsen. Preflight verificerer signaturen og det krypterede arkiv, validerer den beskyttede opgørelse og beviser, at den valgte måldatabase og det valgte bucket-præfiks er tomme, uden at udgive data. Apply gendanner til disse rene mål, verificerer det resulterende PostgreSQL-skema, de præcise S3-objekter og PGVector-posterne og skriver den beskyttede runtimekonfiguration til en ny privat mappe:
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
Peg aldrig en gendannelse mod kildedatabasen, kilde-bucketen, en eksisterende datamappe eller en konfigurationsmappe, der indeholder filer. Opbevar den offentlige signeringsnøgle sammen med runbooken for gendannelse; arkivet og den offentlige nøgle alene kan ikke dekryptere payloaden.
Hvis teamgendannelsen rapporterer, at rollback var ufuldstændig, skal begge valgte mål betragtes som urene, og du må ikke prøve igen med det samme. Inspicér og ryd måldatabasen i PostgreSQL, og find og fjern derefter hver objektversion og hver delete marker under det præcise S3-målpræfiks. Kør restore-team-preflight igen; apply er først sikker at prøve igen, når denne preflight af et rent mål lykkes.
Planlagte, verificerede gendannelsesøvelser
Backups, der aldrig er blevet gendannet, er håb, ikke gendannelse. En øvelse beviser, at instansen faktisk kan gendannes, ved at køre præcis den pipeline, der er beskrevet ovenfor, fra start til slut, uden nedetid og uden en operatør:
- Et snapshot af datamappen i hvile klargøres: SQLite-databasen via online-backup-API'et, blobs og filer ved fysisk kopiering. Øvelsen venter på et roligt øjeblik: den nægter at køre, mens et vedvarende job er i gang, efter samme regel som
recovery-checkhåndhæver. - Den klargjorte kopi bliver til et signeret, AES-256-GCM-krypteret arkiv med midlertidige øvelsesnøgler, og den komplette gendannelsesopgørelse køres.
- Arkivet verificeres og gendannes til et isoleret midlertidigt mål, og det gendannede miljø verificeres igen.
- Øvelsen registrerer, hvad den målte: gendannelsestiden er den demonstrerede RTO, og afstanden mellem vellykkede øvelser begrænser den opnåelige RPO for den aktuelle tidsplan. Derefter sletter den alle artefakter. Øvelser er verifikation, ikke backups: intet arkiv og ingen nøgle bevares.
Aktivér tidsplanen med RECOVERY_DRILL_INTERVAL_HOURS (for eksempel 24); øvelserne kører så på den delte planlægger under en coordinator-lease, så replikaer og overlappende planlægningsrunder ikke kan køre samme øvelse to gange. Siden System viser øvelseshistorikken med knappen "Kør øvelse nu" for administratorer, understøttet af GET /api/recovery/drills og POST /api/recovery/drills/run. En øvelse, der fejler uden opsyn, advarer alle administratorer via notifikationsindbakken (og eventuelle abonnerede webhook-mål); manuelle kørsler rapporterer i stedet afvisningen direkte. RECOVERY_DRILL_HISTORY begrænser den bevarede historik (standard 60 poster).
Øvelser dækker soloprofilen (SQLite), hvor filsystemarkivet er den autoritative backupvej. Teamprofilen beholder sit koordinerede backup create-team-flow, hvor øvelse af gendannelsen indtil videre forbliver et trin i operatørens runbook.