Fluxheim/文件/Configuration Basics

Configuration Basics

Fluxheim 使用 TOML。未知欄位會被拒絕，因此拼寫錯誤會在重啟前失敗。

主要結構

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

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

對於 multi-tenant 部署，請啟用 [server.host_routing].strict = true。缺少或無效的 host identity 會回傳 400，未知 host 則回傳 421，而不會進入 default site。

設定如何組織

區域	這裡放什麼
`server`	Listeners, global limits, trusted proxy handling, and redirects.
`tls`	全域 TLS backend 與相容性策略。
`cache`	Process-wide cache defaults and storage tiers.
`vhosts`	Hostnames, routes, web roots, proxy settings, PHP, TLS, and access policy.
`metrics`	用於運維可見性的 Prometheus 和 export listeners。

Route 結構

[[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"]

一個 route 有一個 matcher 和一個 action。exact path 最先匹配，然後是最長 prefix；啟用 regex 時再匹配 regex route；最後是 fallback route。

HTTP 回應安全

HTTP 回應安全性設定檔是可選的。從baseline開始；僅在測試每個腳本、字體、映像、登入流程和嵌入資源後才使用跨來源隔離。

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

設定檔	它的作用
`off`	保持禁用選擇加入強化標頭。
`baseline`	新增適合大多數網站的保守瀏覽器隔離和資源原則預設值。
`cross-origin-isolated`	為已測試每個外部相依性的應用程式啟用嚴格的跨域隔離。

這兩個設定檔均不啟用 HSTS 或 CSP。在對真實網站進行測試後單獨配置它們。

基於標準的響應元數據

預設情況下會停用響應元資料。僅啟用您需要的欄位； Fluxheim 從實際快取結果、代理失敗和最終回應位元組中派生它們，而不會暴露快取金鑰、後端位址、DNS 名稱或原始錯誤。

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

欄位	報告內容
`Cache-Status`	RFC 9211 快取結果，例如命中、未命中、過時轉送、重新驗證、過期和旁路。
`Proxy-Status`	RFC 9209 Fluxheim 產生的故障的低基數詳細資料。
`Content-Digest`	RFC 9530 SHA-256 壓縮後最終的HTTP 訊息內容。
`Repr-Digest`	SHA-256 僅當 Fluxheim 持有完整的選定表示時。

即時快照和回滾

經身分認證的快照可以發布已驗證的候選設定、取代目前的路由器並執行回復，而不必重新啟動一般的純路由部署。每個請求從開始到結束都使用同一代路由器。

將快照儲存保存在專用的私有目錄中；現有的非私有目錄和檔案系統根被拒絕。
當後台負載平衡器運作狀況或發現服務處於活動狀態時，使用進程升級。
發布或回復後執行快照完整性檢查，並確認所選版本在重新啟動後仍然有效。

閱讀完整的快照運作規範

安全習慣

Run fluxheim --check-config before reloads.
每個站點或應用邊界使用一個 vhost。
將 secrets 放在檔案、環境變數或 container secrets 中，不要放在公共文件裡。
config file 及其每一層既有的父 directory 都應由可信任的主體擁有，且不得開放 group 或其他 user 寫入。
TLS、listener、stream、UDP、ACME、cache purge、tracing 或 managed PHP-FPM process 設定變更時，請替換 process；一般 routing 與 request-time policy 可以使用 snapshot reload。
對上傳和昂貴應用路徑使用 route-level limits。
保持 admin 和 metrics listeners 私有。