技术栈

本文引用的文件
- README.md - Makefile - src/main.v - v.mod - scripts/doctor.sh - src/config/config.v - src/runtime_plan/types.v - docs/VEB_REUSE_1_1_PLAN.md - docs/WEBSOCKET_PHASE2_IMPLEMENTATION_PLAN.md - examples/config/openai-gateway.toml

简介

本技术栈概览聚焦 VHTTPD 的核心技术选型与集成方式，涵盖： - 语言与运行时：V 语言、veb HTTP 框架、QuickJS（嵌入式 JavaScript 运行时） - TLS 支持：OpenSSL 与 mbedTLS 双后端可选 - 内存管理：Boehm GC（BDW-GC）作为默认或可选项 - 数据库客户端：MySQL/MariaDB、PostgreSQL、SQLite（按构建开关启用） - 构建与分发：Makefile、pkg-config、CI 打包与二进制分发策略 - 运行期能力：HTTP/WebSocket/SSE/MCP 统一接入，PHP worker 与 vjsx 执行器并存

该文档帮助开发者理解项目的技术基础、版本兼容性、依赖关系与扩展点。

项目结构

从技术栈视角，关键位置如下： - 入口与路由：src/main.v 基于 veb 注册路由并委派到数据面运行时 - 配置模型：src/config/config.v 定义 TOML 配置结构体（含 DB、OpenAI、Bridge 等） - 运行时计划：src/runtime_plan/types.v 描述 TLS、资源、引擎、适配器、转换器等运行时对象 - 构建脚本：Makefile 控制编译开关（TLS 后端、DB、GC）、依赖安装与测试 - 环境检查：scripts/doctor.sh 校验 v、pkg-config、openssl、bdw-gc 等 - 模块元信息：v.mod 声明模块名与基路径 - 示例配置：examples/config/openai-gateway.toml 展示 vjsx 插件与后端编排

graph TB
A["src/main.v<br/>veb 路由与上下文"] --> B["数据面运行时<br/>HTTP/WS/Stream/MCP"]
C["src/config/config.v<br/>TOML 配置结构体"] --> D["运行时计划<br/>src/runtime_plan/types.v"]
E["Makefile<br/>编译开关与依赖"] --> F["外部库: OpenSSL/mbedTLS, BDW-GC, DB 客户端"]
G["scripts/doctor.sh<br/>环境检查"] --> E
H["v.mod<br/>模块元信息"] --> A
I["examples/config/openai-gateway.toml<br/>vjsx 插件与后端"] --> B

图表来源 - src/main.v:1-117 - src/config/config.v:1-55 - src/runtime_plan/types.v:65-155 - Makefile:1-199 - scripts/doctor.sh:1-58 - v.mod:1-7 - examples/config/openai-gateway.toml:1-64

章节来源 - README.md:1-41 - src/main.v:1-117 - v.mod:1-7

核心组件

V 语言与 veb 框架
vhttpd 以 veb 为 HTTP 事实来源，复用 veb.Context、request_id、SSE 等能力，保持核心轻量，专注传输、worker 编排、流式与可观测性
QuickJS 嵌入（vjsx）
通过 vjsx 模块在构建时准备受控的 QuickJS 源码，提供嵌入式 TypeScript/JavaScript 执行器；支持多线程、TS 转译、内嵌资源
TLS 后端
默认 OpenSSL；可通过变量切换至 mbedTLS（保留长连接读超时参数）
内存管理
默认使用 Boehm GC（BDW-GC），由 Makefile 自动探测与注入；也可显式指定
数据库客户端
默认开启 DB 支持（MySQL/MariaDB、PostgreSQL、SQLite），可按需关闭
运行时计划与配置
通过 TOML 配置生成运行时计划（TLS、监听器、引擎、适配器、转换器、策略、提供者等）

章节来源 - README.md:1416-1462 - README.md:210-271 - Makefile:1-36 - src/config/config.v:255-311 - src/runtime_plan/types.v:65-155

架构总览

下图展示了 vhttpd 的技术栈分层与交互：V/veb 作为网络与中间件层，QuickJS 作为嵌入式 JS 执行器，OpenSSL/mbedTLS 提供 TLS，Boehm GC 负责内存管理，DB 客户端按需链接。

