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/redis.js backend/package.json

1. 使用的框架与工具

• 日志框架：winston ^3.14
• 依赖声明位于 backend/package.json，通过 require('winston') 引入。
• 前端未集成专用日志库，调试主要依赖浏览器控制台。

2. 核心文件与位置

• 日志配置与实例导出：backend/src/config/logger.js
• 应用入口统一引入：backend/src/app.js（const logger = require('./config/logger');）
• 各模块按需引入使用，典型示例：backend/src/routes/auth.js、backend/src/config/redis.js 等。
• 默认日志文件路径：backend/logs/app.log（由 logger.js 自动创建目录并写入）。

3. 架构与约定

• 集中式初始化：所有日志输出均通过 src/config/logger.js 暴露的单一 logger 实例，避免重复配置。
• 输出目标（transports）：同时输出到控制台和文件两个 sink：
  • Console transport：便于本地开发实时观察。
  • File transport：固定文件名 logs/app.log，编码 UTF-8。
• 格式策略：timestamp + level + message + JSON meta 拼接的单行文本格式，时间格式为 YYYY-MM-DD HH:mm:ss；当存在额外元数据时以空格分隔追加 JSON 字符串。
• 级别策略：全局 level: 'info'，代码中仅使用 info / warn / error 三个级别，未见 debug 级别调用。
• 结构化字段：未采用 winston 的 structured log 对象传参方式，而是将业务上下文拼入 message 字符串（如 Login failed for username=${trimmedUsername}），meta 字段基本未使用。
• 数据库层日志：Sequelize 在开发环境启用原生 console.log 打印 SQL，生产环境关闭（logging: isDevelopment ? (msg) => console.log(msg) : false），不走 Winston。

4. 开发者应遵循的规则

• 统一引用：始终从 ../config/logger 或相对路径引用同一 logger 实例，不要自行 createLogger。
• 级别选择：
  • info：记录关键业务流程事件（登录成功、密码修改、服务启动等）。
  • warn：记录可恢复异常或预期外的分支（用户名不存在、资源未找到等）。
  • error：记录异常堆栈信息或不可恢复错误。
  • 不使用 debug 级别。
• 消息内容：将关键上下文（用户名、ID、MAC 等）直接拼入 message 字符串；如需附带复杂对象，可通过第三个参数传入 meta，但当前代码风格倾向于纯文本。
• 敏感信息：禁止在日志中输出密码、token、完整请求体等敏感数据（现有代码已避免输出 password_hash/token 值）。
• 文件轮转：当前未配置 winston-daily-rotate-file 等轮转插件，长期运行需注意 app.log 体积增长，后续可在 transports 中补充轮转策略。