root/video_socket-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
87c4a56306c76a325bbed4c4b84eb248accc4693
video_socket-server/.qoder/repowiki/zh/content/部署指南/监控与日志.md
stary 6c13817527 修改
2026-05-16 13:24:02 +08:00

16 KiB
Raw Blame History

监控与日志

**本文引用的文件** - [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)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本指南聚焦于视频信令服务器的监控与日志配置，覆盖以下方面：

  • 日志系统配置：日志级别、输出格式与时序、HTTP访问日志策略
  • 性能监控指标：连接数统计、内存使用、请求响应时间与错误率
  • 分布式追踪：请求链路跟踪与性能瓶颈定位思路
  • 告警规则：阈值设定、通知渠道与故障恢复建议
  • 工具集成：Prometheus、Grafana、ELK Stack 的对接要点
  • 日志分析与故障诊断：常见问题与监控解决方案

项目结构

该项目采用分层与职责分离的设计：

  • 应用入口负责解析命令行参数、创建HTTP/HTTPS服务器、启动WebSocket信令服务
  • Express服务器负责HTTP路由、静态资源、Swagger文档与HTTP信令接口
  • WebSocket服务器负责实时信令消息的收发与连接生命周期管理
  • 日志模块提供统一的日志级别控制与格式化输出
  • 客户端侧提供前端调试日志开关与媒体统计展示
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

图表来源

章节来源

核心组件

  • 日志模块：提供日志级别枚举、动态级别设置、时间戳格式化与不同级别输出
  • HTTP服务器：基于Express，启用Morgan进行HTTP访问日志，支持多种格式
  • WebSocket信令：基于ws，维护连接组、广播与心跳检测
  • HTTP信令处理器：基于会话与连接ID管理，提供offer/answer/candidate等信令存取
  • Swagger文档：自动生成API文档，便于监控与排障时查阅接口规范

章节来源

架构总览

下图展示了从请求进入、HTTP处理、WebSocket处理到日志输出的整体流程。

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)"

图表来源

详细组件分析

日志系统配置

  • 日志级别
    • 支持 none/error/warn/log/info 五级，可通过运行参数或环境变量设置
    • 默认级别为 info；当级别为 none 时不输出任何日志
  • 输出格式
    • 自动添加ISO时间戳与大写的级别前缀
    • 使用不同console方法区分 error/warn/info/log
  • HTTP访问日志
    • 通过 Morgan 中间件启用，支持 combined/dev/short/tiny 或禁用
    • 日志级别与Morgan日志可并行使用，便于区分业务日志与访问日志
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(["完成"])

图表来源

章节来源

HTTP访问日志与路由

  • 访问日志
    • 通过 Morgan 中间件以配置项启用，支持多种格式
    • 可通过运行参数控制，避免生产环境产生过多日志
  • 信令路由
    • 提供会话创建、连接管理、offer/answer/candidate获取与推送
    • 使用会话ID作为安全约束，确保接口访问受控
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"

图表来源

章节来源

WebSocket信令与连接管理

  • 连接生命周期
    • 建立连接时注册，断开时清理；记录连接/断开/消息等事件
  • 1对多模式
    • host与participants角色分工，offer/answer/candidate按角色路由
    • 支持广播与定向消息，便于扩展聊天、白板等场景
  • 心跳与超时
    • 定期发送ping并检查lastActivity，超时自动断开，降低僵尸连接占用
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 : "委托处理"

图表来源

章节来源

HTTP处理器与会话/连接模型

  • 会话与连接
    • 会话ID唯一标识一次通话或交互；连接ID标识具体端点
    • 支持私有模式下的双向配对与公共模式下的广播
  • 信令存储
    • offer/answer/candidate按连接ID与会话ID存储，支持按时间过滤
  • 超时与清理
    • 基于lastRequestedTime定期清理超时会话，释放资源
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)"]

图表来源

章节来源

客户端日志与媒体统计

  • 客户端调试日志
    • 提供enable/disable与多级别输出，便于前端问题定位
  • 媒体统计
    • 基于RTCStats计算比特率、帧率等指标，辅助性能分析

章节来源

