跳转至

核心架构模式

本文引用的文件
- src/main.v - src/server.v - src/app_runtime_builder.v - src/engine_runtime.v - src/pipeline_runtime.v - src/protocol_ingress_runtime.v - src/kernel_dispatch.v - src/dispatch/kernel.v - src/dispatch/exchange.v - src/dispatch/context.v - src/dispatch/pipeline.v - src/executor/types.v - src/executor/registry.v - docs/ADMIN_CONTROL_PLANE_PLAN.md - docs/CONFIGURATION_MODEL_V2.md - docs/PROTOCOL_PIPELINE_IMPLEMENTATION_PLAN.md

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

引言

本文件聚焦于 VHTTPD 的核心架构模式设计，围绕执行器模式、管道处理模型与事件驱动架构三大理念展开，系统阐述 Server、Control Plane、Data Plane、Kernel 等关键抽象的职责划分与交互关系。同时，从模块化设计原则（组件解耦、接口规范、依赖注入）和分层架构（协议层到业务层职责分离）角度进行深度解析，并辅以架构图与交互图帮助开发者理解整体设计与扩展点。

项目结构

VHTTPD 采用“进程内运行时 + 可插拔执行器 + 管道化分发”的混合架构： - 进程入口与生命周期管理集中在主模块与服务器启动逻辑中； - 数据面负责请求接入、路由匹配、缓存策略、引擎选择与响应渲染； - 控制面提供配置编辑、计划预览/应用、运行态快照与审计； - 内核层统一封装跨协议的分发信封与上下文构造； - 执行器层以工厂+规格注册的方式支持多种后端（PHP Worker、PHP-CGI、In-Proc VJSX 等）。

graph TB
subgraph "进程"
A["App(顶层组合)"]
B["DataPlaneRuntime(数据面)"]
C["ControlPlaneRuntime(控制面)"]
D["ProcessLifecycle(进程生命周期)"]
end
subgraph "数据面"
E["ProtocolIngressRuntime(协议入口)"]
F["PipelineRuntime(管道运行时)"]
G["EngineRuntime(引擎运行时)"]
H["WebSocketRuntime(WS运行时)"]
I["UpstreamRuntimeRegistry(上游注册表)"]
end
subgraph "内核与分发"
J["KernelDispatch(内核分发)"]
K["dispatch.* (Exchange/Context/Pipeline)"]
end
subgraph "执行器"
L["Executor Registry(执行器注册)"]
M["LogicExecutor(逻辑执行器)"]
end
A --> B
A --> C
A --> D
B --> E
B --> F
B --> G
B --> H
B --> I
E --> F
F --> G
G --> M
J --> K
J --> G
L --> M

图表来源 - src/main.v:15-23 - src/app_runtime_builder.v:10-56 - src/engine_runtime.v:177-208 - src/pipeline_runtime.v:40-56 - src/protocol_ingress_runtime.v:10-26 - src/kernel_dispatch.v:9-91 - src/dispatch/exchange.v:78-104 - src/executor/registry.v:65-127

章节来源 - src/main.v:15-23 - src/server.v:276-319 - src/app_runtime_builder.v:10-56

核心组件

  • App 顶层组合体：聚合 DataPlaneRuntime、ControlPlaneRuntime、ProcessLifecycle，并通过 veb 中间件与静态资源处理器暴露 HTTP 路由。
  • DataPlaneRuntime：包含协议入口、管道运行时、引擎运行时、WebSocket 运行时与上游注册表，承担数据面全部职责。
  • ControlPlaneRuntime：面向管理员的控制平面，提供运行时快照、替换预览/应用、事件日志等能力。
  • ProcessLifecycle：进程级生命周期钩子与优雅关停。
  • EngineRuntime：维护主/附加执行器池、队列与套接字选择、请求计数、重启/排空策略、指标与管理员摘要。
  • PipelineRuntime：HTTP 路由匹配、重写、静态根选择、响应缓存策略、Relay 管道描述符装配。
  • ProtocolIngressRuntime：OpenAI/MCP 等协议的优先路由拦截，未命中则回退到通用数据面。
  • KernelDispatch：将不同协议请求包装为统一的分发信封与上下文，交由引擎执行。
  • Executor Registry：内置执行器规格（none/php/php-cgi/vjsx），通过工厂方法构建具体执行器实例。

