更新 wiki

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

@@ -0,0 +1,39 @@
+---
+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 或容器日志收集策略。