docs: 补充完善日志系统与链路追踪设计

- 架构文档新增第八节：日志系统与链路追踪设计 - Trace ID 全链路追踪（HTTP/WebSocket/跨服务） - 日志级别规范（DEBUG/INFO/WARN/ERROR/FATAL） - 结构化日志格式（开发文本/生产JSON） - 函数级日志规范（入口/出口模式） - WebSocket 日志追踪 - Go ↔ mediasoup Node 跨服务链路关联 - 敏感信息脱敏规则 - 前端错误上报机制 - 实施计划 Task 2 补充日志系统详细实现步骤 Made-with: Cursor
2026-02-27 16:36:57 +08:00
parent 8361275e70
commit 8bed227060
2 changed files with 249 additions and 10 deletions
--- a/docs/architecture/system-architecture.md
+++ b/docs/architecture/system-architecture.md
@@ -245,3 +245,202 @@ services:
 | **uniapp (Vue 3)** | 一套代码多端运行（H5/App/小程序） |
 | **Element Plus** | Vue 3 生态最成熟的 PC 端组件库 |
 | **Docker Compose** | 轻量级容器编排，适合初期和开发环境 |
+
+---
+
+## 八、日志系统与链路追踪设计
+
+### 8.1 设计目标
+
+- 每一个请求从进入系统到完成响应，全链路可追踪
+- Go 服务内部的函数调用链清晰可见
+- Go 服务与 mediasoup Node 服务之间的调用可关联
+- WebSocket 消息的处理过程可追踪
+- 日志分级明确，开发/生产环境日志策略不同
+- 日志格式统一、结构化，便于后期接入 ELK/Loki 等日志平台
+
+### 8.2 请求链路追踪（Trace ID / Request ID）
+
+每个请求在进入系统时生成唯一的 `trace_id`，贯穿整个处理链路：
+
+```
+客户端请求
+    │
+    ▼
+Nginx（生成或转发 X-Request-ID）
+    │
+    ▼
+Go 中间件（提取或生成 trace_id，注入 context）
+    │
+    ├── Controller 日志：[trace_id] 收到请求 POST /api/v1/auth/login
+    ├── Service 日志：  [trace_id] 开始处理登录，account=zhangsan
+    ├── DAO 日志：      [trace_id] SQL查询 auth_users WHERE username=zhangsan
+    ├── Redis 日志：    [trace_id] SET echo:auth:token:1
+    │
+    ├── 如果涉及 mediasoup 调用：
+    │   Go 将 trace_id 放入 HTTP Header 传给 Node 服务
+    │   Node 服务日志也携带同一个 trace_id
+    │
+    ▼
+Go 中间件：[trace_id] 请求完成 200 OK 耗时 25ms
+```
+
+**实现方式：**
+
+```go
+// 中间件：为每个请求生成 trace_id 并注入 context
+func TraceMiddleware() gin.HandlerFunc {
+    return func(c *gin.Context) {
+        traceID := c.GetHeader("X-Request-ID")
+        if traceID == "" {
+            traceID = generateTraceID()  // UUID 或 雪花算法
+        }
+        ctx := context.WithValue(c.Request.Context(), "trace_id", traceID)
+        c.Request = c.Request.WithContext(ctx)
+        c.Header("X-Request-ID", traceID)
+        c.Next()
+    }
+}
+```
+
+### 8.3 日志级别规范
+
+| 级别 | 使用场景 | 示例 |
+|------|---------|------|
+| **DEBUG** | 开发调试信息，生产环境不输出 | 函数参数详情、SQL 语句、Redis 操作 |
+| **INFO** | 正常业务流程的关键节点 | 用户登录成功、会议创建、消息发送 |
+| **WARN** | 异常但不影响主流程 | 参数格式警告、缓存未命中、重试操作 |
+| **ERROR** | 业务错误，需要关注 | 数据库查询失败、外部服务调用失败 |
+| **FATAL** | 系统级致命错误 | 数据库连接失败、配置加载失败（启动时） |
+
+**环境日志策略：**
+
+| 环境 | 最低级别 | 输出方式 | 格式 |
+|------|---------|---------|------|
+| 开发 | DEBUG | 控制台（彩色） | 可读文本 |
+| 生产 | INFO | 文件 + 控制台 | JSON 结构化 |
+
+### 8.4 日志格式规范
+
+**结构化日志字段（每条日志必含）：**
+
+```json
+{
+    "level": "info",
+    "timestamp": "2026-02-27T10:30:00.123Z",
+    "trace_id": "abc-123-def-456",
+    "module": "auth",
+    "func": "service.auth_service.Login",
+    "msg": "用户登录成功",
+    "user_id": 1,
+    "ip": "192.168.1.100",
+    "latency_ms": 25
+}
+```
+
+### 8.5 函数级日志规范
+
+每个 Service 和 DAO 层的关键函数遵循统一的日志模式：
+
+```go
+func (s *AuthService) Login(ctx context.Context, req *dto.LoginRequest) (*dto.LoginResponse, error) {
+    funcName := "service.auth_service.Login"
+
+    // 入口日志：记录关键入参（脱敏）
+    logs.Info(ctx, funcName, "开始处理登录",
+        zap.String("account", req.Account),
+    )
+
+    var err error
+    defer func() {
+        if err != nil {
+            // 出口日志（失败）：记录错误信息
+            logs.Error(ctx, funcName, "登录处理失败",
+                zap.String("account", req.Account),
+                zap.Error(err),
+            )
+        } else {
+            // 出口日志（成功）
+            logs.Info(ctx, funcName, "登录处理完成",
+                zap.String("account", req.Account),
+            )
+        }
+    }()
+
+    // 业务逻辑...
+    return resp, err
+}
+```
+
+### 8.6 请求日志中间件
+
+HTTP 请求日志中间件自动记录每个请求的完整信息：
+
+```
+[INFO] trace_id=abc-123 | POST /api/v1/auth/login | status=200 | latency=25ms | ip=192.168.1.100 | user_agent=Mozilla/5.0
+[ERROR] trace_id=def-456 | POST /api/v1/meetings/join | status=500 | latency=150ms | ip=10.0.0.5 | error="mediasoup service unavailable"
+```
+
+### 8.7 WebSocket 日志
+
+WebSocket 连接和消息也纳入日志追踪体系：
+
+```
+[INFO] ws_conn=conn-789 | user_id=1 | WebSocket 连接建立
+[INFO] ws_conn=conn-789 | user_id=1 | trace_id=ws-001 | 收到事件: im.message.send | conversation_id=5
+[INFO] ws_conn=conn-789 | user_id=1 | trace_id=ws-001 | 消息处理完成 | msg_id=10086 | latency=8ms
+[WARN] ws_conn=conn-789 | user_id=1 | 心跳超时，准备断开连接
+[INFO] ws_conn=conn-789 | user_id=1 | WebSocket 连接断开 | 在线时长=3600s
+```
+
+### 8.8 跨服务链路追踪（Go ↔ mediasoup Node）
+
+Go 服务调用 mediasoup Node 服务时，通过 HTTP Header 传递 trace_id：
+
+```
+Go 服务:
+  [INFO] trace_id=abc-123 | 调用 mediasoup: POST /media/transport/create | room=123-456
+
+mediasoup Node 服务:
+  [INFO] trace_id=abc-123 | 收到请求: POST /media/transport/create | room=123-456
+  [INFO] trace_id=abc-123 | Transport 创建成功 | transport_id=xxx | latency=5ms
+
+Go 服务:
+  [INFO] trace_id=abc-123 | mediasoup 调用完成 | transport_id=xxx | latency=12ms
+```
+
+### 8.9 敏感信息脱敏
+
+日志中的敏感信息必须脱敏处理：
+
+| 字段 | 脱敏规则 | 示例 |
+|------|---------|------|
+| 密码 | 不记录 | `password=***` |
+| Token | 只记录前后各 4 位 | `token=eyJh...5NiJ` |
+| 邮箱 | 部分隐藏 | `email=zh***@example.com` |
+| 手机号 | 中间 4 位隐藏 | `phone=138****8000` |
+| IP | 完整记录（用于安全审计） | `ip=192.168.1.100` |
+
+### 8.10 前端日志与错误上报
+
+前端通过 API 上报关键错误和操作日志：
+
+```
+POST /api/v1/client/log    # 前端错误上报接口
+
+{
+    "level": "error",
+    "module": "mediasoup-client",
+    "message": "Transport connection failed",
+    "stack": "Error: ICE connection failed...",
+    "page": "/meeting/room",
+    "user_agent": "...",
+    "timestamp": 1740700000
+}
+```
+
+前端需要记录的关键场景：
+- WebSocket 连接失败/断线
+- mediasoup-client Transport 连接失败
+- API 请求超时/5xx 错误
+- 页面 JS 异常（通过 `window.onerror` / `Vue.config.errorHandler`）