Restore-Runbooks¶

Stand: 2026-05-26

Grundregel¶

Restore-Arbeiten sind produktive Änderungen. Vor dem Restore wird immer ein aktueller Ist-Zustand gesichert, der betroffene Dienst gestoppt oder in Wartung gesetzt und danach ein Healthcheck ausgeführt.

Keine Secret-Werte in Tickets, Git oder Markdown schreiben. Secrets werden aus Vaultwarden geladen oder interaktiv eingegeben.

Recovery-Reihenfolge¶

Empfohlene Reihenfolge bei größerem Ausfall:

Netzwerk, DNS, NPM und TLS-Erreichbarkeit prüfen.
Proxmox-LXC-Status prüfen.
Vaultwarden verfügbar machen, damit Secrets wieder zugreifbar sind.
Gitea und MkDocs wiederherstellen, damit Doku und Runbooks verfügbar sind.
Agent Runtime Stack wiederherstellen: PostgreSQL, Redis, Qdrant, LiteLLM, MCPHub, Tools API.
Open WebUI wiederherstellen.
n8n und Healthcheck wieder aktivieren.
RAG-Ingest und Qdrant-Snapshots validieren.

Runtime Backup Validation¶

Der Read-only-Golden-Path runtime_backup_validation_v1 prüft regelmäßig, ob Backup-Pfade, Zeitstempel, Größen, Rechte und Restore-Runbook-Referenzen aus Sicht der Agent Runtime plausibel sind.

Wichtig:

Der Workflow führt keinen Restore aus.
Der Workflow liest keine Backup-Inhalte.
Der Workflow gibt keine Secret-Werte aus.
Ein roter Status bedeutet zunächst: Backup-Nachweis ist aus der Runtime nicht sichtbar oder nicht belastbar.

Operator-Endpoint:

POST /workflow-catalog/runtime-backup-validation

Details: Runtime Backup Validation.

Metadaten-Snapshots für externe Komponenten liegen unter:

/var/lib/lanstyle-agent/controlled-execution/backup-metadata/

Diese Snapshots enthalten nur Pfad, Existenz, Zeitstempel, Größe, Rechte, Owner, Quelle und Runbook-Referenz. Sie sind kein Ersatz für ein Backup und kein Restore-Test, sondern ein operativer Nachweis für Backup-Sichtbarkeit.

GB10/Ollama-Härtung 2026-05-26:

Metadatenexport vor Änderung: /home/admin/config-backups/metadata-hardening-20260526-173230/pre-change-metadata.tsv
Metadatenexport nach Änderung: /home/admin/config-backups/metadata-hardening-20260526-173230/post-change-metadata.tsv
Keine Backup-Inhalte gelesen.
Keine Backups gelöscht.
Keine Ollama-Konfiguration geändert.
Kein Service-Restart durchgeführt.

Controlled Execution Restore¶

Controlled Execution speichert keine Secrets, aber wichtige Audit- und Backup-Referenzen.

Pfad	Zweck	Restore
`/opt/agent-runtime/controlled-execution/approvals.jsonl`	serverseitige Approval-Records	aus LXC-/Dateibackup wiederherstellen, Rechte `0600`
`/opt/agent-runtime/controlled-execution/backups/`	Export-/Backup-Nachweise je Aktion	aus LXC-/Dateibackup wiederherstellen, Rechte privat halten
`/opt/agent-runtime/logs/controlled-execution.jsonl`	Audit Trail	aus Logbackup wiederherstellen, Rechte `0600`

Nach Restore pruefen:

pct exec 259 -- bash -lc 'stat -c "%a %U:%G %n" /opt/agent-runtime/controlled-execution/approvals.jsonl /opt/agent-runtime/logs/controlled-execution.jsonl'
pct exec 259 -- bash -lc 'curl -sS http://10.0.1.243:3010/controlled-execution/policy | jq .status'

Approval-IDs, die vor dem Restore bereits verbraucht waren, duerfen nicht erneut genutzt werden. Im Zweifel neue Approval-ID erzeugen und alte als gesperrt dokumentieren.

VLAN 70 Pre-Migration Restore¶

Stand der vorbereiteten Backups:

