---
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/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 或容器日志收集策略。