系统架构设计

本文引用的文件
- README.md - src/main.v - src/app_composition_runtime.v - src/app_runtime_core_builder.v - src/server.v - src/server_runtime_orchestrator.v - src/engine_runtime.v - src/http_ingress_runtime.v - src/admin_runtime.v

引言

本文件面向 VHTTPD 的系统架构设计，聚焦控制平面与数据平面的分离、模块化与插件化扩展机制。文档从整体到细节逐层展开：先给出高层架构图与职责划分，再深入到 App 主应用结构、DataPlaneRuntime 数据平面运行时、ControlPlaneRuntime 控制平面运行时、ProcessLifecycle 进程生命周期管理等关键组件的职责边界与交互方式，并解释分层设计的动机、权衡与通信契约。文末提供可操作的排障建议与最佳实践，帮助初学者快速理解，同时为有经验的开发者提供深入的技术细节。

项目结构

VHTTPD 采用“薄入口 + 厚运行时”的模块化组织方式： - 入口与路由：main.v 定义 App 结构体与 HTTP 路由转发；server.v 负责启动、参数解析、信号处理与多实例编排；server_runtime_orchestrator.v 负责启动顺序与监听器绑定。 - 运行时组合：app_composition_runtime.v 定义 DataPlaneRuntime、ControlPlaneRuntime、ProcessLifecycle 三大运行时结构；app_runtime_core_builder.v 提供 ControlPlaneRuntime 构造与 ProcessLifecycle 初始化；app_runtime_builder.v 将配置/计划编译为运行时对象并装配各子系统。 - 协议与调度：http_ingress_runtime.v 统一 HTTP 入口、WebSocket 升级、管道匹配与引擎分发；engine_runtime.v 封装逻辑执行器（php/vjsx）与 worker 后端、流式分发、MCP/WebSocket 事件派发等。 - 管理面：admin_runtime.v 暴露 /admin/* 控制面 API，读取/写入运行时状态、草稿与替换流程。

graph TB
A["入口 main.v<br/>App 结构与路由"] --> B["服务器编排 server_runtime_orchestrator.v<br/>启动/停止/监听"]
A --> C["HTTP 入口 http_ingress_runtime.v<br/>匹配/缓存/分发"]
C --> D["引擎 EngineRuntime engine_runtime.v<br/>选择执行器/worker池/流式路径"]
A --> E["控制面 admin_runtime.v<br/>/admin/* 接口"]
A --> F["运行时组合 app_composition_runtime.v<br/>DataPlaneRuntime/ControlPlaneRuntime/ProcessLifecycle"]
F --> G["构建器 app_runtime_core_builder.v<br/>ControlPlaneRuntime.new/ProcessLifecycle.started_now"]
F --> H["装配器 app_runtime_builder.v<br/>从计划/配置构建运行时"]

图表来源 - src/main.v:16-23 - src/server_runtime_orchestrator.v:55-84 - src/http_ingress_runtime.v:31-40 - src/engine_runtime.v:32-51 - src/admin_runtime.v:7-20 - src/app_composition_runtime.v:14-47 - src/app_runtime_core_builder.v:7-23 - src/app_runtime_builder.v:10-56

章节来源 - src/main.v:16-23 - src/server.v:276-319 - src/server_runtime_orchestrator.v:55-84 - src/app_composition_runtime.v:14-47 - src/app_runtime_core_builder.v:7-23 - src/app_runtime_builder.v:10-56

核心组件

本节聚焦四大核心组件的职责边界与协作方式。

App 主应用结构
作为 veb.Middleware 与 veb.StaticHandler 的组合容器，持有 DataPlaneRuntime、ControlPlaneRuntime、ProcessLifecycle。
通过中间件与静态资源处理器承载数据面请求，并通过 control_plane.emit 向控制面广播事件。
所有 HTTP 方法均委托给 HttpIngressRuntime.route，实现统一的协议入口。
DataPlaneRuntime 数据平面运行时
聚合传输、WebSocket、上游、中继、协议、提供者、引擎、资源、管道、转换器、运行时计划替换等子系统。
以 RuntimePlan 为核心，驱动请求匹配、缓存、响应渲染与执行器选择。
对外暴露快照与诊断能力，供控制面查询。
ControlPlaneRuntime 控制平面运行时
维护 AdminState、HTTP 统计、事件日志路径。
emit 方法对 http.request 与 admin.* 事件进行计数与持久化。
提供 stats_snapshot 与 runtime_snapshot 用于控制面查询。
ProcessLifecycle 进程生命周期管理
记录进程启动时间、数据平面 scheme（http/https）。
在启动阶段设置 scheme 并注入到 worker 环境变量，确保下游一致。

章节来源 - src/main.v:16-23 - src/app_composition_runtime.v:14-47 - src/app_composition_runtime.v:49-87 - src/app_runtime_core_builder.v:7-23

架构总览

VHTTPD 采用“控制平面/数据平面分离 + 模块化 + 插件化”的分层架构： - 控制平面：独立于数据面，提供运行时观测、配置草稿、验证、差异预览、原子替换与最终化能力。 - 数据平面：基于 veb 的 HTTP 源，承担协议终止、管道匹配、缓存、执行器分发与响应渲染。 - 模块化：Transport、WebSocket、Upstream、Relay、Protocol、Provider、Engine、Pipeline、Transformer 等模块按职责解耦。 - 插件化：通过 LogicExecutor 模型抽象 php/vjsx 等执行器，支持未来新增宿主类型；Provider 与 Adapter 体系支撑外部集成。

graph TB
subgraph "控制平面"
CP["ControlPlaneRuntime<br/>AdminState/Stats/EventLog"]
AdminAPI["/admin/* 接口"]
end
subgraph "数据平面"
Ingress["HttpIngressRuntime<br/>入口/匹配/缓存"]
Pipeline["PipelineRuntime<br/>规则/策略/缓存"]
Engine["EngineRuntime<br/>执行器/Worker池/流式"]
WS["WebSocketRuntime<br/>Hub/会话/事件"]
Upstream["UpstreamRuntimeRegistry<br/>长连接/事件"]
Relay["relay.Runtime<br/>消息中继"]
Protocols["ProtocolRuntimeHub<br/>MCP/其他协议"]
Providers["ProviderRuntimeHub<br/>Feishu/Codex/DB/Cache"]
end
Client["客户端/MCP/浏览器"] --> Ingress
Ingress --> Pipeline
Pipeline --> Engine
Pipeline --> WS
Pipeline --> Upstream
Pipeline --> Relay
Pipeline --> Protocols
Engine --> Providers
CP --> AdminAPI
AdminAPI --> CP

图表来源 - src/http_ingress_runtime.v:31-40 - src/engine_runtime.v:32-51 - src/app_composition_runtime.v:14-47 - src/admin_runtime.v:7-20

详细组件分析

App 主应用结构

角色定位：App 是 veb 中间件栈与静态资源处理的宿主，内嵌 DataPlaneRuntime、ControlPlaneRuntime、ProcessLifecycle。
路由行为：所有 HTTP 方法统一委托给 HttpIngressRuntime.route，保证入口一致性。
事件发射：App.emit 调用 control_plane.emit，将 server.、admin. 等事件写入事件日志并更新统计。

classDiagram
class App {
+veb.Middleware[Context]
+veb.StaticHandler
+DataPlaneRuntime
-control_plane ControlPlaneRuntime
-lifecycle ProcessLifecycle
+emit(kind, fields) void
+proxy_get(ctx,path) Result
+proxy_post(ctx,path) Result
+... (其他HTTP方法)
}
class DataPlaneRuntime {
+plan RuntimePlan
+transport TransportRuntimeHub
+websocket WebSocketRuntime
+upstreams UpstreamRuntimeRegistry
+relay relay.Runtime
+protocols ProtocolRuntimeHub
+providers ProviderRuntimeHub
+engines EngineRuntime
+assets AssetsRuntime
+pipelines PipelineRuntime
+transformers TransformerRuntimeHub
+replacement RuntimePlanReplacementRuntime
}
class ControlPlaneRuntime {
+admin AdminState
+http_stats HttpStats
+event_log string
+emit(kind, fields) void
+stats_snapshot(ctx) AdminRuntimeStats
+runtime_snapshot(ctx) AdminRuntimeSummary
}
class ProcessLifecycle {
+started_at_unix i64
+data_plane_scheme string
}
App --> DataPlaneRuntime : "嵌入"
App --> ControlPlaneRuntime : "拥有"
App --> ProcessLifecycle : "拥有"

图表来源 - src/main.v:16-23 - src/app_composition_runtime.v:14-47 - src/app_composition_runtime.v:49-87

章节来源 - src/main.v:83-116 - src/app_composition_runtime.v:14-47 - src/app_composition_runtime.v:49-87

DataPlaneRuntime 数据平面运行时

职责边界：聚合运行时子系统，围绕 RuntimePlan 组织请求匹配、缓存、响应渲染与执行器选择。
关键能力：
管道匹配与策略：根据方法、目标、查询、头部、主体、远端地址、trace_id/request_id 等维度匹配规则。
缓存命中：对 GET/HEAD 且命中缓存的请求直接返回，降低延迟。
执行器选择：根据 dispatch_plan.executor 动态选择主或附加执行器，支持流式分发优先尝试。
响应渲染：统一渲染缓存命中、错误、流式、上游计划与普通响应。

sequenceDiagram
participant C as "客户端"
participant I as "HttpIngressRuntime"
participant P as "PipelineRuntime"
participant E as "EngineRuntime"
participant R as "HttpResponseRuntime"
C->>I : "HTTP 请求"
I->>I : "检测WS升级/方案注入/ID生成"
I->>P : "匹配HTTP管道规则"
P-->>I : "返回dispatch_plan"
I->>P : "尝试处理(静态/重定向/缓存)"
alt "缓存命中"
P-->>R : "返回缓存结果"
R-->>C : "200 缓存响应"
else "需要执行器"
I->>E : "选择执行器并分发"
E-->>I : "返回执行结果"
I->>R : "渲染响应"
R-->>C : "最终响应"
end

图表来源 - src/http_ingress_runtime.v:31-40 - src/http_ingress_runtime.v:56-139 - src/engine_runtime.v:140-155

章节来源 - src/http_ingress_runtime.v:56-139 - src/engine_runtime.v:140-155

ControlPlaneRuntime 控制平面运行时

职责边界：集中管理 AdminState、HTTP 统计与事件日志，提供统计快照与运行时快照。
事件处理：
http.request：累计请求数、错误数、超时数、流式数。
admin.*：累计管理动作数。
将事件追加写入事件日志文件，便于离线分析与审计。
快照能力：stats_snapshot 与 runtime_snapshot 为控制面提供一致的只读视图。

flowchart TD
Start(["收到事件"]) --> CheckKind{"事件类型?"}
CheckKind --> |http.request| IncStats["更新请求/错误/超时/流式计数"]
CheckKind --> |admin.*| IncAdmin["增加管理动作计数"]
IncStats --> WriteLog["写入事件日志"]
IncAdmin --> WriteLog
WriteLog --> End(["完成"])

图表来源 - src/app_composition_runtime.v:49-77

章节来源 - src/app_composition_runtime.v:49-87

ProcessLifecycle 进程生命周期管理

职责边界：记录进程启动时间与数据平面 scheme（http/https），并在启动阶段将 scheme 注入到 worker 环境变量，确保下游一致。
启动流程：
初始化传输与内部管理通道。
启动提供者、挂载静态资源、安装中间件。
启动控制面与上游提供者，输出运行端点日志。

sequenceDiagram
participant S as "ServerOrchestrator"
participant L as "ProcessLifecycle"
participant T as "TransportStartupRuntime"
participant P as "ProviderStartupRuntime"
participant A as "AssetStartupRuntime"
participant C as "ControlPlaneStartupRuntime"
S->>L : "start(runtime_cfg)"
L->>T : "initialize(internal_admin_socket)"
L->>P : "initialize()"
L->>L : "设置 data_plane_scheme"
L->>S : "apply_runtime_scheme_to_worker_envs(scheme)"
L->>S : "engines.start(lifecycle,port, facade)"
L->>A : "mount() / install_middleware()"
L->>C : "emit_server_started(...) / start_admin_plane(...)"
L->>P : "start_upstreams()"
L->>S : "log_runtime_endpoints()"

图表来源 - src/server_runtime_orchestrator.v:55-84 - src/engine_runtime.v:68-76

章节来源 - src/server_runtime_orchestrator.v:55-84 - src/engine_runtime.v:68-76

插件化与执行器模型

执行器模型：LogicExecutor 抽象了不同宿主（php/vjsx/未来宿主）的统一接口，包括 HTTP 分发、流式分发、MCP 分发、WebSocket 事件分发与会话打开。
引擎运行时：EngineRuntime 统一管理主执行器与附加执行器，提供环境注入、指标采集、队列与 worker 生命周期管理。
插件扩展：通过 ProviderRuntimeHub 与 Adapter/Transform/Pipeline 等模块，支持外部协议与业务能力的插拔式接入。

classDiagram
class EngineRuntime {
+start(lifecycle, port, facade) void
+stop(lifecycle, port) void
+dispatch_selection(name) EngineDispatchSelection
+dispatch_http_for_kind(kind, facade, req) Outcome
+metrics() EngineRuntimeMetrics
+apply_scheme(scheme) void
}
class EngineDispatchSelection {
+pool string
+stream_dispatch bool
+executor_kind() string
+dispatch_http(facade, req) Outcome
}
class LogicExecutor {
<<interface>>
+kind() string
+model() LogicExecutorModel
+provider() string
+dispatch_http(facade, req) Outcome
+dispatch_stream(facade, req) Response
+dispatch_mcp(facade, req) Response
+dispatch_websocket_event(facade, frame) Response
+open_websocket_session(facade, req) Outcome
}
EngineRuntime --> LogicExecutor : "使用"
EngineRuntime --> EngineDispatchSelection : "选择"

图表来源 - src/engine_runtime.v:32-51 - src/engine_runtime.v:78-96 - src/engine_runtime.v:140-155

章节来源 - src/engine_runtime.v:32-51 - src/engine_runtime.v:78-96 - src/engine_runtime.v:140-155

控制面 API 与管理流程

运行时观测：/admin/runtime、/admin/events、/admin/runtime/graph、/admin/schema 等接口提供运行时状态、事件与模式图。
配置草稿与替换：/admin/drafts、/admin/config/files、/admin/runtime/plan/replacement 支持创建草稿、校验、差异预览、应用与最终化。
提供者与上游：/admin/runtime/provider-instances、/admin/runtime/upstreams、/admin/runtime/websockets、/admin/runtime/mcp 等接口提供运行时可见性。

sequenceDiagram
participant U as "管理员客户端"
participant A as "AdminRuntime"
participant CP as "ControlPlaneRuntime"
U->>A : "POST /admin/drafts/ : id/validate"
A->>CP : "校验草稿"
CP-->>A : "返回校验结果"
A-->>U : "200/422 响应"
U->>A : "POST /admin/runtime/plan/replacement/apply"
A->>CP : "应用替换"
CP-->>A : "返回应用状态"
A-->>U : "200/400 响应"

图表来源 - src/admin_runtime.v:293-310 - src/admin_runtime.v:398-423

章节来源 - src/admin_runtime.v:7-20 - src/admin_runtime.v:293-310 - src/admin_runtime.v:398-423

依赖关系分析

入口与编排：server.v 负责参数解析、单/多实例模式选择、信号处理与优雅退出；server_runtime_orchestrator.v 负责启动顺序与监听器绑定。
运行时装配：app_runtime_builder.v 从 RuntimePlan 与配置构建运行时对象，组装各子系统；app_runtime_core_builder.v 提供 ControlPlaneRuntime 构造与 ProcessLifecycle 初始化。
协议与调度：http_ingress_runtime.v 统一入口与分发；engine_runtime.v 封装执行器与 worker 后端。
控制面：admin_runtime.v 暴露 /admin/* 接口，读取/写入运行时状态与草稿。

graph LR
Server["server.v"] --> Orchestrator["server_runtime_orchestrator.v"]
Orchestrator --> Builder["app_runtime_builder.v"]
Builder --> CoreBuilder["app_runtime_core_builder.v"]
Orchestrator --> Main["main.v"]
Main --> Ingress["http_ingress_runtime.v"]
Ingress --> Engine["engine_runtime.v"]
Main --> Admin["admin_runtime.v"]

图表来源 - src/server.v:276-319 - src/server_runtime_orchestrator.v:55-84 - src/app_runtime_builder.v:10-56 - src/app_runtime_core_builder.v:7-23 - src/main.v:83-116 - src/http_ingress_runtime.v:31-40 - src/engine_runtime.v:32-51 - src/admin_runtime.v:7-20

章节来源 - src/server.v:276-319 - src/server_runtime_orchestrator.v:55-84 - src/app_runtime_builder.v:10-56 - src/app_runtime_core_builder.v:7-23 - src/main.v:83-116 - src/http_ingress_runtime.v:31-40 - src/engine_runtime.v:32-51 - src/admin_runtime.v:7-20

性能与可扩展性

分层设计动机：
控制面与数据面分离：避免管理操作影响数据面吞吐，提升稳定性与可观测性。
模块化：各子系统职责清晰，便于独立演进与测试。
插件化：通过执行器与提供者模型，支持新宿主与外部集成的低成本接入。
依赖关系与通信：
数据面通过 PipelineRuntime 与 EngineRuntime 协作，减少耦合。
控制面通过 ControlPlaneRuntime 的事件与快照接口获取运行时信息。
可扩展性：
新增执行器：实现 LogicExecutor 接口，注册到 EngineRuntime。
新增提供者：通过 ProviderRuntimeHub 与相关适配器/转换器接入。
新增协议：通过 ProtocolRuntimeHub 与适配层扩展。

[本节为通用指导，不直接分析具体文件]

故障排查指南

启动失败：检查 server_runtime_orchestrator.v 中的预检绑定与 SSL 证书路径；确认端口可用与权限正确。
无逻辑执行器：当没有可用的 HTTP 执行器时，入口会返回 404；检查 EngineRuntime 是否成功启动与 socket 数量。
事件缺失：确认 ControlPlaneRuntime 的事件日志路径可写，且 emit 被正确调用。
管理面不可用：确认 admin_enabled 与 token 配置，以及 /admin/* 路由是否正确挂载。

章节来源 - src/server_runtime_orchestrator.v:18-46 - src/http_ingress_runtime.v:42-50 - src/app_composition_runtime.v:49-77 - src/admin_runtime.v:7-20

结论

VHTTPD 通过控制面与数据面分离、模块化与插件化的分层设计，实现了高内聚、低耦合的可扩展运行时平台。App 主应用结构作为统一入口，DataPlaneRuntime 组织数据面能力，ControlPlaneRuntime 提供管理与观测，ProcessLifecycle 管理进程生命周期。该架构既满足初学者快速上手的需求，也为高级用户提供了深入的扩展与优化空间。

[本节为总结性内容，不直接分析具体文件]

附录

参考文档与示例：
README.md 提供总体说明、运行方式与示例配置。
docs 目录下包含配置模型、架构重构基线、协议流水线实现计划等深度文档。

章节来源 - README.md:1-800