章节来源 - src/main.v:15-23 - src/app_runtime_builder.v:10-56 - src/engine_runtime.v:177-208 - src/pipeline_runtime.v:40-56 - src/protocol_ingress_runtime.v:10-26 - src/kernel_dispatch.v:9-91 - src/executor/registry.v:65-127

架构总览

下图展示从 HTTP 请求进入，到协议入口、管道匹配、引擎选择与执行器调用的完整链路，以及控制面与内核分发的协作方式。

sequenceDiagram
participant Client as "客户端"
participant App as "App(veb路由)"
participant Proto as "ProtocolIngressRuntime"
participant Pipe as "PipelineRuntime"
participant Eng as "EngineRuntime"
participant Exec as "LogicExecutor"
participant Ctrl as "ControlPlaneRuntime"
Client->>App : HTTP 请求
App->>Proto : try_route_http_request()
alt 命中 OpenAI/MCP
Proto-->>Client : 协议专用响应
else 未命中
Proto-->>Pipe : 回退到数据面
Pipe->>Pipe : 路由匹配/重写/缓存策略
Pipe->>Eng : dispatch_http()/stream/mcp/ws
Eng->>Exec : 选择执行器并调用
Exec-->>Eng : 结果/流帧/上游计划
Eng-->>Pipe : 标准化结果
Pipe-->>Client : 渲染响应/流式输出
end
Note over Ctrl,App : 控制面通过 App.emit 接收事件与快照

图表来源 - src/main.v:83-116 - src/protocol_ingress_runtime.v:10-26 - src/pipeline_runtime.v:91-143 - src/engine_runtime.v:177-208 - src/kernel_dispatch.v:9-91

详细组件分析

执行器模式（Executor Pattern）

  • 规格与工厂：通过内置执行器规格（none/php/php-cgi/vjsx）声明生命周期、模型（worker/embedded）、工作后端模式与配置表面，并由工厂方法按需构建具体执行器。
  • 运行时选择：根据监听器与计划投影，选择主或附加执行器池，暴露 HTTP/Stream/MCP/WebSocket 端口。
  • 生命周期：start/warmup/close 贯穿主/附加执行器，配合工作后端自动启停、最大请求数排空与重启。
classDiagram
class BuiltinLogicExecutorSpec {
+string kind
+[]string aliases
+string provider
+LogicExecutorModel logic_model
+WorkerBackendMode worker_backend_mode
+build_executor(args,cfg,factory) LogicExecutor
+runtime_selection(args,cfg,factory) ExecutorRuntimeSelection
}
class ExecutorFactory {
+new_inproc(cfg) LogicExecutor
}
class EngineRuntime {
+dispatch_stream(...)
+dispatch_mcp(...)
+dispatch_websocket_upstream(...)
+dispatch_websocket_event(...)
+open_websocket_session(...)
+dispatch_http_for_kind(...)
}
class LogicExecutor {
<<interface>>
+kind() string
+model() LogicExecutorModel
+provider() string
+warmup(facade) !
+close() void
+dispatch_http(...)
+dispatch_stream(...)
+dispatch_mcp(...)
+dispatch_websocket_upstream(...)
+dispatch_websocket_event(...)
+open_websocket_session(...)
}
BuiltinLogicExecutorSpec --> ExecutorFactory : "使用"
EngineRuntime --> LogicExecutor : "调用端口"

图表来源 - src/executor/registry.v:65-127 - src/executor/registry.v:263-286 - src/engine_runtime.v:177-208

章节来源 - src/executor/registry.v:65-127 - src/executor/registry.v:263-286 - src/engine_runtime.v:177-208

管道处理模型（Pipeline Model）

  • 交换对象：Exchange 承载身份、类型、入站、管道、时间戳、头/元数据与负载，支持请求/响应/事件/流/会话/错误等多种载荷。
  • 转换动作：TransformAction 定义继续管道、直接响应、转发、扇出、拒绝、丢弃等行为。
  • 能力校验：Capabilities 描述入站/出站/全双工/会话/复用/取消/背压/回放等能力，用于管道与入站能力匹配校验。
  • 管道描述：PipelineDescriptor 由 ingress、transforms、policies、egress 组成，并在运行时按 Relay/HTTP 场景装配。