graph TB
subgraph "应用层"
PHP["PHP Worker / 业务逻辑"]
VJSX["vjsx (TypeScript/JS) 插件与网关"]
end
subgraph "vhttpd 运行时"
VEB["veb HTTP 框架<br/>请求/响应/SSE/中间件"]
ROUTE["路由与调度<br/>main.v + 运行时计划"]
WS["WebSocket 会话与上游"]
STREAM["SSE/文本流/NDJSON"]
ADMIN["Admin 平面/可观测性"]
end
subgraph "系统库"
TLS_OSSL["OpenSSL"]
TLS_MBED["mbedTLS"]
GC["Boehm GC (BDW-GC)"]
DB_MY["MySQL/MariaDB 客户端"]
DB_PG["PostgreSQL 客户端"]
DB_SQLITE["SQLite 客户端"]
end
PHP --> VEB
VJSX --> VEB
VEB --> ROUTE
ROUTE --> WS
ROUTE --> STREAM
ROUTE --> ADMIN
ROUTE --> TLS_OSSL
ROUTE --> TLS_MBED
ROUTE --> GC
ROUTE --> DB_MY
ROUTE --> DB_PG
ROUTE --> DB_SQLITE

图表来源 - src/main.v:1-117 - Makefile:1-36 - README.md:210-271

详细组件分析

V 语言与 veb 框架

设计原则
vhttpd 尽量贴近 veb 与 V 标准 HTTP 能力，不重复造轮子；将重点放在传输、worker 编排、流生命周期与可观测性
关键实现
main.v 中 App 组合 veb.Middleware 与 veb.StaticHandler，并通过 Context 注入 request_id
路由方法代理到 HttpIngressRuntime.route，统一进入数据面运行时
扩展建议
优先复用 veb.sse、veb.request_id、静态资源处理等成熟能力；避免替换 vslim 的动态路由模型

classDiagram
class App {
+Context
+veb.Middleware[Context]
+veb.StaticHandler
+DataPlaneRuntime
+control_plane ControlPlaneRuntime
+lifecycle ProcessLifecycle
+proxy_get(ctx,path) Result
+proxy_post(ctx,path) Result
+proxy_put(ctx,path) Result
+proxy_patch(ctx,path) Result
+proxy_delete(ctx,path) Result
+proxy_head(ctx,path) Result
+proxy_options(ctx,path) Result
}
class Context {
+veb.Context
+RequestIdContext
}
App --> Context : "组合"

图表来源 - src/main.v:1-117

章节来源 - README.md:1-41 - docs/VEB_REUSE_1_1_PLAN.md:44-85 - src/main.v:1-117

QuickJS 嵌入（vjsx）

构建与依赖
Makefile 通过 ensure-quickjs.sh 准备受控 QuickJS 源码；本地优先使用 ../quickjs，否则写入工作区 .deps/quickjs
构建标志包含 build_quickjs，并在 CI 中以 VPHP_V_GC=boehm 构建
运行期能力
支持 TS 转译、多线程执行、内嵌资源；提供 vjsx Facade API（runtime、host api、snapshot 等）
配置与编排
示例 openai-gateway.toml 展示 vjsx 插件与后端编排，engine.kind=vjsx，thread_count 可调

sequenceDiagram
participant Dev as "开发者"
participant Build as "Makefile/ensure-quickjs.sh"
participant V as "V 编译器"
participant Bin as "vhttpd 二进制"
participant QJS as "QuickJS 引擎"
Dev->>Build : 触发构建
Build->>Build : 准备 QuickJS 源码(本地或工作区)
Build->>V : 传入 VJS_QUICKJS_PATH 与构建标志
V->>Bin : 编译 vhttpd(嵌入 vjsx/QuickJS)
Dev->>Bin : 启动 vhttpd
Bin->>QJS : 加载 vjsx 模块/资源
QJS-->>Bin : 执行 vjsx 插件/处理器

图表来源 - Makefile:21-26 - Makefile:96-103 - README.md:249-254 - examples/config/openai-gateway.toml:1-64

