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 私有。