81 KiB
Jinkendo – Release, Betrieb & Recovery Blueprint
v0.1 · 16.10.2026 · Spezial-Blueprint nach Phase 3.3 · keine Implementierung oder Betriebsfreigabe
1. Auftrag, Grundlage und Nachweis
Dieser Blueprint konkretisiert den Weg vom qualifizierten Quellstand bis zum nachvollziehbaren Produktionsbetrieb und zur Wiederherstellung nach einem Fehler. Er ist ein Implementierungsauftrag für Cursor im später ausdrücklich benannten Zielrepository. In dieser Lieferung werden ausschließlich Dokumente erstellt. Bestehende Anwendungen, Gitea-Einstellungen, Runner, Server, Datenbanken und Sicherungen bleiben unverändert.
Grundlagen sind Referenzarchitektur A v0.3, Foundation B v0.3, Entscheidungen C v0.3 und der Auth-/Session-/Scope-Blueprint. Die beschlossenen ADR-01 bis ADR-14 bleiben maßgeblich, insbesondere ADR-06/07/11/12/14. Es entstehen keine zusätzlichen ADRs, zentralen Dienste oder neuen Freigabegremien.
Nachweis: V = vorgeschlagene technische Ausgestaltung; I = vorhandene statisch nachgelesene Implementierungsreferenz; T = tatsächlich bestandener Test mit Umfang, Stand und Umgebung; K = noch nicht integrierte/getestete Kombination. Dieser Blueprint und seine Beispiele sind V/K. Quellenverweise sind I. Tests, Release-Gates, Backups und Restores wurden hier nicht ausgeführt; kein T-Nachweis und keine Produktionsreife werden behauptet.
Der bestehende Ablauf bleibt:
develop → Development → Tests → bewusste menschliche Freigabe → main
→ konkreten Produktionskandidaten prüfen → Produktion → Read-only-Smoke
R1 – Build once, deploy many ist bevorzugt. R2 – kontrollierte reproduzierbare getrennte Builds für Dev/Prod bleibt nach ADR-11 zulässig. Beide benötigen vor Produktionsumschaltung vollständige Pflicht-Gates und eine eindeutige Zuordnung von Quellstand, Build, Freigabe und tatsächlich eingesetzten Artefakten. Die menschliche Annahme des Release-PR bleibt die Produktionsfreigabe; R2 erzeugt keine zweite menschliche Freigabeschleife.
1.1 Verbindliche Verträge und technische Defaults
| Verbindlich | Bevorzugter, begründet anpassbarer Default |
|---|---|
| Produktionsversion ist qualifiziert, freigegeben und eindeutig identifizierbar | Docker-Image-Archive mit SHA-256, Image-ID und Plattform; bestehende OCI-Registry ist Alternative |
| Keine synthetischen Mutationstests gegen Live-Dev-/Prod-Daten; kein Erfolg durch fehlende/skippende Pflichtsuiten | Kurzlebiges eigenes Compose-Projekt, PostgreSQL-Instanz und Testnetz je Run |
| Runtime ohne DDL/Owner-/Superuser-/BYPASSRLS-Rechte; Migration separat und nachweisbar | Bestehender SQL-Runnervertrag der Foundation, Migrationen vor Prozessumschaltung |
| Release, Backup und Restore dürfen dieselbe Datenbasis nicht konkurrierend verändern | Ein Deployhost je Produkt/Umgebung; gemeinsamer lokaler flock, persistentes Operationsjournal |
| DB und Medien eines Backups bilden einen definierten konsistenten Wiederherstellungspunkt | Kurzes Wartungsfenster, alle Writer stoppen/drainen, DB-Dump und Medienkopie einfrieren |
| Persönliche Sicherungen geschützt, wiederherstellbar und von Hostverlust unabhängig verfügbar | age-verschlüsseltes Archiv, verifizierte Kopie auf getrenntem vorhandenen Gerät/Host, Schlüssel getrennt |
| Restore aktiviert keine alten Sessions oder ungeprüft zurückgerollten Rechte | Neue Ziel-DB/Mediengeneration, Security-Nachbehandlung und zunächst gesperrte restaurierte Konten |
| RPO/RTO und Aufbewahrung sind explizit; Erreichbarkeit wird durch Übungen belegt | Startprofil: RPO 24 h, RTO 4 h; Sicherung alle zwölf Stunden; 7 tägliche + 4 wöchentliche + 3 monatliche Stände |
Die Zahlen sind Planungsdefaults, keine gemessenen Zusagen. Sie müssen vor dem ersten externen datenverändernden Betrieb im Produktprofil ausdrücklich gewählt und mit gemessener Restorezeit/Backupabständen abgeglichen sein. Eine lokale Begründung genügt; keine neue Familienfreigabe. Quellenpfade, Modulnamen, Tooladapter und Zeitbudgets können angepasst werden, ohne Schutz- oder Releaseverträge abzuschwächen. Dieser Entwurf verlangt weder Kubernetes, neue Registry, neuen Runnerdienst, zentrales Monitoring noch einen Backupserver.
2. Gezielte Referenzen und Übernahmegrenzen
Verwendet wurden das Phase-3.1-Wissensregister, dessen Quellenregister und die folgenden ausgewählten Dateien. Es gab keine vollständige Repository-Neuanalyse oder erneute Produktreifebewertung.
| Referenz I | Übernehmen | Im Zielaufbau gezielt ändern V/K |
|---|---|---|
| Shinkan KI-SHK-12, Security-Runner, Testworkflow | Explizite Securitysuite und propagierter Testexitcode | Keine Paketinstallation/Mutationstests im laufenden Kunden-/Dev-Container; exakte Testfall- und Artefaktzuordnung |
| Shinkan KI-SHK-13, Produktionsworkflow | Bestehende Branch-/Compose-/Smoke-Aufteilung | Kein ungeprüftes build --no-cache → up; Gate vor Umschaltung, Laufzeit-/Imageidentität, kontrollierte Migration |
| Kairo KI-KAI-16, isolierter PR-Stack, Dev-Deploy | Eigener Teststack und Backend-/Frontend-Smoke | Projektnamen/Ports je Run statt fester Namen; garantiertes Cleanup auch bei Fehlern; unveränderte Images testen; keine parallelen Push-/Deployläufe als Zuordnungsbeweis |
| Kanshō KI-KAN-14, Testtrennung | Testdaten von Live-Dev unterscheiden, Providerkeys nicht für Tests verwenden, Live-Smoke read-only | Eigene kurzlebige PostgreSQL-Instanz statt fester DB auf Dev-Postgres; Schutz vor falschem Ziel und parallelen Läufen |
| Mitai KI-MIT-20, Custom-Dump | pg_dump -Fc, Owner-/ACL-unabhängiger Dump |
Explizites Ziel ohne Produktionsdefault, Medienkonsistenz, Verschlüsselung, externe Kopie, Wiederherstellung in neue DB statt --clean auf Live-DB |
| Kanshō KI-KAN-20, Backupmanifest, Archivprüfung, Restore | Manifest, Prüfsummen, Formatversion und Sicherheitskopie vor Ersatz | SQLite bleibt lokale Produktvariante. PostgreSQL-Pfad separat; Archive nicht unverschlüsselt verteilen; Pfad-/Größenprüfung vor Extraktion; DB-/Medienwechsel nicht als dateisystemübergreifend atomar behaupten |
| Kanshō KI-KAN-21, PG-Skript | Vorhandener PostgreSQL-Betriebsweg | Die gesonderte Medienkopie wird in einen gemeinsamen Konsistenz-/Backupzustand eingebunden |
Kanshōs Runtime-Dokument beschreibt lokale Entscheidungen und historische Transferwege. Daraus folgt weder ein familienweiter Produktionspfad noch die Erlaubnis, persönliche Sicherungen generell in Git abzulegen. Für diesen Neuaufbau gilt der explizite Foundation-Migrations-/Releasevertrag. Die vorhandenen Produkte erhalten keinen automatischen Umbauauftrag.
3. Komponentenschnitt und Zuständigkeiten
Gitea qualification → isolierter Image-Teststack → geschützte Releaseablage
Release-PR auf main → menschlicher Merge → Production-Workflow
→ vertrauenswürdiger ReleaseController auf bestehendem Deployhost
→ Provenienz-/Gateprüfung → Hostlock → Backup/Migration → Compose
→ Read-only-Smoke → DeploymentReceipt
Vorhandener Scheduler / explizite CLI → BackupController → verschlüsselte Kopien
Explizite Recovery-CLI → RestoreController → neue DB/Medien → Prüfung → Umschaltung
| Baustein | Verantwortung |
|---|---|
scripts/ci/qualify |
Isolierten Run aufbauen, Artefakte testen, JUnit-/Browsernachweise und Pflichtfallabdeckung auswerten |
ops/contracts.py, ops/manifest.py |
Strikte versionierte Metadaten, Hash-/Datei-/ID-Validierung; keine Secrets |
ops/gitea.py |
Tatsächliche Server-/Runnerfähigkeiten und vertrauenswürdige Run-/Commit-/Mergebelege lesen; versionspassender Adapter |
ops/release.py |
R1/R2-Kandidat verifizieren, Releasezustandsautomat und Deployment koordinieren |
ops/host.py |
Registrierte lokale Profile, Lock, Journal, Wartung, Writerkontrolle, atomare Zeigerdateien |
ops/backup.py, ops/restore.py |
Gemeinsame DB-/Mediensicherung, sichere Verschlüsselung/Kopie, Wiederherstellung in neue Generation |
ops/postgres.py |
Identitätsprüfung, expliziter Foundation-Migrationsaufruf, pg_dump/pg_restore, Rollen-/Schema-/Integritätsprüfung |
ops/health.py |
Kurze begrenzte Read-only-Smokes; sichere Meldung von Revision/Readiness |
| Produktadapter | Tatsächliche Writer, Medienreferenzen, Schlüsselreferenzen, Restore-Securityhooks und fachliche Integrität liefern |
Dies sind produktlokale Werkzeuge/Module, keine Web-Verwaltungs-API und kein neuer Plattformdienst. Linux auf dem vorhandenen Deployhost ist der Betriebsdefault; Windows kann Dokumente/Code bearbeiten. Die folgenden Betriebsbefehle werden hier nicht ausgeführt.
Der privilegierte Controller und seine Profil-/Vertrauenskonfiguration liegen auf dem Host in einem versionierten, gegen Änderung durch untrusted Jobs geschützten Werkzeugverzeichnis. Sein getesteter Stand wird im Operationsjournal festgehalten. Er führt keine beliebigen Shellskripte aus eingereichten PR-Artefakten mit Produktionsrechten aus. Produktmigrationen laufen ausschließlich als freigegebene SQL-Dateien unter der begrenzten Migrationsrolle. Eine spätere Controlleränderung wird selbst getestet/versioniert und bewusst über den bestehenden administrativen Betriebsweg bereitgestellt.
3.1 Rechte und Secrets
| Identität | Darf | Darf nicht |
|---|---|---|
| Untrusted PR-Check | Begrenzte Checks in bereits vorhandener isolierter Ausführung | Prod-/Deploysecrets, Produktionsnetz/Volumes/Dockersocket des Hosts erreichen |
| Vertrauenswürdige Qualification | Ausgewählten geschützten Quellstand bauen/testen, Qualifikationsartefakte schreiben | Prod-DB oder Recovery-Privatschlüssel verwenden |
| Production-Workflow/Controller | Freigegebenen Kandidaten lesen und registrierte Produktoperation ausführen | Beliebigen Upload/Tag ungeprüft deployen oder fremde Produktziele wählen |
| App-Runtime | Begrenzte Fach-DML und Health | Migration/DDL, Backupschlüssel, Dockersteuerung, Betriebskonfiguration ändern |
| Migration/Restore | Benannte Produkt-DB/schema besitzen/verändern; keine fremden DBs | Credentials dem Backend dauerhaft hinterlassen |
| Backup | Vollständigen eigenen Datenbestand lesen und auf erlaubtes Ziel verschlüsseln | App-Secrets/Entschlüsselungsschlüssel als Archivinhalt einsammeln |
| Recoveryoperator | Separat bereitgestellte Entschlüsselungs-/Faktorschlüssel verwenden und geplanten Restore ausführen | Diese Schlüssel in CI-Logs oder Runtimeimages ablegen |
Wenn der vorhandene Runner Fremdcode nicht sicher vom Produktionshost trennen kann, laufen dort keine untrusted PR-Ausführungen mit Hostrechten. Vorhandene isolierte Ausführung verwenden oder vollständige Qualifikation erst auf dem ausdrücklich vertrauenswürdigen develop-Stand ausführen. Fehlende Isolation wird nicht durch einen neuen Runnerdienst in diesem Blueprint kaschiert. runs-on: ubuntu-latest allein beweist keine Isolation.
4. Produkt-/Betriebsprofil
Alle Commands verlangen einen ausdrücklich gewählten Profilpfad; fehlende/ungültige Umgebung bricht ab. Es gibt kein „sonst prod“. Das Profil enthält nur erlaubte Ziele und Secretreferenzen. Beispiel mit fiktiven Werten, V/K:
{
"format_version": 1,
"product_id": "demo-product",
"environment": "production",
"host_id": "registered-deploy-host",
"platform": "linux/arm64",
"public_origin": "https://demo.invalid",
"compose_project": "demo-product-prod",
"operations_root": "/srv/jinkendo/demo-product/operations",
"releases_root": "/srv/jinkendo/demo-product/releases",
"media_generations_root": "/srv/jinkendo/demo-product/media",
"database_ref": "product-prod-db",
"database_instance_id": "provisioned-opaque-instance-id",
"writers": ["backend"],
"build_variant": "R1",
"rpo_seconds": 86400,
"rto_seconds": 14400,
"scheduled_backup_seconds": 43200,
"backup_store_ref": "registered-independent-storage",
"backup_recipient_file_ref": "data-backup-recipients",
"secret_recovery_ref": "separate-recovery-material",
"drain_timeout_seconds": 30,
"startup_timeout_seconds": 120,
"lock_wait_seconds": 60
}
Pflichtauflösung vor Betrieb: konkretes Repository/Gitea, Host/Plattform, Proxy-/Wartungsschalter, Composeversion, Service-/Writerliste, DB-/Volumeidentitäten, vertrauenswürdige Runner/Workflows, Ablage und unabhängiger Sicherungsspeicher, verfügbare Schlüssel-ID-Referenzen. RPO/RTO werden ausdrücklich übernommen oder begründet geändert. Ein fehlendes Pflichtfeld erzeugt profile_incomplete, keinen geratenen Pfad. Alle absoluten Pfade werden vor Move/Extraktion/Cleanup gegen ihre registrierte Wurzel geprüft; Symlinkausbrüche und fremde Mounts sind verboten.
Einmalige Zielprovisionierung setzt eine zufällige Produkt-/Umgebungs-/Instanz-ID in einer kleinen DB-Identitätstabelle und im geschützten Hostprofil. Commands prüfen beide sowie tatsächlichen DB-Namen/Server/Compose-Labels. Diese Prüfung ergänzt getrennte Zugriffsrechte/Netze; ein selbst gesetztes APP_ENV reicht nicht. Restore überschreibt diese Tabelle im neuen Ziel nach dem Einlesen mit dessen bewusst provisionierter Zielidentität. Reale Adressen, Dienste, Secretwerte oder Einstellungen wurden für dieses Dokument nicht abgefragt.
Bei Erstinstallation ist die erwartete Runtimegeneration ausdrücklich uninitialized, die Produkt-DB leer und provisioniert. Es gibt keinen vorigen Image-Rollback; die leere Ausgangs-DB/-Medienwurzel kann als Pre-release-Ausgangspunkt gesichert werden. Erstinstallationsmigration und Erstoperatorweg folgen Foundation/Phase 3.3. Ein fehlender Vorgänger ist nur in diesem verifizierten Fall erlaubt. Der spätere erste externe Datenbetrieb verlangt trotzdem den vorherigen synthetischen Recoverydurchlauf.
5. Artefakte und Nachweisverträge
5.1 Releasepaket
releases/<release_id>/
release.json # immutable Build-/Quell-/Artefaktmetadaten
runtime/backend.tar # oder vorhandene OCI-Referenz
runtime/frontend.tar
runtime/compose.release.yml # keine build:-Abschnitte/Live-Quellmounts
migrations/ # vollständige bisherige SQL-Folge
reports/qualification.json
reports/junit-*.xml
reports/browser-results.json
reports/schema-compatibility.json
release_id, build_id, run_id sind begrenzte IDs aus einer Allowlistzeichenmenge; keine Pfade oder frei ausführbaren Werte. Auflösung ausschließlich innerhalb registrierter Roots. Dateipfade im Paket relativ, keine Links/Geräte/absoluten Pfade. Plattform der getesteten Images entspricht dem Ziel; ein x86-Test qualifiziert nicht still ein separat gebautes ARM-Image.
Erforderliche Felder von release.json v1:
| Gruppe | Inhalt / Prüfung |
|---|---|
| Identität | format_version, product_id, release_id, build_variant, created_at, controller_contract_version |
| Source | Repo-ID, Dev-Commit/Tree, Prod-Commit/Tree, Build-Rezept-/Lockfile-/Basisimagehashes, Plattform/Toolchain, explizite öffentliche Buildparameter |
| Build | Dev-/Prod-Build-ID, je Image Archiv-SHA-256 und Docker-Image-ID, alternativ unveränderliche OCI-Digests |
| Gate | Run-IDs, Workflowidentität/-revision, Qualification-Reporthashes, Pflichtspezifikationshash, Policy-/Konfigurationsprofilhash, getestete Plattform |
| Schema | Hash der geordneten Migrationsdateiliste samt Inhalten, erwarteter Ledgerhead/-digest, benötigte Extension-/DB-Versionslinie |
| Wiederanlauf | Voriges Artefaktpaar, Schema-Kompatibilitätsnachweis oder ausdrückliche Kennzeichnung „kein Image-Rollback qualifiziert“ |
Das Manifest enthält keinen eigenen Hash. Sein SHA-256 wird im vertrauenswürdigen Ablageindex/Deploymentjournal referenziert. Der spätere Freigabe-/Mergebeleg ist ein separater approval-proof.json/vertrauenswürdiger Lookup, damit ein vor dem Merge erzeugtes R1-Paket nachträglich nicht verändert werden muss. Kein Secret, Cookie, persönliches Testdatum oder Providerprompt im Manifest.
SHA-256 schützt gegen versehentliche Änderung, belegt allein aber keine Herkunft. Der Controller nimmt Nachweise nur vom passenden geschützten Gitea-Run oder aus einer ausschließlich durch die vertrauenswürdige Qualification beschreibbaren lokalen Ablage an. Beliebig hochgeladenes Manifest plus passende selbst berechnete Hashes genügen nicht. Controller/Profil legen erlaubte Repo-, Workflow-, Run- und Herausgeberidentitäten fest. Eine Registry oder Signaturinfrastruktur muss dafür nicht neu eingeführt werden.
Docker-Archivhash, Image-ID und OCI-Digest sind unterschiedliche Kennungen. Beim Archivweg: Archivhash vor Load prüfen, danach geladene Image-ID/Plattform und schließlich container.Image prüfen. Ein eindeutiger lokaler Releasetag dient nur zur Composeadressierung. Er wird vor und nach Start gegen die erwartete Image-ID aufgelöst; bewegbares latest ist kein Nachweis. Docker image save beschreibt den vorhandenen Archivtransport.
5.2 Qualifikationsbericht und Deploymentbeleg
qualification.json v1 enthält: Produkt, Build-ID, vollständige Image-/Sourcezuordnung, Environment=test, Test-Run-ID, Start/Ende, Toolversionen, Pflichtfallliste/-hash, je Fall stabilen Namen/Parameter, Status und Suite, Collectionzählung, Failed/Error/Skipped/XFail-Zähler sowie Hashes der Rohberichte. Ein erfolgreicher Gesamt-Exitcode ohne erforderliche Einzeltests reicht nicht. Ein Pflichtfall muss tatsächlich passed sein; skip/xfail/unerwartetes xpass gelten nicht als Erfüllung. Manifest und Berichte sind zusammen unveränderlich aufbewahrt.
deployment-receipt.json entsteht nach erfolgreichem Umschalten: Host-/Profilhash, Release-/Manifest-ID, freigegebener Main-Commit und Merge-/Menschbeleg, konkrete Quell-/Build-/Image-IDs, vorheriger Release, Preflight-/Backup-/Migrationsreferenz, tatsächlicher Ledgerstand, Controllerrevision, Wartungs-/Umschaltzeiten, tatsächliche Container-Image-IDs und sichere Smokeergebnisse. Ein fehlgeschlagener Lauf erhält einen Fehlerbeleg mit letzter sicherer Phase; er wird nicht als Deploymenterfolg ausgegeben.
Das lokale Operationsjournal lebt außerhalb der App-DB, damit ein DB-Restore den neuesten Betriebszustand nicht zurückdreht. Pro Operation immutable ID und Phase, Ergebnis, sichere Reasoncodes; Updates atomar via temporärer Datei, fsync, os.replace und Verzeichnissynchronisierung. Lokale Journalrotation/geschützte unabhängige Kopie erhalten den benötigten Wiederanlaufstand; keine Zugangsdaten oder personenbezogenen Bodies.
6. R1/R2, menschliche Freigabe und Gitea-Anbindung
| Schritt | R1: bevorzugt | R2: zulässig |
|---|---|---|
| Dev-Kandidat | Aus eindeutigem geschütztem Commit mit gelockten Inputs bauen; immutable Images identifizieren | Eigener eindeutig identifizierter Dev-Build mit gelockten Inputs |
| Development/Test | Genau diese Images in Dev bereitstellen und separat im isolierten Stack qualifizieren | Dev-Build ebenso qualifizieren |
| Menschliche Freigabe | Release-PR nach erfolgreicher Dev-Qualifikation bewusst nach main übernehmen |
Gleiche Freigabe; deklarierte Prod-Buildinputs dazugehören |
| Prod-Kandidat | Qualifizierte Images wiederverwenden; Main-/Treebeziehung beweisen | Aus dem freigegebenen Stand separat kontrolliert bauen; tatsächlichen Prod-Build vollständig qualifizieren |
| Gate vor Prod | Vertrauenswürdige Reports, Hashes, Quell-/Mainbeziehung und Betriebsbedingungen prüfen | Dasselbe, einschließlich eigener Prod-Build-/Qualification-ID; unterschiedlicher Dev-/Prod-Hash erlaubt |
| Deployment | Ausschließlich geprüfte Images/Deploymentdefinitionen, kein weiterer Build | Genau den separat qualifizierten Prod-Build, ebenfalls kein weiterer ungeprüfter Build |
Main-HEAD wird am Start des Vorgangs auf den konkreten freigegebenen Commit festgehalten. Der Controller prüft: zum Produkt gehörender Release-PR, erfolgreiche passende Dev-Qualifikation, tatsächlicher menschlicher Mergeactor aus dem erlaubten Personenkreis und keine ungeprüften Änderungen nach diesem Stand. Git-Commit-Autorname oder ein frei gesetztes Manifestfeld ist kein Menschbeleg. Administratorrechte allein ersetzen diesen normalen Freigabepfad nicht; Direct-Push-/Force-Push-Umgehung ist für normale Releases gesperrt.
R1-Default: qualifizierter Sourcecommit ist im freigegebenen Main enthalten und die relevanten Source-Trees sind identisch. Abweichende Trees benötigen ausdrücklich die Qualifikation des passenden tatsächlich freigegebenen Kandidaten; sonst Abbruch. R1 erlaubt dabei keinen versteckten Prod-Neubuild: Neu gebaute Produktionsartefakte werden als R2 qualifiziert, oder der passende Dev-Kandidat wird vor Übernahme neu qualifiziert und eindeutig an die bereits erteilte Quellfreigabe gebunden. R2 darf separate Inputs und Artefakte haben, dokumentiert alle Abweichungen und prüft genau den Prod-Kandidaten. Öffentliche Parameter wie Origin sind keine Secrets; bevorzugt bleibt Same-Origin-Laufzeitkonfiguration. Netzwerkzugriffe beim Build sind auf gelockte Abhängigkeiten und gepinnte Basisimages beschränkt. R2 bedeutet kontrollierbar wiederholbarer Aufbau; bitidentische Dev-/Prod-Archive werden nicht verlangt.
Bei Einführung oder Änderung des Buildrezepts/der Toolchain wird ein Wiederaufbau aus den protokollierten Inputs im isolierten Umfeld geprüft. Abweichungen werden bis zu den Laufzeit-/Assetinhalten erklärt; nichtdeterministische Archiv-/Zeitmetadaten dürfen nicht als unerklärte fachliche Änderung durchgehen. Das verlangt keinen zweiten Build jedes Releases und keine Gleichheit von bewusst unterschiedlich parametrisierten Dev-/Prod-Builds.
6.1 Logische Workflows im bestehenden Gitea
- Qualification (
develop): exakten Commit auschecken, prüfen/builden, Dev bereitstellen, isolierte Pflicht-Gates auf diesen Images ausführen, sicheren Report veröffentlichen. Mutierende Tests sprechen nur den isolierten Stack. Mehrere Runs dürfen sich nicht gegenseitig als „aktuelles Dev“ qualifizieren; Dev-Deployment und devbezogener Smoke sind pro Umgebung serialisiert. - Release-PR nach
main: Pflichtstatus für den richtigen PR-Head/qualifizierten Source, bestehende bewusste menschliche Annahme. Tatsächliche Statuskontextnamen werden aus dem eingesetzten Gitea ermittelt, nicht geraten. - Production (
main): konkrete Merge-/Sourcezuordnung auflösen, R1 übernehmen bzw. R2-Prod-Kandidat qualifizieren, Controller auf registriertem Ziel aufrufen. Einworkflow_run-Trigger allein ist kein Nachweis von Reihenfolge oder Artifactidentität. Bestehende Workflowdateien können die drei Aufgaben abbilden; keine neue CI-Plattform.
Vor tatsächlicher Integration wird lesend ein gitea-capabilities.json erfasst: Server-/Runnerversion, effektive Main-/Develop-Schutzregeln inklusive Ausnahmen, erlaubte Merge-/Pushidentitäten, exakte Pflichtstatuskontexte, Run-/Artefaktlookup und Runner-/Secret-/Socket-/Netzgrenzen. Fehlende Fähigkeit wird sichtbar als nicht verifiziert geführt. Das ist eine technische Bestandsprüfung zu C/O2, keine neue Governance-Analyse. Der Adapter verwendet die API der tatsächlich installierten Version; keine ungeprüften API-/Permissionsbeispiele aus aktueller Cloud-Dokumentation.
Gitea dokumentiert Branchschutz und erforderliche Statuschecks, ignoriert aber jobs.<job_id>.environment. Deshalb ist ein YAML-Environment kein menschliches Gate. Gitea Branchschutz, Actions-Unterschiede. Zusätzlich verweigert der Controller selbst fehlende/rote Nachweise; ein Merge allein darf einen technisch unqualifizierten Kandidaten nicht deployen.
Qualification-Reports aus untrusted PR-Ausführung dürfen weder Produktionssecrets erreichen noch als geschützte Releasenachweise gelten. Herkunft wird über den vertrauenswürdigen Run/Store geprüft; Actions sind kompatibel gepinnt. Shellbefehle erhalten ausschließlich validierte IDs/Argumentlisten. Benutzerbeeinflussbare Event-/Branchtexte werden nicht als ${{ ... }} direkt in Shellcode eingesetzt. Produktionscredentials erscheinen nie im Checkout, Buildkontext, JUnit oder Artefakt.
7. Isolierter Test- und Gatevertrag
7.1 Stackidentität und Schutz vor falschem DB-Ziel
Je Qualification: eindeutiger run_id, Composeprojekt jk-test-<safe_run_id>, eigenes internes Netz, eigene PostgreSQL-Volumes und zufällige kurzlebige Testcredentials. PostgreSQL hat keinen veröffentlichten Hostport. Browser/HTTPtests laufen im Testnetz; nötiger HTTPS-Testproxy nutzt synthetisches Testzertifikat. PUBLIC_ORIGIN entspricht diesem Testorigin. Proxyunterschiede werden als Testkonfiguration dokumentiert; die tatsächlich gebauten Appimages bleiben unverändert.
Vor jedem Schemaaufbau/-reset prüft ein Wächter kumulativ: APP_ENV=test, registrierte Testwurzel, Compose-/Netz-/Volume-Labels mit Run-ID, erlaubten aufgelösten DB-Service, Run-ID im DB-Namen, current_database(), tatsächliche Benutzerrolle und provisionierten Testmarker. Die anfängliche Markeranlage erfolgt erst nach Bestätigung der separaten Run-Instanz unter deren einmaliger Provisionierungsrolle. Kein Zugriff auf reale Dev-/Prod-Endpunkte/Volumes; Netz-/Rollenisolation verhindert diese Ziele zusätzlich. Ein bloßer Name wie *_test reicht nicht.
Testprovisionierung darf ihre eigene DB/Rollen anlegen; Migration- und Runtime-Rolle werden danach getrennt. Beide Negativfälle werden tatsächlich geprüft: Runtime kann Fach-DML im eigenen Scope, aber kein DDL/Owner-/Bypassverhalten. Kein SQLiteersatz. Provider-/SMTP-/Webhookcredentials fehlen; Testadapter und Netzwerkblockade verhindern echte externe Nebenwirkungen. Quellcode wird nicht über das Runtimeimage gemountet. Der Testdriver ist ein getrennt gebautes gelocktes Werkzeugimage bzw. Container, der das unveränderte Runtimeimage über HTTP anspricht; DB-Vertragstests laufen mit demselben Runtimecode/-Abhängigkeiten, Testtools ändern dessen Pins nicht.
Die Testumgebung ist vom App-Laufzeitmodus zu unterscheiden: Der Wächter/Testdriver läuft mit APP_ENV=test gegen den isolierten Teststack. Zusätzlich wird das unveränderte Runtimeimage dort mit APP_ENV=production, synthetischen Pflichtsecrets und HTTPS-Testorigin geprüft. DB/Netz/Volumes bleiben trotzdem ausschließlich die registrierten Testressourcen. Dadurch sind Produktionsstart, sichere Fehler/Diagnosegrenzen und tatsächlich verwendete Konfigurationszweige abgedeckt. qualification.json erfasst Testtarget und App-Laufzeitmodus getrennt. Ein erfolgreicher Testmodus allein qualifiziert keinen unbekannten Produktionskonfigurationspfad.
7.2 Pflicht-Gates
| Gate-ID | Pflichtinhalt |
|---|---|
G01 source-config |
Source-/Tree-/Lock-/Build-/Plattformbindung; keine unbekannte Umgebung oder fehlender Pflichtadapter |
G02 unit-api |
Imports ohne DB-Nebeneffekt, OpenAPI-/Problemvertrag, explizite DTOs, sichere Fehler/204 |
G03 db-migrations |
Leere DB, Upgrade von unterstütztem Vorstand, Prüfsummen/fehlende Dateien, Konkurrenz, Ledger-/SQL-Atomarität, Poolrückgabe/Runtime-Rolle |
G04 auth-scope |
Registrierte Auth-/MFA-/Scopefälle aus Phase 3.3, Cross-Profile-/Cross-Tenant-Negativfälle und Entzugrennen |
G05 frontend-browser |
Build, Client-/epoch-Fehlerfälle, direkte SPA-Route, Login/Logout/CSRF, Scopewechsel und sichere Darstellung |
G06 image-runtime |
Tatsächliche gebaute Images, Start/Readiness/Revision/Plattform, keine Live-Quellmounts oder nachträgliche Paketänderungen |
G07 schema-compatibility |
Geplante Migration/Start mit Zielimage und explizit qualifizierter Rückweg; bei fehlendem Image-Rollback Nachweis des gewählten Restore-/Forward-Fix-Pfads |
G08 operations-contracts |
Controller-/Gate-/Zielschutztests, Fehlerfortsetzung, Backup-/Restoreintegration mit synthetischen Daten, Pflichtfallabdeckung |
Pflichtfälle werden im Zielrepository in einer versionierten required-tests.json je Funktionsprofil explizit benannt. Kleine Apps erhalten keine erfundenen Org-/KI-Funktionen; deren Nichtregistrierung wird geprüft. Auth-/MFA-Pflichtfälle sind mit integriertem Adapter verpflichtend. Eine Testsuite mit null Fällen, fehlender Datei, anderem Commit, falschen parametrisierten IDs oder erforderlichem Skip ist rot. JUnit wird gegen Collection und Pflichtliste geprüft; Rohberichte und deren Hashes bleiben erhalten. Ein || true, npm ci || npm install oder automatisch nachinstalliertes Testpaket kann kein grünes Gate erzeugen.
Exitcode und Pflichtreportprüfung müssen beide erfolgreich sein. Tests dürfen im CI beliebig spät fehlschlagen: Cleanup läuft im finally/Workflow-always, Fehlerexitcode bleibt erhalten. Entfernt werden nur Ressourcen mit passender Projekt-/Run-ID und explizitem Inventory. Keine globalen Docker-Prunes und kein down -v gegen registrierte Liveprojekte. Ein Hostabbruch wird durch einen späteren eng begrenzten Stale-Run-Cleanup behandelt, der noch aktive Runs ausschließt.
Live-Dev-/Prod-Smoke ist ausschließlich read-only: Liveness, Readiness, sichere Buildkennung, SPA-/Proxyantwort. Kein Testnutzer anlegen, kein Testlogin mit Kundenkonto, kein Import oder DBreset. Inhaltliche Mutationstests gehören in den isolierten Stack und sind vor Prod abgeschlossen.
8. Deploymentzustände, Hostlock und Fehlerfortsetzung
Ein exklusiver Lock je product_id/environment umfasst Release, Writerfreeze, Backupaufnahme, Migration, Restore, Umschaltung und zugehöriges Cleanup. Default: Linux-flock auf einer registrierten lokalen Datei, 60 Sekunden Wartebudget. Kein Lock anhand beliebiger Argumentpfade. Ein Controller übergibt seine Lease an untergeordnete Backup-/Migrationsschritte, die nicht erneut denselben Lock anfordern. Mehrhostdeployment wird durch dieses lokale Profil nicht unterstützt; ein entsprechendes Profil bricht ab, statt eine verteilte Sperre zu behaupten.
Journalphasen:
PLANNED → PREFLIGHT_OK → MAINTENANCE → WRITERS_FROZEN
→ BACKUP_COMPLETE → MIGRATING → SCHEMA_READY
→ CANDIDATE_STARTED → SMOKE_OK → COMMITTED → SERVING
Fehler vor Mutation: FAILED_SAFE
Fehler nach möglicher Mutation: FAILED_MAINTENANCE → RECONCILE / ROLLBACK / RESTORE
Jede Phase wird vor/nach dem externen Effekt mit Operation-ID und erwartetem Vorgängerstand protokolliert. Der Exitcode des Prozessschritts allein beweist nach Stromausfall nicht dessen Zustand. reconcile liest tatsächliche Images, Schema, Wartungsschalter, DB-/Mediengeneration und vorhandene Receipts, bevor es einen erlaubten nächsten Schritt plant. Blindes Wiederholen einer unbekannt abgeschlossenen Migration oder Umschaltung ist verboten. Session-Advisory-Lock und Migrationledger bleiben der spezielle DB-Schutz aus A5; der Hostlock ersetzt sie nicht.
8.1 Produktionsablauf
- Plan/Preflight: Profil und erwarteten aktuellen Receipt prüfen; unveränderlichen freigegebenen Commit festhalten; R1-/R2-Nachweise und Artifactdateien prüfen. DB-Identität, Schema-/Lock-/Disk-/Speicherbudget, Schlüsselreferenzen, Sicherungsspeicher und Writerliste auflösen. Letzten erfolgreichen Recoverytest gegen den benötigten Umfang prüfen. Ein paralleler oder inzwischen neuerer Deploystand macht den Plan ungültig.
- Wartung: Bestehender Reverse Proxy liefert für neue öffentliche App-/APIrequests einen sicheren 503-Wartungszustand. Der Schalter ist außerhalb des Appcontainers persistent. Direkte Backendzugänge sind auf das notwendige interne Netz beschränkt. Interner read-only Health bleibt für den Controller möglich.
- Drain/Freeze: Neue Job-/Cron-/Workerstarts stoppen, laufende Requests/Jobs begrenzt drainen, alle registrierten Writer einschließlich Backend stoppen. Bestätigen, dass weder Upload-/Löschprozesse noch Fachtransaktionen weiterlaufen. DB bleibt für Dump/Migration verfügbar. Kein „nur Browser gesperrt, Worker schreibt weiter“.
- Pre-release-Sicherung: Konsistenten DB-/Medienstand nach Abschnitt 10 aufnehmen, verschlüsseln und unabhängig verifiziert ablegen. Der Betriebsdefault verlangt diesen frischen Stand vor der Migration; ein älterer nächtlicher Dump wird nicht als Sicherung unmittelbar vor dem Eingriff ausgegeben.
- Migration: Exakten freigegebenen Migrationssatz unter getrenntem Credential ausführen. Ledger/Head/Checksummen prüfen; Migrationscredential danach entfernen. Kein App-Startup führt Migration/Seed aus. Fehler bleibt Wartungszustand; keine Erfolgsausgabe.
- Start: Backend/Frontend aus qualifizierten Image-IDs über die registrierte Release-Compose-Datei starten, externe Writer weiter pausiert. Keine Runtimebuilds, Paketinstallationen oder Livequellmounts. Composeauflösung darf weder DB-Volume noch fremde Produktressourcen ersetzen.
- Prüfen: Begrenzte interne Liveness/Readiness, erwartete Backendrevision und Container-Image-IDs; Frontendrevision aus eigenem statischen
build.jsonund tatsächlicher Frontend-Image-ID. Eine durchgereichte Backendantwort allein prüft kein Frontendimage. App muss den Zielledgerstand akzeptieren. Anschließend Proxyweg read-only prüfen, ohne Wartung allgemein zu öffnen. - Commit/Öffnen: Geprüfte Runtimegeneration und Receipt atomar veröffentlichen, dann Wartung lösen und registrierte Worker starten. Veröffentlichung von Dateizeiger und Containerprozess ist keine gemeinsame Transaktion; Journal/Reconcile behandeln jedes Zwischenstadium. Nach außen niemals eine gemischte alte/neue Generation freigeben. Sicherer öffentlicher Smoke schließt den Vorgang ab.
Compose-Default für den bereits verifizierten Kandidaten: docker compose ... up -d --no-build --pull never --wait --wait-timeout 120. Die Release-Datei enthält keine build:-Abschnitte; eindeutige lokale Tags lösen zu erwarteten IDs auf. Docker Compose up dokumentiert die verwendeten Optionen. --wait ersetzt weder Revision-/Schema-/Imageprüfung noch den anwendungsbezogenen Smoke. Das Datenbankimage bleibt separat gepinnt; dieser Workflow führt kein PostgreSQL-Majorupgrade aus.
8.2 Fehlerreaktionen
| Fehlerphase | Verbindliches Verhalten |
|---|---|
| Vor Wartung/Mutation | Abbruch ohne Änderung der laufenden App; Fehlerreceipt |
| Freeze/Backup scheitert, DB-/Medienstand sicher unverändert | Alte Generation prüfen und kontrolliert wieder öffnen; sonst Wartung erhalten |
| Migration gescheitert | Tatsächlichen Ledgerstand feststellen. Frühere Dateien können bereits committed sein; keine pauschale Behauptung vollständiger Rücknahme |
| Start/Smoke scheitert | Wartung behalten; nur qualifiziert kompatibles voriges Artefaktpaar starten oder Forward-Fix/Restore planen |
| Öffnung/Writerstart nur teilweise abgeschlossen | Journal als unvollständig führen; Reconcile auf tatsächliche Runtime, keine parallele neue Releaseoperation |
| Host-/Controllerabbruch | Lock wird vom Betriebssystem frei, Wartungs-/Journalzustand bleibt. Nachfolgender Lauf prüft unvollständige Operation zuerst |
Aufräumen entfernt temporäre Ressourcen, aber löst nach möglicher Mutation nicht blind Wartung oder löscht alte Volumes/Backups. Ein „finally: alles wieder starten“ ist für diesen Zustand falsch. Normale getestete Releaseübergänge brauchen keine weitere menschliche Bestätigung. Ein datenrücksetzender Restore ist ein ausdrücklich ausgeführter Recoveryvorgang mit gebundenem Plan; er wird nie als automatischer Image-Rollback versteckt.
9. Migration, Schemakompatibilität und Rückweg
Foundation A5 bleibt unverändert: SQLdateien und Ledgereinträge auf derselben Connection/Transaktion pro Datei, Session-Advisory-Lock, Prüfsummenprüfung aller angewandten Dateien, kein SQLsplit an Semikola, keine psql-Metabefehle/eigenen Commits. Nach Fehlern zählt das tatsächliche Ledger. Runtime ist nicht der Migrationsbenutzer. Restore- und Migrationrechte bleiben vom Appbetrieb getrennt.
schema-compatibility.json bindet vorigen/neuen Build samt Image-IDs, Migrationsdigest, alten/neuen Ledgerstand und tatsächliche Kompatibilitätstest-Runs. Default: Expand/Contract. Ein Release erweitert zunächst kompatibel; destruktive Entfernung erst nach Ablauf des vereinbarten Rückrollfensters und überprüfter Umstellung aller betroffenen Pfade. Readiness muss den tatsächlich geplanten Stand akzeptieren; eine behauptete Datenkompatibilität genügt nicht, wenn das vorige Image dort nicht startet.
Im isolierten Stack wird vorab geprüft: alten synthetischen Datenstand anlegen → geplante Migration durchführen → neues Image starten und Pflichtfälle ausführen → qualifizierten vorherigen Build auf diesem Schema starten und dessen relevanten Read-/Write-/Authvertrag testen. Das erneute Testen des unveränderten alten Images ist ein Kompatibilitätsnachweis, kein Produktionswrite. Bei bewusst nicht kompatiblem Eingriff wird image_rollback_qualified=false dokumentiert und stattdessen die vollständige Restore-/Forward-Fix-Vorsorge getestet. Kein Feld darf fehlende Tests zu Kompatibilität erklären.
Image-Rollback: voriges qualifiziertes Backend-/Frontendpaar auf demselben aktuellen Datenbestand starten, ohne DB-Downgrade. Restore: Daten und Medien auf den Sicherungsstand zurücksetzen, mit möglichem Verlust späterer Änderungen. Forward-Fix: neu qualifizierter korrigierter Kandidat über denselben Freigabe-/Gatevertrag. Diese drei Vorgänge haben unterschiedliche Wirkungen und Receipts. Es gibt kein automatisches produktives „Down“ und keinen ungetesteten Hotfix direkt auf dem Host.
Das aktuelle und mindestens das vorherige qualifizierte Artefaktpaar bleiben über das Rückrollfenster verfügbar; Default sieben Tage. Zu jedem aufbewahrten Backup bleiben ein passendes lauffähiges Restoreimagepaar, Schema-/Konfigurationsstand und benötigte Faktorschlüsselreferenzen verfügbar. Der produktübergreifende Betriebsweg darf nicht versehentlich alle Produkte desselben Hosts stoppen oder deren Datenbankimages aktualisieren.
10. Konsistentes Backup von DB und Medien
10.1 Umfang und Konsistenzpunkt
Ein vollständiger Recoveryset umfasst:
- PostgreSQL-Custom-Dump einschließlich Fach-, Audit-, Auth-, Rechte- und Migrationsdaten.
- Alle für diesen Datenstand referenzierten persistenten Medien/Dateien sowie benötigte fachliche Versionen; kein Docker-Containerfilesystem als Datenspeicher.
- Inneres versioniertes Manifest mit Quellprodukt/-umgebung/-instanz, Release-/Image-/Ledgerstand, Freeze-/Snapshotzeit, Dateiliste, Größe und SHA-256 je Datei, Konfigurationshashes und benötigten Schlüssel-IDs.
- Separat verfügbare passende Runtimeimages, Deployment-/Rollen-/Schema-Rezepte und Recovery-Schlüsselmaterial. Sie gehören nicht ungeprüft in denselben Datenarchiveinhalt.
Ein pg_dump ist DB-intern konsistent; es koordiniert nicht automatisch eine außerhalb liegende Medienablage. Der Default friert deshalb sämtliche Writer ein, bevor DB-Dump und Medienkopie beginnen. Die Snapshotzeit ist der bestätigte Freezezeitpunkt; seitdem verändern sich keine eingeschlossenen Daten. Das DB-Dumpformat wird aus Mitai übernommen, das Medien-/Checksummenmanifest aus Kanshō gezielt angepasst. PostgreSQL pg_dump.
Default-Dumpargumente als getrennte Subprocessargumente: pg_dump --format=custom --no-owner --no-privileges --file <staging/db.dump> --dbname <approved_db_name>. Host/Benutzer/Credential kommen aus dem registrierten Adapter, Passwort über geschützte Passfile-/Servicebereitstellung statt Kommandozeilen-URL. Tool aus passender gepinnter PostgreSQL-16-Linie. Exitcode/Warnungen prüfen; Dumpinventar lesbar, Datei nicht leer. Rollen/Clusterkonfiguration werden aus dem kontrollierten Bereitstellungsrezept rekonstruiert, nicht blind als globale SQLrolle importiert.
Bei RLS braucht die Backupidentität nachweislich vollständige Lesesicht auf die eigene Produkt-DB; fehlende Rechte müssen den Dump scheitern lassen. Kein stiller RLS-gefilterter Teildump als Vollsicherung. Die dafür nötigen Rechte sind getrennt vom Runtimekonto und bleiben auf registrierte Produktziele begrenzt.
10.2 Ablauf und Backupzustände
PLANNED → WRITERS_FROZEN → SNAPSHOT_CAPTURED → VERIFIED_LOCAL
→ ENCRYPTED → COPIED_INDEPENDENT → COMPLETE
Fehler: FAILED; teilweise Dateien behalten den Zusatz .partial
- Gemeinsame Operationslease halten, DB-/Pfadidentität und Platzbudget prüfen, Wartung/Drain durchführen. Release kann seinen bereits bestehenden Freeze übergeben.
- Privates Staging unter freigegebener Wurzel (
0700, Dateien0600) erstellen. DBdump aufnehmen; registrierte Medienwurzeln ohne Symlink-/Mountausbruch kopieren. Quelldateien bleiben im Freeze unverändert. - Produktadapter prüft DB-Medienreferenzen gegen Manifest: jede erforderliche Datei vorhanden, Größe/Hash passend; verwaiste Dateien nach expliziter lokaler Regel gesondert ausweisen. Keine fehlenden Medien als „leere Ablage“ akzeptieren. Manifest erst nach vollständiger Kopie schreiben.
- Bei regulärer Sicherung können Writer nach dem unveränderlichen lokalen Snapshot und dessen Verifikation kontrolliert wieder anlaufen; Verschlüsselung/Kopie verwenden ausschließlich das unveränderliche Staging. Bei Pre-release-Backup bleiben Writer bis zum Releaseabschluss gestoppt, und unabhängige Kopie muss vor Migration vollständig vorliegen.
- Datenarchiv verschlüsseln, Exitcode prüfen, Ciphertexthash/-größe erzeugen, über vorhandenen Transport auf registrierten unabhängigen Speicher kopieren, dort Hash/Größe erneut lesen und vergleichen. Keine Kopie innerhalb desselben Hostdatenträgers als Hostverlustschutz zählen.
- Erst dann äußeren
backup-receipt.jsonatomar alsCOMPLETEveröffentlichen. Staging nach erfolgreicher Prüfung unter sicherer Rootkontrolle entfernen; keine Rohdaten in CIartefakte oder Git hochladen. Fehler hinterlassen einen sichtbaren fehlgeschlagenen Lauf und lösen keinen Retentionslauf aus.
Der äußere Receipt enthält nur Backup-ID, Produkt, Snapshot-/Abschlusszeit, Datenformat, Ciphertexthash/-größe, Speicher-ID, Empfänger-Key-IDs und Referenz zum passenden Recoverymaterial. Die sensible Dateiliste bleibt im verschlüsselten inneren Manifest. COMPLETE bedeutet vollständig aufgenommen, verschlüsselt und unabhängig kopiert; es bedeutet nicht „dieses Backup wurde bereits restored“. restore_verified_at und Drillreport sind getrennte Belege.
Fehlgeschlagenes Rohdatenstaging bleibt ausschließlich unter privater Rootkontrolle und erhält eine explizite kurze Ablaufzeit; Default spätestens 24 Stunden. Der begrenzte Cleanup entfernt nur nachweislich inaktive Staging-IDs unter Operationslock. .partial wird nie in COMPLETE umbenannt, ohne die fehlenden Schritte nachzuholen. Bestehende Host-/Datenträgerverschlüsselung und verfügbare sichere Stagingkapazität werden im Betriebsprofil erfasst; das Tool behauptet kein kryptografisch sicheres Löschen auf unbekannten Datenträgern.
10.3 Verschlüsselung, Schlüssel und Aufbewahrung
Bevorzugter lokaler Verschlüsselungsadapter ist age mit ausdrücklich bereitgestellter Empfängerliste (age -R <recipient_file>); Entschlüsselung nur über separat bereitgestellte Identitätsdatei. Binaryversion und Prüfsumme werden gelockt. Das ist ein kleines lokales Werkzeug, kein neuer Dienst; gleichwertige vorhandene Verschlüsselung kann nach Adapter-/Restoretest verwendet werden. Keine eigene Kryptografie und kein Passwort aus dem DBcredential ableiten. age-Projektdokumentation.
Der Sicherungsprozess benötigt nur öffentliche Empfängerkeys. Recoveryprivatschlüssel werden nicht dauerhaft auf dem Produktionshost oder in CI gehalten und werden gegen Hostverlust selbst gesichert. Im autorisierten Recoveryvorgang sind sie nur temporär in der geschützten Recovery-/Operatorumgebung verfügbar und werden anschließend wieder entzogen. Mindestens eine Wiederherstellung mit tatsächlich zu diesem Profil gehörenden Entschlüsselungsrechten wird vor dem ersten externen Datenbetrieb geprobt; kein angenommener Zugriff aufgrund einer Key-ID. CI verwendet ausschließlich synthetische Testkeys.
MFA-Faktorschlüssel aus Phase 3.3 sind nicht die age-Entschlüsselungsschlüssel. Das Datenmanifest listet alle benötigten MFA-Key-IDs auf. Die passenden Werte kommen aus einem gesondert geschützten, verschlüsselten Recoveryset bzw. vorhandener gesicherter Secretbereitstellung; dieser Zugriff muss ohne den ausgefallenen Host möglich sein. DBrollenpasswörter und Provider-/SMTPtokens werden bei Recovery über den vorhandenen Betriebsweg neu bereitgestellt oder rotiert. .env, Logs, Providerkeys und private Schlüssel werden nicht durch pauschales Archivieren des Appverzeichnisses eingesammelt.
Default: geplante Sicherung alle zwölf Stunden für ein RPO-Ziel von 24 Stunden; dadurch bleibt Puffer für Laufzeit/Wiederholung. Vor strukturellen Produktionsänderungen zusätzlich Pre-release-Sicherung. Retention: 7 tägliche, 4 wöchentliche, 3 monatliche komplette Stände; zusätzlich letzte vollständige Sicherung und durch aktuelle Releases/Drills gebundene Stände. Ein Backup kann mehrere Aufbewahrungsklassen erfüllen. Löschen nur explizit gelisteter nicht mehr gebundener Backup-IDs unter Hostlock, ohne gesetzte lokale Löschsperre; kein freier Verzeichnis-Prune.
Schlüssel und Restoreimages werden erst entfernbar, wenn kein aufbewahrter Recoveryset sie mehr benötigt. Löschungen im Produkt verschwinden nicht automatisch rückwirkend aus Backups; sie werden über die festgelegte Retention ausgetragen. Produktspezifische Lösch-/Hold-Anforderungen bleiben erhalten. Dieser Blueprint legt dafür keinen neuen familienweiten Rechts-/Aufbewahrungskatalog fest.
11. Restoreverfahren und konsistente Umschaltung
11.1 Plan und sichere Zielwahl
restore plan ist read-only und bindet Backup-ID/Ciphertexthash, Profil-/Host-/DBidentität, erwartete aktuelle Runtimegeneration, Zielgeneration, benötigte Images/Keys, Integritätsprüfungen und geschätzten Datenverlust seit Snapshot. Der Plan hat einen Hash und Ablauf (Default 30 Minuten). restore apply benötigt genau diesen Planhash und erwarteten Vorgängerstand. Änderungen dazwischen machen ihn ungültig. Das ist ein technischer Schutz gegen falsche Ziele; die ausdrückliche Recoveryausführung ist keine zusätzliche allgemeine Freigabeschleife.
Der Default restored in eine neue leere Datenbank und eine neue Mediengeneration, während die alte Generation erhalten bleibt. Kein pg_restore --clean auf einer laufenden Produktdatenbank. Neue DB von sauberem Template, passende Extensions/Rollen aus geprüftem Rezept, kein Schema-/Seedautostart. Neue Zielnamen/Volumes bleiben innerhalb der registrierten Produkt-/Umgebungsgrenze. Ein eigener DB-Nutzer mit eingeschränkten Rechten restauriert die eine Ziel-DB; AppRuntime ist weder Restaurator noch Eigentümer.
Archive werden nur aus vertrauenswürdigem eigenem Backupstore angenommen. Erst Ciphertexthash/Quelle, dann vollständige Entschlüsselung und Archivprüfung, erst danach DBrestore. Geprüft werden Formatversion, relative kanonische Pfade, Eindeutigkeit, erlaubte Dateitypen, Dateianzahl, Einzel-/Gesamtgröße und Hashes; keine absoluten/..-Pfade, Symlinks, Hardlinks, Geräte oder Archivbomben. Inhalte werden nicht vor Validierung in die Zielwurzel extrahiert. Grenzwerte stammen aus dem Produktprofil und werden vor Ressourcennutzung geprüft.
11.2 Ausführung
- Lease und Wartung setzen, Writer drainen/stoppen, aktuellen tatsächlichen Stand journalisieren. Wenn lesbar, eigenen Pre-restore-Sicherheitsstand aufnehmen; bei zerstörter Quelle dessen Fehlen ausdrücklich protokollieren statt ein vorhandenes Backup zu überschreiben.
- Neue Ziel-DB/-Mediengeneration provisionieren, vertrauenswürdiges Archiv/Schlüssel prüfen. Geheime Daten nur im privaten Recovery-Staging verarbeiten. Keine Provider-/SMTP-/Webhookverbindung während Prüfung/Wiederanlauf.
- Dump in die neue DB importieren:
pg_restore --no-owner --no-privileges --exit-on-error --single-transaction --dbname <new_target_db> <verified_db.dump>. Kein paralleler--jobsbei diesem Default. PostgreSQL pg_restore beschreibt diese Restoreoptionen. Unter diesem Rollenmodell werden explizite Runtimegrants und ggf. RLS anschließend aus dem kontrollierten Bereitstellungsrezept gesetzt; Runtime wird nicht Owner. - Medien in eigene neue Generation extrahieren und nochmals gegen Manifest prüfen; Herkunfts-DBidentität/Ledger gegen inneres Manifest abgleichen, dann neue Zielidentität setzen. Fehlende Dateien/Keys/Constraints brechen ab. Restore wird nicht als erfolgreich markiert, nur weil
pg_restoreExit 0 meldet. - Sicherheitszustand gemäß Abschnitt 12 nachbehandeln, in eigener DBtransaktion auditieren. Anschließend passendes gesichertes Imagepaar intern starten; keine automatisch nachgezogenen Migrationen. Ein späteres Upgrade wäre ein eigener normaler Releasevorgang.
- Technische/fachliche Read-only-Integritätsprüfungen auf der wiederhergestellten Generation: Ledger/Checksummen, FKs/Constraints/Sequenzen, sichere Aggregat-/Manifestabgleiche, Medienreferenzen, Faktor-Key-Auflösung, Runtimeprivilegien und Auth-/Scope-Sperrwirkung. Reale persönliche Inhalte nicht in Prüfberichte oder Screenshots übernehmen. Mutationstests bleiben auf synthetischen Drilldaten.
- Unter fortbestehender Wartung den privaten Runtimezeiger auf ein Konfigurationspaar
{release_id,database_ref,media_generation}umschalten und betroffene Services neu starten. Beide Ressourcen bleiben gekoppelt. Erst nach Readiness/Revision-/Image-/Referenzprüfung die öffentliche Wartung lösen. Das funktioniert über Stillstand plus Journal; es ist keine behauptete atomare Transaktion zwischen DB und Dateisystem. restore-receipt.jsonmit Backup-/Plan-/Quell-/Ziel-/Image-/Schemaidentitäten, Sicherheitsmaßnahmen, Zeitmessung und verbleibender Kontenquarantäne schreiben. Alte Generation bleibt für das vereinbarte Sicherheitsfenster privat erhalten, ohne Appzugriff; Default sieben Tage unter denselben Schutz-/Speicherregeln.
Fehler vor Umschaltung lässt die alte Generation unangetastet. Fehler während Umschaltung hält Wartung aktiv; reconcile prüft beide Ressourcen. Hat nach Öffnung bereits ein neuer Write stattgefunden, darf ein Zurückschalten auf die alte Generation nicht als verlustfreier technischer Retry erfolgen. Es braucht einen neuen Recoveryplan mit benanntem Datenverlust. Keine automatische Löschung der alten DB/Medien im Fehlerhandler.
Für einen vollständigen Hostverlust werden zuvor Hostwerkzeuge, PostgreSQL-/Compose-/Proxybasis, Produktprofil und neue DBrollen/Runtimecredentials aus den gesicherten Rezepten bereitgestellt. Danach gilt derselbe Restoreablauf. Appdatenbackup ersetzt weder den Gitea-/Runner-Backupbetrieb noch die Sicherung der gesamten privaten Infrastruktur; der Scope dieses Dokuments bleibt das jeweilige Produkt.
12. Authentifizierung und Rechte nach Restore
Restore kann Sicherheitszustand zurückdrehen: vor dem Snapshot noch gültige Sessions, später verbrauchte Recoverycodes, inzwischen deaktivierte Konten oder entzogene Mitgliedschaften. Deshalb reicht ein Neustart des Backends nicht.
Pflicht-Port des Auth-/Produktadapters: invalidate_restored_security_state(tx, restore_id). Er führt für die neue Generation vor Öffnung atomar aus:
- Alle restaurierten Browser-Sessions widerrufen, Konto-
security_epocherhöhen, alle Login-/MFA-/Enrollment-/Reset-/Bestätigungsflows verbrauchen. - Alle restaurierten Recoverycodes ungültig machen; Tokens/grants für Medien und gegebenenfalls technische Credentials ebenfalls gemäß registriertem Produktadapter widerrufen. Ein nicht integrierter erforderlicher Adapter hält Wiederanlauf geschlossen.
- Bei TOTP den gespeicherten akzeptierten Counter mindestens auf den aktuellen DB-Zeitschritt anheben, niemals senken; ein Code aus dem gerade laufenden bereits möglicherweise benutzten Zeitfenster wird nicht erneut akzeptiert. Faktor-Secrets nur mit passenden gesicherten Key-IDs verwenden, nie durch Defaultsecret ersetzen.
- Default Kontenquarantäne: Restaurierte Konten zunächst
disabled; keine automatische Aktivierung alter Betreiber-/Club-/Orgzuordnungen. Wiederfreigabe ausschließlich anhand geprüften aktuellen Kontostatus und aktueller Mitgliedschafts-/Rollenlage. Fehlt eine verlässliche aktuelle Credentiallage, Passwort neu setzen. Backuprechte sind keine Autorität für spätere Entzüge. - Genau einen ausdrücklich ausgewählten Betreiber über den vorhandenen lokalen Recovery-/Provisionierungsweg aus Phase 3.3 wiederherstellen, alte Sessions/Codes dabei geschlossen lassen und erforderliche MFA-Einrichtung/-Prüfung erzwingen. Danach Konten/Zugänge gezielt rekonstruieren; kein pauschales „enable all“ im Restorekommando.
Ein Produkt mit unabhängig vollständig rekonstruierbarem aktuellem Sperr-/Entzugsstand kann einen entsprechenden Abgleichadapter anstelle der pauschalen Kontenquarantäne verwenden. Er muss alle Konto-, Rollen-/Mitgliedschafts-, Token- und Recoveryänderungen seit Snapshot abdecken und negativ getestet sein; ein älteres Audit aus demselben Dump genügt nicht. Dies ist eine begründete Produktvariante mit gleicher Schutzwirkung, kein neuer zentraler Entzugsdienst.
Die technische Verfügbarkeit einer restaurierten App und die Wiederfreigabe ihrer Konten werden getrennt gemessen. service_restored_at bedeutet geprüfter Dienst erreichbar; user_access_restored_at gehört zum konkret gewählten RTO-Ziel und schließt notwendige Konten-/MFA-/Berechtigungsrekonstruktion ein. Der Restorebericht darf vier Stunden RTO nicht allein durch grünes Health behaupten, während alle regulären Zugänge ungeplant gesperrt bleiben.
13. Betriebsbeobachtung und Recoveryübungen
ops status liest Journal/Receipts, tatsächliche Runtime-/DBidentität, sichere Health-/Builddaten und Backupalter. Ausgabe: healthy, degraded, maintenance oder failed, mit sicheren Reasoncodes; keine Personeninhalte, DBpasswörter oder vollständigen Logs. Readiness prüft die Laufzeitabhängigkeiten; ein Backupstatus wird separat berichtet und nicht als Authlogout interpretiert.
RPO-Messwert = aktuelle Zeit bzw. Incidentzeit minus Snapshotzeit des jüngsten unabhängigen COMPLETE-Backups; nicht dessen Kopierabschlusszeit. Default Warnschwelle 18 Stunden, Zielverletzung ab 24 Stunden. Bei Zielverletzung werden neue Produktionsreleases blockiert und über den vorhandenen Betriebskanal/Jobfehler sichtbar gemeldet; die laufende Anwendung wird nicht unbemerkt abgeschaltet. Fehlender Empfänger/Überwachungskanal bleibt eine sichtbar fehlende Betriebsanbindung, keine erfundene Benachrichtigung.
Vorhandener Scheduler (z. B. Hosttimer) ruft die lokale Backup-CLI auf; kein Scheduler in der App und keine Automationsanlage in diesem Auftrag. Überwacht werden auch erfolglose/nie gestartete Jobs über Alter des letzten Receipts. Retentionsjobs sind nur nach vollständiger erfolgreicher Sicherung zulässig. RTO misst Incident-/Übungsbeginn bis zum im Produktprofil definierten Wiederherstellungsziel, einschließlich Beschaffung der Keys/Images, Restore, Integrität und erforderlicher Zugangsfreigabe.
Pflichtübungen im späteren Zielaufbau:
- Vor externem datenveränderndem Betrieb: synthetische End-to-End-Sicherung/Restore mit repräsentativem Medienvolumen, tatsächlichem gewählten Schlüssel-/Speicherweg und begrenzter Runtime-Rolle.
- Vor einer Änderung von Backupformat, Schlüssel-/Speicherweg oder nicht kompatibler Migration: betroffenen Recoverypfad erneut ausführen.
- Regelmäßig, Default monatlich: Restore eines ausgewählten vollständigen Recoverysets; mindestens eine Übung beginnt auf leerer Ersatzumgebung. Produktive Archive gehören nur in eine ausdrücklich autorisierte abgeschottete eigene Recoveryumgebung, niemals in normale CI oder einen fremden Dienst. CI verwendet synthetische Daten und eigene Keys.
Drillbericht: Backup-/Key-/Image-/Schema-/Profilreferenzen, Umfang/Umgebung, Befehlseinstiegspunkte, tatsächliches Ergebnis/Abbruchphase, Daten-/Medienabgleich, Sicherheitsnachbehandlung, gemessene RPO/RTO und verbleibende Lücken. Ein alter erfolgreicher Drill belegt keinen unbekannten neuen Schlüsselsatz oder größeren Datenbestand. Ergebnisse erhalten erst nach tatsächlichem Erfolg den Status T.
14. Konkrete Python-/CLI-Verträge
Der Controller ist ein produktlokales Pythonpaket außerhalb der FastAPI-Runtime. Abhängigkeiten werden separat gelockt; keine Importnebenwirkungen und keine globale Ziel-DB. Ein kleiner Composition Root verdrahtet die folgenden Ports. Datenobjekte werden mit strikten versionierten Schemas validiert, zusätzliche unbekannte Felder verweigert. Die Abkürzungen im Beispiel stehen für die oben definierten vollständigen Manifest-/Profilverträge.
from contextlib import AbstractContextManager
from dataclasses import dataclass
from pathlib import Path
from typing import Literal, Protocol
@dataclass(frozen=True, slots=True)
class TargetRef:
product_id: str
environment: Literal["development", "test", "production"]
host_id: str
profile_sha256: str
database_instance_id: str
@dataclass(frozen=True, slots=True)
class ReleaseRef:
release_id: str
manifest_sha256: str
@dataclass(frozen=True, slots=True)
class VerifiedRelease:
ref: ReleaseRef
approved_main_commit: str
source_tree: str
backend_image_id: str
frontend_image_id: str
migrations_sha256: str
qualification_run_ids: tuple[str, ...]
@dataclass(frozen=True, slots=True)
class OperationPlan:
operation_id: str
action: Literal["deploy", "image_rollback", "restore"]
target: TargetRef
expected_generation_id: str
target_generation_id: str
target_database_instance_id: str
release: ReleaseRef
backup_id: str | None
expires_at: str
class Lease(Protocol):
"""Interne geprüfte Operationslease; nie aus CLI/JSON deserialisieren."""
class FrozenWriters(Protocol):
"""Bestätigter Writerstillstand unter einer gehaltenen Lease."""
class ProvenanceVerifier(Protocol):
def require_qualified_and_approved(
self, target: TargetRef, release: ReleaseRef,
) -> VerifiedRelease: ...
class HostCoordinator(Protocol):
def exclusive(self, target: TargetRef,
operation_id: str) -> AbstractContextManager[Lease]: ...
def freeze(self, lease: Lease) -> FrozenWriters: ...
class BackupController(Protocol):
def capture(self, lease: Lease, frozen: FrozenWriters) -> str:
"""Liefert ausschließlich die ID eines COMPLETE-Backups."""
...
class RecoveryHooks(Protocol):
def require_media_consistency(self, tx: object, media_root: Path,
manifest: dict) -> None: ...
def invalidate_restored_security_state(self, tx: object,
restore_id: str) -> None: ...
VerifiedRelease, Lease und FrozenWriters sind interne Ergebnisse echter Adapterprüfungen. Ein CLIflag --verified, ein JSONstatus oder ein Testfake darf sie im Produktionsaufbau nicht ersetzen. Alle zustandsverändernden Schritte prüfen den gehaltenen Lock und erwartete tatsächliche Zielgeneration erneut. Auth-/Medien-/Integritätsadapter erhalten explizite Transaktionshandles; ihre Pflichtänderungen und Audit committen zusammen. Subprocessaufrufe erfolgen mit Argumentlisten und shell=False, begrenzter Laufzeit, redigierter Ausgabe und geprüftem Exitcode. Keine Passwörter in Arguments/Exceptions.
14.1 Vorgesehene Einstiegspunkte
Die folgenden Befehle sind Spezifikation, nicht in dieser Lieferung angelegte oder ausgeführte Programme. <...> bezeichnet ausdrücklich zu wählende IDs/registrierte Pfade.
| Befehl | Wirkung |
|---|---|
python -m ops.release inspect --profile <profile> |
Read-only: registriertes Ziel, aktueller Stand, effektive Giteafähigkeiten, offene Voraussetzungen als sicheres JSON |
python -m ops.release verify --profile <profile> --release-id <id> |
Quell-/Gate-/Merge-/Artefaktbeziehung lesen und prüfen; keine Liveänderung |
python -m ops.release plan --profile <profile> --release-id <id> --expect-current <generation> |
Gebundenen Deploymentplan und dessen Hash in geschützter Planablage erzeugen |
python -m ops.release apply --profile <profile> --plan-id <id> --plan-sha256 <hash> |
Unter Lock nach erneuter Prüfung den geplanten Release ausführen |
python -m ops.release reconcile --profile <profile> --operation-id <id> |
Tatsächlichen Zustand lesen und zulässigen Fortsetzungsplan erstellen; Änderungen erst über dessen apply |
python -m ops.backup create --profile <profile> |
Gemeinsame Lease, konsistent aufnehmen, verschlüsseln, unabhängig kopieren, Receipt |
python -m ops.backup verify --profile <profile> --backup-id <id> |
Äußere Hash-/Speicherprüfung; meldet ausdrücklich, ob nur Ciphertext oder auch Inhalt geprüft wurde |
python -m ops.backup retention-plan --profile <profile> |
Read-only-Plan der löschbaren IDs einschließlich Bindungs-/Holdprüfung erzeugen |
python -m ops.backup prune --profile <profile> --plan-id <id> --plan-sha256 <hash> |
Ausschließlich zuvor berechnete ungebundene Backup-IDs entfernen; kein automatischer Erfolgspfad bei fehlgeschlagener Sicherung |
python -m ops.restore plan --profile <profile> --backup-id <id> --expect-current <generation> |
Restoreziel, Datenstand, Keys/Images, Verlustfenster und Quarantäne planen |
python -m ops.restore apply --profile <profile> --plan-id <id> --plan-sha256 <hash> |
Neuen DB-/Medienstand vorbereiten, prüfen und kontrolliert umschalten |
python -m ops.restore drill --profile <test-profile> --fixture-set <id> |
Synthetische End-to-End-Übung ohne Livecredentials; Ergebnisbericht |
python -m ops.status --profile <profile> |
Laufzeit-/Backup-/Wartungs-/Recoveryzustand lesen, keine Reparatur |
Planer für Deployment, Restore und Retention teilen die versionierte Planablage; Retention hat eine eigene Planschemaart mit expliziten Lösch-IDs. Der gezeigte OperationPlan beschreibt Runtimewechsel. Plan-IDs werden unter registrierter Operationswurzel aufgelöst; kein beliebiger vom Workflow hochgeladener Plan wird privilegiert ausgeführt. Planhash liegt außerhalb des kanonisch serialisierten Planinhalts; Zeitwerte sind UTC und werden gegen vertrauenswürdige Hostzeit validiert. CLI und Journals schreiben sichere technische IDs, keine Kundennamen oder Secretreferenzen mit eingebetteten Werten.
Wiederholtes apply derselben bereits erfolgreichen Operation führt keinen zweiten Write aus: Nur wenn Receipt und tatsächliche aktuelle Generation noch übereinstimmen, darf der bestehende Erfolg zurückgegeben werden. Nach zwischenzeitlich neuerem Release oder verändertem Ziel ist der Plan stale. Unvollständige Operationen verlangen Reconcile; keine versteckten pauschalen Retries von Restore/Mutation.
14.2 Fehler- und Exitcodevertrag
| Exit | Codegruppe | Verhalten |
|---|---|---|
| 0 | ok |
Vollständig nachgewiesene angeforderte Operation; Read-only-Reports unterscheiden ihre Prüftiefe |
| 2 | profile_invalid, manifest_invalid, plan_invalid |
Schema/Parameter unbekannt oder unvollständig; keine Zielmutation |
| 3 | provenance_denied, gate_missing, gate_failed, approval_missing, artifact_mismatch |
Nicht qualifiziert/freigegeben oder falsches Artefakt; Produktion unverändert |
| 4 | target_mismatch, stale_plan, preflight_failed, backup_stale |
Ziel-/Betriebsbedingung nicht erfüllt; geänderten Plan nicht anwenden |
| 5 | dependency_unavailable, backup_failed, key_unavailable |
Abhängigkeit/Sicherung gestört; Fehlerzustand und sichere Phase melden |
| 6 | migration_failed, switch_incomplete, recovery_required |
Mögliche Mutation, Wartung erhalten und Reconcile/Recovery erforderlich |
| 7 | restore_validation_failed, recovery_objective_missed |
Übung/Integrität/Ziel nicht nachgewiesen; keine Erfolgsmarkierung |
| 8 | operation_busy |
Lock nicht rechtzeitig erhalten; keine parallele Operation |
Fehlerobjekt: operation_id,code,phase,target_id,retry_class,request_or_run_id; sichere Kurzbeschreibung, keine rohen SQL-/Docker-/Secret-/Archivdaten. retry_class ist read_only_retry, replan oder reconcile_required; keine automatische Wiederholung eines unklar abgeschlossenen Write. Das Hosttool hält die ursprüngliche Fehlerursache/Exitnummer trotz fehlgeschlagenem Cleanup fest.
15. Automatisierte Prüfungen und Abnahme
Die folgende Matrix ist ein konkreter Implementierungs-/Testauftrag, keine ausgeführte Testliste. Testdaten: Produkt A/B und Dev/Prod als getrennte synthetische Identitäten, zwei Source-/Buildstände, mindestens ein migrierter Datensatz mit Medienreferenz, Auth-/MFA-/Mitgliedschaftsfixtures aus Phase 3.3, eigene Backup-/Faktorschlüssel. Echtes isoliertes PostgreSQL und lokale Testvolumes; keine Produktserver oder produktiven Schlüssel verwenden.
| ID / Suite | Testfall | Verlangter Nachweis |
|---|---|---|
P01 test_provenance.py |
R1 mit gleichem Tree, abweichendem Mergecommit; R2 mit separaten Dev-/Prodhashes | Nur korrekte Quell-/Merge-/Buildbeziehung erlaubt; beide Varianten ohne Sonderfreigabeschleife |
| P02 | Roter/fehlender/geskippter Pflichtfall, null Collection, xfail, falsche parametrische ID, fremder Run | Gate verweigert; bloß grüne Workflowzusammenfassung genügt nicht |
| P03 | Manipuliertes Manifest/Archiv/Tag, eigener Upload mit passenden selbst erzeugten Hashes | Hash und vertrauenswürdige Herkunft nötig; geladene/gestartete Image-ID stimmt exakt |
| P04 | Falscher Main-Commit, Bot-/Autorname als Menschbeleg, Directpush, Freigabe nach anderer Qualifikation | Kein Deployment; tatsächlicher erlaubter menschlicher Merge ist eindeutig gebunden |
| P05 | Unverifiziertes Gitea-Environment/Branchschutz-/Runlookup oder fehlende Plattform | Konfiguration nicht als wirksam behauptet; Produktivgate geschlossen |
| P06 | Pflichtliste im Kandidaten ausgedünnt, Gateprofil geändert | Hostseitiger Mindestvertrag/-version und freigegebener Profilhash verhindern eigenmächtiges Weglassen obligatorischer Gategruppen |
| P07 | Wiederaufbau bei neuem Rezept/Toolchainstand | Protokollierte Inputs rekonstruierbar; unerklärte Laufzeit-/Assetabweichung verweigert; Metadatenunterschiede explizit eingeordnet |
I01 test_test_isolation.py |
Testziel zeigt auf Dev/Prod, falschen Marker/Benutzer/Run/Netz/Volume | Vor erstem Schemawrite abgebrochen; Livezustand unverändert |
| I02 | Zwei parallele Qualificationruns | Eigene DBs/Netze/Ports/Volumes, keine Kollision oder fremde Cleanups |
| I03 | Test-/Buildfehler, Abbruch und Stale-Run-Cleanup | Ressourcen nur der eigenen Run-ID entfernt; Fehlerexit erhalten; aktive/fremde Runs geschützt |
| I04 | Provider-/SMTP-/Webhookzugriff und Produktions-Dockersocket aus Testjob | Netz-/Credentialgrenze blockiert; keine reale externe Nebenwirkung |
D01 test_release_controller.py |
Vollständiger Deploy R1 und R2, wiederholtes Apply | Richtige Images/Revision/Schema, genau ein Runtimewechsel, vollständiger Receipt |
| D02 | Zwei Deploys bzw. Deploy/Backup/Restore gleichzeitig | Gemeinsamer Lock serialisiert; kein zweite Controllerlease im Kindschritt |
| D03 | Ziel-/Generation-/Profiländerung nach Plan | Staleplan verweigert; keine falsche DB oder fremdes Produkt betroffen |
| D04 | Stromausfall/Exception an jeder Journalphase vor/nach Effekt | Wartung/Journal bleiben konsistent; Reconcile erkennt tatsächlichen Zustand, kein blindes Restart/Öffnen |
| D05 | Kandidatready mit falscher Image-/Build-ID, falschem Frontend oder falschem Schema | Smoke/Gate rot trotz HTTP 200; kein Servingcommit |
| D06 | Fehler vor Migration vs. Fehler nach möglicher Migration | Nur sicher unveränderte alte Generation kontrolliert öffnen; sonst Wartung und gewählter Recoveryweg |
| D07 | Produktionsmodus im isolierten Image-Test mit synthetischer Konfiguration | Production-Startup/Secure-/Diagnosegrenzen tatsächlich geprüft; physisches Testtarget bleibt von Live getrennt |
M01 test_migration_recovery.py |
SQL-/Ledgerfehler, paralleler Runner, Dollar-quoted SQL, Drift/fehlende Datei | Foundation-A5-Atomarität/Prüfsummen/Lock erfüllt; keine Migration beim Runtimeimport/-start |
| M02 | Upgrade und altes Image auf neuem Schema; bewusst inkompatibler Eingriff | Rollback nur bei tatsächlichem Start-/Vertragstest; sonst Restore/Forward-Fix-Vorsorge belegt |
| M03 | Runtimeprivilegien nach Migration und nach Restore | Runtime nicht Owner/Superuser/BYPASSRLS und kein DDL; tatsächliche Fachzugriffe funktionieren |
B01 test_backup.py |
DBwrite, Upload und Löschjob beim Freeze | Alle registrierten Writer gestoppt/drained; gleicher DB-/Medienkonsistenzpunkt; kein fehlendes Referenzobjekt |
| B02 | Leerer/abgebrochener Dump, fehlendes Medium, voller Datenträger | Kein COMPLETE; keine Retentionslöschung oder Erfolgsmeldung |
| B03 | Verschlüsselung scheitert, Empfänger falsch, externe Kopie unvollständig, gleicher Hostpfad | Kein unabhängiger COMPLETE-Nachweis; klare Prüftiefe; keine Keys/Rohdaten in Logs/Artefakten |
| B04 | Retention mit aktuellem/pinned/gesperrtem/letztem Backup, benötigten alten Keys/Images | Benötigte Sets bleiben erhalten; nur explizite ungebundene IDs gelöscht |
| B05 | Snapshotalter vs. Abschlussalter, verpasster Schedulerlauf | RPO korrekt aus Snapshotzeit; Warnung/Zielverletzung sichtbar; neues Release bei verletzter Bedingung gesperrt |
R01 test_restore.py |
Synthetischer Komplettrestore auf leerer Ersatzumgebung | DB-/Medien-/Hash-/Schema-/Key-/Imagebindung stimmt; RPO/RTO einschließlich gewählter Zugangsrekonstruktion gemessen |
| R02 | Pfadtraversal, Symlink/Hardlink, Duplikate, Archivbombe, fremde Quelle/Hash | Vor Extraktion/DBimport verweigert; keine Datei außerhalb Staging/Zielwurzel |
| R03 | Importfehler und fehlende Rollen/Extensions/Keys/Medien | Neue Generation nicht öffentlich; alte Generation erhalten; keine still ignorierten Fehlobjekte |
| R04 | Abbruch nach DBrestore, nach Medienextraktion, während Zeiger-/Containerwechsel | Kein gemischtes DB-/Medienpaar öffentlich; Wartung/Reconcile funktioniert |
| R05 | Rückschalten nach ersten neuen Writes | Kein automatischer verlustfreier Retry behauptet; neuer Recoveryplan nötig |
| R06 | Alte Session, verbrauchter Recoverycode, widerrufener Maschinen-/Medienzugang im Snapshot | Nach Restore nicht nutzbar; Epoch/Flows/Codes/Adapter tatsächlich invalidiert |
| R07 | Nach Snapshot gesperrtes Konto/entzogene Mitgliedschaft im Backup wieder aktiv | Quarantäne bzw. vollständiger aktueller Abgleich verhindert erneuten Zugriff; kein pauschales Enable-all |
| R08 | TOTP-Replaycounter, Betreiber-Recovery und fehlender Faktor-Key | Counter nicht abgesenkt, aktuelle alte OTP nicht akzeptiert; keine Faktorlos-Ausnahme; gezielter sicherer Betreiberwiederanlauf |
| R09 | Gleicher Dump auf falschem Produkt/Umgebung/Instanz | Plan-/Manifest-/Zielprüfung verweigert, außer ausdrücklich als isolierter Testclone registrierter synthetischer Drill |
Zusätzlich: statischer Konfigurationscheck auf build:/Livequellmounts im Releasecompose, Secretwerte in Manifesten, unzulässige Runner-/Deployrechte sowie fehlende Fach-/Auth-/Medienhooks. Syntaktische Checks ersetzen die oben genannten Effekt-/Negativtests nicht.
Die hostseitige Gatepolicy fixiert Mindestgruppen/Vertragsversion und erwartete Funktionsadapter. Ein Kandidat kann seine eigene Pflichtliste nicht beliebig auf eine triviale Suite reduzieren. Geänderte zulässige Pflichtfälle bleiben Teil des bewusst geprüften Quell-/Controller-/Profilstands; keine neue zentrale Governanceplattform.
Pflicht-Gateprobe: Einen erforderlichen Test absichtlich rot machen, danach einmal dessen Report entfernen und einmal einen erforderlichen Test skippen. Jede Variante muss Produktionsverifikation stoppen, bevor Wartung/Migration beginnt. Danach den unveränderten qualifizierten Erfolgsfall vollständig durchlaufen. Diese Probe findet ausschließlich in der isolierten Abnahmeumgebung statt.
16. Implementierungsanweisung für Cursor
Späterer Auftrag; hier wird nichts implementiert oder betrieben. Das konkrete Zielrepository und registrierte Betriebsziel werden im tatsächlichen Umsetzungsauftrag benannt. Der Auth-Blueprint bleibt Phase-3.3-Grundlage; dieser Text startet nicht automatisch dessen Phase-3.4-Implementierung.
- Foundation v0.3 und diesen Blueprint im benannten Zielaufbau verwenden. Vorhandene Reusekandidaten aus Abschnitt 2 gezielt übernehmen, einschließlich Herkunft/Abweichungen. Keine anderen Produktrepos ändern oder zur Laufzeit importieren.
- Kleine getrennte
ops-Toolchain mit Strictschemas, Ziel-/Pfadprüfungen, Dataclasses/Ports und redigiertem Fehlervertrag erstellen. Commands ohne Wirkung importierbar;inspect/verify/planstrikt read-only gegenüber Livezustand. Keine FastAPI-Betriebsverwaltung entwickeln. - Profil und Controllervertrauen konkret verdrahten. Tatsächliche Gitea-/Runner-/Proxy-/Host-/Speicherfähigkeiten lesend erfassen, O2/O3 mit konkreten technischen Werten ausfüllen. Fehlende Zugänge/Ziele im Implementierungsbericht als nicht verifiziert führen; keine erfundenen Servereinstellungen oder pauschalen Neuinstallationen. Neue Produktions-/Giteakonfiguration nur im ausdrücklich autorisierten späteren Integrationsumfang vornehmen.
- Isolierten Qualificationstack und
required-tests.jsonaufbauen, Runtimeimages exakt identifizieren, Testrollen/Marker/Wächter einrichten, Rohberichte auswerten. Feste Devtestdatenbanken und Tests gegen laufende Appcontainer nicht kopieren. Keine Provider-/Kundenschlüssel nutzen. - Gitea-Workflows im vorhandenen System auf Qualification → menschlich freigegebenen Main → geprüftes Deployment binden. R1 als Default unterstützen, R2 gleichwertig gatefähig halten. Fehlende/rote/geskippte Pflichtbelege und untrusted Artefakte blockieren in beiden Varianten. Keine neue Registry, kein ausschließlich nachgelagerter Produktionstest als Gateersatz.
- Hostlock, persistenten Wartungsschalter, Writerinventory/-drain und Journalzustandsautomaten implementieren. Controllerstand geschützt bereitstellen, tatsächliche Laufzeitidentität prüfen, Wiederanlauf nach jedem möglichen Abbruch testen. Der App-Prozess erhält keine Controller-/Docker-/Migrationsrechte.
- Foundation-SQL-Runner anbinden, Image-/Schemakompatibilität tatsächlich testen, frische Pre-release-Sicherung vor Migration verlangen. Kein produktives Schema-Down, keine Container-Migration beim Start und kein automatisches Rollback in unklaren Datenzustand.
- Mitai-Custom-Dump und Kanshō-Manifest als kleine Adapter auf PostgreSQL/Medien übertragen. Gemeinsamen Freeze, vollständige Referenzprüfung, Verschlüsselung, unabhängige Kopie und Retention mit gebundenen Recoverysets implementieren. Nur registrierte Medienpfade, kein Appverzeichnis-Vollbackup mit Secrets.
- Restore in neue DB-/Mediengeneration, Ziel-/Archivschutz, gekoppelte Umschaltung und Auth-/Berechtigungsnachbehandlung implementieren. Fehlende Hooks schließen Recoveryfreigabe. Keine aktive Live-DB durch
--cleanersetzen. Synthetische Hostverlust-/Abbruchübungen samt Keys/Images/RPO/RTO ausführen. - Matrix aus Abschnitt 15 tatsächlich ausführen; bestandene Ergebnisse mit Commit/Build-/Controller-/Profilstand und Umgebung dokumentieren. Erzeugte CLI-/JSON-/Compose-/Workflowdateien, Lockfiles, OpenAPI-/Authintegration soweit betroffen und nachvollziehbare Reports liefern. Nicht implementierte Produktadapter sichtbar schließen und korrekt als K/offen führen.
Ein sinnvoller erster Referenzdurchlauf verwendet ein synthetisches persönliches Objekt mit einer Mediendatei: qualifiziertes Image → freigegebener Release → Migration → konsistentes Backup → absichtlich fehlschlagender Kandidat → qualifizierter Rückweg → Restore in neue Generation → überprüfte Session-/Zugriffssperre. Der Durchlauf muss keine neuen KI-/Billing-/SSO-Funktionen erfinden. Bestehende Appdaten werden dafür nicht benötigt.
Abnahme des späteren Zielaufbaus: erforderliche Tests bestanden, rotes Gate verhindert nachweislich Deployment, Runtime entspricht dem freigegebenen qualifizierten Artefakt, DB-/Medienrestore und Sicherheitsnachbehandlung funktionieren, Betriebs-/Recoveryziele mit realen Messwerten und Grenzen dokumentiert. Das ist noch keine pauschale Reifeaussage für sämtliche Fachfunktionen eines Produkts.
17. Prüfstand dieser Lieferung
Erstellt wurde ausschließlich dieses neue Blueprintdokument. Quellen-/Vorgängerdokumente und Produktrepos wurden nicht bearbeitet. Keine DBverbindungen, Credentials, persönlichen Sicherungen, Live-APIaufrufe, Migrationen, Deployments, Runner-/Branchschutzänderungen, Paketinstallationen oder Anwendungstestläufe. Alle angegebenen Betriebsprogramme, JSON-/Pythonbeispiele und Tests sind Spezifikation V/K.
Dokumentprüfung: lokale Linkziele/-zeilen, Syntax der Python-/JSONbeispiele, Abdeckung von R1/R2, Gate-/Zielschutz, Backup-/Medienkonsistenz, Restore-/Securityhooks, Testmatrix und Cursorauftrag. Dies validiert das Dokument, nicht die geplante Anwendung. Der tatsächliche Gitea-/Host-/Backupzustand bleibt unbekannt, bis die ausdrücklich benannte spätere Integration ihn erfasst.
Externe Gegenprüfung beschränkte sich auf offizielle Gitea-, PostgreSQL-, Docker- und age-Primärquellen für die benannten technischen Details. Es gab keine neue umfassende Recherche. Quellcode und Dokumentation sind statische Referenzen I; der Blueprint bleibt V/K, ohne T-Gesamtnachweis.
17.1 Lokaler Quellstand
Lesestand 16.10.2026. Hashes über vollständige Dateien; Git-HEAD allein behauptet keinen sauberen Checkout.
shinkan-jinkendo: Git-HEADf10c28e5cdcef52cc44e953a8494b4bbe35b77fekairo-jinkendo: Git-HEADea0aa18b8dd9a55f663a996d74e63b7e3ee0dc16Kansho: Git-HEAD89d149684eab9211d6ef21181d018de097a61783mitai-jinkendo: Git-HEAD95453d548a2113555cd7e8f01fbbf267cbe34f3f
| Gezielt verwendete Produktquelle | SHA-256 |
|---|---|
| shinkan-jinkendo/backend/scripts/security_release_checks.py | cc1288ea039fb110c82b989fd3f05ee2a39bd031e6b1aece15af0d9b276666b2 |
| shinkan-jinkendo/.gitea/workflows/test.yml | d4f63d4f41de2d29c1b05aa23ac772caba8e089a77cb401dcb0c60600e3ee0ec |
| shinkan-jinkendo/.gitea/workflows/deploy-prod.yml | b874b49c0efc29e85794d4c557bb7c6c7fce928846421d2f38391451ce784b2a |
| kairo-jinkendo/.gitea/workflows/test.yml | e4d4d02aac13835ff82e4af7e96d3fc1c39d8fd3e736c51188bcd0dc64897591 |
| kairo-jinkendo/.gitea/workflows/deploy-dev.yml | c28ef680d325fa52d6361050bc5e3905e81aadc0de7206f9b1304c5f36e2b8aa |
| kairo-jinkendo/.cursor/rules/kairo-deployment-testing.mdc | 54d7026512de97a3cb17461f44ba1d6256984b861dceb0af5511809bcadf8830 |
| Kansho/.gitea/workflows/test.yml | 9454086f07554af9824280e4a1b4c253f3667b4bf10f2084c1d6c8adce39d574 |
| Kansho/scripts/backup-postgres.sh | d80060974eeffedbfd2930d83b8a2be1488790135d426a1570fb418bc729a729 |
| Kansho/backend/local_backup.py | be02a9e2d1f6c3c5f01acf7b8d8a602d0ca87cf2879eda58adff27a6ffc8d9ff |
| Kansho/docs/architecture/technical/runtime_and_deploy.md | 00cea03867fb09c1bb17dae908b629eb22d512d8f79082a1a005ee7e0e7d58dc |
| Kansho/docs/architecture/technical/security.md | 69e6c39111072e45dc54bfa86d98c2be75e9a9c6ba735acfdf4fa6b1529ae747 |
| mitai-jinkendo/scripts/backup/mitai_pg_dump.sh | 44b16b5ed7c48b25cec1deb6dce349ab9a6b265a3ec32b6b094099c7f61f7a6f |
| mitai-jinkendo/.gitea/workflows/deploy-prod.yml | 9eeae07067cb2f4bbba050b6eafdc05ec9679d5e5425bcc8cc166a0da1caf179 |
Ende dieses Blueprintauftrags. Kein weiterer Blueprint und keine Implementierung werden automatisch gestartet.