章节来源 - Makefile:21-26 - README.md:249-254 - docs/VJSX_FACADE_REFERENCE.md:1-70 - examples/config/openai-gateway.toml:1-64

TLS 支持（OpenSSL / mbedTLS）

默认后端
默认使用 OpenSSL（-d use_openssl）
备选后端
通过 V_TLS_BACKEND=mbedtls 切换至 mbedTLS，并设置长连接读超时参数
运行时计划
TlsPlan/TlsCertificatePlan 描述证书与多主机绑定

flowchart TD
Start(["构建入口"]) --> CheckBackend{"TLS 后端选择"}
CheckBackend --> |OpenSSL| UseOSSL["添加 -d use_openssl"]
CheckBackend --> |mbedTLS| UseMBED["添加 -d mbedtls_client_read_timeout_ms=120000"]
UseOSSL --> LinkLibs["链接 OpenSSL 库"]
UseMBED --> LinkLibs
LinkLibs --> Done(["完成编译"])

图表来源 - Makefile:11-16 - README.md:267-271 - src/runtime_plan/types.v:65-78

章节来源 - Makefile:11-16 - README.md:267-271 - src/runtime_plan/types.v:65-78

内存管理（Boehm GC）

自动探测与注入
Makefile 通过 pkg-config --exists bdw-gc 检测，若存在则启用 Boehm GC；也支持显式 VPHP_V_GC 覆盖
运行期影响
降低手动内存管理负担，提升开发效率与稳定性

flowchart TD
A["开始构建"] --> B["检测 bdw-gc"]
B --> |存在| C["RESOLVED_VPHP_V_GC = boehm"]
B --> |不存在| D["RESOLVED_VPHP_V_GC = none/auto"]
C --> E["传递 -gc boehm 给 V 编译器"]
D --> E
E --> F["生成 vhttpd 二进制"]

图表来源 - Makefile:7-10 - scripts/doctor.sh:49-52

章节来源 - Makefile:7-10 - scripts/doctor.sh:49-52

数据库客户端集成

构建开关
WITH_DB=1 默认启用 DB 支持；可设置为 0 关闭
配置结构
DbConfig/DbMysqlConfig/DbPgsqlConfig 定义连接池、初始化 SQL、空闲心跳等
运行时计划
ResourcePlan 用于抽象 DB 等资源引用

classDiagram
class DbConfig {
+bool enabled
+string socket
+string driver
+string pool_name
+DbMysqlConfig mysql
+DbPgsqlConfig pgsql
}
class DbMysqlConfig {
+string host
+int port
+string username
+string password
+string database
+int pool_size
+int idle_ping_ms
+[]string init_sql
}
class DbPgsqlConfig {
+string host
+int port
+string username
+string password
+string database
+int pool_size
}
class ResourcePlan {
+string id
+string category
+string kind
+PlanOptions options
}
DbConfig --> DbMysqlConfig
DbConfig --> DbPgsqlConfig

图表来源 - src/config/config.v:275-311 - src/runtime_plan/types.v:103-109 - Makefile:31-35

章节来源 - src/config/config.v:275-311 - src/runtime_plan/types.v:103-109 - Makefile:31-35

WebSocket 与流式协议

WebSocket Phase 2
vhttpd 拥有连接，worker 仅处理短事件；通过命令列表驱动发送/加入房间/广播等
SSE/文本流
通过 veb.sse 与 worker stream frames 实现 token streaming 场景
参考实现
文档明确使用 net.websocket、sync 通道与 veb.sse 作为参考

sequenceDiagram
participant Client as "客户端"
participant VHTTPD as "vhttpd(veb)"
participant Hub as "WebSocket Hub"
participant Worker as "php-worker/vjsx"
Client->>VHTTPD : Upgrade : websocket
VHTTPD->>Hub : 建立连接与会话
Client->>VHTTPD : 消息帧
VHTTPD->>Worker : 派发事件(短任务)
Worker-->>VHTTPD : 返回命令(send/join/broadcast...)
VHTTPD->>Client : 执行命令(推送/状态变更)

图表来源 - docs/WEBSOCKET_PHASE2_IMPLEMENTATION_PLAN.md:51-121 - README.md:1447-1462