Komponente	Backup/Snapshot	Restore-Weg	Erwartete Downtime	Abhängigkeiten
Open WebUI LXC `250`	Proxmox Snapshot `vlan70-pre-migration-20260525-2109`	`pct rollback 250 vlan70-pre-migration-20260525-2109` nach Freigabe	mittel, Container-Rollback stoppt/ändert Dienstzustand	NPM `ai.lanstyle.de`, Ollama/LiteLLM, Open Terminal
Open Terminal LXC `255`	Proxmox Snapshot `vlan70-pre-migration-20260525-2109`	`pct rollback 255 vlan70-pre-migration-20260525-2109` nach Freigabe	mittel, laufende Sessions gehen verloren	Open WebUI Toolserver
SearXNG LXC `256`	Proxmox Snapshot `vlan70-pre-migration-20260525-2109`	`pct rollback 256 vlan70-pre-migration-20260525-2109` nach Freigabe	niedrig bis mittel	Open WebUI Websuche, `search.lanstyle.de`
Agent Runtime LXC `259`	Proxmox Snapshot `vlan70-pre-migration-20260525-2109`	`pct rollback 259 vlan70-pre-migration-20260525-2109` nach Freigabe	mittel bis hoch, LiteLLM/MCP/RAG betroffen	OpenCode, Open WebUI Provider, Qdrant, MCPHub
Proxmox Config Exporte	`/root/config-backups/vlan70-pre-migration-20260525-2109/pct-*.conf`	Konfiguration manuell vergleichen und gezielt zurücksetzen	abhängig von Änderung	Proxmox Host
NPM LXC `308`	`/root/config-backups/vlan70-pre-migration-20260525-2110/` im NPM-LXC	DB/Config zurückspielen, NPM reload/restart	mittel, externe Endpunkte betroffen	NPM, TLS, Access Lists
GB10/Ollama	`/home/admin/config-backups/vlan70-pre-migration-20260525-2110-ollama/`	Systemd Override/IP/Route anhand Export zurücksetzen, Ollama restart	niedrig bis mittel, Modell-API betroffen	Open WebUI, LiteLLM, RAG
UniFi/UDM Pro	lokaler Export `.backups/20260525-2108-vlan70-pre-migration/`	Firewall/DNS/Network Policies anhand Export manuell zurücknehmen	abhängig von Änderung	DNS, Firewall, VLAN Routing
SearXNG Canary	`/root/config-backups/vlan70-searxng-canary-*`	`pct set 256 -delete net1`	niedrig, Alt-IP bleibt aktiv	Open WebUI Websuche, `search.lanstyle.de`
Open Terminal Canary	`/root/config-backups/vlan70-open-terminal-canary-*`	`pct set 255 -delete net1`	niedrig, Alt-IP bleibt aktiv	Open WebUI Toolserver
Open WebUI Canary	`/root/config-backups/vlan70-openwebui-canary-*`	`pct set 250 -delete net1`	niedrig, Alt-IP bleibt aktiv	NPM `ai.lanstyle.de`, Open WebUI Nutzer
GB10/Ollama Canary	`/home/admin/config-backups/vlan70-ollama-canary-*`	`nmcli connection down/delete LS_AI_Services_VLAN70`	niedrig, Alt-IPs bleiben aktiv	Open WebUI, LiteLLM, RAG, `ollama.lanstyle.de`
NPM `search.lanstyle.de` Direct-IP Backend Canary	`/root/config-backups/npm-search-canary-` und `/root/config-backups/npm-search-direct-ip-` im NPM-LXC sowie lokaler API-Export `.backups/*-npm-search-direct-ip-canary-api`	Proxy Host ID `48` per NPM-API auf `10.0.1.240:8888` zurückstellen	niedrig, nur Such-FQDN betroffen	SearXNG, `search.lanstyle.de`
NPM `ollama.lanstyle.de` Direct-IP Backend Canary	`.backups/20260525-231852-npm-ollama-direct-ip-canary-api` lokal und NPM-API-Export	Proxy Host ID `41` per NPM-API auf `10.222.70.11:11434` zurückstellen	niedrig bis mittel, Ollama-FQDN/API betroffen	Open WebUI, OpenCode, LiteLLM-Fallbacks, externe Ollama-Clients
NPM `litellm.lanstyle.de` Direct-IP Backend Canary	`.backups/20260525-232802-npm-litellm-direct-ip-canary-api` lokal und NPM-API-Export	Proxy Host ID `46` per NPM-API auf `10.0.1.243:4000` zurückstellen	mittel, zentraler OpenAI-kompatibler API-FQDN betroffen	OpenCode, Open WebUI Provider, Agent Runtime
NPM `mcphub.lanstyle.de` Direct-IP Backend Canary	`.backups/20260525-234056-npm-mcphub-direct-ip-canary-api` lokal und NPM-API-Export	Proxy Host ID `47` per NPM-API auf `10.0.1.243:3000` zurückstellen	mittel, MCPHub-FQDN betroffen	OpenCode, Open WebUI Toolserver, Agent Runtime
NPM `ai.lanstyle.de` Direct-IP Backend Canary	lokale API-Sicherung `.backups/20260526-004335-npm-ai-direct-ip-canary-api/npm-ai-api-export.tgz`, Agent-Runtime-Export `/opt/agent-runtime/backups/20260525-224426-npm-ai-direct-ip-canary-api`, NPM-DB-Backup `/root/config-backups/npm-ai-direct-ip-canary-20260526-004350/database.sqlite.before`	Proxy Host ID `40` per NPM-API auf `10.0.0.250:8080` zurückstellen	niedrig bis mittel, Open-WebUI-FQDN betroffen	Open WebUI, Benutzer-Sessions, Tooling

