Back-ups, herstel en beheer op Unraid

Deze gids beschrijft de M7-functionaliteit: back-ups maken, een back-up herstellen naar een schone omgeving, en de operationele controles rond een Unraid-implementatie. Geschreven voor beheerders/operators, niet voor eindgebruikers. Er is bewust geen scherm in de webapplicatie voor back-upbeheer — dit gebeurt via de API (back-up maken/ lijst tonen) en via een aparte opdrachtregelmodus van dezelfde container-image (herstellen), nooit via een knop in de draaiende applicatie zelf.

Een back-up maken

curl -X POST https://hub.example/api/v1/admin/backups \
  -H "X-CSRF-Token: <csrf-token-van-huidige-sessie>" -b cookies.txt

Dit maakt synchroon een volledige back-up: elke databasetabel (via een schema- onafhankelijke binaire kopie, geen externe pg_dump-tool nodig) plus elk content-adresseerbare bijlagebestand, met een manifest.json dat per bestand een SHA-256-hash bevat. Elk bestand wordt na het schrijven opnieuw gehasht en vergeleken vóór de back-up zichtbaar wordt — een back-up die deze controle niet doorstaat, wordt nooit gepubliceerd en vervangt dus nooit de laatst bekende goede back-up.

curl https://hub.example/api/v1/admin/backups -b cookies.txt

geeft de lijst van voltooide back-ups terug (nieuwste eerst), met alleen veilige, niet-herleidbare informatie (geen bestandspaden, geen connectiegegevens).

Bewaarbeleid

Standaard worden de 14 nieuwste voltooide back-ups bewaard (instelbaar via KnowledgeHub__Backup__RetainedCount); de allerlaatste back-up wordt nooit verwijderd, ook niet als dat aantal wordt overschreden. Back-ups blijven op dezelfde schijf/pool als de applicatie staan — kopieer ze periodiek naar een onafhankelijke opslaglocatie; een back-up op dezelfde schijf alleen is geen rampenherstel.

Een back-up herstellen

Herstel is bewust nooit bereikbaar via de draaiende applicatie zelf — een draaiende applicatie die tegelijk verkeer verwerkt én haar eigen database overschrijft, is precies het scenario dat vermeden moet worden. In plaats daarvan draait dezelfde image in een aparte, kortstondige opdrachtregelmodus, gericht op een schone doelomgeving (nooit de productie-instantie).

Stap 1 — doeldatabase voorbereiden (alleen migreren)

docker run --rm \
  --network itworx-knowledge-hub_knowledge-hub-internal \
  -e KnowledgeHub__Database__Host=<doel-db-host> \
  -e KnowledgeHub__Database__Name=<doel-db> \
  -e KnowledgeHub__Database__Username=<gebruiker> \
  -e KnowledgeHub__Database__Password=<wachtwoord> \
  itworx/knowledge-hub:local \
  dotnet ItWorx.KnowledgeHub.Api.dll --migrate-only

Gebruik hier bewust --migrate-only, niet een gewone opstart: een gewone opstart maakt als bijwerking meteen de installatierij aan (dezelfde rij die bij een eerste installatie hoort), waardoor de doeldatabase niet meer "leeg" is tegen de tijd dat herstel start. --migrate-only past uitsluitend het schema toe en sluit daarna direct af.

Stap 2 — herstellen

Maak eerst een beschrijfbare herstelkopie van de gekozen back-up; herstel neemt een exclusieve opslaglease en schrijft achteraf een herstelbewijs naast het manifest. Geef de CLI de doelconnectie via een door de operator beheerd geheimenbestand, niet via een argument met het wachtwoord erin. Op Unix moet dat bestand alleen voor de restoregebruiker leesbaar zijn (chmod 600 of chmod 400); op Windows beperk je de ACL tot de restore- operator/serviceaccount. Het bestand bevat één PostgreSQL-connectiereeks. De integriteitssleutel moet eveneens beschikbaar zijn in de geconfigureerde Keys-map. Haal de exacte backup-integrity.key uit beschermde externe escrow; herstel vertrouwt geen sleutel die alleen in de back-upkopie zit. De restore verifieert de manifest- handtekening en kopieert de vermelde bestanden eerst naar een privé-stagingmap binnen het lege doelbijlagenvolume. Reserveer daar vrije ruimte voor ten minste de volledige back-upinhoud. De restore gebruikt uitsluitend die geverifieerde snapshot.

