Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
@@ -0,0 +1,188 @@
|
||||
# Plattform-Leads: Backup, Backfill und Cutover
|
||||
|
||||
Dieses Runbook ist der operative Vertrag fuer `R-LEADS` (`HIVEGRID-73`). Es
|
||||
ersetzt den separaten `lead-inbox`-Schreibpfad kontrolliert durch
|
||||
`POST /v1/platform/leads`, ohne die letzte restorable Kopie der Altdaten zu
|
||||
loeschen.
|
||||
|
||||
## Sicherheitsregeln
|
||||
|
||||
- Kein Producer-Deploy ohne unmittelbar davor wiederholte Inventur und Sicherung
|
||||
seines tatsaechlich beschriebenen Fallback-Stores.
|
||||
- Backups enthalten PII und werden deshalb nie unverschluesselt im Repo, in
|
||||
Tickets, Logs oder Import-Manifests abgelegt.
|
||||
- Der verschluesselte Offsite-Stand liegt im privaten Hetzner-Bucket
|
||||
`hivegrid-prod`; Objektpraefixe und Hashes duerfen als PII-freier Proof
|
||||
dokumentiert werden.
|
||||
- Import-Manifests enthalten nur Quelle, Zaehler, Zeitbereich, Hashes und
|
||||
technische Run-IDs.
|
||||
- Ein Import erzeugt weder Benachrichtigungen noch Marketing-Automationen.
|
||||
- Das letzte verschluesselte Backup bleibt erhalten, bis ein eigener
|
||||
Retention-/Loeschentscheid bestaetigt wurde.
|
||||
|
||||
## Erster Safety-Snapshot
|
||||
|
||||
Der Snapshot vom 2026-07-16 liegt unter
|
||||
`backups/platform-leads/20260716T033754Z`. Sein PII-freies Inventar und die
|
||||
Restore-Ergebnisse stehen in
|
||||
`docs/ops/evidence/r-leads-safety-inventory-20260716.json`.
|
||||
|
||||
Ergebnis:
|
||||
|
||||
- `lead-inbox` Postgres: 1 Datensatz, Custom-Dump in frisches Postgres 16
|
||||
restauriert.
|
||||
- HiveGrid-Website Produktion: kein SQLite-File im laufenden Container und kein
|
||||
persistentes Volume; 0 Datensaetze.
|
||||
- HiveGrid-Website Staging: 1 Datensatz, konsistentes SQLite-Backup,
|
||||
`integrity_check=ok`.
|
||||
- HiveGrid-Cloud `Lead`/`LeadEvent`: Produktion 0/0, Staging 0/0.
|
||||
|
||||
Zusaetzlich wurde irrtuemlich ein nicht zu HiveGrid gehoerender Website-Dateistore
|
||||
inventarisiert und verschluesselt gesichert. Das Objekt bleibt zur Vermeidung einer
|
||||
unautorisierten Datenvernichtung erhalten, ist im Evidence-Inventar jedoch mit
|
||||
`excluded_from_hivegrid_import: true` markiert und darf weder als Quelle
|
||||
konfiguriert noch importiert werden. Aufbewahrung oder Loeschung erfordern einen
|
||||
separaten, ausdruecklich autorisierten Retention-/Loeschentscheid.
|
||||
|
||||
## Operator-Tooling
|
||||
|
||||
Vor dem Source-Dry-Run muss der Canary `/leads` mit einer aktiven AdminUser-
|
||||
Identität und der vorgesehenen Sales-Rolle erreichen. Der API-Schalter
|
||||
`PLATFORM_LEADS_INGRESS_ENABLED` schützt unabhängig davon nur den externen Ingress.
|
||||
|
||||
Der Routing-Operator erhaelt vor dem Bootstrap eine Plattformrolle mit mindestens
|
||||
`admin.leads.read_own` und `admin.leads.write`. Der ausfuehrende Operator braucht
|
||||
`admin.leads.admin`. Das Bootstrap-Tool prueft aktiven AdminUser und diese
|
||||
Rechte fail-closed, bevor es einen Plan erzeugt oder Quellen mutiert. Fuer den
|
||||
Haris-Canary wird zusaetzlich verifiziert: Login auf `admin.hivegrid.de`,
|
||||
`/leads` erreichbar, zugewiesener synthetischer Lead sichtbar und eine
|
||||
Status-/Notizmutation erfolgreich.
|
||||
|
||||
Die nativen Quellen werden idempotent ueber den AdminLead-Domain-Service
|
||||
konfiguriert. Haris' Admin-User-ID wird zur Laufzeit uebergeben und ist keine
|
||||
Code-Konstante. Der Dry-Run erzeugt einen PII-freien Plan-Hash; Apply akzeptiert
|
||||
nur genau diesen Stand:
|
||||
|
||||
```bash
|
||||
pnpm platform-leads:source-bootstrap -- \
|
||||
--mode dry-run \
|
||||
--actor-admin-user-id "$PLATFORM_ADMIN_USER_ID" \
|
||||
--routing-admin-user-id "$HARIS_ADMIN_USER_ID" \
|
||||
--manifest "$EVIDENCE_DIR/source-bootstrap.dry-run.json"
|
||||
|
||||
pnpm platform-leads:source-bootstrap -- \
|
||||
--mode apply \
|
||||
--actor-admin-user-id "$PLATFORM_ADMIN_USER_ID" \
|
||||
--routing-admin-user-id "$HARIS_ADMIN_USER_ID" \
|
||||
--expected-plan-sha256 "$PLAN_SHA256" \
|
||||
--manifest "$EVIDENCE_DIR/source-bootstrap.apply.json"
|
||||
```
|
||||
|
||||
Die aktuelle Website-Quelle wird aktiviert, Haris wird als Default-Assignee
|
||||
und mindestens als Notification-Empfaenger konfiguriert. Bereits vorhandene
|
||||
weitere Empfaenger bleiben erhalten. Die beiden reinen Importquellen bleiben
|
||||
deaktiviert. Das Bootstrap-Tool stellt bewusst keine Credentials aus; deren
|
||||
einmalig angezeigter Klartext wird ueber `/leads/sources` erzeugt und direkt in
|
||||
den jeweiligen Server-Runtime-Secrets hinterlegt.
|
||||
|
||||
Der Backfill liest UTF-8-JSONL oder ein JSON-Array. Die feste Zuordnung ist:
|
||||
|
||||
| Legacy-Store | Native Source |
|
||||
|---|---|
|
||||
| `lead-inbox-postgres` | `lead-inbox-legacy` |
|
||||
| `hivegrid-website-production-sqlite` | `hivegrid-website` |
|
||||
| `hivegrid-website-staging-sqlite` | `hivegrid-website` |
|
||||
| `hivegrid-cloud-legacy` | `hivegrid-legacy-cloud` |
|
||||
|
||||
Pro Store wird zuerst ein Dry-Run mit einer neuen Manifest-Datei ausgefuehrt.
|
||||
Apply und Replay verlangen sowohl dessen exakten Input-Hash als auch die
|
||||
akzeptierte Zeilenzahl und schreiben bei Drift oder Rejections keine Zeile:
|
||||
|
||||
```bash
|
||||
pnpm platform-leads:backfill -- \
|
||||
--mode dry-run \
|
||||
--store "$LEGACY_STORE" \
|
||||
--input "$RESTORED_EXPORT" \
|
||||
--manifest "$EVIDENCE_DIR/$LEGACY_STORE.dry-run.json"
|
||||
|
||||
pnpm platform-leads:backfill -- \
|
||||
--mode apply \
|
||||
--store "$LEGACY_STORE" \
|
||||
--input "$RESTORED_EXPORT" \
|
||||
--actor-admin-user-id "$PLATFORM_ADMIN_USER_ID" \
|
||||
--expected-input-sha256 "$INPUT_SHA256" \
|
||||
--expected-accepted "$ACCEPTED_COUNT" \
|
||||
--manifest "$EVIDENCE_DIR/$LEGACY_STORE.apply.json"
|
||||
|
||||
pnpm platform-leads:backfill -- \
|
||||
--mode replay \
|
||||
--store "$LEGACY_STORE" \
|
||||
--input "$RESTORED_EXPORT" \
|
||||
--actor-admin-user-id "$PLATFORM_ADMIN_USER_ID" \
|
||||
--expected-input-sha256 "$INPUT_SHA256" \
|
||||
--expected-accepted "$ACCEPTED_COUNT" \
|
||||
--manifest "$EVIDENCE_DIR/$LEGACY_STORE.replay.json"
|
||||
```
|
||||
|
||||
Ein erfolgreicher Replay hat `created=0`, `failed=0` und keine Gate-Failures.
|
||||
Die Manifeste enthalten nur Hashes, Zaehler, technische IDs und Zeitbereiche;
|
||||
Input-Pfade, Lead-Inhalte und Klartext-Legacy-IDs werden nicht aufgenommen. Jede
|
||||
Manifest-Datei wird exklusiv mit Modus `0600` angelegt und nicht ueberschrieben.
|
||||
Importe laufen ausschliesslich ueber `importLead`, bewahren Originalzeitpunkte,
|
||||
native Legacy-Status und unterstuetzte Activities und loesen weder M011-
|
||||
Benachrichtigungen noch Automationen aus.
|
||||
|
||||
Cloud-Legacy-Status werden verlustarm auf den nativen M040a-Vertrag abgebildet:
|
||||
`trial` und `customer` werden `qualified`, `churned` wird `disqualified`; der
|
||||
Originalwert bleibt als `metadata.legacyStatus` erhalten. Historische
|
||||
`score-changed`- und `converted`-Events werden als `legacy_event` mit
|
||||
`legacyType` im begrenzten Activity-Payload uebernommen. Unbekannte Status- oder
|
||||
Eventtypen bleiben Rejections und stoppen Apply. Damit wird keine M040b-
|
||||
Deal-Semantik vorgezogen, aber der historische Verlauf geht nicht verloren.
|
||||
|
||||
## Cutover-Reihenfolge
|
||||
|
||||
1. Native Tabellen, RLS/Pre-Tenant-Capability, Domain-Service, API, Worker und
|
||||
Admin-Inbox nach Staging deployen; Operatorrolle wie oben anlegen und
|
||||
Berechtigungs- sowie Direkt-Routen gegen 404 pruefen.
|
||||
2. Source-Credentials einmalig erzeugen und ausschliesslich in den jeweiligen
|
||||
Server-Runtime-Secrets speichern.
|
||||
3. Staging-Canary je Source ausfuehren: Create, identischer Replay, Hash-Konflikt,
|
||||
Auth-Fehler, Rate-Limit, Delivery/Retry und Admin-Bearbeitung.
|
||||
4. Alle Altquellen dry-run importieren. Zaehler und Hashes gegen das Safety-
|
||||
Inventar pruefen.
|
||||
5. Apply und anschliessenden Replay ausfuehren. Der Replay muss `created=0`
|
||||
liefern.
|
||||
6. Direkt vor jedem Website-Deploy den jeweiligen aktuellen Store erneut sichern
|
||||
und nur das Finaldelta importieren.
|
||||
7. Producer einzeln umstellen; nach jeder Quelle einen synthetisch markierten
|
||||
Produktions-Canary und den Admin-/Delivery-Nachweis abwarten.
|
||||
8. Legacy-Endpoint read-only/drain-faehig belassen und mindestens sieben volle
|
||||
Tage auf eingehenden Traffic, Fehler, Queue-Failures und Source-Lag beobachten.
|
||||
9. Nur bei Nulltraffic: App stoppen, Secrets revoken, DNS entfernen und Repo
|
||||
archivieren. Die Datenbank nicht irreversibel loeschen.
|
||||
|
||||
## Rollback
|
||||
|
||||
Innerhalb des Drain-Fensters werden Producer-Secrets/URLs auf den weiterhin
|
||||
laufenden Legacy-Endpoint zurueckgestellt. Nach einem bereits erfolgten Stop wird
|
||||
das letzte bekannte Image gestartet und Postgres aus dem geprueften Custom-Dump
|
||||
restauriert. Native Importe sind idempotent und loeschen keine Quelle; sie muessen
|
||||
fuer einen Rollback nicht rueckgaengig gemacht werden.
|
||||
|
||||
## Decommission-Gates
|
||||
|
||||
Der externe Dienst darf erst gestoppt werden, wenn alle folgenden Nachweise gruen
|
||||
sind:
|
||||
|
||||
- der HiveGrid-Website-Producer produktiv auf dem nativen Endpoint;
|
||||
- Finaldelta importiert und Replay `created=0`;
|
||||
- sieben volle Tage kein Legacy-Write-Traffic;
|
||||
- Native-API-, Admin- und Notification-Monitoring ohne offene kritische Fehler;
|
||||
- letzter Dump offsite vorhanden und Restore erneut erfolgreich;
|
||||
- DNS-/Secret-/Mailjet-Abhaengigkeiten inventarisiert und Rollback-Werte sicher
|
||||
hinterlegt.
|
||||
|
||||
DNS-Loeschung, Secret-Revoke und App-Stop werden mit Zeitstempel und externer
|
||||
Run-ID in der Ticket-Doc dokumentiert. Eine endgueltige Backup- oder DB-Loeschung
|
||||
ist nicht Teil dieses Tickets.
|
||||
Reference in new issue
Block a user