Agent Runtime Canary-Rollback:

ssh root@10.0.0.220
pct exec 259 -- bash -lc 'cd /opt/agent-runtime && cp docker-compose.yml docker-compose.yml.bak-before-canary-rollback'
pct exec 259 -- bash -lc 'cd /opt/agent-runtime && python3 - <<PY
from pathlib import Path
p = Path("docker-compose.yml")
text = p.read_text()
for line in [
    "      - \\"10.222.70.20:6333:6333\\"\\n",
    "      - \\"10.222.70.20:6334:6334\\"\\n",
    "      - \\"10.222.70.20:4000:4000\\"\\n",
    "      - \\"10.222.70.20:3000:3000\\"\\n",
    "      - \\"10.222.70.20:3010:3010\\"\\n",
]:
    text = text.replace(line, "")
p.write_text(text)
PY
docker compose up -d qdrant litellm mcphub lanstyle-tools-api'
pct set 259 -delete net1

Danach prüfen:

pct exec 259 -- bash -lc 'ip -br addr; ss -ltnp | grep 10.0.1.243'

SearXNG Canary-Rollback:

ssh root@10.0.0.220
pct set 256 -delete net1
pct exec 256 -- bash -lc 'ip -br addr; curl -sS -m 8 -o /dev/null -w "%{http_code}\n" http://10.0.1.240:8888/'

Open Terminal Canary-Rollback (historisch / rollback-only):

Der frühere Legacy-Pfad 10.0.1.253:8001-8004 ist seit Open Terminal VLAN70-only nicht mehr produktiv aktiv. Dieser Block bleibt ausschließlich als historischer Rollback-/Audit-Kontext erhalten und darf nicht als aktueller Healthcheck-Zielpfad verwendet werden.

ssh root@10.0.0.220
pct set 255 -delete net1
pct exec 255 -- bash -lc 'ip -br addr; for p in 8001 8002 8003 8004; do curl -sS -m 8 -o /dev/null -w "$p:%{http_code}\n" http://10.0.1.253:$p/health; done'

Open WebUI Canary-Rollback:

ssh root@10.0.0.220
pct set 250 -delete net1
pct exec 250 -- bash -lc 'ip -br addr; curl -sS -m 8 -o /dev/null -w "%{http_code}\n" http://10.0.0.250:8080/'

GB10/Ollama Canary-Rollback:

ssh admin@gb10-01.ad.lanstyle.de
sudo nmcli connection down LS_AI_Services_VLAN70
sudo nmcli connection delete LS_AI_Services_VLAN70
ip -br addr
curl -sS -m 8 -o /dev/null -w "%{http_code}\n" http://10.222.70.11:11434/api/tags

NPM search.lanstyle.de Backend-Canary-Rollback:

export NPM_TOKEN="$(curl -sS -X POST http://10.222.50.10:81/api/tokens \
  -H 'Content-Type: application/json' \
  --data '{"identity":"<user>","secret":"<pass>"}' | jq -r .token)"

curl -sS http://10.222.50.10:81/api/nginx/proxy-hosts/48 \
  -H "Authorization: Bearer $NPM_TOKEN" \
  | jq '{domain_names,forward_scheme,forward_host,forward_port,certificate_id,ssl_forced,hsts_enabled,hsts_subdomains,http2_support,block_exploits,caching_enabled,allow_websocket_upgrade,access_list_id,advanced_config,meta,locations}
        | .forward_host="10.0.1.240" | .forward_port=8888 | .forward_scheme="http"' \
  > /tmp/search-proxy-rollback.json

curl -sS -X PUT http://10.222.50.10:81/api/nginx/proxy-hosts/48 \
  -H "Authorization: Bearer $NPM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @/tmp/search-proxy-rollback.json

curl -k -sS -o /dev/null -w "%{http_code}\n" https://search.lanstyle.de/

NPM ollama.lanstyle.de Backend-Canary-Rollback:

