Jerrit Fritzsche
610719c316
Enterprise-Backup-, Recovery-, Verification-, Security- und Monitoring-Plattform fuer Proxmox VE, Windows, Linux und Dateisysteme. Der Leitsatz, der fast jede Entscheidung erklaert: Ein Backup gilt erst als vertrauenswuerdig, wenn Integritaet geprueft und Wiederherstellbarkeit nachgewiesen wurde. Deshalb steigt ein Wiederherstellungspunkt erst nach einem tatsaechlich durchgefuehrten Restore-Test auf "recoverable", und Unbekanntes geht in keine Bewertung als "gut" ein. Umfang (Phasen 0-23): - Repository Engine: inhaltsadressierte Bloecke, atomares Commit-Protokoll, Katalogaufbau allein aus den Manifesten — ohne Datenbank - Backup Engine: inhaltsabhaengiges Chunking, Deduplizierung trotz Verschluesselung, zstd, AES-256-GCM, Streaming mit Gegendruck - Agenten fuer Windows und Linux mit Auftragsabholung (Pull-Modell) - Proxmox-Provider mit beiden Zugriffswegen auf die Sicherungsarchive - Scheduler, Recovery Engine mit Pruefpunkt, Verification, Unveraenderlichkeit - Weboberflaeche, Kennzahlen, Meldungen, Berichte, Security Center, Ransomware-Heuristik (meldet, handelt nie) - Disaster Recovery, Haertung, Leistungsmessung, Chaos Testing - Eingefrorene Vertraege fuer API, Migrationen, Backup-Format und Repository - Auslieferungspaket fuer linux/amd64, linux/arm64 und windows/amd64 Nicht enthalten und als solches gekennzeichnet: Kapazitaetsprognose, Backup Copy, Changed Block Tracking bei Proxmox, erweiterte Attribute und ACLs. Gebaut, aber nie auf echter Hardware gefahren: der Windows-Dienst, die systemd-Einheit und der verpflichtende Proxmox-Meilenstein — ob eine wiederhergestellte VM startet, ist ungeprueft. Einzelheiten in CHANGELOG.md und docs/release-candidate.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
100 lines
3.9 KiB
Markdown
100 lines
3.9 KiB
Markdown
# Entwicklungsumgebung
|
|
|
|
## Voraussetzungen
|
|
|
|
| Werkzeug | Version | Zweck |
|
|
| --- | --- | --- |
|
|
| Go | 1.26+ | Backend, Agents, Migrationen |
|
|
| Node.js | 22+ | Weboberfläche |
|
|
| Docker | aktuell | lokale PostgreSQL-Instanz |
|
|
|
|
## Erstes Aufsetzen
|
|
|
|
```bash
|
|
make dev-env # erzeugt .env mit zufälligem Datenbankpasswort
|
|
make dev-up # startet PostgreSQL im Container
|
|
make migrate-up # legt das Datenbankschema an
|
|
```
|
|
|
|
`make dev-env` erzeugt das Passwort lokal per `openssl rand`. Die entstehende `.env` ist von der Versionsverwaltung ausgeschlossen und erhält die Berechtigung `600`. Eine bestehende `.env` wird nie überschrieben.
|
|
|
|
## Täglicher Ablauf
|
|
|
|
```bash
|
|
make run-api # API auf 127.0.0.1:8080
|
|
make web-dev # Oberfläche auf 127.0.0.1:5173
|
|
make check # alle Prüfungen wie in der CI
|
|
```
|
|
|
|
Der Entwicklungsserver der Oberfläche reicht `/api` und `/health` an den Go-Dienst weiter. Dadurch ist der Ursprung identisch und es wird lokal kein CORS benötigt.
|
|
|
|
## Konfiguration
|
|
|
|
Alle Einstellungen kommen aus Umgebungsvariablen mit dem Präfix `SYNCOVA_`. Die vollständige Liste steht in `.env.example`.
|
|
|
|
Zwei Eigenschaften sind bewusst so gestaltet:
|
|
|
|
- **Secrets haben keinen Standardwert.** Fehlt `SYNCOVA_DB_PASSWORD`, startet kein Dienst. Ein Standardpasswort wäre eine stillschweigend unsichere Konfiguration.
|
|
- **Alle Fehler werden gesammelt gemeldet.** Ein Start mit unvollständiger Konfiguration nennt sämtliche fehlenden Variablen auf einmal statt eine nach der anderen.
|
|
|
|
## Migrationen
|
|
|
|
```bash
|
|
make migrate-status # aktueller Stand
|
|
make migrate-up # alle ausstehenden Migrationen anwenden
|
|
make migrate-down # genau eine Migration zurücknehmen
|
|
```
|
|
|
|
Regeln:
|
|
|
|
- Migrationen laufen **nie** automatisch beim Start eines Dienstes. Der API-Dienst prüft beim Start lediglich, ob das Schema zu seiner Programmversion passt, und verweigert andernfalls den Start.
|
|
- `down` nimmt immer nur **einen** Schritt zurück. Ein versehentlicher Rücklauf auf Version 0 würde die gesamte Control Plane löschen.
|
|
- In der Produktion verlangt `down` zusätzlich `SYNCOVA_MIGRATE_CONFIRM_DOWN=yes`.
|
|
- Migrationen sind in das Binary eingebettet. Eine Installation bringt damit immer genau die Migrationen mit, die zu ihrer Version gehören.
|
|
|
|
Eine neue Migration anlegen:
|
|
|
|
```bash
|
|
# Nummer fortlaufend erhöhen, beide Richtungen anlegen
|
|
touch migrations/000002_users.up.sql migrations/000002_users.down.sql
|
|
```
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
make test # Go-Tests mit Race-Detector
|
|
make test-coverage # zusätzlich Coverage-Bericht
|
|
make web-test # Frontend-Tests
|
|
```
|
|
|
|
Der Race-Detector ist Standard, nicht optional: die Backup Engine wird stark nebenläufig arbeiten, und eine Datenrace-Warnung ist dort ein potenzieller Integritätsfehler.
|
|
|
|
## Codekonventionen
|
|
|
|
**Go**
|
|
|
|
- Kommentare an allen exportierten Deklarationen; sprechende Bezeichner statt Kürzel.
|
|
- Fehler werden klassifiziert und mit Kontext weitergereicht, nie verschluckt.
|
|
- Interne Fehlerursachen gehören ins Log, niemals in eine API-Antwort.
|
|
- Verbindungszeichenketten werden ausschließlich in redigierter Form ausgegeben (`RedactedConnectionString`).
|
|
|
|
**TypeScript**
|
|
|
|
- `strict` samt `noUncheckedIndexedAccess` und `exactOptionalPropertyTypes`.
|
|
- Jede API-Antwort läuft über `requestApi`; Fehler kommen dort immer als `ApiError` an.
|
|
- Es werden nie Platzhalterwerte angezeigt. Solange kein echtes Ergebnis vorliegt, zeigt die Oberfläche „lädt“ oder eine Fehlermeldung.
|
|
|
|
## Fehlersuche
|
|
|
|
**Der API-Dienst startet nicht und meldet einen Schemastand**
|
|
|
|
Das Datenbankschema passt nicht zur Programmversion. `make migrate-status` zeigt den Stand, `make migrate-up` behebt es.
|
|
|
|
**`make dev-up` meldet einen fehlenden Docker-Daemon**
|
|
|
|
Docker Desktop starten und erneut versuchen.
|
|
|
|
**Ein Request lässt sich im Log nicht wiederfinden**
|
|
|
|
Jede Antwort trägt `X-Request-ID` und `X-Correlation-ID` im Header sowie `meta.request_id` im Body. Die Correlation ID steht in jeder zugehörigen Logzeile.
|