flowchart TD
Start(["进入管道"]) --> BuildEx["构造 Exchange"]
BuildEx --> MatchCap{"能力满足?"}
MatchCap -- 否 --> Reject["返回能力不匹配错误"]
MatchCap -- 是 --> ApplyT["依次执行 Transform"]
ApplyT --> Action{"TransformAction"}
Action -- continue_pipeline --> NextT["下一个转换器"]
Action -- respond --> Render["渲染响应"]
Action -- forward/fanout --> Route["路由/扇出"]
Action -- reject/drop --> End(["结束"])
NextT --> ApplyT
Render --> End
Route --> ApplyT

图表来源 - src/dispatch/exchange.v:78-104 - src/dispatch/exchange.v:106-145 - src/dispatch/pipeline.v:3-12 - src/dispatch/pipeline.v:44-55

章节来源 - src/dispatch/exchange.v:78-104 - src/dispatch/exchange.v:106-145 - src/dispatch/pipeline.v:3-12 - src/dispatch/pipeline.v:44-55

事件驱动架构（Event-driven Architecture）

  • 事件发射：App.emit 将 server.started/failed/stopped、admin.started/failed/internal_admin.error、worker.select.failed 等事件写入追踪日志并透传到控制面。
  • 控制面订阅：ControlPlaneRuntime 接收事件，结合运行时快照与审计记录，支撑在线编辑、预览与应用。
  • 进程信号：server.v 注册 SIGINT/SIGTERM 处理器，触发优雅关停、清理子进程组与临时文件。
sequenceDiagram
participant Main as "main.v"
participant App as "App"
participant Ctrl as "ControlPlaneRuntime"
participant OS as "操作系统信号"
OS->>Main : SIGINT/SIGTERM
Main->>Ctrl : emit("server.stopped", fields)
Ctrl-->>Main : 持久化/快照更新
Main->>Main : 清理子进程组/临时文件
Main-->>OS : exit(128+sig)

图表来源 - src/main.v:75-81 - src/server.v:116-135 - docs/ADMIN_CONTROL_PLANE_PLAN.md:39-67

章节来源 - src/main.v:75-81 - src/server.v:116-135 - docs/ADMIN_CONTROL_PLANE_PLAN.md:39-67

关键抽象：Server、Control Plane、Data Plane、Kernel

  • Server：进程入口与多监听器编排，负责参数解析、时区配置、单/多服务模式切换、优雅关停。
  • Control Plane：基于 V2 配置域（listeners/control/observability 等）提供运行时对象的可视化与热替换。
  • Data Plane：协议入口、管道匹配、引擎调度、响应渲染与缓存策略。
  • Kernel：统一分发信封与上下文构造，屏蔽底层协议差异，向上游提供一致的执行语义。
graph LR
S["Server(进程入口)"] --> CP["Control Plane(控制面)"]
S --> DP["Data Plane(数据面)"]
DP --> K["Kernel(内核分发)"]
K --> EX["执行器(LogicExecutor)"]

图表来源 - src/server.v:276-319 - docs/CONFIGURATION_MODEL_V2.md:218-275 - src/kernel_dispatch.v:9-91

章节来源 - src/server.v:276-319 - docs/CONFIGURATION_MODEL_V2.md:218-275 - src/kernel_dispatch.v:9-91

模块化设计原则

  • 组件解耦：App 仅持有顶层运行时所有者字段，具体行为下沉至独立运行时（EngineRuntime、PipelineRuntime、ProtocolIngressRuntime 等）。
  • 接口定义规范：ExecutorFactory 以函数指针打破循环依赖；LogicExecutor 暴露统一端口；Exchange/TransformAction/Capabilities 定义清晰的数据契约。
  • 依赖注入机制：App 构建阶段通过 build_app_runtime 注入运行时计划、路由规则、资产与额外工作进程环境，形成“计划驱动”的装配。

章节来源 - src/app_runtime_builder.v:10-56 - src/executor/registry.v:29-40 - src/dispatch/exchange.v:78-104

分层架构决策

  • 协议层：ProtocolIngressRuntime 优先拦截 OpenAI/MCP 等协议，未命中则回退到通用数据面。
  • 路由与管道层：PipelineRuntime 负责匹配、重写、静态根选择与响应缓存策略，并将请求转换为执行器可调度的形式。
  • 引擎层：EngineRuntime 管理执行器池、队列、套接字选择、请求计数与重启策略，并对外暴露统一分发接口。
  • 执行器层：LogicExecutor 实现具体业务逻辑（PHP Worker、PHP-CGI、In-Proc VJSX 等），支持流式与命令式两种模式。