章节来源 - docs/WEBSOCKET_PHASE2_IMPLEMENTATION_PLAN.md:51-121 - README.md:1447-1462

依赖关系分析

构建期依赖
V 编译器、pkg-config、C 编译器
OpenSSL 或 mbedTLS（二选一）
BDW-GC（Boehm GC）
DB 客户端库（MySQL/MariaDB、PostgreSQL、SQLite，按 WITH_DB 开关）
vjsx 模块与受控 QuickJS 源码
运行期依赖
二进制优先加载打包的 runtime/libs（libssl/libcrypto/libgc/libmysqlclient/libpq 等）
环境变量与 TOML 配置驱动行为（如 VJSX_ASSET_ROOT、VHTTPD_CONFIG）

graph LR
V["V 编译器"] --> BIN["vhttpd 二进制"]
PKG["pkg-config"] --> V
CC["C 编译器"] --> V
OSSL["OpenSSL"] --> BIN
MBED["mbedTLS"] --> BIN
GC["BDW-GC"] --> BIN
MY["MySQL/MariaDB 客户端"] --> BIN
PG["PostgreSQL 客户端"] --> BIN
SQLITE["SQLite 客户端"] --> BIN
VJSX["vjsx + QuickJS 源码"] --> BIN

图表来源 - Makefile:1-36 - README.md:332-346 - scripts/doctor.sh:49-52

章节来源 - Makefile:1-36 - README.md:332-346 - scripts/doctor.sh:49-52

性能与内存管理

内存管理
启用 Boehm GC 可降低手动管理成本，适合快速迭代与复杂对象图；生产环境可根据负载评估是否启用
并发与流式
vjsx 多线程执行；WebSocket Phase 2 解耦连接与 worker 生命周期，提高吞吐与可扩展性
日志与追踪
Admin 平面与事件日志便于定位问题；trace_id/request_id 贯穿请求链路

章节来源 - Makefile:7-10 - docs/WEBSOCKET_PHASE2_IMPLEMENTATION_PLAN.md:51-121 - src/main.v:25-56

构建工具链与环境要求

构建目标
make vhttpd：默认启用 OpenSSL 与 DB 支持
make prod/build-prod：启用 -prod 优化
make deps-core/deps-vjsx/deps-db/deps-full：一键安装依赖
make doctor：检查 v、pkg-config、openssl、bdw-gc 及 vjsx 模块
环境变量与开关
V_TLS_BACKEND：选择 TLS 后端
WITH_DB：控制 DB 支持
VPHP_V_GC：强制 GC 策略
VJS_QUICKJS_PATH：指向 QuickJS 源码
分发与运行
推荐分发打包工件，内含 runtime/libs；用户仅需 core/db 运行时配置
通过 systemd/launchd 前台运行，实例化多配置

章节来源 - Makefile:96-123 - README.md:256-271 - README.md:376-419 - scripts/doctor.sh:1-58

故障排查指南

常见环境问题
缺少 v/pkg-config/OpenSSL/BDW-GC：使用 make doctor 诊断并按提示安装
vjsx 模块缺失：先执行 make deps-vjsx 确保 vjsx 与 QuickJS 源码就绪
TLS 后端不一致：确认 V_TLS_BACKEND 与系统库匹配
DB 客户端缺失：根据错误提示安装对应客户端库或使用打包工件
配置校验
路径解析失败：检查 TOML 中的 paths.root 与相对路径展开
端口冲突/权限不足：调整 server.host/server.port 或进程用户

章节来源 - scripts/doctor.sh:1-58 - README.md:210-271 - src/config/config.v:1-55

结论

VHTTPD 以 V/veb 为核心，结合 QuickJS 嵌入式执行器、OpenSSL/mbedTLS 与 Boehm GC，形成高性能、可扩展且易于运维的传输运行时。通过统一的运行时计划与 TOML 配置，vhttpd 将 HTTP/WebSocket/SSE/MCP 与 PHP/vjsx 执行器整合在同一进程内，既满足现代 AI 与实时通信需求，又兼顾传统 PHP 生态的平滑演进。开发者可在不破坏既有业务的前提下，逐步引入 vjsx 插件与流式能力，获得更一致的运行时体验与更强的可观测性。

技术栈

目录

简介