41 lines
2.8 KiB
Markdown
41 lines
2.8 KiB
Markdown
|
---
|
|||
|
|
kind: logging_system
|
|||
|
|
name: 后端日志系统（Winston 文件+控制台输出）
|
|||
|
|
category: logging_system
|
|||
|
|
scope:
|
|||
|
|
- '**'
|
|||
|
|
source_files:
|
|||
|
|
- backend/src/config/logger.js
|
|||
|
|
- backend/src/app.js
|
|||
|
|
- backend/logs/app.log
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 使用的框架与工具
|
|||
|
|
- 日志框架：winston v3，通过 backend/src/config/logger.js 统一创建并导出单例实例。
|
|||
|
|
- 依赖声明在 backend/package.json 中："winston": "^3.14"。
|
|||
|
|
- 前端（frontend / frontend_v2）未发现独立的日志模块，主要使用浏览器 console，未纳入本仓库的日志体系。
|
|||
|
|
|
|||
|
|
## 2. 核心文件与位置
|
|||
|
|
- backend/src/config/logger.js — winston 初始化、格式、传输层配置。
|
|||
|
|
- backend/src/app.js — 应用入口，启动时记录数据库同步、服务监听等关键事件。
|
|||
|
|
- backend/logs/app.log — 默认文件输出路径（由 logger 自动创建目录）。
|
|||
|
|
|
|||
|
|
## 3. 架构与约定
|
|||
|
|
- 全局单例模式：所有模块通过 require('./config/logger') 获取同一 logger 实例，避免重复配置。
|
|||
|
|
- 日志级别策略：默认 level 为 info，业务代码按语义选择 info/warn/error；未发现 debug 级别的使用。
|
|||
|
|
- 结构化字段：通过 printf 将 timestamp、level、message 以及任意 meta 对象序列化为 JSON 字符串拼接在消息末尾，便于后续解析。
|
|||
|
|
- 双通道输出：同时写入 Console 和 File（logs/app.log），未做按级别分文件、轮转或远程收集的配置。
|
|||
|
|
- 错误处理：路由与服务层捕获异常后统一 logger.error(...) 输出，未定义全局错误中间件集中记录 HTTP 请求日志。
|
|||
|
|
- 数据库日志：Sequelize 仅在开发环境开启 SQL 日志到 console.log，生产环境关闭，不进入 winston。
|
|||
|
|
- Redis 缓存：EQ 缓存读写失败通过 logger.error 记录，属于业务级告警而非基础设施错误。
|
|||
|
|
|
|||
|
|
## 4. 开发者应遵循的规则
|
|||
|
|
- 统一导入：在需要日志的模块顶部 const logger = require('../config/logger');，禁止直接使用 console.log 输出业务信息。
|
|||
|
|
- 级别选择：
|
|||
|
|
- info：正常业务流程关键点（登录成功、数据创建/更新、服务启动）。
|
|||
|
|
- warn：可恢复的异常情况（资源不存在、参数校验失败但返回 4xx）。
|
|||
|
|
- error：不可恢复错误或外部调用失败（DB/Redis/HTTP 异常）。
|
|||
|
|
- 结构化元数据：尽量以第三个参数传入对象，例如 logger.info('User logged in', { username })，以便后续提取字段。
|
|||
|
|
- 敏感信息脱敏：不要在日志中记录密码、token、完整手机号等敏感字段。
|
|||
|
|
- 性能考虑：当前无日志轮转，生产环境需配合外部 logrotate 或容器日志采集方案，避免 app.log 无限增长。
|
|||
|
|
- 前端日志：前端未集成统一日志 SDK，如需埋点建议在后端 API 层记录请求上下文（IP、UA、耗时等），前端仅保留调试用 console。
|