docker run --rm \
  --network itworx-knowledge-hub_knowledge-hub-internal \
  -v <beschrijfbare-herstelkopie>:/var/lib/knowledge-hub/backups:rw \
  -e KnowledgeHub__Paths__Backups=/var/lib/knowledge-hub/backups \
  -v <map-met-backup-integriteitssleutel>:/var/lib/knowledge-hub/keys:ro \
  -e KnowledgeHub__Paths__Keys=/var/lib/knowledge-hub/keys \
  -v <beveiligd-doelconnectiebestand>:/run/secrets/restore-target-connection:ro \
  -v <doel-bijlagen-volume>:/var/lib/knowledge-hub/attachments \
  itworx/knowledge-hub:local \
  dotnet ItWorx.KnowledgeHub.Api.dll \
  --restore \
  --backup-id=<back-up-id> \
  --target-connection-file=/run/secrets/restore-target-connection \
  --target-attachments=/var/lib/knowledge-hub/attachments

De echte herstel-drill haalt de back-up via SSH op, maar leest de integriteitssleutel uit een lokaal door de operator beheerd escrowbestand. Geef alleen het bestandspad mee; de drill maakt tijdens uitvoering een tijdelijke kopie met modus 0600 en verwijdert die bij opruimen:

KNOWLEDGE_HUB_BACKUP_INTEGRITY_KEY_FILE=/secure/escrow/backup-integrity.key \
  bash scripts/v2-r4-real-backup-restore-drill.sh <back-up-id>

De doeldatabase moet leeg zijn — herstel weigert expliciet als er al rijen in staan, om nooit per ongeluk bestaande gegevens te vermengen met herstelde gegevens.

Het proces rapporteert per tabel het aantal herstelde versus verwachte rijen, het aantal herstelde bijlagen, en sluit af met GESLAAGD of MISLUKT (afsluitcode 0 respectievelijk 1). Een MISLUKT-resultaat laat expliciet zien welke tabel niet overeenkomt — er wordt nooit stilzwijgend een onvolledig herstel als geslaagd gerapporteerd. Providerfoutdetails worden niet afgedrukt omdat die connectiegegevens kunnen bevatten.

Opstartgedrag en migraties

Bij elke opstart:

De applicatie weigert te starten als de database al een migratie heeft toegepast die deze build niet kent (bijvoorbeeld na een terugzetting naar een oudere image-versie tegen een nieuwere database) — dit voorkomt dat de applicatie onbedoeld tegen een onbekende schemavorm gaat werken.
Normale voorwaartse migratie (een oudere database die bijwerkt naar een nieuwere applicatieversie) blijft het gewone pad en gebeurt automatisch bij opstart.

Statuscontroles

GET /health/live — altijd anoniem bereikbaar; faalt nooit vanwege een tijdelijk onbereikbare database. Gebruik dit voor de container-gezondheidscontrole.
GET /health/ready — anoniem bereikbaar maar geeft alleen een minimale status terug (geen details): controleert databaseverbinding, of alle migraties zijn toegepast, en of alle geconfigureerde opslagpaden beschrijfbaar zijn.
GET /api/v1/system/info — vereist beheerdersaanmelding. Toont productversie, schemaversie, commit en uptime — gebruik dit na een herstart/upgrade om te bevestigen welke versie en welk schema daadwerkelijk draait.

Logboeken

In productie schrijft de applicatie gestructureerde JSON-logregels naar stdout/stderr, elk met een correlatie-ID zodat alle logregels van één aanvraag samen te herleiden zijn. Wachtwoorden, ruwe tokens, cookies, autorisatie-headers, connectiereeksen en paginainhoud worden nooit gelogd. Logrotatie gebeurt op Docker/Unraid-niveau, niet binnen de applicatie.

7.2 KiB Raw Permalink Blame History