Plattformbetrieb

Diese Seite dokumentiert die operative Oberfläche, die hinter dem Produkt sitzt: den Lebenszyklus des Abuse-Status, der das Senden freischaltet, die Rolle des Plattform-Admins und ihre Queries, die Warteschlange zur Inhaltsprüfung, den Walker für die Organisationslöschung, Systemzustand und In-App-Selbstupdate sowie die Dev-Mode-Endpunkte, Crons und Migrationen, die ein Deployment wartbar halten. Sie richtet sich an Betreiber und Mitwirkende, die an einer selbst gehosteten Owlat-Instanz arbeiten.

Lebenszyklus des Abuse-Status und das Sende-Gate

Jedes Deployment trägt genau einen Abuse-Status auf instanceSettings.abuseStatus. Er steuert, ob die Instanz senden darf. Die vier Status, definiert in apps/api/convex/organizations/abuseStatus.ts, bilden eine Schweregradleiter:

Lese- und Schreibhälfte sind bewusst in Geschwistermodule getrennt (ADR-0011, docs/adr/0011-abuse-status-modules.md):

• Abuse-Gate (apps/api/convex/organizations/abuseGate.ts) ist die Heimat des Sende-Prädikats. Es exportiert zwei Oberflächen: isSendingAllowed(status), das reine Prädikat, das die Live-Sendepfade aufrufen (der Transaktions-Dispatch-Pfad in transactional/dispatch.ts), und requireSendingAllowed(ctx), ein Helfer für den Mutation-Kontext, der instanceSettings lädt und bei suspended/banned wirft. Der Kampagnen-Sendepfad erzwingt dasselbe Prädikat inline über seine Pre-Flight-Query (campaigns/preflight.ts, die abuseStatus direkt gegen suspended/banned prüft), statt den Helfer aufzurufen. So oder so läuft das Gate immer — es steht nicht hinter einem Feature-Flag.
• Abuse-Status (apps/api/convex/organizations/abuseStatus.ts) ist der einzige Schreiber von abuseStatus und den zugehörigen Feldern (abuseStatusReason, abuseStatusChangedAt, abuseStatusChangedBy).

Übergangsregeln

Es gibt zwei Schreib-Einstiegspunkte. Der Pfad für interne Schreiber erzwingt die Schweregradregeln; der Admin-Pfad umgeht sie.

Beide Pfade schreiben bei jedem Aufruf eine Audit-Log-Zeile abuse_status_changed, auch bei No-Ops auf denselben Zustand (damit „Circuit Breaker erneut ausgelöst, während bereits gewarnt“ beobachtbar ist). Eine fehlende instanceSettings-Zeile liefert { ok: false, reason: 'no_settings_row' }, statt zu werfen — ein Sonderfall in der Frühphase eines Deployments.

Was den Status automatisch umschaltet

Die Reputation wird beim Lesen abgeleitet (ein rollierendes 30-Tage-Fenster — siehe Deliverability-Infrastruktur), doch die Auto-Durchsetzung wird bewusst vom heißen Lesepfad ferngehalten: Ein stündlicher Cron evaluate reputation auto-enforce (apps/api/convex/crons.ts) ruft evaluateAutoEnforce auf, das das Org-Fenster zusammenfasst und autoEnforceReputation einplant, wenn das Risiko hoch oder kritisch ist. Ein separater stündlicher Cron cleanup sending reputation (recalculateAll) lässt Buckets älter als 60 Tage ausaltern. Weil Herabstufungen des Schweregrads abgelehnt werden, lockert ein Übergang critical → warned niemals stillschweigend eine bestehende Sperre.

Plattform-Admin-Rolle, Verzeichnis und operative Queries

Plattform-Admins sind Zeilen in der Tabelle platformAdmins, geschlüsselt über die BetterAuth-Benutzer-ID. Es gibt zwei Rollen: admin und superadmin. Ein Betreiber kann den ersten Admin von Hand anlegen mit convex run migrations/0036_seed_platform_admin:run; das gelingt nur, solange die Tabelle leer ist, und legt stets einen superadmin an. Danach verwalten superadmins das Verzeichnis.

Die Absicherung ist in apps/api/convex/platformAdmin/platformAdmin.ts zentralisiert:

Die Web-App sichert die einzige Admin-Seite mit der Route-Middleware platform-admin (apps/web/app/middleware/platform-admin.ts) ab, die isPlatformAdmin aufruft und Nicht-Admins auf /dashboard umleitet.