章节来源 - src/protocol_ingress_runtime.v:10-26 - src/pipeline_runtime.v:91-143 - src/engine_runtime.v:177-208 - src/executor/registry.v:65-127

依赖关系分析

  • 低耦合高内聚：各运行时模块职责单一，通过明确接口与数据结构交互，避免在 App 中堆积状态与逻辑。
  • 直接依赖：
  • main.v 依赖 server.v 的启动流程与信号处理；
  • app_runtime_builder.v 依赖 executor、provider、runtime_plan 与 server_lifecycle；
  • engine_runtime.v 依赖 executor 与 worker 后端；
  • pipeline_runtime.v 依赖 dispatch、executor、relay、runtime_plan；
  • protocol_ingress_runtime.v 依赖 veb 与上层协议端口；
  • kernel_dispatch.v 依赖 upstream.transport 与 executor。
  • 潜在环依赖规避：通过 ExecutorFactory 函数指针与运行时计划投影降低循环依赖风险。
graph TB
M["main.v"] --> SV["server.v"]
M --> ARB["app_runtime_builder.v"]
ARB --> ER["engine_runtime.v"]
ARB --> PR["pipeline_runtime.v"]
ARB --> PI["protocol_ingress_runtime.v"]
ER --> EXE["executor/*"]
PR --> DIS["dispatch/*"]
PR --> REL["relay/*"]
PI --> VEB["veb"]
KD["kernel_dispatch.v"] --> UPT["upstream.transport"]
KD --> EXE

图表来源 - src/main.v:15-23 - src/server.v:276-319 - src/app_runtime_builder.v:10-56 - src/engine_runtime.v:177-208 - src/pipeline_runtime.v:40-56 - src/protocol_ingress_runtime.v:10-26 - src/kernel_dispatch.v:9-91

章节来源 - src/main.v:15-23 - src/server.v:276-319 - src/app_runtime_builder.v:10-56 - src/engine_runtime.v:177-208 - src/pipeline_runtime.v:40-56 - src/protocol_ingress_runtime.v:10-26 - src/kernel_dispatch.v:9-91

性能考量

  • 队列与超时：EngineRuntime 暴露队列等待、拒绝、超时统计与深度监控，便于容量规划与限流策略调整。
  • 套接字选择：按执行器种类选择对应 socket，减少跨池开销；支持按 kind 定向调度。
  • 响应缓存：PipelineRuntime 对 GET 等可缓存请求实施 TTL 与 bypass 策略，降低下游压力。
  • 流式处理：内核分发支持 open/next/close 三段式流，适合长连接与 SSE/WS 场景。
  • 优雅关停：信号处理与最大请求数排空确保零丢失下线。

章节来源 - src/engine_runtime.v:234-249 - src/pipeline_runtime.v:174-223 - src/kernel_dispatch.v:97-127 - src/server.v:116-135

故障排查指南

  • 事件追踪：通过 runtime_trace 与 emit 输出 server/admin/worker 相关事件，定位启动失败、内部错误与工作节点选择失败。
  • 传输错误分类：dispatch.kernel 提供 transport_failure 与 stream_failure 映射，快速识别后端错误类别与状态码。
  • 执行器健康：EngineRuntime.metrics 与 admin snapshots 暴露队列深度、池大小、后端模式与生命周期状态。
  • 优雅关停：检查信号处理是否生效、子进程组是否被正确终止、临时文件是否清理。

章节来源 - src/main.v:25-81 - src/dispatch/kernel.v:12-28 - src/engine_runtime.v:234-249 - src/server.v:116-135

结论

VHTTPD 通过“执行器模式 + 管道模型 + 事件驱动”的组合，实现了高内聚、低耦合、可扩展的进程内运行时架构。Server/Control Plane/Data Plane/Kernel 的职责边界清晰，配合 V2 配置模型与计划驱动的装配机制，既保证了生产稳定性，又提供了强大的在线治理能力。建议在扩展新协议或执行器时遵循现有接口与能力校验规范，充分利用管道与事件体系，保持系统的可观测性与可演进性。

附录

  • 重构与迁移计划参考：Protocol Pipeline 实现计划明确了 P1-P7 阶段的拆分目标与验收标准，有助于理解当前代码的组织与后续演进方向。

章节来源 - docs/PROTOCOL_PIPELINE_IMPLEMENTATION_PLAN.md:752-892