syncova-backup/docs/recovery.md

# Recovery Engine

## Status

Umgesetzt sind Vorabprüfung, Wiederherstellung von Dateien und Ordnern über die API, Sitzungen mit Prüfpunkt, Schutz gegen versehentliches Überschreiben und die Ausführungsschleife.

Nicht umgesetzt: Plattenwiederherstellung, vollständige Systemwiederherstellung und Proxmox-VM-Wiederherstellung. Für Proxmox fehlt der `ArchiveTransport` (siehe `proxmox.md`); ohne ihn kommt schon die Sicherung nicht zustande.

## Die Vorabprüfung ist der Kern

> Ein Backup gilt erst als vertrauenswürdig, wenn Integrität geprüft und Wiederherstellbarkeit nachgewiesen wurde.

Ein Nachweis, der erst im Ernstfall erbracht wird, ist keiner. `POST /restores/validate` prüft deshalb **ohne etwas zu schreiben**, ob eine Wiederherstellung gelingen kann:

| Prüfung | Gewicht bei Befund |
| --- | --- |
| Manifest lesbar | verhindernd |
| Abschlussvermerk vorhanden | verhindernd |
| **Jeder benötigte Block vorhanden** | verhindernd |
| Datenschlüssel des Repositorys auffindbar | verhindernd |
| Zielverzeichnis erreichbar, Elternverzeichnis vorhanden | verhindernd |
| Freier Platz ausreichend (5 % Aufschlag) | verhindernd |
| Ziel nicht leer, ohne Zustimmung | verhindernd |
| Ziel wird überschrieben, mit Zustimmung | Warnung |
| Backup unverschlüsselt | Warnung |
| Schlüsselversion weicht ab | Warnung |
| Blockprüfung übersprungen | Hinweis |

**Die Blockprüfung ist der eigentliche Nachweis.** Ein Manifest allein belegt nur, dass jemand einmal etwas gesichert hat — nicht, dass die Daten noch da sind. Ein versehentlich aufgeräumtes Verzeichnis, ein unvollständig kopiertes Repository, ein fehlgeschlagenes Prune: Alles das fällt hier auf und nicht erst, wenn man es braucht.

Real geprüft: Nach dem Entfernen eines einzigen Blocks meldet die Prüfung

```
can_proceed: False
NICHT WIEDERHERSTELLBAR: 1 Hindernisse, 1 fehlende Bloecke.
[blocking] 1 von 16 benoetigten Bloecken fehlen im Repository.
         betroffen: daten/datei-8.bin
```

Die **betroffene Datei** wird genannt, nicht nur eine Zahl. „Ein Block fehlt" hilft niemandem weiter; „daten/datei-8.bin lässt sich nicht wiederherstellen" schon.

Wird die Blockprüfung übersprungen (`skip_deep_check`), steht das als Hinweis im Bericht. Sonst hielte man einen halben Nachweis für einen ganzen.

**Die Prüfung läuft zweimal:** einmal beim Anlegen des Auftrags und erneut unmittelbar vor dem Schreiben. Der Bericht am Auftrag kann Minuten oder Tage alt sein; in der Zwischenzeit kann ein Block verschwunden oder das Ziel gefüllt worden sein. Der Bericht wird am Auftrag gespeichert — später muss belegbar sein, was vor dem Start bekannt war.

## Drei Hürden vor dem Überschreiben

Eine Wiederherstellung an einen belegten Ort richtet sich gegen Daten, die es noch gibt — und die könnten genau die sein, die man eigentlich retten will.

1. **Ohne `overwrite_existing` wird ein nicht leeres Ziel abgelehnt.**
2. **`restores.overwrite` ist eine eigene Berechtigung**, nicht in `restores.execute` enthalten. Wer wiederherstellen darf, darf nicht automatisch überschreiben.
3. **`confirm_overwrite` muss den Zielpfad wörtlich wiederholen.** Ein zweites Feld neben dem Kennzeichen ist keine Umständlichkeit: Ein versehentlich gesetztes Kennzeichen in einem Skript oder einer Vorlage reicht damit nicht aus, um Daten zu vernichten. Wer den Pfad abtippt, hat ihn gelesen.