export NPM_TOKEN="$(curl -sS -X POST http://10.222.50.10:81/api/tokens \
  -H 'Content-Type: application/json' \
  --data '{"identity":"<user>","secret":"<pass>"}' | jq -r .token)"

curl -sS http://10.222.50.10:81/api/nginx/proxy-hosts/41 \
  -H "Authorization: Bearer $NPM_TOKEN" \
  | jq '{domain_names,forward_scheme,forward_host,forward_port,certificate_id,ssl_forced,hsts_enabled,hsts_subdomains,http2_support,block_exploits,caching_enabled,allow_websocket_upgrade,access_list_id,advanced_config,meta,locations}
        | .forward_host="10.0.0.249" | .forward_port=11434 | .forward_scheme="http"' \
  > /tmp/ollama-proxy-rollback.json

curl -sS -X PUT http://10.222.50.10:81/api/nginx/proxy-hosts/41 \
  -H "Authorization: Bearer $NPM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @/tmp/ollama-proxy-rollback.json

curl -k -sS -o /dev/null -w "%{http_code}\n" https://ollama.lanstyle.de/api/tags

NPM ai.lanstyle.de Backend-Canary-Rollback:

export NPM_TOKEN="$(curl -sS -X POST http://10.222.50.10:81/api/tokens \
  -H 'Content-Type: application/json' \
  --data '{"identity":"<user>","secret":"<pass>"}' | jq -r .token)"

curl -sS http://10.222.50.10:81/api/nginx/proxy-hosts/40 \
  -H "Authorization: Bearer $NPM_TOKEN" \
  | jq '{domain_names,forward_scheme,forward_host,forward_port,certificate_id,ssl_forced,hsts_enabled,hsts_subdomains,http2_support,block_exploits,caching_enabled,allow_websocket_upgrade,access_list_id,advanced_config,meta,locations}
        | .forward_host="10.0.0.250" | .forward_port=8080 | .forward_scheme="http"' \
  > /tmp/ai-proxy-rollback.json

curl -sS -X PUT http://10.222.50.10:81/api/nginx/proxy-hosts/40 \
  -H "Authorization: Bearer $NPM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @/tmp/ai-proxy-rollback.json

curl -k -sS -o /dev/null -w "%{http_code}\n" https://ai.lanstyle.de/

Rollback-Befehle für Proxmox-Snapshots sind bewusst nicht automatisch auszuführen:

ssh root@10.0.0.220
pct listsnapshot 250
pct rollback 250 vlan70-pre-migration-20260525-2109

Vor jedem Rollback:

Aktuellen Ist-Zustand erneut sichern.
Betroffene externe Endpunkte in NPM auf Alt-IP belassen oder zurückstellen.
Betroffene Dienste nach Rollback starten und prüfen.
Healthcheck ausführen.
Ursache dokumentieren, bevor ein zweiter Migrationsversuch startet.

Qdrant Restore¶

Quelle:

/opt/agent-runtime/backups/qdrant/

Vorbereitung:

ssh root@10.0.0.220
pct exec 259 -- bash -lc 'docker ps --filter name=qdrant'
pct exec 259 -- bash -lc 'ls -lh /opt/agent-runtime/backups/qdrant/'

Restore-Ablauf:

pct exec 259 -- bash -lc '
set -euo pipefail
cd /opt/agent-runtime
TS=$(date +%Y%m%d-%H%M%S)
mkdir -p backups/pre-restore-$TS
docker compose exec -T qdrant curl -sS -H "api-key: $QDRANT_API_KEY" http://127.0.0.1:6333/collections > backups/pre-restore-$TS/collections.json
# Snapshot-Datei und Collection bewusst auswählen.
# Restore erst nach expliziter Freigabe ausführen.
'

Nacharbeiten:

Collection-Status green prüfen.
Punkteanzahl prüfen.
Query-Script gegen relevante Suchbegriffe testen.
Healthcheck ausführen.

LiteLLM PostgreSQL Restore¶

LiteLLM nutzt PostgreSQL im Agent-Runtime-LXC. Vor einem Restore muss der aktuelle Datenbankstand gesichert werden.

Vorbereitung:

pct exec 259 -- bash -lc '
cd /opt/agent-runtime
TS=$(date +%Y%m%d-%H%M%S)
mkdir -p backups/postgres/pre-restore-$TS
docker compose exec -T postgres pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB" > backups/postgres/pre-restore-$TS/litellm.sql
'

Restore nur nach Freigabe:

pct exec 259 -- bash -lc '
cd /opt/agent-runtime
docker compose stop litellm
# psql-Restore mit ausgewähltem Dump ausführen.
docker compose start litellm
'

Validierung:

