故障排除指南

本文引用的文件
- scripts/doctor.sh - scripts/runtime_doctor.sh - src/logging/runtime_logger.v - README.md - articles/11-observability.md - src/upstream/transport/error_classifier.v - src/http_stats.v - src/worker_backend_admin_runtime.v

简介

本指南面向生产与运维人员，聚焦 vhttpd 的常见故障场景与系统化排查方法。内容覆盖： - 启动失败、配置错误、性能问题、网络连接异常等典型问题 - 系统健康检查工具与脚本（如 doctor.sh、runtime_doctor.sh）的使用方法 - 日志分析与调试技巧（日志级别、关键日志识别、性能瓶颈定位） - 内存泄漏检测、CPU 使用率分析、磁盘空间监控等系统级问题 - 网络连通性测试、端口占用检查、依赖服务状态验证等基础设施层面的步骤

项目结构

围绕“可观测性与排障”的关键位置包括： - 诊断脚本：scripts/doctor.sh、scripts/runtime_doctor.sh - 运行时日志与级别控制：src/logging/runtime_logger.v - Admin Plane 端点与健康检查：README.md、articles/11-observability.md - 错误分类与统计：src/upstream/transport/error_classifier.v、src/http_stats.v - Worker 进程指标采集：src/worker_backend_admin_runtime.v

graph TB
A["诊断脚本<br/>scripts/doctor.sh"] --> B["构建依赖检查"]
C["运行时诊断脚本<br/>scripts/runtime_doctor.sh"] --> D["运行期依赖检查"]
E["日志级别控制<br/>src/logging/runtime_logger.v"] --> F["环境变量 VHTTPD_LOG_LEVEL"]
G["Admin Plane 端点<br/>README.md / articles/11-observability.md"] --> H["/health, /admin/*"]
I["错误分类器<br/>src/upstream/transport/error_classifier.v"] --> J["HTTP 错误码映射"]
K["HTTP 统计<br/>src/http_stats.v"] --> L["请求/错误/超时计数"]
M["Worker 管理接口<br/>src/worker_backend_admin_runtime.v"] --> N["RSS 内存采集"]

图表来源 - scripts/doctor.sh:1-108 - scripts/runtime_doctor.sh:1-126 - src/logging/runtime_logger.v:1-42 - README.md:1090-1289 - articles/11-observability.md:1-177 - src/upstream/transport/error_classifier.v:1-19 - src/http_stats.v:1-32 - src/worker_backend_admin_runtime.v:1-40

章节来源 - scripts/doctor.sh:1-108 - scripts/runtime_doctor.sh:1-126 - src/logging/runtime_logger.v:1-42 - README.md:1090-1289 - articles/11-observability.md:1-177 - src/upstream/transport/error_classifier.v:1-19 - src/http_stats.v:1-32 - src/worker_backend_admin_runtime.v:1-40

核心组件

诊断脚本
构建期环境检查：编译器、pkg-config、OpenSSL、BDW-GC、QuickJS、sqlite3、MySQL/MariaDB/PostgreSQL 客户端工具等
运行期二进制依赖检查：Linux ldd、macOS otool、sqlite3、数据库客户端工具、VJSX 资源嵌入情况
日志子系统
通过环境变量 VHTTPD_LOG_LEVEL 控制日志级别；默认在 prod 与非 prod 下不同
Admin Plane 与可观测性
/health 健康检查、/admin/workers、/admin/stats、/admin/runtime 等端点用于运行时观测与管理
错误分类与统计
将后端错误消息分类为 HTTP 状态码与错误类型，便于上层统一处理与告警
维护全局 HTTP 请求/错误/超时/流式响应/管理动作计数
Worker 进程指标
暴露 worker 存活、队列长度、已服务请求数、重启次数、RSS 内存等

章节来源 - scripts/doctor.sh:1-108 - scripts/runtime_doctor.sh:1-126 - src/logging/runtime_logger.v:1-42 - README.md:1090-1289 - articles/11-observability.md:1-177 - src/upstream/transport/error_classifier.v:1-19 - src/http_stats.v:1-32 - src/worker_backend_admin_runtime.v:1-40

架构总览

下图展示了从外部调用到内部统计与诊断的整体路径，以及健康检查与错误分类的位置。

sequenceDiagram
participant Client as "客户端"
participant Server as "vhttpd 服务"
participant Admin as "Admin Plane"
participant Logger as "日志模块"
participant Stats as "HTTP 统计"
participant Classifier as "错误分类器"
participant Worker as "Worker 进程"
Client->>Server : "GET /health"
Server-->>Client : "200 OK"
Client->>Server : "业务请求"
Server->>Stats : "inc_requests()"
Server->>Logger : "按级别记录日志"
Server->>Worker : "派发请求"
Worker-->>Server : "返回结果或错误"
Server->>Classifier : "classify_worker_backend_error(err)"
Classifier-->>Server : "HTTP 状态码 + 错误类型"
Server->>Stats : "inc_errors()/inc_timeouts() 等"
Server-->>Client : "响应"
Client->>Admin : "GET /admin/stats"
Admin-->>Client : "统计快照"