Läuft der Schalter ins Leere — das Ziel ist leer —, entfällt die Bestätigung. Ein Ritual ohne Anlass gewöhnt nur das Wegklicken an.

Jede Wiederherstellung wird auditiert, das Überschreiben unter eigener Aktion (`RESTORE_OVERWRITE_REQUESTED`) und zusätzlich als Warnung im Protokoll.

## Sitzungen und Prüfpunkte

Ein Abbruch bei 90 Prozent darf nicht bedeuten, dass alles von vorn beginnt — bei mehreren Terabyte wäre das der Unterschied zwischen Stunden und Tagen, und zwar in einer Lage, in der ohnehin schon etwas schiefging.

Jeder Auftrag bekommt eine Sitzung mit Prüfpunkt. Der Prüfpunkt hält **einen einzigen Pfad**: den zuletzt vollständig zurückgeschriebenen. Das genügt, weil die Objekte im Manifest fest sortiert sind — alles lexikographisch davor ist erledigt. Eine Liste wäre bei einer Million Dateien unbrauchbar groß.

**Der Prüfpunkt entsteht erst, nachdem die Datei vollständig und unter ihrem endgültigen Namen am Platz liegt.** Ein Prüfpunkt auf eine halb geschriebene Datei wäre schlimmer als keiner: Die Fortsetzung übersprünge sie als erledigt.

Geschrieben wird er nicht bei jeder Datei, sondern höchstens alle paar Sekunden — bei einer Million kleiner Dateien wären das sonst eine Million Schreibvorgänge in die Datenbank. Der Preis ist, dass eine Fortsetzung wenige Sekunden Arbeit wiederholt.

Bei einer Fortsetzung greift der Schutz gegen ein volles Zielverzeichnis **nicht**: Dort liegt notwendigerweise der bereits zurückgeschriebene Teil. Ihn über `overwrite_existing` auszuhebeln wäre falsch — das erlaubte zugleich das Überschreiben fremder Daten.

Die Endzahlen beschreiben den **gesamten** Vorgang, nicht nur den letzten Versuch: drei Objekte aus dem ersten Lauf plus zwei aus dem zweiten ergeben fünf.

## Kein automatischer Wiederholungsversuch

Anders als eine Sicherung wird eine gescheiterte Wiederherstellung **nicht** automatisch erneut gestartet. Ein zweiter Lauf in ein halb gefülltes Zielverzeichnis kann Daten beschädigen, die der erste Versuch bereits am Platz hatte. Der Betreiber soll hinsehen, bevor erneut geschrieben wird — die Sitzung mit ihrem Prüfpunkt bleibt dafür offen.

Das gilt auch für verwaiste Aufträge: Stirbt ein Control-Server mitten in einer Wiederherstellung, wird der Auftrag nach fünf Minuten als `SCHEDULER_LOST` gescheitert vermerkt, aber nicht erneut eingereiht. Die Sitzung überlebt.

## Nebenläufigkeit

**Standard ist eine Wiederherstellung zur Zeit.** Sie läuft im Ernstfall, und dann zählt die Geschwindigkeit *einer* Wiederherstellung, nicht der Durchsatz mehrerer: Wer zwei gleichzeitig laufen lässt, halbiert die Geschwindigkeit derjenigen, auf die alle warten.

Ein Teilindex verhindert zwei gleichzeitige Wiederherstellungen in **dasselbe Ziel**. Sie schrieben sich gegenseitig zu — und zwar ohne dass es auffiele, weil beide erfolgreich endeten.

