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/routes/auth.js backend/src/config/database.js

1. 核心框架与配置

• 框架: 使用 winston 作为后端 Node.js 应用的统一日志框架。
• 配置文件: backend/src/config/logger.js 负责初始化 logger 实例。
• 日志级别: 默认设置为 info，涵盖 info, warn, error 等级别。
• 输出格式:
  • 采用自定义的文本格式：${timestamp} - ${level} - ${message} ${JSON.stringify(meta)}。
  • 时间戳格式为 YYYY-MM-DD HH:mm:ss。
  • 额外元数据（meta）会被序列化为 JSON 字符串附加在消息后。

2. 日志输出目标 (Transports)

• 控制台 (Console): 所有级别的日志都会输出到标准输出，便于本地开发和容器日志采集。
• 文件 (File): 所有日志同时写入 backend/logs/app.log 文件。
  • 目录 logs/ 若不存在会在初始化时自动创建。
  • 目前未配置日志轮转（Log Rotation），长期运行需注意文件大小。

3. 使用规范与模式

• 引入方式: 在各业务模块中通过 require('../config/logger') 获取单例 logger。
• 记录模式:
  • 信息类: logger.info('描述性消息')，如服务启动、用户登录成功、数据库同步完成。
  • 警告类: logger.warn('异常但可恢复的情况')，如登录失败、资源未找到。
  • 错误类: logger.error('错误详情')，通常在 catch 块中记录异常信息 e.message。
• 上下文记录: 建议在 message 中包含关键业务 ID 或参数，例如 User ${username} logged in 或 id=${brandId}。

4. 特殊场景处理

• 数据库日志: 在 backend/src/config/database.js 中，Sequelize 的 SQL 日志仅在开发环境 (APP_ENV === 'development') 下通过 console.log 输出，生产环境关闭以避免性能损耗和日志污染。
• 前端日志: 前端项目 (frontend/) 目前未发现统一的日志封装，主要依赖浏览器控制台默认的 console 输出。