图表来源 - README.md:1090-1289 - src/logging/runtime_logger.v:1-42 - src/http_stats.v:1-32 - src/upstream/transport/error_classifier.v:1-19

详细组件分析

诊断脚本：构建期与环境检查

功能要点
检查 v、pkg-config、openssl、bdw-gc 等编译依赖
检查 vjsx 构建模块与 QuickJS 源码是否就绪
检查 sqlite3、mysql_config/mariadb_config、pg_config 等可选依赖
输出 ok/warn/bad 三类信息并设置退出码
适用场景
首次安装、CI 构建前校验、升级后回归检查

章节来源 - scripts/doctor.sh:1-108

诊断脚本：运行期依赖检查

功能要点
校验二进制存在与可执行位
Linux 使用 ldd、macOS 使用 otool 解析动态库依赖并判断缺失
检查 sqlite3、mysql_config/mariadb_config、pg_config 是否存在
检查 VJSX 资源是否内嵌或受 VJSX_ASSET_ROOT 覆盖
适用场景
部署后快速自检、容器镜像完整性验证、跨平台迁移验证

章节来源 - scripts/runtime_doctor.sh:1-126

日志级别与配置

行为说明
支持 debug/info/warn/error/fatal 级别
通过环境变量 VHTTPD_LOG_LEVEL 覆盖默认级别
非 prod 默认 info，prod 默认 warn
排障建议
临时提升为 debug 以捕获更多上下文
结合 Admin Plane 事件日志进行关联分析

章节来源 - src/logging/runtime_logger.v:1-42

Admin Plane 健康检查与运行时观测

健康检查
GET /health 返回 200 OK，适合探针与负载均衡健康检查
运行时观测
GET /admin/workers：Worker 池状态、存活、队列、重启计数
GET /admin/stats：进程级计数器（请求、错误、超时、流式、管理动作等）
GET /admin/runtime：能力标志、活跃连接/会话、队列容量与深度等
认证模型
当启用 admin token 时，需携带 x-vhttpd-admin-token 或通过查询参数传递
端口策略
admin 独立端口时，数据平面 /admin/ 返回 404；未启用时数据平面提供 /admin/

章节来源 - README.md:1090-1289 - articles/11-observability.md:1-177

错误分类与统计

错误分类
根据后端错误消息关键词映射为 HTTP 状态码与错误类型（如 worker_pool_exhausted、worker_queue_full、worker_queue_timeout、timeout、transport_error）
统计项
requests_total、errors_total、timeouts_total、streams_total、admin_actions_total
应用价值
统一错误语义，便于告警规则与仪表盘展示

章节来源 - src/upstream/transport/error_classifier.v:1-19 - src/http_stats.v:1-32

Worker 进程指标采集

指标范围
id、socket、alive、pid、rss_kb、draining、inflight_requests、served_requests、restart_count、next_retry_ts
实现方式
通过 ps -o rss= -p 获取 RSS（KB），兼容 macOS/Linux
使用建议
结合 /admin/workers 与 /admin/stats 观察内存与负载趋势

章节来源 - src/worker_backend_admin_runtime.v:1-40

依赖关系分析

脚本与系统工具
doctor.sh 依赖 v、pkg-config、openssl、bdw-gc、sqlite3、mysql_config/mariadb_config、pg_config
runtime_doctor.sh 依赖 ldd/otool、sqlite3、数据库客户端工具
运行时与 Admin Plane
日志模块由环境变量驱动
Admin Plane 提供健康与统计端点，供外部监控系统拉取
错误分类与统计
上游传输层错误经分类器归一化，统计模块聚合计数

graph LR
Doctor["scripts/doctor.sh"] --> SysTools["系统工具链"]
RuntimeDoctor["scripts/runtime_doctor.sh"] --> Binaries["动态库解析工具"]
Logger["src/logging/runtime_logger.v"] --> Env["VHTTPD_LOG_LEVEL"]
Admin["README.md / observability.md"] --> Endpoints["/health, /admin/*"]
Classifier["error_classifier.v"] --> Stats["http_stats.v"]

图表来源 - scripts/doctor.sh:1-108 - scripts/runtime_doctor.sh:1-126 - src/logging/runtime_logger.v:1-42 - README.md:1090-1289 - articles/11-observability.md:1-177 - src/upstream/transport/error_classifier.v:1-19 - src/http_stats.v:1-32

性能注意事项

关注队列深度与拒绝计数
通过 /admin/stats 中的 worker_queue_* 相关计数判断拥塞
关注 Worker 内存增长
结合 /admin/workers 中 memory_mb 与 RSS 变化评估是否需要限流或重启
关注超时与错误比例
通过 timeouts_total、errors_total 与 p95/p99 延迟指标联动分析

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