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/src/services/curveClient.js backend/src/services/measurementStorage.js backend/src/services/otaStorage.js

1. 使用的系统与框架

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

2. 核心文件与包

• backend/src/config/logger.js — Winston 实例定义、格式与传输层配置。
• backend/logs/app.log — 默认文件输出路径，由 Dockerfile / 启动脚本挂载持久化。
• 各模块通过 require('../config/logger') 或同级相对路径引入 logger，如 routes/auth.js、services/*.js、config/redis.js 等。

3. 架构与约定

• 全局级别：默认 level: 'info'，低于 info 的日志被丢弃。
• 格式化：时间戳 YYYY-MM-DD HH:mm:ss + level + message + 可选 meta JSON；meta 对象会被 JSON.stringify 拼接在末尾，便于结构化检索。
• 双通道输出：
  • Console transport：容器标准输出，供 docker-compose / k8s 收集。
  • File transport：写入 backend/logs/app.log，UTF-8 编码。
• 使用模式：业务代码直接调用 logger.info/warn/error(...)，参数为模板字符串，将关键上下文（用户名、URL、S3 key 等）拼入消息体，而非传递结构化对象。
• 数据库 SQL 日志：Sequelize 仅在开发环境启用 console.log 输出 SQL，生产环境关闭，避免污染主日志。

4. 开发者应遵循的规则

• 统一从 ../config/logger 引入 logger，不要直接使用 console.log 记录业务事件。
• 按语义选择级别：正常流程用 info，可恢复异常或降级用 warn，不可恢复错误用 error。
• 将关键上下文（用户、设备、外部服务 URL、S3 key 等）以字符串形式嵌入 message，保持单行可读；如需结构化字段，可通过第三个参数传入对象，Winston 会自动序列化到末尾。
• 敏感信息（密码、token）不得写入日志；认证失败仅记录用户名等非敏感字段。
• 新增模块若需额外文件输出或按级别分片，应在 config/logger.js 中扩展 transports，而不是在各处重复创建 logger。