配置系统

本文引用的文件
- config.v - v2_config.v - runtime_plan_loader.v - v1_plan_compat.v - runtime_plan_cli_overlay.v - server_lifecycle_runtime_config.v - CONFIGURATION_MODEL_V2.md - PROTOCOL_PIPELINE_IMPLEMENTATION_PLAN.md - README.md - vhttpd.example.toml - vhttpd.multi.example.toml - vhttpd.vjsx.example.toml

简介

本文件系统性阐述 VHTTPD 的配置系统架构与实现原理，覆盖以下主题： - TOML 配置文件解析流程（V1 兼容与 V2 严格模式） - 环境变量注入机制与路径别名系统 - 多层配置覆盖策略（全局、站点、执行器、CLI 覆盖） - 运行时配置热更新机制与验证流程 - 完整配置项参考、常用模式与最佳实践 - 调试技巧与常见问题排查

项目结构

配置相关代码集中在 src/config 下，包含 V1/V2 两套模型、加载器、编译器与 CLI 覆盖层；示例配置位于 config 目录；设计目标与迁移路线在 docs 中说明。

graph TB
A["TOML 配置<br/>vhttpd.example.toml / vhttpd.multi.example.toml / vhttpd.vjsx.example.toml"] --> B["版本检测<br/>detect_config_version()"]
B --> |version=2| C["V2 严格解码<br/>decode_v2_config_strict()"]
B --> |无 version 或 version=1| D["V1 兼容解码<br/>load_vhttpd_config()"]
C --> E["变量展开与路径解析<br/>resolve_v2_config_variables_and_paths()"]
D --> F["变量展开与路径解析<br/>resolve_config_variables()"]
E --> G["V2 编译为 RuntimePlan<br/>compile_v2_runtime_plan()"]
D --> H["V1→V2 兼容编译<br/>compile_v1_to_v2() + compile_v2_runtime_plan()"]
G --> I["运行时装配<br/>server_lifecycle/runtime_config.v"]
H --> I

图表来源 - runtime_plan_loader.v:10-46 - config.v:448-482 - v1_plan_compat.v:5-9 - v2_config.v:1-19

章节来源 - config.v:448-482 - runtime_plan_loader.v:10-46 - v1_plan_compat.v:5-9 - v2_config.v:1-19

核心组件

版本检测与入口
detect_config_version：从 TOML 的 version 字段判断 V1/V2
load_runtime_plan_file：根据版本选择 V2 严格解码或 V1 兼容路径
V2 严格解码与校验
decode_v2_config_strict：严格键名校验、类型推断、扩展选项合并
validate_*：顶层与子表键白名单校验，拒绝未知字段
V1 兼容解码与编译
load_vhttpd_config：读取并解析 V1 TOML，支持多监听器与站点
compile_v1_to_v2：将 V1 概念映射到 V2 资源/适配器/管道/策略
变量展开与路径解析
resolve_v2_config_variables_and_paths：对 V2 各段进行 ${env.X} 与 ${paths.*} 展开
resolve_config_variables：对 V1 各段进行相同处理
CLI 覆盖层
apply_worker/php/vjsx_cli_overrides：命令行参数覆盖计划选项
运行时装配
server_lifecycle/runtime_config.v：基于 RuntimePlan 启动监听器、引擎、控制面等

章节来源 - runtime_plan_loader.v:10-46 - runtime_plan_loader.v:108-117 - config.v:448-482 - v1_plan_compat.v:5-9 - runtime_plan_cli_overlay.v:84-204 - server_lifecycle/runtime_config.v:89-112

架构总览

V2 配置模型以“资源域”为中心，强调“一个概念一个家”，通过声明式计划（RuntimePlan）驱动运行时装配。V1 配置通过兼容层编译为 V2 计划，保证行为一致且可诊断。

