---
kind: logging_system
name: 后端日志系统（Winston 统一输出）
category: logging_system
scope:
    - '**'
source_files:
    - 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。