itworx-knowledge-hub-Public/docs/guides/operationele-runbooks-overzicht.md

Operationele runbooks — overzicht

Deze gids wijst naar de bestaande, feitelijk geïmplementeerde runbook-onderwerpen (docs/25-release-and-operations.md "Operational runbooks required by 1.0") en beschrijft de twee onderwerpen die nog geen eigen gids hadden. Waar een onderwerp niet of nog niet volledig is geïmplementeerd, staat dat hier expliciet — nooit stilzwijgend verondersteld.

Onderwerp	Status	Waar
Eerste implementatie	Geïmplementeerd en getest	docs/23-deployment-unraid.md "First deployment"; docs/guides/eerste-installatie-en-aanmelden.md
Eigenaarherstel (wachtwoord)	Geïmplementeerd en getest	docs/guides/eerste-installatie-en-aanmelden.md (herstel-token)
Back-up maken	Geïmplementeerd en getest	docs/guides/back-ups-herstel-en-unraid-beheer.md
Schoon herstel	Geïmplementeerd en getest	docs/guides/back-ups-herstel-en-unraid-beheer.md
Applicatie bijwerken	Geïmplementeerd en getest	docs/23-deployment-unraid.md "Updates"; schema-driftweigering (M7)
Applicatie terugzetten (rollback)	Geïmplementeerd en getest	docs/23-deployment-unraid.md "Rollback"; zie ook onderstaande sectie
PostgreSQL kleine update	Geïmplementeerd en getest	Onderstaande sectie (nieuw voor M8)
PostgreSQL grote upgrade (rehearsal)	Niet uitgevoerd	Zie "Bekende beperkingen" hieronder
Opslag-/integriteitsstoring	Geïmplementeerd en getest	Onderstaande sectie (nieuw voor M8)
Import en rollback	Geïmplementeerd en getest	docs/guides/bijlagen-en-leafwiki-import.md
Gecompromitteerd service-token	Geïmplementeerd en getest	docs/guides/service-accounts-en-automatisering.md (intrekken)
Gegevensexport	Niet geïmplementeerd	Zie "Bekende beperkingen" hieronder
LeafWiki-overstap (cutover)	Ontworpen, niet uitgevoerd tegen echte data	docs/17-leafwiki-migration.md; echte overstap is M9-scope

PostgreSQL kleine update

Kleine (minor) PostgreSQL-updates binnen dezelfde hoofdversie (18.x) zijn compatibel met hetzelfde datavolume:

1. Bevestig een recente, geverifieerde back-up (docs/guides/back-ups-herstel-en-unraid-beheer.md).
2. Werk de postgres-image-tag bij naar de nieuwe kleine versie in docker-compose.yml (bijvoorbeeld postgres:18.5-bookworm).
3. docker compose pull db && docker compose up -d db — het bestaande datavolume (knowledge-hub-db) wordt hergebruikt; PostgreSQL werkt zelf bij bij het opstarten.
4. Controleer docker compose ps (status healthy) en start daarna de applicatie opnieuw op (docker compose up -d app).
5. Controleer GET /health/ready en een geauthenticeerde GET /api/v1/system/info.

Nooit een grote (major) versiesprong op deze manier uitvoeren — zie hieronder.

Opslag-/integriteitsstoring

Wanneer GET /health/ready onbereikbaarheid van de database of een niet-beschrijfbaar opslagpad rapporteert (DatabaseHealthCheck/StorageHealthCheck, M7):

1. Controleer docker compose ps en docker logs itworx-knowledge-hub-db-1 / itworx-knowledge-hub-app-1 voor de onderliggende fout.
2. Controleer of de onderliggende Unraid-schijf/-pool vol is of in fout-status staat (buiten het bereik van de applicatie zelf — de applicatie draait immers met een alleen-lezen hoofdbestandssysteem en kan de hostopslag niet zelf herstellen).
3. Herstel de opslag/host-laag eerst; herstart pas daarna de containers.
4. Als gegevensverlies of -corruptie wordt vermoed: schrijf niets meer naar de database totdat een back-up is bevestigd. Herstel bij twijfel vanaf de laatst geverifieerde back-up naar een schone doelomgeving (docs/guides/back-ups-herstel-en-unraid-beheer.md) in plaats van de productie- database rechtstreeks te herstellen met ad-hoc SQL (docs/25-release-and-operations.md "Incident priorities": "Do not 'repair' production data through undocumented ad hoc SQL").

Bekende beperkingen

• Gegevensexport is nog niet geïmplementeerd als eindgebruikersfunctie. De enige vorm van "export" die vandaag bestaat, is de back-up zelf (docs/guides/back-ups-herstel-en-unraid-beheer.md), die het volledige datamodel bevat maar niet bedoeld is als leesbaar exportformaat voor een individuele pagina of project. Een gerichte exportfunctie (bijvoorbeeld Markdown-export per pagina/project) is niet gepland vóór een toekomstige milestone met een expliciet acceptatiecriterium.
• De PostgreSQL major-upgrade-rehearsal is niet uitgevoerd. Dit vereist een tweede, oudere PostgreSQL-hoofdversie plus pg_upgrade- of dump/restore-oefening, wat buiten de tijdsbox van dit release-traject valt en geen acuut risico vormt zolang de applicatie op één vaste hoofdversie (18) blijft draaien. Voer deze oefening uit vóórdat een major-upgrade daadwerkelijk wordt gepland.
• De echte LeafWiki-overstap vereist de echte LeafWiki-momentopname en productie- Unraid-omgeving van de gebruiker — een expliciete externe blokkade (CLAUDE.md §3), uitgevoerd in M9 zodra beschikbaar.