classDiagram
class V2Config {
+int version
+map listeners
+map engines
+map adapters
+map transforms
+map policies
+[] pipelines
+map relays
+map providers
}
class V2EngineSpec
class V2AdapterSpec
class V2TransformSpec
class V2PolicySpecs
class V2PipelineSpec
class V2RelaySpec
class V2ProviderSpec
V2Config --> V2ListenerSpec : "包含"
V2Config --> V2EngineSpec : "包含"
V2Config --> V2AdapterSpec : "包含"
V2Config --> V2TransformSpec : "包含"
V2Config --> V2PolicySpecs : "包含"
V2Config --> V2PipelineSpec : "包含"
V2Config --> V2RelaySpec : "包含"
V2Config --> V2ProviderSpec : "包含"

图表来源 - v2_config.v:1-19 - v2_config.v:120-155 - v2_config.v:157-182 - v2_config.v:184-197 - v2_config.v:199-207 - v2_config.v:279-288 - v2_config.v:302-317 - v2_config.v:261-269

详细组件分析

TOML 解析与版本路由

入口函数 load_runtime_plan_file 依据 version 字段分流：
V2：严格解码、变量展开、编译为 RuntimePlan
V1：调用 V1 兼容解码，再经 V1→V2 编译
若未提供配置文件，返回默认配置并走 V1 兼容编译

sequenceDiagram
participant CLI as "命令行"
participant Loader as "load_runtime_plan_file"
participant V2 as "V2 严格解码"
participant V1 as "V1 兼容解码"
participant Compat as "V1→V2 编译"
participant Plan as "compile_v2_runtime_plan"
CLI->>Loader : 传入 --config 或位置参数
Loader->>Loader : detect_config_version()
alt version == 2
Loader->>V2 : decode_v2_config_strict()
V2-->>Loader : V2Config
Loader->>Plan : compile_v2_runtime_plan(V2Config, source_path, strict=true)
else version == 1 或未设置
Loader->>V1 : load_vhttpd_config()
V1-->>Loader : VhttpdConfig
Loader->>Compat : compile_v1_to_v2()
Compat-->>Loader : V2Config
Loader->>Plan : compile_v2_runtime_plan(V2Config, source_path, compat=true)
end
Plan-->>CLI : RuntimePlan

图表来源 - runtime_plan_loader.v:34-46 - runtime_plan_loader.v:108-117 - v1_plan_compat.v:5-9

章节来源 - runtime_plan_loader.v:34-46 - config.v:448-482 - v1_plan_compat.v:5-9

环境变量注入机制

V2 路径与值展开：
内置变量：config.dir、paths.root
环境变量：${env.VAR:-default}
路径字段自动按配置目录相对解析
V1 路径与值展开：
同样支持 ${env.} 与 ${paths.}，并在多监听/站点场景下逐段展开

flowchart TD
Start(["开始"]) --> ReadEnv["读取进程环境 os.environ()"]
ReadEnv --> BuildVars["构建 vars = {config.dir, paths.root}"]
BuildVars --> WalkCfg["遍历配置树listeners/resources/engines/adapters..."]
WalkCfg --> Expand{"字符串是否含 ${env.*} 或 ${paths.*} ?"}
Expand --> |是| DoExpand["expand_config_string() 替换"]
Expand --> |否| Next["继续下一个字段"]
DoExpand --> ResolvePath{"是否为路径字段?"}
ResolvePath --> |是| AbsPath["resolve_config_path(相对于配置目录)"]
ResolvePath --> |否| Next
AbsPath --> Next
Next --> End(["完成"])

图表来源 - runtime_plan_loader.v:416-493 - config.v:1861-1886

章节来源 - runtime_plan_loader.v:416-493 - config.v:1861-1886

路径别名系统

[paths] 定义根与别名集合，所有非绝对路径按 [paths].root 解析
V2 中 paths.root 默认等于配置目录，便于 include 与相对路径
示例配置展示了 root、php_app、web_root 等常见别名用法

章节来源 - README.md:613-617 - vhttpd.example.toml:1-6 - vhttpd.multi.example.toml:1-10 - vhttpd.vjsx.example.toml:1-6

多层配置覆盖策略

层级顺序（优先级由低到高）： 1) 基础 TOML（V1 或 V2） 2) V2 include 合并（同名 ID 冲突报错） 3) CLI 覆盖（针对 worker/php/vjsx 等选项） 4) 运行时装配时应用（如 admin 端口/令牌可由 CLI 覆盖）
V2 include 合并规则：
命名对象（listeners、engines、adapters、transforms、providers、relays、pipelines）按 ID 去重合并
重复 ID 直接报错，避免静默覆盖
CLI 覆盖范围：
worker 池大小、队列容量/超时、重启退避、最大请求数等
php 二进制、worker/app entry、extensions、args
vjsx entry/module_root/build_root/signature 等