Operative Queries

Alle diese liegen in apps/api/convex/platformAdmin/queries.ts und beginnen mit requirePlatformAdmin. Sie lesen die Singleton-Zeile instanceSettings sowie abgeleitete Reputations-/Statistikwerte:

Mutationen für Verzeichnis + Status

Diese liegen in apps/api/convex/platformAdmin/mutations.ts:

Warteschlange zur Inhaltsprüfung (ausstehende Inhalte freigeben/ablehnen)

Kampagnen und Transaktionsmails können im Status pending_review landen (etwa wenn das Content-Scanning sie markiert — siehe E-Mail-Sicherheit). Die Prüfoberfläche ist ausschließlich Plattform-Admins vorbehalten.

getContentReviewQueue (in platformAdmin/queries.ts) liefert die ausstehenden Objekte samt ihrem jüngsten Inhaltsscan-Ergebnis sowie das Protokoll der kürzlich geprüften Objekte:

{
  pending: [{ type: 'campaign' | 'transactional', id, name, subject, scan: { score, level } | null, ... }],
  pendingCount: number,
  recentlyReviewed: [{ action, details, userId, createdAt }],
}

Die drei Prüf-Mutationen (in platformAdmin/mutations.ts) verlangen allesamt pending_review als aktuellen Status und schreiben eine Audit-Zeile platform_admin.content_approved oder platform_admin.content_rejected:

Beide Freigabepfade und der Ablehnungspfad holen die Ressource aus der Warteschlange; es gibt keinen separaten terminalen Zustand „blockiert“ für geprüfte Inhalte — eine Ablehnung führt zurück auf draft, wobei der Grund im Audit-Log festgehalten wird.

Walker für die Organisationslöschung

Die Organisation zu löschen ist ein harter, unumkehrbarer Wipe der gesamten Data Plane. Er ist dem Eigentümer vorbehalten: organizationSettings.remove (in apps/api/convex/organizations/settings.ts) prüft session.role === 'owner' und plant internal.organizations.deletion.walker.start ein. Der Walker liegt in apps/api/convex/organizations/deletion/walker.ts und setzt ADR-0025 um (docs/adr/0025-organization-deletion-module-family.md).

Funktionsweise:

• Geordnete Kaskade. STEPS ist eine geordnete Liste des vollständigen Tabellensatzes pro Organisation, ~90 Tabellen. Kinder werden vor Eltern gelöscht; Tabellen mit Storage-Bezug (z. B. mediaAssets, semanticFiles, mailMessages) räumen ihre Blobs vor dem Löschen der Zeile ab; auditLogs steht an vorletzter Stelle (es sammelt während des Wipes weiterhin Einträge aus delegierten Lifecycle-Aufrufen an); instanceSettings ist der abschließende Schritt.
• Ein Modul pro Tabelle. Jeder Eintrag hat ein Geschwister-Step-Modul unter deletion/steps/<table>.ts, das den Contract deleteBatch(ctx) aus steps/_common.ts implementiert (Standard-Batchgröße 100). Einige Tabellen delegieren — so fegt der Step contacts fünf Kindtabellen mit (contactTopics, contactPropertyValues, contactActivities, contactIdentities, contactRelationships), die keine eigenständigen Steps sind.
• Selbstgeplanter Hop. runStep führt einen Batch aus, feuert sich selbst erneut, solange hasMore wahr ist, rückt auf nextTable vor, wenn ein Step leerläuft, und endet, wenn es keinen nächsten Step gibt. Das Argument table wird gegen die Literal-Union in _common.ts validiert, sodass ein Tippfehler ein Compile- und Boot-Zeit-Fehler ist statt eines stillen No-Ops.

Jede neue Tabelle pro Organisation, die dem Schema hinzugefügt wird, muss außerdem ein Literal in OrganizationDeletionTable und ein Geschwister-Step-Modul ergänzen, sonst lässt die Löschkaskade sie verwaist zurück.

Systemzustand und In-App-Selbstupdate (Updater-Sidecar)

Die Seite System & Updates (/dashboard/admin/system, nur für Plattform-Admins) zeigt die aktuelle Version, den Container-Zustand, die GitHub-Release-Prüfung, den Update-Ablauf und die Update-Historie.

Update-Prüfung

