jf/syncova-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
0c5a106a83
syncova-backup/docs/development.md
Jerrit Fritzsche 610719c316
Some checks failed
CI / Backend (Go) (push) Failing after 3m7s
Details
CI / Frontend (React/TypeScript) (push) Successful in 37s
Details
CI / Sicherheitsprüfungen (push) Successful in 44s
Details
Syncova Backups V1 
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>
2026-08-17 09:10:54 +02:00

3.9 KiB
Raw Blame History

Entwicklungsumgebung

Voraussetzungen

Werkzeug Version Zweck
Go 1.26+ Backend, Agents, Migrationen
Node.js 22+ Weboberfläche
Docker aktuell lokale PostgreSQL-Instanz

Erstes Aufsetzen

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

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

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:

# Nummer fortlaufend erhöhen, beide Richtungen anlegen
touch migrations/000002_users.up.sql migrations/000002_users.down.sql

Tests

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.