**Das Repository wird schreibgeschützt geöffnet.** Eine Wiederherstellung liest nur und kann deshalb neben einer laufenden Sicherung stattfinden, statt auf deren Schreibsperre zu warten. Im Ernstfall wartet niemand gern.

## Übergangene Objekte sind ein Teilfehler

Wie bei den Sicherungen: Eine Wiederherstellung, die zwei Dateien nicht zurückschreiben konnte, ist unvollständig. Sie darf nicht als Erfolg dastehen — der Anwender glaubte sonst, alles sei wieder da. Die Datenbank erzwingt das über ein CHECK.

## API

```
POST   /api/v1/restores/validate      restores.read      prüft, schreibt nichts
POST   /api/v1/restores               restores.execute   202: reiht ein, auditiert
GET    /api/v1/restores               restores.read      Liste mit Pagination
GET    /api/v1/restores/{id}          restores.read      inkl. Prüfpunkt bei Abbruch
POST   /api/v1/restores/{id}/cancel   restores.execute   auditiert
```

Die Vorabprüfung braucht nur das **Leserecht**: Sie schreibt nichts und soll niedrigschwellig sein — wer den Zustand der Backups beurteilen soll, muss sie ausführen können.

```json
{
  "backup_id": "…",
  "target_path": "/wiederhergestellt",
  "path_prefix": "dokumente/2026",
  "overwrite_existing": true,
  "confirm_overwrite": "/wiederhergestellt"
}
```

`path_prefix` beschränkt auf einen Teilbaum — der häufigste Fall im Betrieb ist nicht die vollständige Wiederherstellung, sondern eine einzelne versehentlich gelöschte Datei. Die Präfixgrenze achtet auf Verzeichnisse: `dokumente` trifft nicht auch `dokumentation`.

`POST /restores` antwortet mit **202**, nicht 201: Der Auftrag ist eingereiht, die Daten sind noch nicht zurück. Beim Abbruch wird ausdrücklich gesagt, dass bereits zurückgeschriebene Daten am Ziel liegen bleiben — sonst hielte man das Ziel für unberührt.

## Nachgewiesen

Gegen den laufenden Dienst, 11,4 MiB in 12 Objekten:

| Schritt | Ergebnis |
| --- | --- |
| Vorabprüfung | „Wiederherstellbar: 9 Dateien, 11.4 MiB", 16 Blöcke geprüft, 0 fehlend |
| Quelle gelöscht, über die API wiederhergestellt | `succeeded`, 12 Objekte in 0,11 s |
| Vergleich | **bitgenau identisch** inkl. Rechten (600), Symlink, leerem Verzeichnis |
| Volles Ziel ohne Zustimmung | abgelehnt |
| `overwrite_existing` ohne Bestätigung | abgelehnt, nennt den zu wiederholenden Pfad |
| Falscher Bestätigungswert | abgelehnt |
| Mit korrekter Bestätigung | 202, überschrieben, im Protokoll als Warnung |
| Ein Block entfernt | `can_proceed: false`, betroffene Datei benannt, Auftrag mit 422 abgelehnt |

## Offene Punkte

- **Keine Platten- und Systemwiederherstellung.** Sie setzen Provider voraus, die noch nicht liefern.
- **Proxmox-VM-Wiederherstellung** ist im Provider umgesetzt, aber ungeprüft und ohne `ArchiveTransport` nicht erreichbar.
- **Keine Fortsetzung über die API.** Der Prüfpunkt liegt vor und die Schleife nutzt ihn, aber es gibt keinen Endpunkt, der einen gescheiterten Auftrag erneut einreiht — nur den Weg über die Datenbank.
- **Kein `GET /restores/{id}/logs` und `/metrics`** (SYNCOVA_API.md §13).
- **Keine Wiederherstellung in der Oberfläche.** Sie geht nur über die API.
- **Kein Wiederherstellungstest als eigener Auftrag.** Das ist Phase 10 — und der Punkt, an dem aus „prüfbar" ein regelmäßiger Nachweis wird.