Fluxheim/Dokumentation/Configuration Basics

Configuration Basics

Fluxheim nutzt TOML. Unbekannte Felder werden abgelehnt, damit Tippfehler vor dem Neustart auffallen.

Grundstruktur

[server]
listen = ["0.0.0.0:8080"]
default_vhost = "site"

[[vhosts]]
name = "site"
hosts = ["example.com"]

Aktivieren Sie bei mandantenfähigen Bereitstellungen [server.host_routing].strict = true, damit eine fehlende oder ungültige Host-Identität 400 und ein unbekannter Host 421 zurückgibt, statt die Standard-Site zu erreichen.

Wie die Konfiguration organisiert ist

Bereich	Was dort hingehort
`server`	Listeners, global limits, trusted proxy handling, and redirects.
`tls`	Globale TLS-Backend- und Kompatibilitatspolitik.
`cache`	Process-wide cache defaults and storage tiers.
`vhosts`	Hostnames, routes, web roots, proxy settings, PHP, TLS, and access policy.
`metrics`	Prometheus- und Export-Listener fur operative Sichtbarkeit.

Routenform

[[vhosts.routes]]
name = "app"
path_prefix = "/app/"
methods = ["GET", "HEAD", "POST"]
max_request_body_bytes = "16MiB"

[vhosts.routes.proxy]
upstreams = ["127.0.0.1:3000"]

Eine Route hat einen Matcher und eine Aktion. Exakte Pfade gewinnen zuerst, dann langste Prefixe, dann Regex-Routen wenn Regex aktiviert ist, dann eine Fallback-Route.

HTTP-Antwortsicherheit

HTTP-Antwortsicherheitsprofile sind optional. Beginnen Sie mit baseline; Verwenden Sie die ursprungsübergreifende Isolierung erst, nachdem Sie jedes Skript, jede Schriftart, jedes Bild, jeden Anmeldeablauf und jede eingebettete Ressource getestet haben.

[headers.response.hardening]
profile = "baseline"

Profil	Was es bewirkt
`off`	Hält die Opt-in-Hardening-Header deaktiviert.
`baseline`	Fügt konservative Browserisolation und Standardeinstellungen für Ressourcenrichtlinien hinzu, die für die meisten Websites geeignet sind.
`cross-origin-isolated`	Ermöglicht eine strikte ursprungsübergreifende Isolierung für Anwendungen, die alle externen Abhängigkeiten getestet haben.

Keines der Profile aktiviert HSTS oder CSP. Konfigurieren Sie diese separat, nachdem Sie sie mit der realen Site getestet haben.

Standardbasierte Antwortmetadaten

Antwortmetadaten sind standardmäßig deaktiviert. Aktivieren Sie nur die Felder, die Sie benötigen. Fluxheim leitet sie aus dem tatsächlichen Cache-Ergebnis, dem Proxy-Fehler und den endgültigen Antwortbytes ab, ohne Cache-Schlüssel, Backend-Adressen, DNS-Namen oder Rohfehler offenzulegen.

[headers.response.metadata]
identifier = "edge-gateway"
cache_status = true
proxy_status = true
content_digest = true
repr_digest = true

Antwortfeld	Gemeldete Information
`Cache-Status`	RFC 9211 Cache-Ergebnisse wie Hit, Miss, Stale Forwarding, Revalidierung, Ablauf und Bypass.
`Proxy-Status`	RFC 9209 Details mit niedriger Kardinalität für Fehler, die von Fluxheim generiert wurden.
`Content-Digest`	SHA-256 gemäß RFC 9530 über den endgültigen HTTP-Nachrichteninhalt nach der Komprimierung.
`Repr-Digest`	SHA-256 nur, wenn Fluxheim die vollständige ausgewählte Darstellung vorhält.

Live-Schnappschüsse und Rollback

Authentifizierte Snapshots können einen validierten Kandidaten veröffentlichen, den aktiven Router ersetzen und zurückgesetzt werden, ohne normale reine Routing-Bereitstellungen neu zu starten. Jede Anfrage bleibt von Anfang bis Ende auf derselben Routergeneration.

Bewahren Sie den Snapshot-Speicher in einem eigenen privaten Verzeichnis auf; vorhandene nicht private Verzeichnisse und Dateisystemwurzeln werden abgelehnt.
Verwenden Sie ein Prozess-Upgrade, wenn im Hintergrund Zustandsprüfungen des Load-Balancers oder Erkennungsdienste aktiv sind.
Führen Sie nach der Veröffentlichung oder dem Rollback Snapshot-Integritätsprüfungen durch und stellen Sie sicher, dass die ausgewählte Generation den Neustart übersteht.

Lesen Sie den vollständigen Snapshot-Vertrag

Sichere Gewohnheiten

Run fluxheim --check-config before reloads.
Nutze einen Vhost pro Site oder Anwendungsgrenze.
Bewahre Secrets in Dateien, Umgebung oder Container-Secrets auf, nicht in öffentlichen Docs.
Konfigurationsdateien und alle vorhandenen übergeordneten Verzeichnisse müssen vertrauenswürdige Eigentümer haben und dürfen für Gruppen oder andere Benutzer nicht beschreibbar sein.
Ersetzen Sie den Prozess, wenn sich TLS, Listener, Streams, UDP, ACME, Cache-Bereinigung, Tracing oder Einstellungen verwalteter PHP-FPM-Prozesse ändern; für gewöhnliches Routing und Richtlinien zur Anfragezeit genügt ein Snapshot-Neuladen.
Nutze Routenlimits fur Uploads und teure Anwendungspfade.
Halte Admin- und Metrik-Listener privat.