apps/api/convex/systemUpdates.ts fragt die GitHub-Releases-API ab (https://api.github.com/repos/wolvesdotink/owlat/releases/latest), cacht das Ergebnis in einer Singleton-Zeile systemUpdates (kind: 'latestCheck') mit einer TTL von 1 Stunde und berechnet updateAvailable, indem es die gecachte neueste Version mit der laufenden OWLAT_VERSION vergleicht.

Ein lokaler Build, der OWLAT_VERSION=dev (oder einen Nicht-Semver-Wert) meldet, gilt immer als „kein Update verfügbar“, weil Owlat nicht feststellen kann, ob ein Dev-Build dem Release-Tag voraus oder hinterher ist.

Ein Update anwenden

Ein Klick auf Jetzt aktualisieren postet an die Nitro-Route apps/web/server/api/system/update.post.ts, die:

Der Updater-Sidecar

Der Updater (apps/updater/src/index.ts, Image ghcr.io/wolvesdotink/updater, lauscht auf Port 3200, ausschließlich in einem internen Docker-Netzwerk exponiert (kein Host-Port-Mapping), sodass ihn nur der Web-Container über http://updater:3200 erreichen kann) ist die einzige Komponente, die Docker anfasst. Er authentifiziert jede Anfrage mit einem timing-sicheren Vergleich von X-Instance-Secret und erreicht Docker über einen Socket-Proxy nach dem Least-Privilege-Prinzip (er kann Container pullen/neu erstellen/auflisten, aber nicht exec ausführen, bauen oder Volumes anfassen).

Die Seite System & Updates liest /health (über apps/web/server/api/internal/updater-health.get.ts weitergereicht), um die Tabelle zum Container-Zustand zu rendern. Die Reihenfolge convex-deploy vor Neustart ist die Sicherheitseigenschaft: Ein inkompatibles Schema lässt den Deploy-Schritt scheitern, und die laufenden Web-/MTA-Container werden nie gegen ein halb deploytes Backend neu gestartet.

Das betreiberseitige Playbook für Updates (Rollback, Wiederherstellung, Automatisierung) finden Sie unter Wartung & Updates.

Dev-Mode-Endpunkte, Crons und Migrationen

Dev-Mode-Endpunkte

Für die lokale Entwicklung existiert eine kleine Menge destruktiver Abkürzungen. Sie sind fail-closed: Der Guard in apps/api/convex/devShortcuts/_guard.ts behandelt das Deployment als Produktion, sofern der Betreiber nicht ausdrücklich OWLAT_DEV_MODE=true in der Laufzeitumgebung des Convex-Backends setzt (npx convex env set OWLAT_DEV_MODE true). Die CLI-seitige Umgebungsvariable CONVEX_DEPLOYMENT wird nicht in die Function-Runtime propagiert und taugt daher nicht als Sicherheitsgrenze.

Der Wunsch nach Demo-Inhalten ist kein Grund, ihn zu aktivieren. POST /sample-data/{install,remove,status} (apps/api/convex/sampleData/) spielt denselben Datensatz abzüglich der Dummy-Anmeldungen und Postfächer ein, wird allein mit X-Instance-Secret authentifiziert und entfernt exakt das, was es eingefügt hat (auf seedTag eingegrenzt, innerhalb der Löschtransaktion erneut geprüft). Steuern Sie ihn mit owlat sample-data <install|remove|status>.

Crons

Geplante Jobs sind in apps/api/convex/crons.ts registriert. Operativ relevant sind unter anderem:

Die Crons zum Zählerabgleich (reconcile contact counts, reconcile topic member counts, refresh segment counts, reconcile transactional send counts) halten denormalisierte Zähler gegenüber jeglicher Drift aus Teilfehlern ehrlich.

Migrationen

Schema-/Datenmigrationen sind einmalige interne Mutationen unter apps/api/convex/migrations/, die jeweils eine run-Mutation exportieren. Sie folgen dem Pre-Prod-Muster der „atomaren Breaking Change“: Jede Migration ist idempotent (ein erneuter Lauf ist ein No-Op, sobald jede Zeile umgeschrieben ist), und weil Deployments einorganisatorisch und zurücksetzbar sind, laufen die meisten synchron gegen .collect().

Sie rufen eine Migration namentlich über die Convex-CLI auf, zum Beispiel:

npx convex run migrations/0033_campaign_audience:run

Verwandte Seiten