依赖关系分析

  • 运行时依赖
    • Express、ws、morgan、swagger-ui-express、uuid等
  • 开发与测试
    • Jest、ts-jest、mock-socket等
  • 构建与打包
    • TypeScript编译、pkg打包静态资源
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"]

图表来源

章节来源

性能考量

  • 连接数统计
    • WebSocket侧：通过连接集合与连接组统计当前活跃连接数
    • HTTP侧：通过会话与连接映射统计会话数量与连接数
  • 内存使用
    • 信令消息以Map/Set存储，需关注超时清理与消息大小
    • 前端媒体统计可辅助判断网络拥塞与编码开销
  • 请求响应时间与错误率
    • HTTP接口响应时间可通过中间件埋点或外部APM采集
    • 错误率可通过HTTP状态码分布统计
  • 轮询与长连接
    • HTTP轮询模式下应限制轮询频率，避免CPU与带宽浪费
    • WebSocket心跳与超时可减少无效连接占用

[本节为通用性能指导，无需特定文件引用]

故障排查指南

  • 常见问题
    • 会话不存在：HTTP处理器校验session-id，缺失或过期导致404
    • 连接ID冲突：私有模式下重复使用连接ID会触发400
    • WebSocket超时：长时间无活动将被自动断开
    • 文件上传失败：服务端重命名异常导致500
  • 排查步骤
    • 启用更细粒度日志（info/log），复现问题并核对日志时间线
    • 使用Swagger查看接口规范，确认请求头与参数
    • 检查WebSocket消息类型与路由逻辑，确认角色与目标参与者
    • 对比前后两次RTCStats，定位带宽与帧率异常

章节来源

结论

本项目提供了清晰的日志体系与信令处理能力，结合Morgan访问日志与Swagger文档，能够满足日常运维与排障需求。建议在生产环境中：

  • 明确日志级别与轮转策略，避免磁盘与IO压力
  • 引入APM或Prometheus/Grafana进行指标采集与可视化
  • 建立告警规则与通知通道，配合健康检查与自动恢复机制
  • 使用分布式追踪定位跨服务链路瓶颈

[本节为总结性内容，无需特定文件引用]

附录

日志系统配置清单

  • 日志级别
    • 可选：none/error/warn/log/info
    • 默认：info
  • 输出格式
    • ISO时间戳 + 大写级别前缀
    • 区分 error/warn/info/log
  • HTTP访问日志
    • 可选：combined/dev/short/tiny 或 none
    • 通过运行参数控制

章节来源

性能监控指标定义

  • 连接数
    • WebSocket活跃连接数：基于连接集合统计
    • HTTP会话数与连接数：基于会话映射统计
  • 内存使用
    • 服务端：关注Map/Set规模与消息队列长度
    • 客户端：媒体统计辅助判断编码与传输效率
  • 请求响应时间与错误率
    • 通过中间件或外部APM采集
    • 错误率基于HTTP状态码分布

章节来源

分布式追踪配置建议

  • 链路跟踪
    • 在HTTP入口与WebSocket消息处理处打点
    • 关键节点：创建会话、创建连接、发送/接收offer/answer/candidate
  • 瓶颈定位
    • 结合日志时间戳与追踪ID，定位慢查询与阻塞点
    • 媒体统计与网络指标联动分析

[本节为通用实践建议，无需特定文件引用]

告警规则与通知

  • 阈值建议
    • 连接数：单节点并发连接数峰值阈值
    • 错误率：HTTP 5xx占比、WebSocket断连率
    • 响应时间：P95/P99延迟阈值
  • 通知渠道
    • 邮件、IM、电话分级告警
  • 故障恢复
    • 自动扩容、熔断降级、快速回滚

[本节为通用实践建议，无需特定文件引用]

监控工具集成要点

  • Prometheus
    • 暴露指标端点，采集连接数、内存、请求速率与错误率
  • Grafana
    • 仪表板展示趋势、告警与热力图
  • ELK Stack
    • 收集HTTP与业务日志，建立检索与聚合分析

[本节为通用实践建议，无需特定文件引用]

Reference in New Issue View Git Blame Copy Permalink