flowchart TD
Base["基础 TOML"] --> Include["V2 include 合并"]
Include --> CLI["CLI 覆盖"]
CLI --> Assemble["运行时装配"]
Assemble --> Plan["最终 RuntimePlan"]

图表来源 - runtime_plan_loader.v:119-184 - runtime_plan_cli_overlay.v:84-204 - server_lifecycle/runtime_config.v:89-112

章节来源 - runtime_plan_loader.v:119-184 - runtime_plan_cli_overlay.v:84-204 - server_lifecycle/runtime_config.v:89-112

运行时配置的热更新机制与验证流程

预览阶段：
加载候选配置文本，生成新 RuntimePlan，计算差异（diff），输出允许的策略与动作清单
应用阶段：
轻量替换：无需监听器重启/引擎排空/中继重载的变更可直接原子替换
受限替换：需要监听器重启、引擎排空、中继重载或状态迁移的变更会被拒绝并给出结构化原因
观测性：
预览/应用尝试均记录事件日志与快照，暴露于管理端点

sequenceDiagram
participant Admin as "管理端"
participant Loader as "load_runtime_plan_text"
participant Diff as "diff_runtime_plan_replacement"
participant Apply as "apply_runtime_plan_replacement"
participant Log as "事件日志/快照"
Admin->>Loader : 提交 next.toml 文本
Loader-->>Admin : 新 RuntimePlan
Admin->>Diff : 计算 diff(old,new)
Diff-->>Admin : 策略与动作轻量/受限
alt 轻量替换
Admin->>Apply : 执行替换
Apply-->>Log : 记录成功
Apply-->>Admin : 返回成功
else 受限替换
Apply-->>Log : 记录拒绝原因
Apply-->>Admin : 返回 409 及原因
end

图表来源 - PROTOCOL_PIPELINE_IMPLEMENTATION_PLAN.md:1247-1254 - logic_executor_test.v:507-602 - runtime_plan/replacement_test.v:440-476

章节来源 - PROTOCOL_PIPELINE_IMPLEMENTATION_PLAN.md:1247-1254 - logic_executor_test.v:507-602 - runtime_plan/replacement_test.v:440-476

V1→V2 概念映射与站点 DSL

V1 中的 server/listener/site/executor/routes 等概念被映射到 V2 的 listeners/engines/adapters/pipelines/policies 等稳定领域
站点 DSL 简化了 host/port/root/executor/worker.entry 等常用字段的表达
兼容性编译会产出诊断信息，提示哪些特性被转换

章节来源 - CONFIGURATION_MODEL_V2.md:132-164 - v1_plan_compat.v:49-100 - vhttpd.multi.example.toml:37-43

依赖关系分析

模块耦合
runtime_plan_loader 依赖 toml 解析与 runtime_plan 类型
v1_plan_compat 仅负责将 V1 转为 V2，不持有运行时状态
server_lifecycle/runtime_config 消费 RuntimePlan 进行装配
外部依赖
TOML 库用于解析与类型推断
操作系统 API 用于环境变量与文件系统路径解析

graph LR
RPL["runtime_plan_loader.v"] --> CFG["config.v (V1 解码)"]
RPL --> V2CFG["v2_config.v (V2 模型)"]
RPL --> COMPAT["v1_plan_compat.v (V1→V2)"]
RPL --> PLAN["runtime_plan (类型)"]
SLRC["server_lifecycle/runtime_config.v"] --> PLAN

图表来源 - runtime_plan_loader.v:1-6 - config.v:1-5 - v2_config.v:1-19 - v1_plan_compat.v:1-4 - server_lifecycle/runtime_config.v:89-112

章节来源 - runtime_plan_loader.v:1-6 - config.v:1-5 - v2_config.v:1-19 - v1_plan_compat.v:1-4 - server_lifecycle/runtime_config.v:89-112