配置指南

本文引用的文件
- config/vhttpd.example.toml - config/vhttpd.multi.example.toml - config/vhttpd.vjsx.example.toml - src/config/config.v - src/config/v2_config.v - src/config/v2_plan_compiler.v - src/config/runtime_plan_loader.v - src/server_lifecycle/multi_config.v - src/server_lifecycle/runtime_config.v - docs/CONFIGURATION_MODEL_V2.md - docs/SITE_CONFIG_DSL.md - README.md

简介

本指南面向生产环境用户，系统化说明 VHTTPD 的 TOML 配置语法、优先级规则、变量扩展与环境变量集成方式，覆盖全局配置、站点（Site）配置、执行器（Executor）配置、多监听器模式、安全、性能调优与日志等主题。文档同时提供 V1 兼容 DSL 与 V2 资源模型对照，帮助在迁移期平滑过渡。

项目结构

VHTTPD 的配置解析与编译位于 src/config 模块，运行时装配与多监听器绑定在 server_lifecycle 模块；示例配置位于 config 目录；V2 目标架构说明见 docs。

graph TB
A["配置文件<br/>TOML"] --> B["配置解析与变量展开<br/>src/config/config.v"]
B --> C["V2 配置模型定义<br/>src/config/v2_config.v"]
C --> D["V2 计划编译器<br/>src/config/v2_plan_compiler.v"]
D --> E["运行时计划 RuntimePlan"]
E --> F["多监听器装配<br/>src/server_lifecycle/multi_config.v"]
F --> G["运行时参数合并<br/>src/server_lifecycle/runtime_config.v"]

图表来源 - src/config/config.v:1487-1591 - src/config/v2_config.v:1-318 - src/config/v2_plan_compiler.v:1-203 - src/server_lifecycle/multi_config.v:1-94 - src/server_lifecycle/runtime_config.v:89-171

章节来源 - README.md:447-531 - docs/CONFIGURATION_MODEL_V2.md:1-216

核心组件

配置加载与变量展开：支持 ${paths.}、${server.}、${env.VAR:-默认值} 等表达式，按作用域解析并递归展开。
V1 兼容 DSL：[sites.] 简写、自动合成 listener、app 别名、worker.entry 别名、vjsx.module_root 默认跟随 root。
V2 资源模型：以 version=2 声明，将 server/listeners/control/observability/resources/engines/adapters/transforms/policies/pipelines/relays 作为稳定领域，由编译器生成不可变 RuntimePlan。
多监听器模式：一个进程可绑定多个 host:port，每个 listener 指向一个 site，各自拥有独立应用运行环境与执行器选择。

章节来源 - src/config/config.v:2307-2392 - docs/SITE_CONFIG_DSL.md:1-184 - docs/CONFIGURATION_MODEL_V2.md:132-216 - src/server_lifecycle/multi_config.v:20-94

架构总览

下图展示从 TOML 到运行时计划的编译链路，以及多监听器如何映射到站点与执行器。

sequenceDiagram
participant U as "用户"
participant CFG as "配置解析<br/>config.v"
participant V2 as "V2 模型/编译器<br/>v2_config.v / v2_plan_compiler.v"
participant PLAN as "RuntimePlan"
participant ML as "多监听器装配<br/>multi_config.v"
participant RT as "运行时参数合并<br/>runtime_config.v"
U->>CFG : 读取 TOML 并展开变量
CFG-->>U : 解析后的 V1/V2 配置
U->>V2 : 若 version=2 则编译为计划
V2-->>PLAN : 生成不可变计划
U->>ML : 启动时解析多监听器绑定
ML->>RT : 为每个 listener/site 合并运行时参数
RT-->>U : 最终运行期配置

图表来源 - src/config/config.v:1487-1591 - src/config/v2_plan_compiler.v:1-203 - src/server_lifecycle/multi_config.v:20-94 - src/server_lifecycle/runtime_config.v:89-171

详细组件分析

全局配置（V1 兼容）

paths：根路径与工作区路径，供 ${paths.*} 引用。
server：监听地址与端口、索引页、SSL 等。
files：PID 文件、事件日志路径。
runtime：时区等进程级设置。
worker：工作进程池、超时、重启退避、队列容量、环境变量等。
executor：执行器类型（php/vjsx 等）。
php/vjsx：执行器专属参数（入口、扩展、构建目录、线程数等）。
admin：管理平面主机、端口、令牌。
assets：静态资源前缀、根目录、缓存控制。
feishu/codex/mcp 等：协议/提供者相关开关与连接参数。

