---
kind: logging_system
name: 后端日志系统（Winston 单文件输出）
category: logging_system
scope:
    - '**'
source_files:
    - backend/src/config/logger.js
    - backend/logs/app.log
    - backend/src/app.js
---

## 1. 使用的框架与工具
- 后端采用 Winston 作为统一日志库，通过 backend/src/config/logger.js 创建全局 logger 实例并导出。
- 前端未引入专用日志框架，调试依赖浏览器控制台，无集中式前端日志方案。

## 2. 核心文件与位置
- backend/src/config/logger.js — Winston 初始化、格式与传输配置。
- backend/logs/app.log — 当前唯一持久化日志文件，由 File transport 写入。
- backend/src/app.js — 应用入口，启动阶段使用 logger 记录数据库同步与服务监听信息。
- 各业务模块（如 routes/auth.js、routes/blacklist.js、config/redis.js）通过 require('../config/logger') 或同级引用获取 logger 实例。

## 3. 架构与约定
- 单例模式：logger 在 config/logger.js 中 createLogger 一次后 module.exports，所有模块共享同一实例。
- 日志级别：默认 level 为 info，代码中使用 logger.info / logger.warn / logger.error 三种级别；未发现 debug 级别的使用。
- 输出格式：自定义 printf 模板，形如 YYYY-MM-DD HH:mm:ss - level - message + JSON(meta)，时间戳固定格式，额外字段以 JSON 字符串拼接在消息末尾。
- Sinks（传输）：
  - Console transport：直接输出到标准输出，便于 Docker 容器收集 stdout。
  - File transport：追加写入 backend/logs/app.log，UTF-8 编码，未配置按天/大小轮转。
- 目录自动创建：启动时若 logs/ 不存在则 fs.mkdirSync(..., { recursive: true }) 自动创建。
- 第三方库日志：Sequelize 在开发环境将 SQL 语句通过 console.log 输出，生产环境关闭；Redis 错误通过统一 logger 记录。

## 4. 开发者应遵循的规则
- 统一导入：在任意模块中通过 const logger = require('./config/logger')（相对路径根据层级调整）获取 logger，禁止直接使用 console.log 输出业务日志。
- 级别选择：仅使用 info / warn / error 三个级别，避免引入 debug；关键流程用 info，可恢复异常用 warn，不可恢复错误用 error。
- 结构化字段：需要附加上下文数据时，以对象形式传入第三个参数，例如 logger.info('User logged in', { userId: user.id })，会被序列化为 JSON 拼接到消息后。
- 敏感信息脱敏：不要在日志中明文记录密码、token、完整请求体等敏感内容。
- 日志文件管理：当前没有按天/大小轮转策略，长期运行需配合外部 logrotate 或容器日志驱动进行清理，避免 app.log 无限增长。
- Docker 集成：由于同时输出到 stdout，建议通过容器编排平台（docker-compose、K8s）收集 stdout 作为主日志源，本地开发保留 app.log 用于快速排查。