14 KiB
14 KiB
日志系统
**本文引用的文件** - [src/log.ts](file://src/log.ts) - [src/index.ts](file://src/index.ts) - [src/class/httphandler.ts](file://src/class/httphandler.ts) - [src/class/websockethandler.ts](file://src/class/websockethandler.ts) - [client/src/logger.js](file://client/src/logger.js) - [package.json](file://package.json) - [src/class/options.ts](file://src/class/options.ts)目录
简介
本技术文档聚焦于视频服务器项目的日志系统模块，系统性阐述日志级别管理、输出格式控制与日志轮转机制现状，解释 LogLevel 枚举的使用场景与差异，说明当前日志输出目标（控制台为主），并给出性能优化建议、调试技巧以及与日志分析与监控告警的集成思路。由于仓库中未发现文件落盘或远程日志服务的直接实现，本文在“输出目标”部分明确指出当前限制，并在“附录”中提供可扩展的实践建议。
项目结构
日志系统主要由以下部分组成：
- 服务端日志模块：定义日志级别、格式化与输出逻辑
- 应用入口：解析命令行参数并调用日志模块进行启动信息输出
- 业务处理器：在 HTTP 与 WebSocket 层面使用统一日志模块进行运行态事件记录
- 客户端日志模块：提供简易调试开关与条件输出（与服务端日志模块独立）
graph TB
A["应用入口<br/>src/index.ts"] --> B["日志模块<br/>src/log.ts"]
C["HTTP处理器<br/>src/class/httphandler.ts"] --> B
D["WebSocket处理器<br/>src/class/websockethandler.ts"] --> B
E["客户端日志模块<br/>client/src/logger.js"] -. 独立调试 .-> B
图表来源
- src/index.ts:11-91
- src/log.ts:1-51
- src/class/httphandler.ts:11
- src/class/websockethandler.ts:8
- client/src/logger.js:1-30
章节来源
- src/index.ts:11-91
- src/log.ts:1-51
- src/class/httphandler.ts:11
- src/class/websockethandler.ts:8
- client/src/logger.js:1-30
核心组件
- 日志级别枚举与控制
- LogLevel 枚举定义了 none、error、warn、log、info 五个级别，数值越大级别越高
- 提供 setLogLevel 与 parseLogLevel，支持从字符串解析并动态调整全局日志级别
- 日志输出与格式
- 输出统一走浏览器/Node 控制台接口，自动添加 ISO 时间戳与大写的级别前缀
- 不同级别对应不同的控制台输出方法，便于在浏览器开发者工具中区分
- 使用分布
- 应用入口在启动阶段输出网络地址、协议类型与模式等关键信息
- HTTP 与 WebSocket 处理器在连接建立、断开、超时、信令交互等关键节点输出运行态日志
章节来源
架构总览
日志模块在服务端采用集中式设计：统一的枚举与格式化逻辑，配合各业务模块按需调用。整体调用链路如下：
sequenceDiagram
participant CLI as "命令行/环境变量"
participant App as "应用入口<br/>src/index.ts"
participant Log as "日志模块<br/>src/log.ts"
participant HTTP as "HTTP处理器<br/>src/class/httphandler.ts"
participant WS as "WebSocket处理器<br/>src/class/websockethandler.ts"
CLI->>App : 解析参数(-l/-m/-t等)
App->>Log : 输出启动信息(info/warn)
HTTP->>Log : 关键事件(log/info/warn/error)
WS->>Log : 关键事件(log/info/warn/error)
Log-->>Console : 控制台输出(带时间戳与级别)
图表来源
详细组件分析
日志模块（src/log.ts）
- 设计要点
- 通过全局变量维护当前日志级别，决定是否输出
- parseLogLevel 支持从字符串解析级别，默认回退到 info
- formatTimestamp 统一 ISO 时间戳格式
- 根据级别选择控制台输出方法，便于区分错误、警告、信息与普通日志
- 性能与行为
- 条件判断在输出前完成，避免不必要的字符串拼接
- 控制台输出为同步 I/O，适合开发与调试；生产环境建议结合外部日志采集
flowchart TD
Start(["进入 log(level, ...args)"]) --> Check["比较 level 与当前级别<br/>与 none 特判"]
Check --> |不满足| Exit["直接返回"]
Check --> |满足| Stamp["生成 ISO 时间戳"]
Stamp --> Prefix["构造前缀: [时间戳] [级别]"]
Prefix --> Switch{"根据级别选择输出方法"}
Switch --> |error| OutErr["console.error(...)"]
Switch --> |warn| OutWarn["console.warn(...)"]
Switch --> |info| OutInfo["console.info(...)"]
Switch --> |其他| OutLog["console.log(...)"]
OutErr --> End(["结束"])
OutWarn --> End
OutInfo --> End
OutLog --> End
图表来源
章节来源
应用入口与日志使用（src/index.ts）
- 启动阶段日志
- 输出 HTTP/HTTPS 地址、信令协议类型、模式等关键信息
- 对不支持的信令类型发出警告并回退到默认值
- 参数来源
- 通过 commander 解析命令行参数，同时兼容环境变量
- logging 参数与 morgan 中间件相关（见“依赖关系分析”）
sequenceDiagram
participant Entrypoint as "应用入口<br/>src/index.ts"
participant Log as "日志模块<br/>src/log.ts"
Entrypoint->>Log : info("启动地址/模式/协议等")
Entrypoint->>Log : warn("不支持的信令类型/回退提示")
图表来源
章节来源
HTTP 处理器中的日志（src/class/httphandler.ts）
- 关键节点日志
- 会话超时清理：输出被删除的会话 ID
- 连接/断开/参与者加入/离开等事件：输出连接 ID 与上下文信息
- 错误场景：对非法参数或冲突状态输出警告
- 日志级别选择
- 一般事件使用 log 或 info
- 异常或异常流程使用 warn
sequenceDiagram
participant HTTP as "HTTP处理器<br/>src/class/httphandler.ts"
participant Log as "日志模块<br/>src/log.ts"
HTTP->>Log : log("超时删除会话 sessionId=...")
HTTP->>Log : warn("连接ID已使用/参数缺失等")
HTTP->>Log : log("参与者加入/离开/断开连接等")
图表来源
章节来源
WebSocket 处理器中的日志（src/class/websockethandler.ts）
- 关键节点日志
- 连接建立/断开、参与者加入/离开、主机断开、心跳超时等
- 心跳定时器：周期性输出心跳状态与超时检测
- 日志级别选择
- 事件性信息使用 log
- 超时与异常使用 warn
sequenceDiagram
participant WS as "WebSocket处理器<br/>src/class/websockethandler.ts"
participant Log as "日志模块<br/>src/log.ts"
WS->>Log : log("Add WebSocket/参与者加入/断开连接等")
WS->>Log : warn("WebSocket连接超时, closing...")
WS->>Log : log("WebSocket连接心跳 lastActivity=...")
图表来源
- src/class/websockethandler.ts:77
- src/class/websockethandler.ts:154
- src/class/websockethandler.ts:192
- src/class/websockethandler.ts:413
- src/class/websockethandler.ts:420
章节来源
- src/class/websockethandler.ts:77
- src/class/websockethandler.ts:154
- src/class/websockethandler.ts:192
- src/class/websockethandler.ts:413
- src/class/websockethandler.ts:420
客户端日志模块（client/src/logger.js）
- 功能概述
- 提供启用/禁用调试开关
- 在调试开启时输出 debug/info/log/warn/error 级别消息
- 适用场景
- 前端调试与本地开发，与服务端日志模块解耦
flowchart TD
Start(["调用 debug/info/log/warn/error"]) --> Check["检查 isDebug 标志"]
Check --> |false| Exit["直接返回"]
Check --> |true| Console["console.debug/info/log/warn/error(...)"]
Console --> End(["结束"])
图表来源
章节来源
依赖关系分析
- 日志模块依赖
- 服务端日志模块仅依赖标准控制台输出，无第三方依赖
- 客户端日志模块同样依赖浏览器/Node 控制台
- HTTP 中间件与日志
- 项目包含 morgan（HTTP 请求访问日志中间件），与自研日志模块互补
- logging 参数影响 morgan 的日志格式（如 combined/dev/short/tiny 或 none）
graph LR
Log["日志模块<br/>src/log.ts"] --> Console["控制台输出"]
HTTP["HTTP中间件(morgan)"] --> Console
App["应用入口<br/>src/index.ts"] --> Log
HTTPMod["HTTP处理器<br/>src/class/httphandler.ts"] --> Log
WSMod["WebSocket处理器<br/>src/class/websockethandler.ts"] --> Log
图表来源
章节来源
性能考量
- 当前实现特点
- 控制台输出为同步 I/O，简单可靠，适合开发与小规模生产调试
- 未内置异步写盘或远程上报能力
- 性能优化建议
- 降低高频事件日志量：将细粒度 log 降级为 info 或在高并发场景减少输出
- 使用 parseLogLevel 与 setLogLevel 动态调整级别：生产环境默认 info 或 warn
- 结合 morgan 的短格式或关闭策略，减少 HTTP 访问日志对吞吐的影响
- 对热点路径的日志进行采样或聚合，避免频繁 I/O
- 与 morgan 的协同
- logging 参数可选：combined/dev/short/tiny 或 none，按需选择以平衡可观测性与性能
章节来源
故障排查指南
- 常见问题定位
- 无法看到预期日志：确认当前日志级别是否高于目标级别，或是否被 none 特判拦截
- 信令异常：关注 HTTP/WS 处理器中的 warn 与 error 输出，定位参数缺失、冲突或超时
- 心跳超时：WebSocket 处理器会输出超时警告，检查网络质量与客户端活跃度
- 调试技巧
- 在应用入口处临时提升日志级别，获取更详细的启动与初始化信息
- 使用客户端 logger.js 的调试开关，在前端侧快速验证消息流转
- 结合浏览器开发者工具的控制台筛选功能，按级别过滤输出
章节来源
结论
本项目的日志系统以轻量、集中式为核心：统一的级别与格式化逻辑，配合业务模块在关键节点输出运行态信息。当前实现以控制台输出为主，未包含文件落盘与远程上报。通过合理设置日志级别、结合 morgan 的访问日志策略，可在开发与生产环境中取得良好的可观测性与性能平衡。若需进一步增强，可在现有日志模块基础上扩展文件轮转与远程推送能力。
附录
日志级别与应用场景
- none：完全屏蔽日志输出
- error：致命错误，应立即修复
- warn：潜在风险或异常流程，需关注
- log：常规事件性信息，适合高频但非关键的运行态记录
- info：重要状态变更与启动/停止信息
章节来源
日志输出目标与扩展
- 当前实现
- 仅控制台输出，无文件落盘与远程日志服务
- 扩展建议
- 文件落盘：在日志模块中增加文件句柄与滚动策略（按大小/时间）
- 远程上报：在日志模块中增加 HTTP 推送或 SDK 接入（如 Loki、ELK、Sentry）
- 与 morgan 协同：通过 logging 参数控制 HTTP 访问日志格式与级别
章节来源
日志分析与监控告警集成
- 分析工具
- 将控制台输出重定向至文件或管道，接入日志收集系统（如 Fluent Bit、Filebeat）
- 使用正则提取时间戳与级别字段，构建结构化日志
- 监控告警
- 基于 error/warn 比例与速率阈值触发告警
- 结合业务指标（连接数、超时率、信令成功率）进行综合评估
章节来源