更新 wiki

.qoder/repowiki/knowledge/zh/后端日志系统（Winston 单文件输出）/后端日志系统（Winston 单文件输出）.md

@@ -6,34 +6,34 @@ scope:
     - '**'
 source_files:
     - backend/src/config/logger.js
+    - backend/logs/app.log
     - 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` 集中创建并导出实例。
-- 前端未引入独立日志库，调试依赖浏览器控制台，无结构化前端日志方案。
+## 1. 使用的框架与工具
+- 后端采用 Winston 作为统一日志库，通过 backend/src/config/logger.js 创建全局 logger 实例并导出。
+- 前端未引入专用日志框架，调试依赖浏览器控制台，无集中式前端日志方案。
 
 ## 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` 映射到宿主机）
+- 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 实例，所有模块共享同一配置，避免重复初始化。
-- **输出目标**：同时写入 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。
+- 单例模式：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. 开发者应遵循的规则
-- 统一从 `../config/logger` 导入并使用，禁止直接 `console.log` 输出业务日志。
-- 关键事件使用对应级别：成功/常规信息用 `info`，可恢复异常或降级用 `warn`，不可恢复错误用 `error`。
-- 如需附加上下文，通过第三个参数对象传入（会被序列化为 JSON 拼接到消息后），例如 `logger.info('msg', { userId })`。
-- 不要在日志中记录敏感信息（密码、token、完整请求体等）。
-- 当前未实现日志轮转，生产部署时应配合外部 logrotate 或容器日志收集策略。
+- 统一导入：在任意模块中通过 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 用于快速排查。