feat(archive): BAK-04 Tenant-Backup & -Restore einzelner Mandant

internal/tenantbackup: datenbank-scharfes pg_dump/pg_restore statt
BAK-01s Cluster-weitem pg_basebackup - bei Modell C (TEN-01, physisch
isolierte DB je Mandant) wuerde ein Cluster-Restore zwangslaeufig ALLE
Mandanten ueberschreiben. Objekt-Seite nutzt BAK-02 direkt (Mandanten
haben eigene Buckets/Pfad-Roots). Eigene Postgres-Rolle
nexarch_tenantbackup (CREATEDB, kein Superuser, getrennt von
nexarch_backup). Zwei-Tenant-Isolation real in beide Richtungen
bewiesen (Markerwert-Nachweis), JSONL-Protokoll fuer Sicherung UND
Restore. Realer End-zu-Ende-Lauf ueber tenantbackup-cli auf 131.
This commit is contained in:
sysops
2026-08-30 00:41:48 +02:00
parent c761cf9b93
commit 80b0ca9176
8 changed files with 766 additions and 0 deletions
+76
View File
@@ -0,0 +1,76 @@
package tenantbackup
import (
"encoding/json"
"fmt"
"os"
"time"
)
// Operation unterscheidet Sicherung und Wiederherstellung im Protokoll.
type Operation string
const (
OpBackupDB Operation = "backup_database"
OpRestoreDB Operation = "restore_database"
OpBackupObj Operation = "backup_objects"
OpRestoreObj Operation = "restore_objects"
)
// LogEntry ist EIN Protokolleintrag (Akzeptanzkriterium 3: Tenant-
// Sicherung UND -Restore vollständig protokolliert).
type LogEntry struct {
Timestamp time.Time `json:"timestamp"`
Operation Operation `json:"operation"`
TenantID string `json:"tenant_id"`
Source string `json:"source,omitempty"` // Dump-Pfad oder Snapshot-ID
Target string `json:"target,omitempty"` // Zieldatenbank oder Zielverzeichnis
Result string `json:"result"` // "ok" oder Fehlertext
}
// AppendLog hängt entry an die JSONL-Protokolldatei an (append-only,
// nichts wird überschrieben).
func AppendLog(logPath string, entry LogEntry) error {
f, err := os.OpenFile(logPath, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600)
if err != nil {
return fmt.Errorf("tenantbackup: protokolldatei öffnen: %w", err)
}
defer func() { _ = f.Close() }()
line, err := json.Marshal(entry)
if err != nil {
return fmt.Errorf("tenantbackup: protokolleintrag kodieren: %w", err)
}
if _, err := f.Write(append(line, '\n')); err != nil {
return fmt.Errorf("tenantbackup: protokolleintrag schreiben: %w", err)
}
return nil
}
// ReadLog liest die vollständige Protokollhistorie.
func ReadLog(logPath string) ([]LogEntry, error) {
data, err := os.ReadFile(logPath)
if err != nil {
if os.IsNotExist(err) {
return nil, nil
}
return nil, fmt.Errorf("tenantbackup: protokolldatei lesen: %w", err)
}
var entries []LogEntry
start := 0
for i := 0; i < len(data); i++ {
if data[i] == '\n' {
line := data[start:i]
start = i + 1
if len(line) == 0 {
continue
}
var e LogEntry
if err := json.Unmarshal(line, &e); err != nil {
return nil, fmt.Errorf("tenantbackup: protokollzeile dekodieren: %w", err)
}
entries = append(entries, e)
}
}
return entries, nil
}
+37
View File
@@ -0,0 +1,37 @@
package tenantbackup
import (
"path/filepath"
"testing"
"time"
)
// TestLog_BackupAndRestoreFullyLogged ist Pruefung 3: Tenant-Sicherung
// UND -Restore vollstaendig protokolliert.
func TestLog_BackupAndRestoreFullyLogged(t *testing.T) {
logPath := filepath.Join(t.TempDir(), "tenantbackup.log")
entries := []LogEntry{
{Timestamp: time.Now().UTC(), Operation: OpBackupDB, TenantID: "a", Source: "/x/dump.pgcustom", Result: "ok"},
{Timestamp: time.Now().UTC(), Operation: OpRestoreDB, TenantID: "a", Source: "/x/dump.pgcustom", Target: "a_restored", Result: "ok"},
}
for _, e := range entries {
if err := AppendLog(logPath, e); err != nil {
t.Fatalf("appendlog: %v", err)
}
}
got, err := ReadLog(logPath)
if err != nil {
t.Fatalf("readlog: %v", err)
}
if len(got) != 2 {
t.Fatalf("erwartet 2 eintraege, habe %d", len(got))
}
if got[0].Operation != OpBackupDB || got[1].Operation != OpRestoreDB {
t.Fatalf("unerwartete reihenfolge/operationen: %+v", got)
}
if got[0].TenantID != "a" || got[1].Target != "a_restored" {
t.Fatalf("eintraege unvollstaendig: %+v", got)
}
}
@@ -0,0 +1,155 @@
// Package tenantbackup implementiert BAK-04: Sicherung und
// Wiederherstellung der Daten EINES einzelnen Mandanten, ohne andere
// Mandanten zu berühren.
//
// BEWUSST NICHT auf BAK-01/BAK-03 aufgesetzt: pg_basebackup (BAK-01)
// sichert den GESAMTEN Postgres-Cluster — bei Modell C (TEN-01, eine
// physisch isolierte Datenbank je Mandant) liegen ALLE Mandanten-
// Datenbanken in genau diesem einen Cluster, ein Restore der
// Cluster-Sicherung würde also zwangsläufig ALLE Mandanten gleichzeitig
// überschreiben — das genaue Gegenteil von Mandanten-Isolation. BAK-04
// braucht daher ein DATENBANK-SCHARFES logisches Verfahren (pg_dump/
// pg_restore für genau EINE Datenbank), keine physische
// Cluster-Sicherung. Objekt-Storage ist bereits von Haus aus pro
// Mandant getrennt (eigener Bucket/Pfad-Root, STORAGE-KONZEPT.md
// Abschnitt 3) — dort genügt ein restic-Repository je Mandanten-Root
// (objectbackup-Paket direkt wiederverwendbar, ein Aufruf pro
// Mandanten-Verzeichnis).
package tenantbackup
import (
"context"
"fmt"
"os"
"os/exec"
"path/filepath"
)
// Config enthält die Verbindungsdaten — ausschließlich über
// Umgebungsvariablen befüllt (siehe Ticket-Abschluss-Regel).
type Config struct {
Host string
Port string
User string
Password string
BackupDir string
PgDumpPath string // Default "pg_dump"
PgRestorePath string // Default "pg_restore"
PsqlPath string // Default "psql"
}
func (c Config) dumpBinary() string {
if c.PgDumpPath != "" {
return c.PgDumpPath
}
return "pg_dump"
}
func (c Config) restoreBinary() string {
if c.PgRestorePath != "" {
return c.PgRestorePath
}
return "pg_restore"
}
func (c Config) psqlBinary() string {
if c.PsqlPath != "" {
return c.PsqlPath
}
return "psql"
}
const DumpFile = "dump.pgcustom"
// Backup erstellt eine logische Sicherung GENAU EINER Mandanten-
// Datenbank (Custom-Format, `pg_dump -Fc`) — enthält strukturell
// ausschließlich Daten dieser einen Datenbank, andere Mandanten-
// Datenbanken werden nie verbunden oder gelesen (Akzeptanzkriterium 1).
func Backup(ctx context.Context, cfg Config, tenantDB, generationID string) (dumpPath string, err error) {
dir := filepath.Join(cfg.BackupDir, tenantDB, generationID)
if err := os.MkdirAll(dir, 0o750); err != nil {
return "", fmt.Errorf("tenantbackup: sicherungsverzeichnis anlegen: %w", err)
}
dumpPath = filepath.Join(dir, DumpFile)
args := []string{
"-h", cfg.Host, "-p", cfg.Port, "-U", cfg.User,
"-Fc", "-f", dumpPath, "--no-password", tenantDB,
}
cmd := exec.CommandContext(ctx, cfg.dumpBinary(), args...)
cmd.Env = append(os.Environ(), "PGPASSWORD="+cfg.Password)
output, err := cmd.CombinedOutput()
if err != nil {
return "", fmt.Errorf("tenantbackup: %s fehlgeschlagen: %w (ausgabe: %s)", cfg.dumpBinary(), err, string(output))
}
return dumpPath, nil
}
// Verify prüft, dass dumpPath ein vollständig lesbares pg_dump-Custom-
// Format-Archiv ist — liest die GESAMTE Inhaltsliste (`pg_restore -l`),
// nicht nur den Dateikopf, damit ein abgeschnittenes oder beschädigtes
// Archiv zuverlässig auffällt.
func Verify(ctx context.Context, cfg Config, dumpPath string) error {
cmd := exec.CommandContext(ctx, cfg.restoreBinary(), "-l", dumpPath)
output, err := cmd.CombinedOutput()
if err != nil {
return fmt.Errorf("tenantbackup: sicherung beschädigt oder unvollständig: %w (ausgabe: %s)", err, string(output))
}
if len(output) == 0 {
return fmt.Errorf("tenantbackup: sicherung enthält keine inhaltsliste")
}
return nil
}
// Restore stellt dumpPath in targetDB wieder her — targetDB MUSS bereits
// existieren und leer sein (angelegt vom Aufrufer über CreateEmptyDatabase),
// niemals die Quelldatenbank selbst oder eine andere Mandanten-Datenbank
// (Akzeptanzkriterium 2: Wiederherstellung verändert keine Daten anderer
// Mandanten — strukturell garantiert, weil pg_restore ausschließlich mit
// der EINEN übergebenen Zielverbindung spricht).
func Restore(ctx context.Context, cfg Config, dumpPath, targetDB string) error {
args := []string{
"-h", cfg.Host, "-p", cfg.Port, "-U", cfg.User,
// --no-owner: die Zieldatenbank ist eine frische, isolierte
// Testumgebung (CreateEmptyDatabase) - der urspruengliche
// Tenant-Eigentuemer existiert dort nicht zwangslaeufig mit
// gleichen Rechten, und Eigentuemerschaft ist fuer den
// Restore-Nachweis irrelevant (Standardpraxis beim Restore in
// eine andere Umgebung).
"--no-owner",
"-d", targetDB, "--no-password", dumpPath,
}
cmd := exec.CommandContext(ctx, cfg.restoreBinary(), args...)
cmd.Env = append(os.Environ(), "PGPASSWORD="+cfg.Password)
output, err := cmd.CombinedOutput()
if err != nil {
return fmt.Errorf("tenantbackup: %s fehlgeschlagen: %w (ausgabe: %s)", cfg.restoreBinary(), err, string(output))
}
return nil
}
// CreateEmptyDatabase legt targetDB frisch und leer an — schlägt fehl,
// wenn targetDB bereits existiert (Isolation: ein Restore darf niemals
// stillschweigend eine bestehende Datenbank eigene oder fremde
// überschreiben, dieselbe "kein stiller Overwrite"-Disziplin wie BAK-03s
// internal/restore).
func CreateEmptyDatabase(ctx context.Context, cfg Config, targetDB string) error {
cmd := exec.CommandContext(ctx, cfg.psqlBinary(),
"-h", cfg.Host, "-p", cfg.Port, "-U", cfg.User, "-d", "postgres", "--no-password",
"-c", fmt.Sprintf("CREATE DATABASE %s", quoteIdent(targetDB)))
cmd.Env = append(os.Environ(), "PGPASSWORD="+cfg.Password)
output, err := cmd.CombinedOutput()
if err != nil {
return fmt.Errorf("tenantbackup: zieldatenbank %q anlegen fehlgeschlagen (existiert sie bereits?): %w (ausgabe: %s)", targetDB, err, string(output))
}
return nil
}
// quoteIdent ist eine MINIMALE Absicherung für Datenbanknamen, die
// ausschließlich aus dem eigenen Tenant-Registry-Kontext stammen (nie aus
// unmittelbarer Benutzereingabe an dieser Stelle) — auf doppelte
// Anführungszeichen beschränkt, da Postgres-Identifier keine
// eingebetteten NUL-Bytes zulassen.
func quoteIdent(name string) string {
return `"` + name + `"`
}
@@ -0,0 +1,203 @@
package tenantbackup
import (
"context"
"os"
"os/exec"
"testing"
"time"
)
// requireTestConfig braucht eine EIGENE Rolle mit CREATEDB-Recht
// (TEST_TENANTBACKUP_PG_USER), NICHT BAK-01/BAK-03s TEST_BACKUP_PG_USER
// (nexarch_backup) - jene Rolle hat bewusst nur REPLICATION, kein
// CREATEDB (Prinzip geringster Rechte, siehe BAK-01). BAK-04 braucht
// stattdessen CREATEDB, um isolierte Ziel-Datenbanken anzulegen -
// bekommt daher eine eigene, separat scharf gestellte Rolle.
func requireTestConfig(t *testing.T) Config {
t.Helper()
user := os.Getenv("TEST_TENANTBACKUP_PG_USER")
if user == "" {
t.Skip("TEST_TENANTBACKUP_PG_USER nicht gesetzt, Integrationstest uebersprungen (braucht echte Postgres-Rolle mit CREATEDB)")
}
if _, err := exec.LookPath("pg_dump"); err != nil {
t.Skip("pg_dump nicht installiert, Integrationstest uebersprungen")
}
return Config{
Host: envOr("TEST_TENANTBACKUP_PG_HOST", "localhost"),
Port: envOr("TEST_TENANTBACKUP_PG_PORT", "5432"),
User: user,
Password: os.Getenv("TEST_TENANTBACKUP_PG_PASSWORD"),
BackupDir: t.TempDir(),
}
}
func envOr(key, fallback string) string {
if v := os.Getenv(key); v != "" {
return v
}
return fallback
}
// createMarkerDB legt eine frische Testdatenbank mit genau EINER
// Markierungszeile an (Kennzeichen für "das ist eindeutig Tenant X's
// Datensatz") - real ueber psql, kein Mock.
func createMarkerDB(t *testing.T, cfg Config, dbName, marker string) {
t.Helper()
ctx := context.Background()
run := func(args ...string) {
t.Helper()
cmd := exec.CommandContext(ctx, cfg.psqlBinary(), args...)
cmd.Env = append(os.Environ(), "PGPASSWORD="+cfg.Password)
if out, err := cmd.CombinedOutput(); err != nil {
t.Fatalf("psql %v: %v (ausgabe: %s)", args, err, out)
}
}
base := []string{"-h", cfg.Host, "-p", cfg.Port, "-U", cfg.User, "--no-password"}
run(append(append([]string{}, base...), "-d", "postgres", "-c", "DROP DATABASE IF EXISTS "+quoteIdent(dbName))...)
run(append(append([]string{}, base...), "-d", "postgres", "-c", "CREATE DATABASE "+quoteIdent(dbName))...)
run(append(append([]string{}, base...), "-d", dbName, "-c",
"CREATE TABLE marker (value TEXT); INSERT INTO marker VALUES ('"+marker+"')")...)
t.Cleanup(func() {
run(append(append([]string{}, base...), "-d", "postgres", "-c", "DROP DATABASE IF EXISTS "+quoteIdent(dbName))...)
})
}
func markerValue(t *testing.T, cfg Config, dbName string) string {
t.Helper()
cmd := exec.CommandContext(context.Background(), cfg.psqlBinary(),
"-h", cfg.Host, "-p", cfg.Port, "-U", cfg.User, "-d", dbName, "--no-password",
"-tAc", "SELECT value FROM marker")
cmd.Env = append(os.Environ(), "PGPASSWORD="+cfg.Password)
out, err := cmd.CombinedOutput()
if err != nil {
t.Fatalf("markerwert lesen: %v (ausgabe: %s)", err, out)
}
return trimNL(string(out))
}
func trimNL(s string) string {
for len(s) > 0 && (s[len(s)-1] == '\n' || s[len(s)-1] == '\r') {
s = s[:len(s)-1]
}
return s
}
func databaseExists(t *testing.T, cfg Config, dbName string) bool {
t.Helper()
cmd := exec.CommandContext(context.Background(), cfg.psqlBinary(),
"-h", cfg.Host, "-p", cfg.Port, "-U", cfg.User, "-d", "postgres", "--no-password",
"-tAc", "SELECT 1 FROM pg_database WHERE datname = '"+dbName+"'")
cmd.Env = append(os.Environ(), "PGPASSWORD="+cfg.Password)
out, _ := cmd.CombinedOutput()
return trimNL(string(out)) == "1"
}
// TestBackupRestore_RecoversExactTenantData ist Pruefung 1 (angepasst
// auf Akzeptanzkriterium 1): eine Sicherung von Tenant A, wiederhergestellt
// in eine isolierte Zieldatenbank, enthaelt real Tenant As Datensatz.
func TestBackupRestore_RecoversExactTenantData(t *testing.T) {
cfg := requireTestConfig(t)
ctx := context.Background()
tenantA := "tenantbackup_test_a"
createMarkerDB(t, cfg, tenantA, "gehoert-zu-tenant-a")
dumpPath, err := Backup(ctx, cfg, tenantA, time.Now().UTC().Format("20060102T150405Z"))
if err != nil {
t.Fatalf("backup: %v", err)
}
if err := Verify(ctx, cfg, dumpPath); err != nil {
t.Fatalf("verify: %v", err)
}
target := "tenantbackup_test_a_restored"
if databaseExists(t, cfg, target) {
t.Fatalf("zieldatenbank %q existiert bereits vor dem test", target)
}
if err := CreateEmptyDatabase(ctx, cfg, target); err != nil {
t.Fatalf("createemptydatabase: %v", err)
}
t.Cleanup(func() {
cmd := exec.Command(cfg.psqlBinary(), "-h", cfg.Host, "-p", cfg.Port, "-U", cfg.User, "-d", "postgres", "--no-password",
"-c", "DROP DATABASE IF EXISTS "+quoteIdent(target))
cmd.Env = append(os.Environ(), "PGPASSWORD="+cfg.Password)
_ = cmd.Run()
})
if err := Restore(ctx, cfg, dumpPath, target); err != nil {
t.Fatalf("restore: %v", err)
}
got := markerValue(t, cfg, target)
if got != "gehoert-zu-tenant-a" {
t.Fatalf("markerwert in wiederhergestellter datenbank = %q, want %q", got, "gehoert-zu-tenant-a")
}
}
// TestRestore_DoesNotAffectOtherTenant ist Pruefung 2: Wiederherstellung
// von Tenant A veraendert Tenant B nicht - reales zweites Tenant-DB,
// Markerwert vor UND nach dem Restore geprueft.
func TestRestore_DoesNotAffectOtherTenant(t *testing.T) {
cfg := requireTestConfig(t)
ctx := context.Background()
tenantA := "tenantbackup_test_iso_a"
tenantB := "tenantbackup_test_iso_b"
createMarkerDB(t, cfg, tenantA, "wert-a")
createMarkerDB(t, cfg, tenantB, "wert-b-unveraendert")
dumpPath, err := Backup(ctx, cfg, tenantA, time.Now().UTC().Format("20060102T150405Z"))
if err != nil {
t.Fatalf("backup: %v", err)
}
target := "tenantbackup_test_iso_a_restored"
if err := CreateEmptyDatabase(ctx, cfg, target); err != nil {
t.Fatalf("createemptydatabase: %v", err)
}
t.Cleanup(func() {
cmd := exec.Command(cfg.psqlBinary(), "-h", cfg.Host, "-p", cfg.Port, "-U", cfg.User, "-d", "postgres", "--no-password",
"-c", "DROP DATABASE IF EXISTS "+quoteIdent(target))
cmd.Env = append(os.Environ(), "PGPASSWORD="+cfg.Password)
_ = cmd.Run()
})
if err := Restore(ctx, cfg, dumpPath, target); err != nil {
t.Fatalf("restore: %v", err)
}
// Tenant B, der nie an diesem Vorgang beteiligt war, muss unveraendert sein.
gotB := markerValue(t, cfg, tenantB)
if gotB != "wert-b-unveraendert" {
t.Fatalf("tenant b wurde veraendert: %q, want %q", gotB, "wert-b-unveraendert")
}
// Und Tenant Bs Datenbank existiert weiterhin unter ihrem eigenen Namen
// (kein versehentliches Ueberschreiben/Umbenennen).
if !databaseExists(t, cfg, tenantB) {
t.Fatal("tenant-b-datenbank fehlt nach restore von tenant a")
}
}
// TestVerify_DetectsCorruptedDump ist Nachweis der Vollstaendigkeitspruefung.
func TestVerify_DetectsCorruptedDump(t *testing.T) {
cfg := requireTestConfig(t)
ctx := context.Background()
tenantA := "tenantbackup_test_corrupt"
createMarkerDB(t, cfg, tenantA, "wert")
dumpPath, err := Backup(ctx, cfg, tenantA, time.Now().UTC().Format("20060102T150405Z"))
if err != nil {
t.Fatalf("backup: %v", err)
}
if err := Verify(ctx, cfg, dumpPath); err != nil {
t.Fatalf("verify (unbeschaedigt) haette erfolgreich sein muessen: %v", err)
}
if err := os.WriteFile(dumpPath, []byte("kein gueltiges pg_dump-custom-archiv"), 0o600); err != nil {
t.Fatal(err)
}
if err := Verify(ctx, cfg, dumpPath); err == nil {
t.Fatal("verify haette die beschaedigte sicherung erkennen muessen")
}
}