dashboard/.qoder/repowiki/knowledge/zh/基于 Winston 的日志系统/基于 Winston 的日志系统.md

kind, name, category, scope, source_files

kind	name	category	scope	source_files
logging_system	基于 Winston 的日志系统	logging_system	**	backend/src/config/logger.js backend/src/app.js backend/src/config/database.js backend/package.json

1. 使用的系统与框架

• 后端采用 Winston v3 作为统一日志框架，通过 backend/src/config/logger.js 集中创建并导出单例 logger。
• 前端（Vue3）未发现专用日志库，未在前端代码中引入结构化日志输出。
• Sequelize 在开发环境将 SQL 查询直接 console.log 到控制台，生产环境关闭 SQL 日志。

2. 核心文件与包

• backend/src/config/logger.js — Winston 实例定义、格式与传输配置
• backend/src/app.js — 应用启动时记录数据库同步、服务监听等关键事件
• backend/package.json — 依赖声明 winston: ^3.14
• backend/logs/app.log — 默认文件日志输出路径
• backend/src/config/database.js — Sequelize 的 logging 开关逻辑

3. 架构与约定

• 单例导出：logger.js 使用 winston.createLogger() 创建全局 logger，并通过 module.exports = logger 供各模块 require('../config/logger') 复用。
• 日志级别：全局默认 level 为 info；业务代码中使用 logger.info / warn / error 三个级别，未见 debug 调用。
• 输出格式：时间戳 + 级别 + 消息 + 可选 JSON meta 字段，形如：

  2026-06-09 12:34:56 - info - User admin logged in {}
  

• 双通道输出：同时写入 Console 和文件 backend/logs/app.log，编码 UTF-8。
• 无按级别/日期分片：当前仅一个 app.log 文件，未启用 FileTransport 的 maxsize、maxFiles、filename 模板等滚动策略。
• Sequelize SQL 日志：仅在 isDevelopment 时开启，输出到 console.log，不经过 Winston。
• 中间件层：未集成 Express 请求日志中间件（如 morgan），HTTP 访问日志未统一采集。

4. 开发者应遵循的规则

• 统一入口：所有日志必须通过 const logger = require('../config/logger') 获取，禁止直接使用 console.log 输出业务日志。
• 级别选择：
  • info：正常业务流程事件（登录成功、密码修改、数据操作完成等）
  • warn：可恢复异常或潜在问题（登录失败、参数校验警告等）
  • error：不可恢复错误（数据库异常、外部服务调用失败等）
• 结构化字段：通过第三个参数传入对象以附加上下文，例如 logger.warn({ username, ip }, 'Login failed')，该对象会被序列化为 JSON 追加到消息末尾。
• 敏感信息：避免在日志中记录明文密码、完整 token 等敏感内容。
• SQL 调试：如需查看底层 SQL，确保环境变量处于开发模式以使 Sequelize logging 生效；生产环境应保持关闭以避免性能损耗。
• 日志轮转：当前未配置自动轮转，部署时应配合外部工具（如 logrotate、Docker log driver）管理 backend/logs/app.log 大小。