dashboard/.qoder/repowiki/knowledge/zh/后端日志系统（Winston 单文件输出）__2/后端日志系统（Winston 单文件输出）__2.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 backend/package.json

1. 使用的系统与框架

• 后端采用 Winston v3 作为统一日志框架，通过 backend/src/config/logger.js 集中创建并导出实例。
• 前端未引入独立日志库，调试依赖浏览器控制台，无结构化前端日志方案。

2. 核心文件与位置

• 日志配置与实例：backend/src/config/logger.js
• 应用入口挂载：backend/src/app.js（require('./config/logger') 后在启动/错误路径调用）
• 各路由模块按需 require('../config/logger') 使用（如 routes/auth.js、routes/blacklist.js 等）
• 数据库 SQL 日志由 Sequelize 单独控制：backend/src/config/database.js 中 logging: isDevelopment ? console.log : false
• 日志持久化目录：backend/logs/app.log（由 Dockerfile 中的 /app/logs 映射到宿主机）

3. 架构与约定

• 单例模式：全局唯一 logger 实例，所有模块共享同一配置，避免重复初始化。
• 输出目标：同时写入 Console 与本地文件 logs/app.log，编码 UTF-8；未启用按天/大小轮转。
• 日志级别：默认 info，业务代码中使用 logger.info / warn / error 三种级别，未见 debug 使用。
• 格式规范：时间戳 YYYY-MM-DD HH:mm:ss + 级别 + 消息体；额外字段以 JSON 字符串拼接在末尾（...meta 展开为 JSON.stringify(meta)），非结构化 JSON 行。
• 环境变量：日志级别未暴露为环境变量，硬编码为 'info'。
• Sequelize SQL 日志：开发环境通过 console.log 输出，生产关闭，不进入 Winston。

4. 开发者应遵循的规则

• 统一从 ../config/logger 导入并使用，禁止直接 console.log 输出业务日志。
• 关键事件使用对应级别：成功/常规信息用 info，可恢复异常或降级用 warn，不可恢复错误用 error。
• 如需附加上下文，通过第三个参数对象传入（会被序列化为 JSON 拼接到消息后），例如 logger.info('msg', { userId })。
• 不要在日志中记录敏感信息（密码、token、完整请求体等）。
• 当前未实现日志轮转，生产部署时应配合外部 logrotate 或容器日志收集策略。