章节来源 - config/vhttpd.example.toml:1-67 - README.md:447-531

站点配置（V1 兼容 DSL）

[sites.]：host/port/root/executor 等基础信息。
快捷别名：
root = project_root
app = php.app_entry 或 vjsx.app_entry
worker.entry = php.worker_entry
vjsx.module_root 默认等于 site root
省略 listeners 时，系统根据 sites 的 host+port 自动合成监听器。

章节来源 - docs/SITE_CONFIG_DSL.md:1-184 - config/vhttpd.multi.example.toml:37-73

执行器配置（V1 兼容）

executor.kind：选择执行器（如 php、vjsx）。
php：bin、worker_entry、app_entry、extensions、args 等。
vjsx：app_entry、module_root、build_root、runtime_profile、thread_count 等。
worker：autostart、pool_size、socket/socket_prefix、read_timeout_ms、max_requests、restart_backoff_* 等。

章节来源 - config/vhttpd.example.toml:19-36 - config/vhttpd.vjsx.example.toml:18-26 - config/vhttpd.multi.example.toml:44-55

多监听器模式

显式 listeners：指定 host/port/site 绑定。
隐式 listeners：未定义 listeners 时，按每个 sites. 的 host+port 自动生成。
校验：同一 host:port 重复绑定会报错；listener 必须指向存在的 site。
每站点隔离：每个 listener/site 拥有独立的运行环境与执行器选择。

章节来源 - src/server_lifecycle/multi_config.v:20-94 - README.md:533-589 - config/vhttpd.multi.example.toml:44-73

变量扩展机制与环境变量集成

语法：${key} 与 ${key:-默认值}。
作用域：当 key 不含点号且当前作用域非空时，优先尝试 ${scope}.${key}。
环境变量：${env.VAR} 读取进程环境变量；缺失且无默认值时报错。
递归展开：被引用的值若仍含变量，会继续展开。
路径解析：部分字段在加载阶段进行相对路径解析。

flowchart TD
Start(["开始"]) --> Scan["扫描字符串中的 '${...}' 片段"]
Scan --> HasDefault{"是否包含 ':-' 默认值?"}
HasDefault --> |是| Split["拆分键名与默认值"]
HasDefault --> |否| UseKey["使用原始键名"]
Split --> ResolveEnv{"键名是否以 'env.' 开头?"}
UseKey --> ScopeCheck{"键名是否含 '.' ?"}
ScopeCheck --> |否| TryScope["拼接 ${scope}.${key} 查找"]
ScopeCheck --> |是| DirectLookup["直接查找 key"]
TryScope --> FoundScope{"找到值?"}
FoundScope --> |是| Recurse["若值含变量则递归展开"]
FoundScope --> |否| DirectLookup
DirectLookup --> FoundDirect{"找到值?"}
FoundDirect --> |是| Recurse
FoundDirect --> |否| DefaultOrError{"有默认值?"}
DefaultOrError --> |是| ReturnDefault["返回默认值"]
DefaultOrError --> |否| Error["报错：未知变量或缺失环境变量"]
Recurse --> Replace["替换片段并继续扫描"]
Replace --> Scan

图表来源 - src/config/config.v:2307-2392 - src/config/runtime_plan_loader.v:495-503

章节来源 - src/config/config.v:2307-2392 - src/config/runtime_plan_loader.v:470-503

配置项优先级与继承

全局 → 站点层叠加：with_site 会将站点配置合并到全局，覆盖同名项。
路径与文档根：若站点未显式 document_root，则回落到 paths.root；并在 worker.env 中注入 DOCUMENT_ROOT。
SSL 合并：站点 ssl 与全局 server.ssl 合并。
执行器与 PHP/VJSX 配置：分别合并，站点覆盖全局。
CLI 参数覆盖：运行时参数合并阶段，命令行参数可覆盖配置与计划中的值（例如 worker 队列、超时、admin 端口等）。

章节来源 - src/config/runtime_config.v:540-571 - src/server_lifecycle/runtime_config.v:89-171

V2 资源模型（目标架构）

顶层领域：version、server、listeners、control、observability、resources、engines、adapters、transforms、policies、pipelines、relays。
版本化：version=2 启用严格校验；未知字段报错；废弃别名不接受。
资源引用：通过 ID 引用，避免重复配置。
计划编译：TOML → 解码为 V2Config → 编译为不可变 RuntimePlan → 运行时消费。