https://litellm.lanstyle.de/v1/models mit gültigem Key prüfen.
Completion-Smoke-Test pro Alias ausführen.
LiteLLM-Containerlogs auf Migration-/DB-Fehler prüfen.

Open WebUI DB Restore¶

Open WebUI liegt im LXC 250. Vorher Containerstatus, Datenpfad und Service prüfen.

Vorbereitung:

pct status 250
pct exec 250 -- systemctl status open-webui --no-pager
pct exec 250 -- bash -lc 'find / -maxdepth 4 -iname "*webui*.db" 2>/dev/null'

Restore-Prinzip:

Aktuelle DB/dateibasierte Daten sichern.
Open-WebUI-Service stoppen.
Restore-Datei einspielen.
Dateirechte prüfen.
Service starten.
Login, Provider, Modelle und Tool-Verbindungen prüfen.

Es wird kein pauschaler Pfad dokumentiert, weil der genaue Pfad vor jedem Restore aus dem laufenden Container geprüft werden muss.

Vaultwarden Backup/Restore¶

Vaultwarden ist Secret Source of Truth. Restore nur mit besonderer Sorgfalt und nur nach expliziter Freigabe.

Vorbereitung:

pct status 256
pct exec 256 -- systemctl status vaultwarden --no-pager || true

Restore-Prinzip:

Aktuellen Vaultwarden-Datenpfad identifizieren.
Aktuellen Datenstand offline sichern.
Dienst stoppen.
Backup einspielen.
Rechte und Owner prüfen.
Dienst starten.
Login mit Admin-/Userkonto testen.
Admin-Token nicht in Logs oder Git schreiben.

Hinweis: Das Masterpasswort für m.eberhardt@lanstyle.de liegt im Apple iCloud Passwortsafe, nicht in Git.

Gitea Backup/Restore¶

Gitea ist zentrale Quelle für Code, Doku und Prompt-/Runbook-Artefakte.

Vorbereitung:

pct status 252
pct exec 252 -- systemctl status gitea --no-pager || true

Restore-Prinzip:

Aktuelle Gitea-Datenbank und Repositories sichern.
Dienst stoppen.
DB und Repositories konsistent aus Backup wiederherstellen.
Rechte prüfen.
Dienst starten.
Login, Organisationen, Repos, SSH-Clone und HTTP-Clone testen.
Wiki-Repo und MkDocs-Deploy validieren.

Abschlussprüfung¶

Nach jedem Restore:

agent-runtime/scripts/test-agent-runtime.sh

Auf dem n8n-LXC:

/opt/lanstyle-agent/lanstyle-healthcheck.sh

Außerdem prüfen:

OpenCode kann https://litellm.lanstyle.de/v1 nutzen.
Open WebUI sieht die lanstyle/* Modelle.
Qdrant lanstyle_docs und lanstyle_inventory sind green.
Wiki ist erreichbar und aktuell.

Restore-Test-Status¶

Aktueller Stand:

Komponente	Runbook	letzter Restore-Test	Status
Agent Runtime / Controlled Execution	vorhanden	nicht produktiv ausgeführt	sandbox-konzept erforderlich
Qdrant	vorhanden	nicht produktiv ausgeführt	Snapshot-Metadaten sichtbar
LiteLLM PostgreSQL	vorhanden	nicht produktiv ausgeführt	DB-Backup-Pfad prüfen
Open WebUI DB	vorhanden	nicht produktiv ausgeführt	Backup-Metadaten sichtbar
Vaultwarden	vorhanden	nicht produktiv ausgeführt	nur mit Offline-Sicherung und Wartungsfenster
Gitea/MkDocs	vorhanden	nicht produktiv ausgeführt	Repo-/Backup-Metadaten sichtbar
GB10/Ollama Config	vorhanden	nicht produktiv ausgeführt	Backup-Rechte gehärtet

Sandbox-Restore-Konzept:

Restore nie direkt auf produktive Dienste.
Isolierte Test-LXC oder temporärer Compose-Stack.
Backup-Metadaten vorab prüfen.
Backup-Inhalte nur im Restore-Testsystem lesen.
Secrets nach Test verwerfen.
Ergebnis als Restore-Test-Artefakt dokumentieren.

Restore Readiness Scoring¶

Die Tools API berechnet zusätzlich einen read-only Score:

GET /ops/restore-readiness-scoring

Scoring:

green: 100 Punkte
yellow: 70 Punkte
red: 20 Punkte

Der Score ersetzt keinen echten Restore-Test. Er zeigt nur, ob Backup-Metadaten, Alter, Rechte und Runbook-Referenzen plausibel sind.