首页新增新增&日活报表

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

@@ -6,34 +6,40 @@ scope:
     - '**'
 source_files:
     - backend/src/config/logger.js
-    - backend/logs/app.log
     - backend/src/app.js
+    - backend/src/routes/auth.js
+    - backend/src/config/redis.js
+    - backend/package.json
 ---
 
 ## 1. 使用的框架与工具
-- 后端采用 Winston 作为统一日志库，通过 backend/src/config/logger.js 创建全局 logger 实例并导出。
-- 前端未引入专用日志框架，调试依赖浏览器控制台，无集中式前端日志方案。
+- 日志框架：`winston ^3.14`
+- 依赖声明位于 `backend/package.json`，通过 `require('winston')` 引入。
+- 前端未集成专用日志库，调试主要依赖浏览器控制台。
 
 ## 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 实例。
+- 日志配置与实例导出：`backend/src/config/logger.js`
+- 应用入口统一引入：`backend/src/app.js`（`const logger = require('./config/logger');`）
+- 各模块按需引入使用，典型示例：`backend/src/routes/auth.js`、`backend/src/config/redis.js` 等。
+- 默认日志文件路径：`backend/logs/app.log`（由 `logger.js` 自动创建目录并写入）。
 
 ## 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 记录。
+- **集中式初始化**：所有日志输出均通过 `src/config/logger.js` 暴露的单一 `logger` 实例，避免重复配置。
+- **输出目标（transports）**：同时输出到控制台和文件两个 sink：
+  - Console transport：便于本地开发实时观察。
+  - File transport：固定文件名 `logs/app.log`，编码 UTF-8。
+- **格式策略**：`timestamp + level + message + JSON meta` 拼接的单行文本格式，时间格式为 `YYYY-MM-DD HH:mm:ss`；当存在额外元数据时以空格分隔追加 JSON 字符串。
+- **级别策略**：全局 `level: 'info'`，代码中仅使用 `info / warn / error` 三个级别，未见 `debug` 级别调用。
+- **结构化字段**：未采用 winston 的 structured log 对象传参方式，而是将业务上下文拼入 message 字符串（如 `Login failed for username=${trimmedUsername}`），meta 字段基本未使用。
+- **数据库层日志**：Sequelize 在开发环境启用原生 `console.log` 打印 SQL，生产环境关闭（`logging: isDevelopment ? (msg) => console.log(msg) : false`），不走 Winston。
 
 ## 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 用于快速排查。
+- **统一引用**：始终从 `../config/logger` 或相对路径引用同一 logger 实例，不要自行 `createLogger`。
+- **级别选择**：
+  - `info`：记录关键业务流程事件（登录成功、密码修改、服务启动等）。
+  - `warn`：记录可恢复异常或预期外的分支（用户名不存在、资源未找到等）。
+  - `error`：记录异常堆栈信息或不可恢复错误。
+  - 不使用 `debug` 级别。
+- **消息内容**：将关键上下文（用户名、ID、MAC 等）直接拼入 message 字符串；如需附带复杂对象，可通过第三个参数传入 meta，但当前代码风格倾向于纯文本。
+- **敏感信息**：禁止在日志中输出密码、token、完整请求体等敏感数据（现有代码已避免输出 password_hash/token 值）。
+- **文件轮转**：当前未配置 winston-daily-rotate-file 等轮转插件，长期运行需注意 `app.log` 体积增长，后续可在 transports 中补充轮转策略。