章节来源 - docs/CONFIGURATION_MODEL_V2.md:1-216 - src/config/v2_config.v:1-318 - src/config/v2_plan_compiler.v:1-203

安全配置

TLS/证书：可在 listener 或站点级别配置 cert/cert_key/enabled；V2 中由 listeners.tls 统一管理。
响应头与安全策略：V2 policies.security 支持 required_headers、allowed_origins、denied_query_patterns 等。
上传限制：V2 policies.limits 支持 max_body_bytes、timeout_ms、queue_capacity。
建议：生产环境开启必要的安全响应头，限制请求体大小，合理设置 allowed_origins。

章节来源 - src/config/v2_config.v:224-234 - src/config/v2_config.v:217-222 - src/config/v2_plan_compiler.v:549-578

性能调优

Worker 池与队列：pool_size、queue_capacity、queue_timeout_ms、read_timeout_ms、max_requests、restart_backoff_*。
线程与并发：vjsx.thread_count、concurrency 策略（affinity/actor、max_in_flight、per-key 队列上限等）。
资源池：DB pool_size、idle_ping_ms；Cache socket/url/namespace；Storage root/bucket。
超时与重试：retry.max_attempts/backoff/max_backoff。

章节来源 - src/config/v2_config.v:120-155 - src/config/v2_config.v:243-259 - src/config/v2_config.v:82-94 - src/config/v2_config.v:96-103 - src/config/v2_config.v:236-241

日志与可观测性

事件日志：files.event_log（V1）或 observability.event_log（V2）。
日志级别：observability.log_level。
追踪导出：observability.tracing.enabled/exporter/endpoint/sample_rate。

章节来源 - config/vhttpd.example.toml:12-17 - src/config/v2_config.v:59-72

依赖关系分析

配置解析依赖 toml 库与路径解析工具。
V2 编译器依赖 runtime_plan 类型，产出不可变计划。
多监听器装配依赖已编译的计划与站点配置，确保 listener→site 绑定唯一且有效。
运行时参数合并阶段引入 CLI 覆盖与路径规范化。

classDiagram
class ConfigParser {
+expand_config_string()
+decode_multi_listener_config()
+decode_single_site_config()
}
class V2Config {
+version
+server
+listeners
+control
+observability
+resources
+engines
+adapters
+transforms
+policies
+pipelines
+relays
}
class PlanCompiler {
+compile_v2_runtime_plan()
+validate_runtime_plan_references()
}
class MultiListener {
+resolve_multi_server_runtime_config()
}
class RuntimeMerge {
+resolve_for_target_with_plan()
}
ConfigParser --> V2Config : "解析/展开"
V2Config --> PlanCompiler : "编译为计划"
PlanCompiler --> MultiListener : "提供计划"
MultiListener --> RuntimeMerge : "合并运行时参数"

图表来源 - src/config/config.v:1487-1591 - src/config/v2_config.v:1-318 - src/config/v2_plan_compiler.v:1-203 - src/server_lifecycle/multi_config.v:20-94 - src/server_lifecycle/runtime_config.v:89-171

章节来源 - src/config/config.v:1487-1591 - src/config/v2_plan_compiler.v:638-701

性能考虑

合理设置 worker.pool_size 与 queue_capacity，结合 read_timeout_ms 与 max_requests 平衡吞吐与内存占用。
对长连接/流式场景，调整 queue_timeout_ms 与 restart_backoff_*，避免雪崩。
数据库连接池 pool_size 与 idle_ping_ms 需匹配后端能力与网络延迟。
使用 concurrency 策略限制并发度与 per-key 队列上限，配合 affinity/actor 提升局部性。
静态资源启用缓存控制，减少后端压力。

故障排查指南

变量展开错误：检查 ${...} 语法是否正确、是否存在缺失的环境变量或未定义的变量键。
多监听器冲突：确认不同 listener 的 host:port 不重复，且 site 存在。
计划引用无效：V2 模式下，所有引用（engine/adapter/transform/policy/pipeline/relay/provider）必须存在且类型正确。
管理员端口冲突：在多监听器模式下，admin 端口可能绑定到首个 listener，注意端口占用。

章节来源 - src/config/config.v:2307-2392 - src/server_lifecycle/multi_config.v:40-68 - src/config/v2_plan_compiler.v:638-701