修改

2026-05-16 13:24:02 +08:00
parent eae60714b4
commit 6c13817527
42 changed files with 15921 additions and 0 deletions
--- a/.qoder/repowiki/zh/content/部署指南/监控与日志.md
+++ b/.qoder/repowiki/zh/content/部署指南/监控与日志.md
@@ -0,0 +1,412 @@
+# 监控与日志
+
+<cite>
+**本文引用的文件**
+- [src/log.ts](file://src/log.ts)
+- [src/index.ts](file://src/index.ts)
+- [src/server.ts](file://src/server.ts)
+- [src/class/options.ts](file://src/class/options.ts)
+- [src/class/httphandler.ts](file://src/class/httphandler.ts)
+- [src/class/websockethandler.ts](file://src/class/websockethandler.ts)
+- [src/websocket.ts](file://src/websocket.ts)
+- [src/signaling.ts](file://src/signaling.ts)
+- [src/swagger.ts](file://src/swagger.ts)
+- [client/src/logger.js](file://client/src/logger.js)
+- [client/public/js/stats.js](file://client/public/js/stats.js)
+- [package.json](file://package.json)
+- [run.bat](file://run.bat)
+</cite>
+
+## 目录
+1. [简介](#简介)
+2. [项目结构](#项目结构)
+3. [核心组件](#核心组件)
+4. [架构总览](#架构总览)
+5. [详细组件分析](#详细组件分析)
+6. [依赖关系分析](#依赖关系分析)
+7. [性能考量](#性能考量)
+8. [故障排查指南](#故障排查指南)
+9. [结论](#结论)
+10. [附录](#附录)
+
+## 简介
+本指南聚焦于视频信令服务器的监控与日志配置，覆盖以下方面：
+- 日志系统配置：日志级别、输出格式与时序、HTTP访问日志策略
+- 性能监控指标：连接数统计、内存使用、请求响应时间与错误率
+- 分布式追踪：请求链路跟踪与性能瓶颈定位思路
+- 告警规则：阈值设定、通知渠道与故障恢复建议
+- 工具集成：Prometheus、Grafana、ELK Stack 的对接要点
+- 日志分析与故障诊断：常见问题与监控解决方案
+
+## 项目结构
+该项目采用分层与职责分离的设计：
+- 应用入口负责解析命令行参数、创建HTTP/HTTPS服务器、启动WebSocket信令服务
+- Express服务器负责HTTP路由、静态资源、Swagger文档与HTTP信令接口
+- WebSocket服务器负责实时信令消息的收发与连接生命周期管理
+- 日志模块提供统一的日志级别控制与格式化输出
+- 客户端侧提供前端调试日志开关与媒体统计展示
+
+```mermaid
+graph TB
+A["应用入口<br/>src/index.ts"] --> B["Express服务器<br/>src/server.ts"]
+A --> C["WebSocket信令<br/>src/websocket.ts"]
+B --> D["HTTP信令路由<br/>src/signaling.ts"]
+D --> E["HTTP处理器<br/>src/class/httphandler.ts"]
+C --> F["WebSocket处理器<br/>src/class/websockethandler.ts"]
+A --> G["日志模块<br/>src/log.ts"]
+B --> H["Swagger文档<br/>src/swagger.ts"]
+I["客户端调试日志<br/>client/src/logger.js"] -.-> A
+```
+
+**图表来源**
+- [src/index.ts:13-108](file://src/index.ts#L13-L108)
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+- [src/websocket.ts:6-117](file://src/websocket.ts#L6-L117)
+- [src/signaling.ts:1-24](file://src/signaling.ts#L1-L24)
+- [src/class/httphandler.ts:1-120](file://src/class/httphandler.ts#L1-L120)
+- [src/class/websockethandler.ts:1-66](file://src/class/websockethandler.ts#L1-L66)
+- [src/log.ts:1-51](file://src/log.ts#L1-L51)
+- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
+- [client/src/logger.js:1-30](file://client/src/logger.js#L1-L30)
+
+**章节来源**
+- [src/index.ts:13-108](file://src/index.ts#L13-L108)
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+- [src/websocket.ts:6-117](file://src/websocket.ts#L6-L117)
+- [src/signaling.ts:1-24](file://src/signaling.ts#L1-L24)
+- [src/class/httphandler.ts:1-120](file://src/class/httphandler.ts#L1-L120)
+- [src/class/websockethandler.ts:1-66](file://src/class/websockethandler.ts#L1-L66)
+- [src/log.ts:1-51](file://src/log.ts#L1-L51)
+- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
+- [client/src/logger.js:1-30](file://client/src/logger.js#L1-L30)
+
+## 核心组件
+- 日志模块：提供日志级别枚举、动态级别设置、时间戳格式化与不同级别输出
+- HTTP服务器：基于Express，启用Morgan进行HTTP访问日志，支持多种格式
+- WebSocket信令：基于ws，维护连接组、广播与心跳检测
+- HTTP信令处理器：基于会话与连接ID管理，提供offer/answer/candidate等信令存取
+- Swagger文档：自动生成API文档，便于监控与排障时查阅接口规范
+
+**章节来源**
+- [src/log.ts:1-51](file://src/log.ts#L1-L51)
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+- [src/websocket.ts:6-117](file://src/websocket.ts#L6-L117)
+- [src/class/httphandler.ts:1-120](file://src/class/httphandler.ts#L1-L120)
+- [src/class/websockethandler.ts:1-66](file://src/class/websockethandler.ts#L1-L66)
+- [src/swagger.ts:16-65](file://src/swagger.ts#L16-L65)
+
+## 架构总览
+下图展示了从请求进入、HTTP处理、WebSocket处理到日志输出的整体流程。
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant HTTP as "HTTP服务器<br/>src/server.ts"
+participant Sig as "HTTP信令路由<br/>src/signaling.ts"
+participant Hdl as "HTTP处理器<br/>src/class/httphandler.ts"
+participant WS as "WebSocket服务器<br/>src/websocket.ts"
+participant WSH as "WebSocket处理器<br/>src/class/websockethandler.ts"
+participant Log as "日志模块<br/>src/log.ts"
+Client->>HTTP : "HTTP请求"
+HTTP->>Sig : "路由到/signaling"
+Sig->>Hdl : "调用处理器(如创建会话/获取offer)"
+Hdl-->>HTTP : "响应(200/4xx)"
+HTTP-->>Client : "HTTP响应"
+Client->>WS : "WebSocket连接"
+WS->>WSH : "on('connection')"
+WSH-->>Log : "记录连接/断开/消息"
+WSH-->>Client : "信令消息(offer/answer/candidate)"
+```
+
+**图表来源**
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+- [src/signaling.ts:1-24](file://src/signaling.ts#L1-L24)
+- [src/class/httphandler.ts:398-641](file://src/class/httphandler.ts#L398-L641)
+- [src/websocket.ts:27-115](file://src/websocket.ts#L27-L115)
+- [src/class/websockethandler.ts:145-206](file://src/class/websockethandler.ts#L145-L206)
+- [src/log.ts:30-50](file://src/log.ts#L30-L50)
+
+## 详细组件分析
+
+### 日志系统配置
+- 日志级别
+  - 支持 none/error/warn/log/info 五级，可通过运行参数或环境变量设置
+  - 默认级别为 info；当级别为 none 时不输出任何日志
+- 输出格式
+  - 自动添加ISO时间戳与大写的级别前缀
+  - 使用不同console方法区分 error/warn/info/log
+- HTTP访问日志
+  - 通过 Morgan 中间件启用，支持 combined/dev/short/tiny 或禁用
+  - 日志级别与Morgan日志可并行使用，便于区分业务日志与访问日志
+
+```mermaid
+flowchart TD
+Start(["设置日志级别"]) --> Parse["解析字符串级别<br/>parseLogLevel()"]
+Parse --> Set["setLogLevel() 更新全局级别"]
+Set --> Check{"当前级别是否允许输出？"}
+Check --> |否| Exit["直接返回"]
+Check --> |是| Format["formatTimestamp()<br/>拼装前缀"]
+Format --> Emit{"根据级别选择输出方法"}
+Emit --> Console["console.error/warn/info/log"]
+Console --> End(["完成"])
+```
+
+**图表来源**
+- [src/log.ts:11-24](file://src/log.ts#L11-L24)
+- [src/log.ts:26-50](file://src/log.ts#L26-L50)
+
+**章节来源**
+- [src/log.ts:1-51](file://src/log.ts#L1-L51)
+- [src/server.ts:18-20](file://src/server.ts#L18-L20)
+- [src/index.ts:28](file://src/index.ts#L28)
+- [package.json:9](file://package.json#L9)
+- [run.bat:8](file://run.bat#L8)
+
+### HTTP访问日志与路由
+- 访问日志
+  - 通过 Morgan 中间件以配置项启用，支持多种格式
+  - 可通过运行参数控制，避免生产环境产生过多日志
+- 信令路由
+  - 提供会话创建、连接管理、offer/answer/candidate获取与推送
+  - 使用会话ID作为安全约束，确保接口访问受控
+
+```mermaid
+sequenceDiagram
+participant Client as "客户端"
+participant Server as "Express服务器"
+participant Router as "HTTP信令路由"
+participant Handler as "HTTP处理器"
+Client->>Server : "GET /signaling/connection"
+Server->>Router : "匹配路由"
+Router->>Handler : "checkSessionId() 校验"
+Handler-->>Router : "返回连接列表"
+Router-->>Server : "JSON响应"
+Server-->>Client : "HTTP 200"
+```
+
+**图表来源**
+- [src/server.ts:25-86](file://src/server.ts#L25-L86)
+- [src/signaling.ts:6-24](file://src/signaling.ts#L6-L24)
+- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
+
+**章节来源**
+- [src/server.ts:14-89](file://src/server.ts#L14-L89)
+- [src/signaling.ts:1-24](file://src/signaling.ts#L1-L24)
+- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
+
+### WebSocket信令与连接管理
+- 连接生命周期
+  - 建立连接时注册，断开时清理；记录连接/断开/消息等事件
+- 1对多模式
+  - host与participants角色分工，offer/answer/candidate按角色路由
+  - 支持广播与定向消息，便于扩展聊天、白板等场景
+- 心跳与超时
+  - 定期发送ping并检查lastActivity，超时自动断开，降低僵尸连接占用
+
+```mermaid
+classDiagram
+class WSSignaling {
+server
+wss
+constructor(server, mode)
+}
+class WebSocketHandler {
+reset(mode)
+add(ws)
+remove(ws)
+onConnect(ws, connectionId)
+onDisconnect(ws, connectionId)
+onOffer(ws, message)
+onAnswer(ws, message)
+onCandidate(ws, message)
+onBroadcast(ws, message)
+onMessage(ws, message)
+AddHeartbeat(ws, connectionId)
+RemoveHeartbeat(ws)
+}
+WSSignaling --> WebSocketHandler : "委托处理"
+```
+
+**图表来源**
+- [src/websocket.ts:15-117](file://src/websocket.ts#L15-L117)
+- [src/class/websockethandler.ts:63-479](file://src/class/websockethandler.ts#L63-L479)
+
+**章节来源**
+- [src/websocket.ts:6-117](file://src/websocket.ts#L6-L117)
+- [src/class/websockethandler.ts:145-338](file://src/class/websockethandler.ts#L145-L338)
+
+### HTTP处理器与会话/连接模型
+- 会话与连接
+  - 会话ID唯一标识一次通话或交互；连接ID标识具体端点
+  - 支持私有模式下的双向配对与公共模式下的广播
+- 信令存储
+  - offer/answer/candidate按连接ID与会话ID存储，支持按时间过滤
+- 超时与清理
+  - 基于lastRequestedTime定期清理超时会话，释放资源
+
+```mermaid
+flowchart TD
+S["创建会话(createSession)"] --> C["创建连接(createConnection)"]
+C --> O["接收/存储offer"]
+C --> A["接收/存储answer"]
+C --> K["接收/存储candidate"]
+O --> R["按fromtime过滤返回(getOffer)"]
+A --> R2["按fromtime过滤返回(getAnswer)"]
+K --> R3["按fromtime过滤返回(getCandidate)"]
+T["超时检测(_checkForTimedOutSessions)"] --> Del["删除会话(_deleteSession)"]
+```
+
+**图表来源**
+- [src/class/httphandler.ts:664-675](file://src/class/httphandler.ts#L664-L675)
+- [src/class/httphandler.ts:739-783](file://src/class/httphandler.ts#L739-L783)
+- [src/class/httphandler.ts:218-232](file://src/class/httphandler.ts#L218-L232)
+- [src/class/httphandler.ts:200-213](file://src/class/httphandler.ts#L200-L213)
+
+**章节来源**
+- [src/class/httphandler.ts:106-120](file://src/class/httphandler.ts#L106-L120)
+- [src/class/httphandler.ts:218-232](file://src/class/httphandler.ts#L218-L232)
+- [src/class/httphandler.ts:398-641](file://src/class/httphandler.ts#L398-L641)
+
+### 客户端日志与媒体统计
+- 客户端调试日志
+  - 提供enable/disable与多级别输出，便于前端问题定位
+- 媒体统计
+  - 基于RTCStats计算比特率、帧率等指标，辅助性能分析
+
+**章节来源**
+- [client/src/logger.js:1-30](file://client/src/logger.js#L1-L30)
+- [client/public/js/stats.js:7-91](file://client/public/js/stats.js#L7-L91)
+
+## 依赖关系分析
+- 运行时依赖
+  - Express、ws、morgan、swagger-ui-express、uuid等
+- 开发与测试
+  - Jest、ts-jest、mock-socket等
+- 构建与打包
+  - TypeScript编译、pkg打包静态资源
+
+```mermaid
+graph LR
+P["package.json"] --> E["express"]
+P --> W["ws"]
+P --> M["morgan"]
+P --> S["swagger-ui-express"]
+P --> U["uuid"]
+P --> J["jest/ts-jest"]
+P --> T["typescript"]
+```
+
+**图表来源**
+- [package.json:14-46](file://package.json#L14-L46)
+
+**章节来源**
+- [package.json:14-46](file://package.json#L14-L46)
+
+## 性能考量
+- 连接数统计
+  - WebSocket侧：通过连接集合与连接组统计当前活跃连接数
+  - HTTP侧：通过会话与连接映射统计会话数量与连接数
+- 内存使用
+  - 信令消息以Map/Set存储，需关注超时清理与消息大小
+  - 前端媒体统计可辅助判断网络拥塞与编码开销
+- 请求响应时间与错误率
+  - HTTP接口响应时间可通过中间件埋点或外部APM采集
+  - 错误率可通过HTTP状态码分布统计
+- 轮询与长连接
+  - HTTP轮询模式下应限制轮询频率，避免CPU与带宽浪费
+  - WebSocket心跳与超时可减少无效连接占用
+
+[本节为通用性能指导，无需特定文件引用]
+
+## 故障排查指南
+- 常见问题
+  - 会话不存在：HTTP处理器校验session-id，缺失或过期导致404
+  - 连接ID冲突：私有模式下重复使用连接ID会触发400
+  - WebSocket超时：长时间无活动将被自动断开
+  - 文件上传失败：服务端重命名异常导致500
+- 排查步骤
+  - 启用更细粒度日志（info/log），复现问题并核对日志时间线
+  - 使用Swagger查看接口规范，确认请求头与参数
+  - 检查WebSocket消息类型与路由逻辑，确认角色与目标参与者
+  - 对比前后两次RTCStats，定位带宽与帧率异常
+
+**章节来源**
+- [src/class/httphandler.ts:128-145](file://src/class/httphandler.ts#L128-L145)
+- [src/class/httphandler.ts:747-763](file://src/class/httphandler.ts#L747-L763)
+- [src/class/websockethandler.ts:404-430](file://src/class/websockethandler.ts#L404-L430)
+- [src/server.ts:74-82](file://src/server.ts#L74-L82)
+
+## 结论
+本项目提供了清晰的日志体系与信令处理能力，结合Morgan访问日志与Swagger文档，能够满足日常运维与排障需求。建议在生产环境中：
+- 明确日志级别与轮转策略，避免磁盘与IO压力
+- 引入APM或Prometheus/Grafana进行指标采集与可视化
+- 建立告警规则与通知通道，配合健康检查与自动恢复机制
+- 使用分布式追踪定位跨服务链路瓶颈
+
+[本节为总结性内容，无需特定文件引用]
+
+## 附录
+
+### 日志系统配置清单
+- 日志级别
+  - 可选：none/error/warn/log/info
+  - 默认：info
+- 输出格式
+  - ISO时间戳 + 大写级别前缀
+  - 区分 error/warn/info/log
+- HTTP访问日志
+  - 可选：combined/dev/short/tiny 或 none
+  - 通过运行参数控制
+
+**章节来源**
+- [src/log.ts:1-51](file://src/log.ts#L1-L51)
+- [src/server.ts:18-20](file://src/server.ts#L18-L20)
+- [src/index.ts:28](file://src/index.ts#L28)
+
+### 性能监控指标定义
+- 连接数
+  - WebSocket活跃连接数：基于连接集合统计
+  - HTTP会话数与连接数：基于会话映射统计
+- 内存使用
+  - 服务端：关注Map/Set规模与消息队列长度
+  - 客户端：媒体统计辅助判断编码与传输效率
+- 请求响应时间与错误率
+  - 通过中间件或外部APM采集
+  - 错误率基于HTTP状态码分布
+
+**章节来源**
+- [src/class/websockethandler.ts:20-37](file://src/class/websockethandler.ts#L20-L37)
+- [src/class/httphandler.ts:42-84](file://src/class/httphandler.ts#L42-L84)
+- [client/public/js/stats.js:7-91](file://client/public/js/stats.js#L7-L91)
+
+### 分布式追踪配置建议
+- 链路跟踪
+  - 在HTTP入口与WebSocket消息处理处打点
+  - 关键节点：创建会话、创建连接、发送/接收offer/answer/candidate
+- 瓶颈定位
+  - 结合日志时间戳与追踪ID，定位慢查询与阻塞点
+  - 媒体统计与网络指标联动分析
+
+[本节为通用实践建议，无需特定文件引用]
+
+### 告警规则与通知
+- 阈值建议
+  - 连接数：单节点并发连接数峰值阈值
+  - 错误率：HTTP 5xx占比、WebSocket断连率
+  - 响应时间：P95/P99延迟阈值
+- 通知渠道
+  - 邮件、IM、电话分级告警
+- 故障恢复
+  - 自动扩容、熔断降级、快速回滚
+
+[本节为通用实践建议，无需特定文件引用]
+
+### 监控工具集成要点
+- Prometheus
+  - 暴露指标端点，采集连接数、内存、请求速率与错误率
+- Grafana
+  - 仪表板展示趋势、告警与热力图
+- ELK Stack
+  - 收集HTTP与业务日志，建立检索与聚合分析
+
+[本节为通用实践建议，无需特定文件引用]