---
kind: logging_system
name: 基于 Winston 的日志系统
category: logging_system
scope:
    - '**'
source_files:
    - backend/src/config/logger.js
    - backend/src/app.js
    - backend/src/config/database.js
    - backend/package.json
---

## 1. 使用的系统与框架
- 后端采用 **Winston v3** 作为统一日志框架，通过 `backend/src/config/logger.js` 集中创建并导出单例 logger。
- 前端（Vue3）未发现专用日志库，未在前端代码中引入结构化日志输出。
- Sequelize 在开发环境将 SQL 查询直接 `console.log` 到控制台，生产环境关闭 SQL 日志。

## 2. 核心文件与包
- `backend/src/config/logger.js` — Winston 实例定义、格式与传输配置
- `backend/src/app.js` — 应用启动时记录数据库同步、服务监听等关键事件
- `backend/package.json` — 依赖声明 `winston: ^3.14`
- `backend/logs/app.log` — 默认文件日志输出路径
- `backend/src/config/database.js` — Sequelize 的 `logging` 开关逻辑

## 3. 架构与约定
- **单例导出**：`logger.js` 使用 `winston.createLogger()` 创建全局 logger，并通过 `module.exports = logger` 供各模块 `require('../config/logger')` 复用。
- **日志级别**：全局默认 level 为 `info`；业务代码中使用 `logger.info / warn / error` 三个级别，未见 `debug` 调用。
- **输出格式**：时间戳 + 级别 + 消息 + 可选 JSON meta 字段，形如：
  ```
  2026-06-09 12:34:56 - info - User admin logged in {}
  ```
- **双通道输出**：同时写入 Console 和文件 `backend/logs/app.log`，编码 UTF-8。
- **无按级别/日期分片**：当前仅一个 `app.log` 文件，未启用 `FileTransport` 的 `maxsize`、`maxFiles`、`filename` 模板等滚动策略。
- **Sequelize SQL 日志**：仅在 `isDevelopment` 时开启，输出到 `console.log`，不经过 Winston。
- **中间件层**：未集成 Express 请求日志中间件（如 `morgan`），HTTP 访问日志未统一采集。

## 4. 开发者应遵循的规则
- **统一入口**：所有日志必须通过 `const logger = require('../config/logger')` 获取，禁止直接使用 `console.log` 输出业务日志。
- **级别选择**：
  - `info`：正常业务流程事件（登录成功、密码修改、数据操作完成等）
  - `warn`：可恢复异常或潜在问题（登录失败、参数校验警告等）
  - `error`：不可恢复错误（数据库异常、外部服务调用失败等）
- **结构化字段**：通过第三个参数传入对象以附加上下文，例如 `logger.warn({ username, ip }, 'Login failed')`，该对象会被序列化为 JSON 追加到消息末尾。
- **敏感信息**：避免在日志中记录明文密码、完整 token 等敏感内容。
- **SQL 调试**：如需查看底层 SQL，确保环境变量处于开发模式以使 Sequelize logging 生效；生产环境应保持关闭以避免性能损耗。
- **日志轮转**：当前未配置自动轮转，部署时应配合外部工具（如 `logrotate`、Docker log driver）管理 `backend/logs/app.log` 大小。