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